projects / privoxy.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
user-manual: Note that protocol and host have to be added
[privoxy.git] / doc / source / user-manual.sgml
diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index 2bd0921..91a53b0 100644 (file)
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -14,11 +14,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.29">
-<!entity p-status "stable">
+<!entity p-version "3.0.30">
+<!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">
@@ -133,7 +133,7 @@ Hal.
 <para>
  In addition to the core
  features of ad blocking and
 <para>
  In addition to the core
  features of ad blocking and
- <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookie</ulink> management,
+ <ulink url="https://en.wikipedia.org/wiki/Browser_cookie">cookie</ulink> management,
  <application>Privoxy</application> provides many supplemental
  features<![%p-not-stable;[, some of them currently under development]]>,
  that give the end-user more control, more privacy and more freedom:
  <application>Privoxy</application> provides many supplemental
  features<![%p-not-stable;[, some of them currently under development]]>,
  that give the end-user more control, more privacy and more freedom:
@@ -659,7 +659,7 @@ MAKENSIS = ./nsis/makensis.exe
  <listitem>
   <para>
    Set your browser to use <application>Privoxy</application> as HTTP and
  <listitem>
   <para>
    Set your browser to use <application>Privoxy</application> as HTTP and
-   HTTPS (SSL)  <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>
+   HTTPS (SSL)  <ulink url="https://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>
    by setting the proxy configuration for address of
    <literal>127.0.0.1</literal> and port <literal>8118</literal>.
    <emphasis>DO NOT</emphasis> activate proxying for <literal>FTP</literal> or
    by setting the proxy configuration for address of
    <literal>127.0.0.1</literal> and port <literal>8118</literal>.
    <emphasis>DO NOT</emphasis> activate proxying for <literal>FTP</literal> or
@@ -672,7 +672,7 @@ MAKENSIS = ./nsis/makensis.exe
   <para>
     Flush your browser's disk and memory caches, to remove any cached ad images.
     If using <application>Privoxy</application> to manage
   <para>
     Flush your browser's disk and memory caches, to remove any cached ad images.
     If using <application>Privoxy</application> to manage
-    <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
+    <ulink url="https://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
     you should remove any currently stored cookies too.
   </para>
  </listitem>
     you should remove any currently stored cookies too.
   </para>
  </listitem>
@@ -1025,7 +1025,7 @@ MAKENSIS = ./nsis/makensis.exe
  Before launching <application>Privoxy</application> for the first time, you
  will want to configure your browser(s) to use
  <application>Privoxy</application> as a HTTP and HTTPS (SSL)
  Before launching <application>Privoxy</application> for the first time, you
  will want to configure your browser(s) to use
  <application>Privoxy</application> as a HTTP and HTTPS (SSL)
- <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>. The default is
+ <ulink url="https://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>. The default is
  127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions
  used port 8000). This is the one configuration step <emphasis>that must be done
 </emphasis>!
  127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions
  used port 8000). This is the one configuration step <emphasis>that must be done
 </emphasis>!
@@ -1037,13 +1037,13 @@ MAKENSIS = ./nsis/makensis.exe
 
  <!-- image of Mozilla Proxy configuration -->
   <figure pgwide="0" float="0"><title>Proxy Configuration Showing
 
  <!-- image of Mozilla Proxy configuration -->
   <figure pgwide="0" float="0"><title>Proxy Configuration Showing
-  Mozilla/Netscape HTTP and HTTPS (SSL) Settings</title>
+  Mozilla Firefox HTTP and HTTPS (SSL) Settings</title>
    <mediaobject>
      <imageobject>
       <imagedata  fileref="proxy_setup.jpg" format="jpg">
        </imageobject>
        <textobject>
    <mediaobject>
      <imageobject>
       <imagedata  fileref="proxy_setup.jpg" format="jpg">
        </imageobject>
        <textobject>
-        <phrase>[ Screenshot of Mozilla Proxy Configuration ]</phrase>
+        <phrase>[ Screenshot of Mozilla Firefox Proxy Configuration ]</phrase>
       </textobject>
    </mediaobject>
   </figure>
       </textobject>
    </mediaobject>
   </figure>
@@ -1054,7 +1054,7 @@ MAKENSIS = ./nsis/makensis.exe
 </para>
 
 <literallayout>
 </para>
 
 <literallayout>
