Add a FAQ entry for tainted sockets
[privoxy.git] / doc / source / user-manual.sgml
index 4a21476..b4ad6a3 100644 (file)
@@ -13,7 +13,7 @@
 <!entity p-authors SYSTEM "p-authors.sgml">
 <!entity config SYSTEM "p-config.sgml">
 <!entity changelog SYSTEM "changelog.sgml">
-<!entity p-version "3.0.22">
+<!entity p-version "3.0.25">
 <!entity p-status "UNRELEASED">
 <!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc  -->
 <!entity % p-not-stable "INCLUDE">
@@ -36,7 +36,7 @@
                 This file belongs into
                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
 
- $Id: user-manual.sgml,v 2.188 2014/06/12 13:07:19 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.203 2016/02/26 12:27:32 fabiankeil Exp $
 
  Copyright (C) 2001-2014 Privoxy Developers http://www.privoxy.org/
  See LICENSE.
@@ -62,7 +62,7 @@
  </subscript>
 </pubdate>
 
-<pubdate>$Id: user-manual.sgml,v 2.188 2014/06/12 13:07:19 fabiankeil Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.203 2016/02/26 12:27:32 fabiankeil Exp $</pubdate>
 
 <!--
 
@@ -624,18 +624,6 @@ How to install the binary packages depends on your operating system:
   </para>
  </listitem>
 
-<!--
- Did anyone test these lately?
- fk 2007-11-10
- <listitem>
-  <para>
-   For easy access to &my-app;'s most important controls, drag the provided
-   <link linkend="bookmarklets">Bookmarklets</link> into your browser's
-   personal toolbar.
-  </para>
- </listitem>
--->
-
  <listitem>
   <para>
    Please see the section <link linkend="contact">Contacting the
@@ -1078,6 +1066,29 @@ How to install the binary packages depends on your operating system:
 </para>
 </sect2>
 
+<sect2 id="start-freebsd">
+<title>FreeBSD and ElectroBSD</title>
+<para>
+ To start <application>Privoxy</application> upon booting, add
+ "privoxy_enable='YES'" to <filename>/etc/rc.conf</filename>.
+ <application>Privoxy</application> will use
+ <filename>/usr/local/etc/privoxy/config</filename> as its main
+ configuration file.
+</para>
+<para>
+ If you installed <application>Privoxy</application> into a jail, the
+ paths above are relative to the jail root.
+</para>
+<para>
+ To start <application>Privoxy</application> manually, run:
+</para>
+<para>
+ <screen>
+ # service privoxy onestart
+</screen>
+</para>
+</sect2>
+
 <sect2 id="start-windows">
 <title>Windows</title>
 <para>
@@ -1097,15 +1108,21 @@ Click on the &my-app; Icon to start <application>Privoxy</application>. If no co
 </sect2>
 
 <sect2 id="start-unices">
-<title>Solaris, NetBSD, FreeBSD, HP-UX and others</title>
+<title>Generic instructions for Unix derivates (Solaris, NetBSD, HP-UX etc.)</title>
 <para>
 Example Unix startup command:
 </para>
 <para>
  <screen>
- # /usr/sbin/privoxy /etc/privoxy/config
+ # /usr/sbin/privoxy --user privoxy /etc/privoxy/config
 </screen>
 </para>
+<para>
+ Note that if you installed <application>Privoxy</application> through
+ a package manager, the package will probably contain a platform-specific
+ script or configuration file to start <application>Privoxy</application>
+ upon boot.
+</para>
 </sect2>
 
 <sect2 id="start-os2">
@@ -1121,32 +1138,21 @@ Example Unix startup command:
 <sect2 id="start-macosx">
 <title>Mac OS X</title>
 <para>
-  After downloading the privoxy software, unzip the downloaded file by
-  double-clicking on the zip file icon.  Then, double-click on the
-  installer package icon and follow the installation process.
-</para>
-<para>
-  The privoxy service will automatically start after a successful
-  installation.  In addition, the privoxy service will automatically
-  start every time your computer starts up.
-</para>
-<para>
-  To prevent the privoxy service from automatically starting when your
-  computer starts up, remove or rename the folder named
-  /Library/StartupItems/Privoxy.
-</para>
-<para>
-  A simple application named Privoxy Utility has been created which
-  enables administrators to easily start and stop the privoxy service.
+ The privoxy service will automatically start after a successful installation
+ (and thereafter every time your computer starts up) however you will need to
+ configure your web browser(s) to use it. To do so, configure them to use a
+ proxy for HTTP and HTTPS at the address 127.0.0.1:8118.
 </para>
 <para>
-  In addition, the Privoxy Utility presents a simple way for
-  administrators to edit the various privoxy config files.  A method
-  to uninstall the software is also available.
+ To prevent the privoxy service from automatically starting when your computer
+ starts up, remove or rename the file <literal>/Library/LaunchDaemons/org.ijbswa.privoxy.plist</literal>
+ (on OS X 10.5 and higher) or the folder named
+ <literal>/Library/StartupItems/Privoxy</literal> (on OS X 10.4 'Tiger').
 </para>
 <para>