- <guibutton>Tools</guibutton> -> <guibutton>Options</guibutton> ->  <guibutton>Advanced</guibutton> -> <guibutton>Network</guibutton> -><guibutton>Connection</guibutton> -> <guibutton>Settings</guibutton>
+ <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> ->  <guibutton>Network Settings</guibutton> -> <guibutton>Settings</guibutton>
 </literallayout>
 
 <para>
 </literallayout>
 
 <para>
@@ -1111,7 +1111,7 @@ MAKENSIS = ./nsis/makensis.exe
 <para>
  After doing this, flush your browser's disk and memory caches to force a
  re-reading of all pages and to get rid of any ads that may be cached. Remove
 <para>
  After doing this, flush your browser's disk and memory caches to force a
  re-reading of all pages and to get rid of any ads that may be cached. Remove
- any <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
+ any <ulink url="https://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
  if you want <application>Privoxy</application> to manage that. You are now
  ready to start enjoying the benefits of using
  <application>Privoxy</application>!
  if you want <application>Privoxy</application> to manage that. You are now
  ready to start enjoying the benefits of using
  <application>Privoxy</application>!
@@ -1759,7 +1759,7 @@ for details.
     The default profiles, and their associated actions, as pre-defined in
     <filename>default.action</filename> are:
    </para>
     The default profiles, and their associated actions, as pre-defined in
     <filename>default.action</filename> are:
    </para>
-    <table frame=all><title>Default Configurations</title>
+    <table frame=all id="default-configurations"><title>Default Configurations</title>
     <tgroup cols=4 align=left colsep=1 rowsep=1>
     <colspec colname=c1>
     <colspec colname=c2>
     <tgroup cols=4 align=left colsep=1 rowsep=1>
     <colspec colname=c1>
     <colspec colname=c2>
@@ -2045,7 +2045,7 @@ for details.
  The pattern matching syntax is different for the host and path parts of
  the URL. The host part uses a simple globbing type matching technique,
  while the path part uses more flexible
  The pattern matching syntax is different for the host and path parts of
  the URL. The host part uses a simple globbing type matching technique,
  while the path part uses more flexible
- <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+ <ulink url="https://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
   Expressions</quote></ulink> (POSIX 1003.2).
 </para>
 <para>
   Expressions</quote></ulink> (POSIX 1003.2).
 </para>
 <para>
@@ -2207,7 +2207,7 @@ for details.
  themselves. These work similarly to shell globbing type wild-cards:
  <quote>*</quote> represents zero or more arbitrary characters (this is
  equivalent to the
  themselves. These work similarly to shell globbing type wild-cards:
  <quote>*</quote> represents zero or more arbitrary characters (this is
  equivalent to the
- <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+ <ulink url="https://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
  Expression</quote></ulink> based syntax of <quote>.*</quote>),
  <quote>?</quote>  represents any single character (this is equivalent to the
  regular expression syntax of a simple <quote>.</quote>), and you can define
  Expression</quote></ulink> based syntax of <quote>.*</quote>),
  <quote>?</quote>  represents any single character (this is equivalent to the
  regular expression syntax of a simple <quote>.</quote>), and you can define
@@ -2275,7 +2275,7 @@ for details.
 
 <para>
  <application>Privoxy</application> uses <quote>modern</quote> POSIX 1003.2
 
 <para>
  <application>Privoxy</application> uses <quote>modern</quote> POSIX 1003.2
-  <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+  <ulink url="https://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
   Expressions</quote></ulink> for matching the path portion (after the slash),
   and is thus more flexible.
 </para>
   Expressions</quote></ulink> for matching the path portion (after the slash),
   and is thus more flexible.
 </para>
@@ -2932,6 +2932,11 @@ example.org/blocked-example-page</screen>
     one. This can be used to rewrite the request destination behind the client's
     back, for example to specify a Tor exit relay for certain requests.
    </para>
     one. This can be used to rewrite the request destination behind the client's
     back, for example to specify a Tor exit relay for certain requests.
    </para>
+   <para>
+    Note that to change the destination host for
+    <link linkend="HTTPS-INSPECTION">https-inspected</link>
+    requests a protocol and host has to be added to the URI.
+   </para>
    <para>
     Please refer to the <link linkend="filter-file">filter file chapter</link>
     to learn which client-header filters are available by default, and how to
    <para>
     Please refer to the <link linkend="filter-file">filter file chapter</link>
     to learn which client-header filters are available by default, and how to