-  An administrator username and password must be supplied in order for
-  the Privoxy Utility to perform any of the tasks.
+ To manually start or stop the privoxy service, use the scripts startPrivoxy.sh
+ and stopPrivoxy.sh supplied in /Applications/Privoxy. They must be run from an
+ administrator account, using sudo.
 </para>
 </sect2>
 
@@ -1402,7 +1408,7 @@ for details.
 
 <!--   ~~~~~       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
@@ -1458,10 +1464,7 @@ for details.
  it as a test to see whether it is <application>Privoxy</application>
  causing the problem or not. <application>Privoxy</application> continues
  to run as a proxy in this case, but all manipulation is disabled, i.e.
- <application>Privoxy</application> acts like a normal forwarding proxy. There
- is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
- that you can toggle <application>Privoxy</application> with one click from
- your browser.
+ <application>Privoxy</application> acts like a normal forwarding proxy.
 </para>
 
 <para>
@@ -1870,7 +1873,7 @@ for details.
 </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
@@ -1895,7 +1898,7 @@ for details.
 </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
@@ -2216,7 +2219,7 @@ for details.
 
 
 <!--   ~~~~~       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
@@ -2793,7 +2796,7 @@ for details.
   <term>Type:</term>
   <!-- boolean, parameterized, Multi-value -->
   <listitem>
-   <para>Parameterized.</para>
+   <para>Multi-value.</para>
   </listitem>
  </varlistentry>
 
@@ -2880,7 +2883,7 @@ for details.
   <term>Type:</term>
   <!-- boolean, parameterized, Multi-value -->
   <listitem>
-   <para>Parameterized.</para>
+   <para>Multi-value.</para>
   </listitem>
  </varlistentry>
 
@@ -3631,7 +3634,7 @@ problem-host.example.com</screen>
   <term>Type:</term>
   <!-- boolean, parameterized, Multi-value -->
   <listitem>
-   <para>Parameterized.</para>
+   <para>Multi-value.</para>
   </listitem>
  </varlistentry>
 
@@ -3843,7 +3846,7 @@ problem-host.example.com</screen>
   <term>Type:</term>
   <!-- boolean, parameterized, Multi-value -->
   <listitem>
-   <para>Parameterized.</para>
+   <para>Multi-value.</para>
   </listitem>
  </varlistentry>
 
@@ -4160,7 +4163,7 @@ new action
   <term>Type:</term>
   <!-- Boolean, Parameterized, Multi-value -->
   <listitem>
-   <para>Multi-value.</para>
+   <para>Parameterized.</para>
   </listitem>
  </varlistentry>
 
@@ -4193,6 +4196,32 @@ new action
       for socks5 connections (with remote DNS resolution).
      </para>
     </listitem>
+    <listitem>
+     <para>
+      <quote>forward-webserver 127.0.0.1:80</quote> to use the HTTP
+      server listening at 127.0.0.1 port 80 without adjusting the
+      request headers.
+     </para>
+     <para>
+      This makes it more convenient to use Privoxy to make
+      existing websites available as onion services as well.
+     </para>
+     <para>
+      Many websites serve content with hardcoded URLs and
+      can't be easily adjusted to change the domain based
+      on the one used by the client.
+     </para>
+     <para>
+      Putting Privoxy between Tor and the webserver (or an stunnel
+      that forwards to the webserver) allows to rewrite headers and
+      content to make client and server happy at the same time.
+     </para>
+     <para>
+      Using Privoxy for webservers that are only reachable through
+      onion addresses and whose location is supposed to be secret
+      is not recommended and should not be necessary anyway.
+     </para>
+    </listitem>
    </itemizedlist>
   </listitem>
  </varlistentry>
@@ -4215,7 +4244,8 @@ new action
     <para>
      If the ports are missing or invalid, default values will be used. This might change
      in the future and you shouldn't rely on it. Otherwise incorrect syntax causes Privoxy
-     to exit.
+     to exit. Due to design limitations, invalid parameter syntax isn't detected until the
+     action is used the first time.
     </para>
     <para>
      Use the <ulink url="http://config.privoxy.org/show-url-info">show-url-info CGI page</ulink>
@@ -4230,15 +4260,17 @@ new action
   <listitem>
    <para>
      <screen>
-# Always use direct connections for requests previously tagged as
+# Use an ssh tunnel for requests previously tagged as
 # <quote>User-Agent: fetch libfetch/2.0</quote> and make sure
 # resuming downloads continues to work.
+#
 # This way you can continue to use Tor for your normal browsing,
 # without overloading the Tor network with your FreeBSD ports updates
 # or downloads of bigger files like ISOs.
+#
 # Note that HTTP headers are easy to fake and therefore their
 # values are as (un)trustworthy as your clients and users.