@@ -2955,6 +2960,83 @@ example.org/blocked-example-page</screen>
 </variablelist>
 </sect3>
 
 </variablelist>
 </sect3>
 
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect3 renderas="sect4" id="client-body-filter">
+<title>client-body-filter</title>
+
+<variablelist>
+ <varlistentry>
+  <term>Typical use:</term>
+  <listitem>
+   <para>
+   Rewrite or remove client request body.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Effect:</term>
+  <listitem>
+   <para>
+    All request bodies to which this action applies are filtered on-the-fly through
+    the specified regular expression based substitutions.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Type:</term>
+  <!-- boolean, parameterized, Multi-value -->
+  <listitem>
+   <para>Multi-value.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Parameter:</term>
+  <listitem>
+   <para>
+    The name of a client-body filter, as defined in one of the
+    <link linkend="filter-file">filter files</link>.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    Please refer to the <link linkend="filter-file">filter file chapter</link>
+    to learn how to create your own client-body filters.
+   </para>
+   <para>
+    The distribution <filename>default.filter</filename> file contains a selection of
+    client-body filters for example purposes.
+   </para>
+   <para>
+    The amount of data that can be filtered is limited by 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 whole
+    request body is passed through unfiltered.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Example usage (section):</term>
+  <listitem>
+     <screen>
+# Remove "test" everywhere in the request body
+{+client-body-filter{remove-test}}
+/
+</screen>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
 
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3 renderas="sect4" id="client-header-tagger">
 
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3 renderas="sect4" id="client-header-tagger">
@@ -4054,15 +4136,15 @@ problem-host.example.com</screen>
    <para>
    <quote>Rolling your own</quote>
     filters requires a knowledge of
    <para>
    <quote>Rolling your own</quote>
     filters requires a knowledge of
-     <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+     <ulink url="https://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
      Expressions</quote></ulink> and
      Expressions</quote></ulink> and
-      <ulink url="http://en.wikipedia.org/wiki/Html"><quote>HTML</quote></ulink>.
+      <ulink url="https://en.wikipedia.org/wiki/Html"><quote>HTML</quote></ulink>.
     This is very powerful feature, and potentially very intrusive.
     Filters should be used with caution, and where an equivalent
     <quote>action</quote> is not available.
    </para>
    <para>
     This is very powerful feature, and potentially very intrusive.
     Filters should be used with caution, and where an equivalent
     <quote>action</quote> is not available.
    </para>
    <para>
-    The amount of data that can be filtered is limited to the
+    The amount of data that can be filtered is limited by 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
     <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
@@ -5104,7 +5186,7 @@ new action
      More information on known user-agent strings can be found at
      <ulink url="http://www.user-agents.org/">http://www.user-agents.org/</ulink>
      and
      More information on known user-agent strings can be found at
      <ulink url="http://www.user-agents.org/">http://www.user-agents.org/</ulink>
      and
-     <ulink url="http://en.wikipedia.org/wiki/User_agent">http://en.wikipedia.org/wiki/User_agent</ulink>.
+     <ulink url="https://en.wikipedia.org/wiki/User_agent">http://en.wikipedia.org/wiki/User_agent</ulink>.
    </para>
    </listitem>
  </varlistentry>
    </para>
    </listitem>
  </varlistentry>
@@ -5112,7 +5194,7 @@ new action
  <varlistentry>
   <term>Example usage:</term>
   <listitem>
  <varlistentry>
   <term>Example usage:</term>
   <listitem>
-     <screen>+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}</screen>
+     <screen>+hide-user-agent{Mozilla/5.0 (X11; ElectroBSD i386; rv:78.0) Gecko/20100101 Firefox/78.0}</screen>
   </listitem>
  </varlistentry>
 </variablelist>
   </listitem>
  </varlistentry>
 </variablelist>
@@ -5752,6 +5834,10 @@ example.com/.*toChange=(?!bar)
 # Redirect Destination = https://www.illumos.org/issues/4974
 i[0-9][0-9][0-9][0-9]*/
 
 # Redirect Destination = https://www.illumos.org/issues/4974
 i[0-9][0-9][0-9][0-9]*/
 
+# Redirect requests for the old Tor Hidden Service of the Privoxy website to the new one
+{+redirect{s@^http://jvauzb4sb3bwlsnc.onion/@http://l3tczdiiwoo63iwxty4lhs6p7eaxop5micbn7vbliydgv63x5zrrrfyd.onion/@}}
+jvauzb4sb3bwlsnc.onion/
+
 # 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@}}
@@ -5932,6 +6018,63 @@ TAG:^image/
 </sect3>
 
 
 </sect3>
 
 
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect3 renderas="sect4" id="suppress-tag">
+<title>suppress-tag</title>
+
+<variablelist>
+ <varlistentry>
+  <term>Typical use:</term>
+  <listitem>
+   <para>
+   Suppress client or server tag.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Effect:</term>
+  <listitem>
+   <para>
+    Server or client tags to which this action applies are not added to the request,
+    thus making all actions that are specific to these request tags inactive.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Type:</term>
+  <!-- boolean, parameterized, Multi-value -->
+  <listitem>
+   <para>Multi-value.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Parameter:</term>
+  <listitem>
+   <para>
+    The result tag of a server-header or client-header tagger, as defined in one of the
+    <link linkend="filter-file">filter files</link>.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Example usage (section):</term>
+  <listitem>
+     <screen>
+# Suppress tag produced by range-requests client-header tagger for requests coming from address 10.0.0.1
+{+suppress-tag{RANGE-REQUEST}}
+TAG:^IP-ADDRESS: 10\.0\.0\.1$
+</screen>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3 renderas="sect4" id="session-cookies-only">
 <title>session-cookies-only</title>
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3 renderas="sect4" id="session-cookies-only">
 <title>session-cookies-only</title>
@@ -6824,13 +6967,15 @@ stupid-server.example.com/</screen>
 </para>
 
 <para>
 </para>
 
 <para>
- &my-app; supports three different pcrs-based filter actions:
+ &my-app; supports four 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>
- to rewrite headers that are send by the client, and
+ to rewrite headers that are send by the client,
  <literal><link linkend="server-header-filter">server-header-filter</link></literal>
  <literal><link linkend="server-header-filter">server-header-filter</link></literal>
- to rewrite headers that are send by the server.
+ to rewrite headers that are send by the server, and
+ <literal><link linkend="client-body-filter">client-body-filter</link></literal>
+ to rewrite client request body.
 </para>
 
 <para>
 </para>
 
 <para>
@@ -6889,7 +7034,8 @@ stupid-server.example.com/</screen>
  filter file is organized in sections, which are called <emphasis>filters</emphasis>
  here. Each filter consists of a heading line, that starts with one of the
  <emphasis>keywords</emphasis> <literal>FILTER:</literal>,
  filter file is organized in sections, which are called <emphasis>filters</emphasis>
  here. Each filter consists of a heading line, that starts with one of the
  <emphasis>keywords</emphasis> <literal>FILTER:</literal>,
- <literal>CLIENT-HEADER-FILTER:</literal> or <literal>SERVER-HEADER-FILTER:</literal>
+ <literal>CLIENT-HEADER-FILTER:</literal>, <literal>SERVER-HEADER-FILTER:</literal> or
+ <literal>CLIENT-BODY-FILTER:</literal>
  followed by the filter's <emphasis>name</emphasis>, and a short (one line)
  <emphasis>description</emphasis> of what it does. Below that line
  come the <emphasis>jobs</emphasis>, i.e. lines that define the actual
  followed by the filter's <emphasis>name</emphasis>, and a short (one line)
  <emphasis>description</emphasis> of what it does. Below that line
  come the <emphasis>jobs</emphasis>, i.e. lines that define the actual
@@ -6956,7 +7102,7 @@ stupid-server.example.com/</screen>
 
 <para>
  If you are new to
 
 <para>
  If you are new to
-  <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+  <ulink url="https://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
   Expressions</quote></ulink>, you might want to take a look at
  the <link linkend="regex">Appendix on regular expressions</link>, and
  see the <ulink url="http://perldoc.perl.org/perlre.html">Perl
   Expressions</quote></ulink>, you might want to take a look at
  the <link linkend="regex">Appendix on regular expressions</link>, and
  see the <ulink url="http://perldoc.perl.org/perlre.html">Perl
The official Privoxy git repository