-{+forward-override{forward .} \
+{+forward-override{forward-socks5 10.0.0.2:2222 .} \
  -hide-if-modified-since      \
  -overwrite-last-modified     \
 }
@@ -5368,9 +5400,15 @@ new action
     <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>
@@ -5420,6 +5458,12 @@ search.msn.com//results\.aspx\?q=
 {+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@}}
@@ -5460,7 +5504,7 @@ www.privoxy.org/user-manual/</screen>
   <term>Type:</term>
   <!-- boolean, parameterized, Multi-value -->
   <listitem>
-   <para>Parameterized.</para>
+   <para>Multi-value.</para>
   </listitem>
  </varlistentry>
 
@@ -5543,7 +5587,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not
   <term>Type:</term>
   <!-- boolean, parameterized, Multi-value -->
   <listitem>
-   <para>Parameterized.</para>
+   <para>Multi-value.</para>
   </listitem>
  </varlistentry>
 
@@ -5814,7 +5858,7 @@ TAG:^image/
 
 
 <!--   ~~~~~       New section      ~~~~~     -->
-<sect3>
+<sect3 id="summary">
 <title>Summary</title>
 <para>
  Note that many of these actions have the potential to cause a page to
@@ -5957,7 +6001,7 @@ hal stop here
  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>,
@@ -6000,7 +6044,7 @@ hal stop here
 </para>
 </sect3>
 
-<sect3>
+<sect3 id="default-action">
 <title>default.action</title>
 
 <para>
@@ -6289,7 +6333,7 @@ wiki.
 
 </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,
@@ -6703,7 +6747,7 @@ stupid-server.example.com/</screen>
 
 <!--   ~~~~~~~~       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
@@ -7873,7 +7917,7 @@ Requests</title>
 
 
 <!--   ~~~~~       New section      ~~~~~     -->
-<sect2>
+<sect2 id="internal-pages">
 <title>Privoxy's Internal Pages</title>
 
 <para>
@@ -7990,84 +8034,6 @@ Requests</title>
  </itemizedlist>
 </para>
 
-<para>
- These may be bookmarked for quick reference. See next.
-
-</para>
-
-<sect3 id="bookmarklets">
-<title>Bookmarklets</title>
-<para>
- Below are some <quote>bookmarklets</quote> to allow you to easily access a
- <quote>mini</quote> version of some of <application>Privoxy's</application>
- special pages. They are designed for MS Internet Explorer, but should work
- equally well in Netscape, Mozilla, and other browsers which support
- JavaScript. They are designed to run directly from your bookmarks - not by
- clicking the links below (although that should work for testing).
-</para>
-<para>
- To save them, right-click the link and choose <quote>Add to Favorites</quote>
- (IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
- the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
- Bookmarklet directly from your favorites/bookmarks. For even faster access,
- you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
- Toolbar</quote> (Netscape), and run them with a single click.
-</para>
-
-<para>
- <itemizedlist>
-
-  <listitem>
-   <para>
-    <ulink
-    url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&#38;set=enabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Enable</ulink>
-   </para>
-  </listitem>
-
-  <listitem>
-   <para>
-    <ulink
-    url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&#38;set=disabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Disable</ulink>
-   </para>
-  </listitem>
-
-  <listitem>
-   <para>
-    <ulink
-    url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&#38;set=toggle','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Toggle Privoxy</ulink> (Toggles between enabled and disabled)
-   </para>
-  </listitem>
-
-  <listitem>
-   <para>
-    <ulink
-    url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y','ijbstatus','width=250,height=2,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy- View Status</ulink>
-   </para>
-  </listitem>
-<!--
-  <listitem>
-   <para>
-    <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions/index.php?url='+escape(location.href),'Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Submit Actions File Feedback</ulink>
-   </para>
-  </listitem>
- -->
-  <listitem>
-   <para>
-    <ulink url="javascript:void(window.open('http://config.privoxy.org/show-url-info?url='+escape(location.href),'Why').focus());">Privoxy - Why?</ulink>
-   </para>
-  </listitem>
- </itemizedlist>
-</para>
-
-<para>
- Credit: The site which gave us the general idea for these bookmarklets is
- <ulink url="http://www.bookmarklets.com/">www.bookmarklets.com</ulink>. They
- have more information about bookmarklets.
-</para>
-
-
-</sect3>
-
 </sect2>
 
 
@@ -8219,8 +8185,7 @@ Requests</title>
 <para>
  One quick test to see if <application>Privoxy</application> is causing a problem
  or not, is to disable it temporarily. This should be the first troubleshooting
- step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick
- and easy way to do this (be sure to flush caches afterward!). Looking at the
+ step (be sure to flush caches afterward!). Looking at the
  logs is a good idea too. (Note that both the toggle feature and logging are
  enabled via <filename>config</filename> file settings, and may need to be
  turned <quote>on</quote>.)