<!entity license SYSTEM "license.sgml">
<!entity p-authors SYSTEM "p-authors.sgml">
<!entity config SYSTEM "p-config.sgml">
-<!entity p-version "3.0.7">
+<!entity p-version "3.0.8">
<!entity p-status "stable">
<!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc -->
<!entity % p-not-stable "IGNORE">
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.36 2007/08/26 16:47:14 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.57 2008/02/03 19:10:14 fabiankeil Exp $
- Copyright (C) 2001-2007 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2008 Privoxy Developers http://www.privoxy.org/
See LICENSE.
========================================================================
<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 - 2007 by
+ <link linkend="copyright">Copyright</link> &my-copy; 2001 - 2008 by
<ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
</subscript>
</pubdate>
-<pubdate>$Id: user-manual.sgml,v 2.36 2007/08/26 16:47:14 fabiankeil Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.57 2008/02/03 19:10:14 fabiankeil Exp $</pubdate>
<!--
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-deb"><title>Debian</title>
+<sect3 id="installation-deb"><title>Debian and Ubuntu</title>
<para>
DEBs can be installed with <literal>apt-get install privoxy</literal>,
and will use <filename>/etc/privoxy</filename> for the location of
in the same directory as you installed <application>Privoxy</application> in.
</para>
<para>
- Version 3.0.
4 introduced full <application>Windows</application> service
+ Version 3.0.
5 beta introduced full <application>Windows</application> service
functionality. On Windows only, the <application>Privoxy</application>
program has two new command line arguments to install and uninstall
<application>Privoxy</application> as a <emphasis>service</emphasis>.
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, HP-UX</title>
+<sect3 id="installation-pack-bintgz"><title>Solaris <!--, NetBSD, HP-UX--></title>
<para>
Create a new directory, <literal>cd</literal> to it, then unzip and
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-mac"><title>Mac OSX</title>
+<sect3 id="installation-mac"><title>Mac OS X</title>
<para>
Unzip the downloaded file (you can either double-click on the file
from the finder, or from the desktop if you downloaded it there).
<para>
The port skeleton and the package can also be downloaded from the
<ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">File Release
- Page</ulink>, but if you're interested in stable releases only you don't
- gain anything by using them.
+ Page</ulink>, but there's no reason to use them unless you're interested in the
+ beta releases which are only available there.
</para>
</sect3>
<itemizedlist>
<listitem>
<para>
- Header filtering can be done with dedicated header filters now. As a result
+ Two new actions <link
+ linkend="server-header-tagger">server-header-tagger</link>
+ and <link
+ linkend="client-header-tagger">client-header-tagger</link>
+ that can be used to create arbitrary <quote>tags</quote>
+ based on client and server headers.
+ These <quote>tags</quote> can then subsequently be used
+ to control the other actions used for the current request,
+ greatly increasing &my-app;'s flexibility and selectivity. See <link
+ linkend="tag-pattern">tag patterns</link> for more information on tags.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Header filtering is done with dedicated header filters now. As a result
the actions <quote>filter-client-headers</quote> and <quote>filter-server-headers</quote>
that were introduced with <application>Privoxy 3.0.5</application> to apply
- the content filters to the headers as, well have been removed again.
+ content filters to the headers have been removed.
+ See the new actions <link
+ linkend="server-header-filter">server-header-filter</link>
+ and <link
+ linkend="client-header-filter">client-header-filter</link> for details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ There are four new options for the main <filename>config</filename> file:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <link
+ linkend="allow-cgi-request-crunching">allow-cgi-request-crunching</link>
+ which allows requests for Privoxy's internal CGI pages to be
+ blocked, redirected or (un)trusted like ordinary requests.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link
+ linkend="split-large-forms">split-large-forms</link>
+ that will work around a browser bug that caused IE6 and IE7 to
+ ignore the Submit button on the Privoxy's edit-actions-for-url CGI
+ page.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link
+ linkend="accept-intercepted-requests">accept-intercepted-requests</link>
+ which allows to combine Privoxy with any packet filter to create an
+ intercepting proxy for HTTP/1.1 requests (and for HTTP/1.0 requests
+ with Host header set). This means clients can be forced to use
+ &my-app; even if their proxy settings are configured differently.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link
+ linkend="templdir">templdir</link>
+ to designate an alternate location for &my-app;'s
+ locally customized CGI templates so that
+ these are not overwritten during upgrades.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ A new command line option <literal>--pre-chroot-nslookup hostname</literal> to
+ initialize the resolver library before chroot'ing. On some systems this
+ reduces the number of files that must be copied into the chroot tree.
+ (Patch provided by Stephen Gildea)
</para>
</listitem>
-<!-- pre-3.0.6 changes:
- <listitem>
- <para>
- There are a number of new <link linkend="actions-file">actions</link>:
+ <listitem>
+ <para>
+ The <link
+ linkend="forward-override">forward-override</link> action
+ allows changing of the forwarding settings through the actions files.
+ Combined with tags, this allows to choose the forwarder based on
+ client headers like the <literal>User-Agent</literal>, or the request origin.
</para>
-
- <para>
- <itemizedlist>
-
- <listitem>
- <para>
- <literal><link linkend="content-type-overwrite">content-type-overwrite</link></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><link linkend="crunch-client-header">crunch-client-header</link></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><link linkend="crunch-server-header">crunch-server-header</link></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><link linkend="filter-client-headers">filter-client-headers</link></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><link linkend="filter-server-headers">filter-server-headers</link></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><link linkend="force-text-mode">force-text-mode</link></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><link linkend="handle-as-empty-document">handle-as-empty-document</link></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><link linkend="hide-accept-language">hide-accept-language</link></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><link linkend="hide-content-disposition">hide-content-disposition</link></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><link linkend="inspect-jpegs">inspect-jpegs</link></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><link linkend="redirect">redirect</link></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><link linkend="treat-forbidden-connects-like-blocks">treat-forbidden-connects-like-blocks</link></literal>
- </para>
- </listitem>
+ </listitem>
- </itemizedlist>
- </para>
- <para>
- In addition, <literal><link linkend="fast-redirects">fast-redirects</link></literal>
- has been significantly improved with enhanced syntax.
- </para>
+ <listitem>
<para>
- And <literal><link linkend="hide-referrer">hide-referrer</link></literal>
- has a new option, <literal>conditional block</literal>.
+ The <link
+ linkend="redirect">redirect</link> action can now use regular
+ expression substitutions against the original URL.
</para>
-
- </listitem>
+ </listitem>
<listitem>
<para>
- <application>MS-Windows</application> versions can now be
- <link
- linkend="installation-pack-win">installed and
- started as a <emphasis>Windows service</emphasis></link>.
+ <application>zlib</application> support is now available as a compile
+ time option to filter compressed content. Patch provided by Wil Mahan.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Improve various filters, and add new ones.
</para>
</listitem>
+
<listitem>
<para>
- <filename>config</filename> has two new options:
- <link
- linkend="enable-remote-http-toggle">enable-remote-http-toggle</link>,
- and <link
- linkend="forwarded-connect-retries">forwarded-connect-retries</link>.
- </para>
- <para>
- And there is improved handling of the <link
- linkend="user-manual">user-manual</link>
- option, for placing documentation and help files on the local system.
+ Include support for RFC 3253 so that <filename>Subversion</filename> works
+ with &my-app;. Patch provided by Petr Kadlec.
</para>
</listitem>
-
+
<listitem>
<para>
- There are six new <link linkend="FILTER">filters</link>.
+ Logging can be completely turned off by not specifying a logfile directive.
</para>
</listitem>
+
<listitem>
<para>
- Actions files problems and suggestions are now being directed to:
- <ulink url="http://sourceforge.net/tracker/?group_id=11118&atid=460288">http://sourceforge.net/tracker/?group_id=11118&atid=460288</ulink>.
- Please use this to report such configuration related problems as missed
- ads, sites that don't function properly due to one action or another,
- innocent images being blocked, etc.
+ A number of improvements to Privoxy's internal CGI pages, including the
+ use of favicons for error and control pages.
</para>
</listitem>
-
+
<listitem>
<para>
- In addition, there are numerous bug fixes and significant enhancements,
- including error pages should no longer be cached if the problem is fixed,
- much better DNS error handling, various logging improvements, and
- configuration updates for better ad blocking and junk elimination.
+ Many bugfixes, memory leaks addressed, code improvements, and logging
+ improvements.
</para>
</listitem>
--->
</itemizedlist>
</para>
+<para>
+ For a more detailed list of changes please have a look at the ChangeLog.
+</para>
<!-- ~~~~~ New section ~~~~~ -->
<para>
<itemizedlist>
+ <listitem>
+ <para>
+ The recommended way to upgrade &my-app; is to backup your old
+ configuration files, install the new ones, verify that &my-app;
+ is working correctly and finally merge back your changes using
+ <application>diff</application> and maybe <application>patch</application>.
+ </para>
+ <para>
+ There are a number of new features in each &my-app; release and
+ most of them have to be explicitly enabled in the configuration
+ files. Old configuration files obviously don't do that and due
+ to syntax changes using old configuration files with a new
+ &my-app; isn't always possible anyway.
+ </para>
+ </listitem>
<listitem>
<para>
- Some installers may remove earlier versions completely, including
- configuration files. Save any important configuration files!
+ Note that some installers remove earlier versions completely,
+ including configuration files, therefore you should really save
+ any important configuration files!
</para>
</listitem>
<listitem>
<para>
- On the other hand, other installers may not overwrite any existing configuration
- files, thinking you will want to do that. You may want to manually check
- your saved files against the newer versions to see if the improvements have
- merit, or whether there are new options that you may want to consider.
- There are a number of new features, but most won't be available unless
- these features are incorporated into your configuration somehow.
+ On the other hand, other installers don't overwrite existing configuration
+ files, thinking you will want to do that yourself.
</para>
</listitem>
<listitem>
- <para>
- See the full documentation on
- <literal><link linkend="fast-redirects">fast-redirects</link></literal>
- which has changed syntax, and will require adjustments to local configs,
- such as <filename>user.action</filename>. You must reference the new
- syntax:
- </para>
- <para>
- <screen>
- { +fast-redirects{check-decoded-url} }
- .example.com
- mybank.com
- .google.</screen>
-</para>
+ <para>
+ <filename>standard.action</filename> now only includes the enabled actions.
+ Not all actions as before.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In the default configuration only fatal errors are logged now.
+ You can change that in the <link linkend="DEBUG">debug section</link>
+ of the configuration file. You may also want to enable more verbose
+ logging until you verified that the new &my-app; version is working
+ as expected.
+ </para>
+ </listitem>
- </listitem>
<listitem>
<para>
- The <filename>jarfile</filename>,
- <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookie</ulink> logger, is off by default now.
+ Three other config file settings are now off by default:
+ <link linkend="enable-remote-toggle">enable-remote-toggle</link>,
+ <link linkend="enable-remote-http-toggle">enable-remote-http-toggle</link>,
+ and <link linkend="enable-edit-actions">enable-edit-actions</link>.
+ If you use or want these, you will need to explicitly enable them, and
+ be aware of the security issues involved.
</para>
</listitem>
+ <listitem>
+ <para>
+ The <quote>filter-client-headers</quote> and
+ <quote>filter-server-headers</quote> actions that were introduced with
+ <application>Privoxy 3.0.5</application> to apply content filters to
+ the headers have been removed and replaced with new actions.
+ See the <link
+ linkend="whatsnew">What's New section</link> above.
+ </para>
+ </listitem>
+
+
+<!--
<listitem>
<para>
What constitutes a <quote>default</quote> configuration has changed,
settings as yet (see above).
</para>
</listitem>
-
+-->
+<!--
<listitem>
<para>
The default actions setting is now <literal>Cautious</literal>. Previous
<listitem>
<para>
-<!-- I think it is best to keep this somewhat vague, in case -->
-<!-- the situation changes under our feet. -->
Some installers may not automatically start
<application>Privoxy</application> after installation.
</para>
</listitem>
-
+-->
</itemizedlist>
</para>
+
</sect2>
</sect1>
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
- any protocols besides HTTP and HTTPS (SSL)! It won't work!
+ any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
+ browser from using these protocols.
</para>
</listitem>
A default installation should provide a reasonable starting point for
most. There will undoubtedly be occasions where you will want to adjust the
configuration, but that can be dealt with as the need arises. Little
- to no initial configuration is required in most cases.
+ to no initial configuration is required in most cases, you may want
+ to enable the
+ <ulink url="config.html#ENABLE-EDIT-ACTIONS">web-based action editor</ulink> though.
+ Be sure to read the warnings first.
</para>
<para>
See the <link linkend="configuration">Configuration section</link> for more
</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
personal toolbar.
</para>
</listitem>
+-->
<listitem>
<para>
Now enjoy surfing with enhanced control, comfort and privacy!
</para>
</listitem>
-
+
</itemizedlist>
</para>
Secondly, a brief explanation of <application>Privoxy's </application>
<quote>actions</quote>. <quote>Actions</quote> in this context, are
the directives we use to tell <application>Privoxy</application> to perform
- some task relating to WWW transactions (i.e. web browsing). We tell
+ some task relating to HTTP transactions (i.e. web browsing). We tell
<application>Privoxy</application> to take some <quote>action</quote>. Each
action has a unique name and function. While there are many potential
<application>actions</application> in <application>Privoxy's</application>
</itemizedlist>
</para>
+<para>
+ Advanced users will eventually want to explore &my-app;
+ <literal><link linkend="filter">filters</link></literal> as well. Filters
+ are very different from <literal><link
+ linkend="block">blocks</link></literal>.
+ A <quote>block</quote> blocks a site, page, or unwanted contented. Filters
+ are a way of filtering or modifying what is actually on the page. An example
+ filter usage: a text replacement of <quote>no-no</quote> for
+ <quote>nasty-word</quote>. That is a very simple example. This process can be
+ used for ad blocking, but it is more in the realm of advanced usage and has
+ some pitfalls to be wary off.
+</para>
+
<para>
The quickest way to adjust any of these settings is with your browser through
the special <application>Privoxy</application> editor at <ulink
url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
(shortcut: <ulink url="http://p.p/">http://p.p/show-status</ulink>). This
- is an internal page, and does not require Internet access. Select the
- appropriate <quote>actions</quote> file, and click
+ is an internal page, and does not require Internet access.
+</para>
+
+<para>
+ Note that as of <application>Privoxy</application> 3.0.7 beta the
+ action editor is disabled by default. Check the
+ <ulink url="config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions
+ section in the configuration file</ulink> to learn why and in which
+ cases it's safe to enable again.
+</para>
+
+<para>
+ If you decided to enable the action editor, select the appropriate
+ <quote>actions</quote> file, and click
<quote><guibutton>Edit</guibutton></quote>. It is best to put personal or
local preferences in <filename>user.action</filename> since this is not
meant to be overwritten during upgrades, and will over-ride the settings in
</para>
<literallayout>
- <guibutton>Tools</guibutton> -> <guibutton>Options</guibutton> -> <guibutton>General</guibutton> -> <guibutton>Connection Settings</guibutton> -> <guibutton>Manual Proxy Configuration</guibutton>
+ <guibutton>Tools</guibutton> -> <guibutton>Options</guibutton> -> <guibutton>Advanced</guibutton> -> <guibutton>Network</guibutton> -><guibutton>Connection</guibutton> -> <guibutton>Settings</guibutton>
</literallayout>
</literallayout>
<para>
- For <application>Internet Explorer v.5-6</application>:
+ For <application>Internet Explorer v.5-7</application>:
</para>
<literallayout>
</para>
</sect2>
-<!--
- omitting 10/31/06 HB
-
-<sect2 id="start-suse">
-<title>SuSE</title>
-<para>
-We use a script. It will use the file <filename>/etc/privoxy/config</filename>
-as its main configuration file. Note that SuSE starts Privoxy upon booting
-your PC.
-</para>
-<para>
- <screen>
- # rcprivoxy start
-</screen>
-</para>
-</sect2>
--->
<sect2 id="start-windows">
<title>Windows</title>
<para>
</sect2>
<sect2 id="start-macosx">
-<title>Mac OSX</title>
+<title>Mac OS X</title>
<para>
During installation, <application>Privoxy</application> is configured to
start automatically when the system restarts. To start &my-app; manually,
your browser.
</para>
+<para>
+ Note that several of the features described above are disabled by default
+ in <application>Privoxy</application> 3.0.7 beta and later.
+ Check the
+ <ulink url="config.html">configuration file</ulink> to learn why
+ and in which cases it's safe to enable them again.
+</para>
+
</sect2>
<!-- ~ End section ~ -->
The easiest way to edit the actions files is with a browser by
using our browser-based editor, which can be reached from <ulink
url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
- The editor allows both fine-grained control over every single feature on a
- per-URL basis, and easy choosing from wholesale sets of defaults like
- <quote>Cautious</quote>, <quote>Medium</quote> or <quote>Advanced</quote>.
- Warning: the <quote>Advanced</quote> setting is more aggressive, and
- will be more likely to cause problems for some sites. Experienced users only!
-</para>
+ Note: the config file option <link
+ linkend="enable-edit-actions">enable-edit-actions</link> must be enabled for
+ this to work. The editor allows both fine-grained control over every single
+ feature on a per-URL basis, and easy choosing from wholesale sets of defaults
+ like <quote>Cautious</quote>, <quote>Medium</quote> or
+ <quote>Advanced</quote>. Warning: the <quote>Advanced</quote> setting is more
+ aggressive, and will be more likely to cause problems for some sites.
+ Experienced users only!
+ </para>
<para>
If you prefer plain text editing to GUIs, you can of course also directly edit the
<term><literal>.example.com</literal></term>
<listitem>
<para>
- matches any domain that <emphasis>ENDS</emphasis> in
- <literal>.example.com</literal>
+ matches any domain with first-level domain <literal>com</literal>
+ and second-level domain <literal>example</literal>.
+ For example <literal>www.example.com</literal>,
+ <literal>example.com</literal> and <literal>foo.bar.baz.example.com</literal>.
+ Note that it wouldn't match if the second-level domain was <literal>another-example</literal>.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
matches any domain that <emphasis>STARTS</emphasis> with
- <literal>www.</literal>
+ <literal>www.</literal> (It also matches the domain
+ <literal>www</literal> but most of the time that doesn't matter.)
</para>
</listitem>
</varlistentry>
can tell them apart from URL 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 (Privoxy doesn't silently add a <quote>^</quote>,
+ automatically (&my-app; doesn't silently add a <quote>^</quote>,
you have to do it yourself if you need it).
</para>
</para>
<para>
- For example you could tag client requests which use the POST method,
- use this tag to activate another tagger that adds a tag if cookies
- are send, and then block based on the cookie tag. However if you'd
- reverse the position of the described taggers, and activated the method
- tagger based on the cookie tagger, no method tags would be created.
+ For example you could tag client requests which use the
+ <literal>POST</literal> method,
+ then use this tag to activate another tagger that adds a tag if cookies
+ are sent, and then use a block action based on the cookie tag. This allows
+ the outcome of one action, to be input into a subsequent action. However if
+ you'd reverse the position of the described taggers, and activated the
+ method tagger based on the cookie tagger, no method tags would be created.
The method tagger would look for the request line, but at the time
- the cookie tag is created the request line has already been parsed.
+ the cookie tag is created, the request line has already been parsed.
</para>
<para>
Client-header filters are executed after the other header actions have finished
and use their output as input.
</para>
+ <para>
+ If the request URL gets changed, &my-app; will detect that and use the new
+ 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>
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
<listitem>
<para>
<screen>
+# Hide Tor exit notation in Host and Referer Headers
{+client-header-filter{hide-tor-exit-notation}}
-.exit/
+/
</screen>
</para>
</listitem>
<para>
<screen>
# Tag every request with the User-Agent header
-{+client-header-filter{user-agent}}
+{+client-header-tagger{user-agent}}
/
</screen>
</para>
<para>
<quote>forward-socks4a 127.0.0.1:9050 .</quote> to use the socks4a proxy listening at
127.0.0.1 port 9050. Replace <quote>forward-socks4a</quote> with <quote>forward-socks4</quote>
- to use a socks4 connection (with local DNS resolution) instead.
+ to use a socks4 connection (with local DNS resolution) instead, use <quote>forward-socks5</quote>
+ for socks5 connections (with remote DNS resolution).
</para>
</listitem>
<listitem>
<quote>forward-socks4a 127.0.0.1:9050 proxy.example.org:8000</quote> to use the socks4a proxy
listening at 127.0.0.1 port 9050 to reach the HTTP proxy listening at proxy.example.org port 8000.
Replace <quote>forward-socks4a</quote> with <quote>forward-socks4</quote> to use a socks4 connection
- (with local DNS resolution) instead.
+ (with local DNS resolution) instead, use <quote>forward-socks5</quote>
+ for socks5 connections (with remote DNS resolution).
</para>
</listitem>
</itemizedlist>
<term>Notes:</term>
<listitem>
<para>
- This action takes parameters similar to the <!-- I hope this link actual works -->
+ This action takes parameters similar to the
<link linkend="forwarding">forward</link> directives in the configuration
file, but without the URL pattern. It can be used as replacement, but normally it's only
used in cases where matching based on the request URL isn't sufficient.
# 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 .} \
-hide-if-modified-since \
-overwrite-last-modified \
</para>
<para>
Randomizing the value of the <quote>If-Modified-Since:</quote> makes
- sure it isn't used as a cookie replacement, but you will run into
- caching problems if the random range is too high.
+ it less likely that the server can use the time as a cookie replacement,
+ but you will run into caching problems if the random range is too high.
</para>
<para>
It is a good idea to only use a small negative value and let
</para>
<para>
It is also recommended to use this action together with
- <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>.
+ <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>,
+ otherwise it's more or less pointless.
</para>
</listitem>
</varlistentry>
<term>Example usage (section):</term>
<listitem>
<para>
- <screen># Let the browser revalidate without being tracked across sessions
-{ +hide-if-modified-since{-60} \
+ <screen># Let the browser revalidate but make tracking based on the time less likely.
+{+hide-if-modified-since{-60} \
+overwrite-last-modified{randomize} \
+crunch-if-none-match}
/</screen>
<varlistentry>
<term>Typical use:</term>
<listitem>
- <para>Improve privacy by not embedding the source of the request in the HTTP headers.</para>
+ <para>Improve privacy by not forwarding the source of the request in the HTTP headers.</para>
</listitem>
</varlistentry>
<term>Effect:</term>
<listitem>
<para>
- Deletes any existing <quote>X-Forwarded-for:</quote> HTTP header from client requests,
- and prevents adding a new one.
+ Deletes any existing <quote>X-Forwarded-for:</quote> HTTP header from client requests.
</para>
</listitem>
</varlistentry>
<term>Notes:</term>
<listitem>
<para>
- It is safe to leave this on.
+ It is safe and recommended to leave this on.
</para>
</listitem>
</varlistentry>
<listitem>
<para><quote>conditional-block</quote> to delete the header completely if the host has changed.</para>
</listitem>
-<!--
<listitem>
<para><quote>conditional-forge</quote> to forge the header if the host has changed.</para>
</listitem>
--->
<listitem>
<para><quote>block</quote> to delete the header unconditionally.</para>
</listitem>
<para>
Always blocking the referrer, or using a custom one, can lead to
failures on servers that check the referrer before they answer any
- requests, in an attempt to prevent their valuable content from being
+ requests, in an attempt to prevent their content from being
embedded or linked to elsewhere.
</para>
<para>
<varlistentry>
<term>Typical use:</term>
<listitem>
- <para>Conceal your type of browser and client operating system</para>
+ <para>Try to conceal your type of browser and client operating system</para>
</listitem>
</varlistentry>
order to customize their content for different browsers (which, by the
way, is <emphasis>NOT</emphasis> the right thing to do: good web sites
work browser-independently).
- <!--
- <ulink url="http://www.javascriptkit.com/javaindex.shtml">smart way to do
- that</ulink>!).
- -->
</para>
</warning>
<para>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="inspect-jpegs">
<title>inspect-jpegs</title>
-<!--
-new action
--->
<variablelist>
<varlistentry>
<term>Typical use:</term>
<listitem>
- <para>To protect against the MS buffer over-run in JPEG processing</para>
+ <para>Try to protect against a MS buffer over-run in JPEG processing</para>
</listitem>
</varlistentry>
allow execution of code on the target system, giving an attacker access
to the system in question by merely planting an altered JPEG image, which
would have no obvious indications of what lurks inside. This action
- prevents this exploit.
+ tries to prevent this exploit if delivered through unencrypted HTTP.
</para>
<para>
- Note that the described exploit is only one of many,
- using this action does not mean that you no longer
- have to patch the client.
+ Note that the exploit mentioned is several years old
+ and it's unlikely that your client is still vulnerable
+ against it. This action may be removed in one of the
+ next releases.
</para>
</listitem>
This action is most appropriate for browsers that don't have any controls
for unwanted pop-ups. Not recommended for general usage.
</para>
-
- <!--
<para>
- An alternate spelling is <literal>+kill-popup</literal>, which is
- interchangeable.
+ This action doesn't work very reliable and may be removed in future releases.
</para>
- -->
</listitem>
</varlistentry>
(<quote>https://</quote> URLs) through proxies. It works very simply:
the proxy connects to the server on the specified port, and then
short-circuits its connections to the client and to the remote server.
- This can be a big security hole, since CONNECT-enabled proxies can be
- abused as TCP relays very easily.
+ This means CONNECT-enabled proxies can be used as TCP relays very easily.
</para>
<para>
<application>Privoxy</application> relays HTTPS traffic without seeing
<term>Typical use:</term>
<listitem>
<para>
- Disable or disable filters based on the Content-Type header.
+ Enable or disable filters based on the Content-Type header.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
<screen>
-# Tag every request with the declared content type
-{+client-header-filter{content-type}}
+# Tag every request with the content type declared by the server
+{+server-header-tagger{content-type}}
/
</screen>
</para>
<para>
Again, at the start of matching, all actions are disabled, so there is
- no real need to disable any actions here, but we will do that nonetheless,
- to have a complete listing for your reference. (Remember: a <quote>+</quote>
+ no need to disable any actions here. (Remember: a <quote>+</quote>
preceding the action name enables the action, a <quote>-</quote> disables!).
Also note how this long line has been made more readable by splitting it into
multiple lines with line continuation.
# "Defaults" section:
##########################################################################
{ \
- -<link linkend="ADD-HEADER">add-header</link> \
- -<link linkend="CLIENT-HEADER-FILTER">client-header-filter{hide-tor-exit-notation}</link> \
- -<link linkend="BLOCK">block</link> \
- -<link linkend="CONTENT-TYPE-OVERWRITE">content-type-overwrite</link> \
- -<link linkend="CRUNCH-CLIENT-HEADER">crunch-client-header</link> \
- -<link linkend="CRUNCH-IF-NONE-MATCH">crunch-if-none-match</link> \
- -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> \
- -<link linkend="CRUNCH-SERVER-HEADER">crunch-server-header</link> \
- -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link> \
+<link linkend="DEANIMATE-GIFS">deanimate-gifs</link> \
- -<link linkend="DOWNGRADE-HTTP-VERSION">downgrade-http-version</link> \
- -<link linkend="FAST-REDIRECTS">fast-redirects{check-decoded-url}</link> \
- -<link linkend="FILTER-JS-ANNOYANCES">filter{js-annoyances}</link> \
- -<link linkend="FILTER-JS-EVENTS">filter{js-events}</link> \
+<link linkend="FILTER-HTML-ANNOYANCES">filter{html-annoyances}</link> \
- -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link> \
+<link linkend="FILTER-REFRESH-TAGS">filter{refresh-tags}</link> \
- -<link linkend="FILTER-UNSOLICITED-POPUPS">filter{unsolicited-popups}</link> \
- -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link> \
- -<link linkend="FILTER-IMG-REORDER">filter{img-reorder}</link> \
- -<link linkend="FILTER-BANNERS-BY-SIZE">filter{banners-by-size}</link> \
- -<link linkend="FILTER-BANNERS-BY-LINK">filter{banners-by-link}</link> \
+<link linkend="FILTER-WEBBUGS">filter{webbugs}</link> \
- -<link linkend="FILTER-TINY-TEXTFORMS">filter{tiny-textforms}</link> \
- -<link linkend="FILTER-JUMPING-WINDOWS">filter{jumping-windows}</link> \
- -<link linkend="FILTER-FRAMESET-BORDERS">filter{frameset-borders}</link> \
- -<link linkend="FILTER-DEMORONIZER">filter{demoronizer}</link> \
- -<link linkend="FILTER-SHOCKWAVE-FLASH">filter{shockwave-flash}</link> \
- -<link linkend="FILTER-QUICKTIME-KIOSKMODE">filter{quicktime-kioskmode}</link> \
- -<link linkend="FILTER-FUN">filter{fun}</link> \
- -<link linkend="FILTER-CRUDE-PARENTAL">filter{crude-parental}</link> \
+<link linkend="FILTER-IE-EXPLOITS">filter{ie-exploits}</link> \
- -<link linkend="FILTER-GOOGLE">filter{google}</link> \
- -<link linkend="FILTER-YAHOO">filter{yahoo}</link> \
- -<link linkend="FILTER-MSN">filter{msn}</link> \
- -<link linkend="FILTER-BLOGSPOT">filter{blogspot}</link> \
- -<link linkend="FILTER-NO-PING">filter{no-ping}</link> \
- -<link linkend="FORCE-TEXT-MODE">force-text-mode</link> \
- -<link linkend="HANDLE-AS-EMPTY-DOCUMENT">handle-as-empty-document</link> \
- -<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> \
- -<link linkend="HIDE-ACCEPT-LANGUAGE">hide-accept-language</link> \
- -<link linkend="HIDE-CONTENT-DISPOSITION">hide-content-disposition</link> \
- -<link linkend="HIDE-IF-MODIFIED-SINCE">hide-if-modified-since</link> \
+<link linkend="HIDE-FORWARDED-FOR-HEADERS">hide-forwarded-for-headers</link> \
+<link linkend="HIDE-FROM-HEADER">hide-from-header{block}</link> \
+<link linkend="HIDE-REFERER">hide-referrer{forge}</link> \
- -<link linkend="HIDE-USER-AGENT">hide-user-agent</link> \
- -<link linkend="INSPECT-JPEGS">inspect-jpegs</link> \
- -<link linkend="KILL-POPUPS">kill-popups</link> \
- -<link linkend="LIMIT-CONNECT">limit-connect</link> \
+<link linkend="PREVENT-COMPRESSION">prevent-compression</link> \
- -<link linkend="OVERWRITE-LAST-MODIFIED">overwrite-last-modified</link> \
- -<link linkend="REDIRECT">redirect</link> \
- -<link linkend="SEND-VANILLA-WAFER">send-vanilla-wafer</link> \
- -<link linkend="SEND-WAFER">send-wafer</link> \
- -<link linkend="SERVER-HEADER-FILTER">server-header-filter{xml-to-html}</link> \
- -<link linkend="SERVER-HEADER-FILTER">server-header-filter{html-to-xml}</link> \
+<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> \
+<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
- -<link linkend="TREAT-FORBIDDEN-CONNECTS-LIKE-BLOCKS">treat-forbidden-connects-like-blocks</link> \
}
/ # forward slash will match *all* potential URL patterns.</screen>
</para>
<para>
- The default behavior is now set. Note that some actions, like not hiding
+ The default behavior is now set.
+ <!--
+ This needs rewording, but it can wait for now.
+ fk 2007-11-17
+
+ Note that some actions, like not hiding
the user agent, are part of a <quote>general policy</quote> that applies
universally and won't get any exceptions defined later. Other choices,
like not blocking (which is <emphasis>understandably</emphasis> the
default!) need exceptions, i.e. we need to specify explicitly what we
want to block in later sections.
+ -->
</para>
<para>
<para>
<screen>
-# My user.action file. <fred@foobar.com></screen>
+# My user.action file. <fred@example.com></screen>
</para>
<para>
<screen>
{ +<link linkend="BLOCK">block</link> }
www.example.com/nasty-ads/sponsor\.gif
- another.popular.site.net/more/junk/here/</screen>
+ another.example.net/more/junk/here/</screen>
</para>
<para>
<para>
You like the <quote>fun</quote> text replacements in <filename>default.filter</filename>,
- but it is disabled in the distributed actions file. (My colleagues on the team just
- don't have a sense of humour, that's why! ;-). So you'd like to turn it on in your private,
+ but it is disabled in the distributed actions file.
+ So you'd like to turn it on in your private,
update-safe config, once and for all:
</para>
<literal><link linkend="client-header-filter">client-header-filter</link></literal>
to rewrite headers that are send by the client, and
<literal><link linkend="server-header-filter">server-header-filter</link></literal>
- to rewrite headers that are send by the server, and
+ to rewrite headers that are send by the server.
</para>
<para>
<literal><link linkend="client-header-tagger">client-header-tagger</link></literal>
and
<literal><link linkend="server-header-tagger">server-header-tagger</link></literal>.
- Taggers and filters use the same syntax in the filter files, the differnce
+ Taggers and filters use the same syntax in the filter files, the difference
is that taggers don't modify the text they are filtering, but use a rewritten
version of the filtered text as tag. The tags can then be used to change the
applying actions through sections with <link linkend="tag-pattern">tag-patterns</link>.
<para>
Multiple filter files can be defined through the <literal> <link
linkend="filterfile">filterfile</link></literal> config directive. The filters
- as supplied by the developers will be found in
+ as supplied by the developers are located in
<filename>default.filter</filename>. It is recommended that any locally
defined or modified filters go in a separately defined file such as
<filename>user.filter</filename>.
-
-</para>
+ </para>
<para>
- Command tasks for content filters are to eliminate common annoyances in
+ Common tasks for content filters are to eliminate common annoyances in
HTML and JavaScript, such as pop-up windows,
exit consoles, crippled windows without navigation tools, the
infamous <BLINK> tag etc, to suppress images with certain
</para>
<para>
- Content filtering works on any text-based document type, including
- HTML, JavaScript, CSS etc. (all <literal>text/*</literal>
- MIME types, <emphasis>except</emphasis> <literal>text/plain</literal>).
+ Enabled content filters are applied to any content whose
+ <quote>Content Type</quote> header is recognised as a sign
+ of text-based content, with the exception of <literal>text/plain</literal>.
+ Use the <link linkend="FORCE-TEXT-MODE">force-text-mode</link> action
+ to also filter other content.
+</para>
+
+<para>
Substitutions are made at the source level, so if you want to <quote>roll
your own</quote> filters, you should first be familiar with HTML syntax,
and, of course, regular expressions.
<para>
The templates are basically normal HTML files, but with place-holders (called symbols
- or exports), which <application>Privoxy</application> fills at run time. You can
- edit the templates with a normal text editor, should you want to customize them.
- (<emphasis>Not recommended for the casual user</emphasis>). Note that
- just like in configuration files, lines starting with <literal>#</literal> are
- ignored when the templates are filled in.
+ or exports), which <application>Privoxy</application> fills at run time. It
+ is possible to edit the templates with a normal text editor, should you want
+ to customize them. (<emphasis>Not recommended for the casual
+ user</emphasis>). Should you create your own custom templates, you should use
+ the <filename>config</filename> setting <link linkend="templdir">templdir</link>
+ to specify an alternate location, so your templates do not get overwritten
+ during upgrades.
+ </para>
+ <para>
+ Note that just like in configuration files, lines starting
+ with <literal>#</literal> are ignored when the templates are filled in.
</para>
<para>
<listitem>
<para>
- Toggle Privoxy on or off. In this case, <quote>Privoxy</quote> continues
- to run, but only as a pass-through proxy, with no actions taking place:
+ Toggle Privoxy on or off. This feature can be turned off/on in the main
+ <filename>config</filename> file. When toggled <quote>off</quote>, <quote>Privoxy</quote>
+ continues to run, but only as a pass-through proxy, with no actions taking
+ place:
</para>
<blockquote>
<para>
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
- logs is a good idea too.
+ 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>.)
</para>
<para>
Another easy troubleshooting step to try is if you have done any
<para>
<screen>
- Matches for http://google.com:
+ Matches for http://www.google.com:
In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
- {-add-header
- -block
- -client-header-filter{hide-tor-exit-notation}
- -content-type-overwrite
- -crunch-client-header
- -crunch-if-none-match
- -crunch-incoming-cookies
- -crunch-outgoing-cookies
- -crunch-server-header
- +deanimate-gifs {last}
- -downgrade-http-version
+ {+deanimate-gifs {last}
+fast-redirects {check-decoded-url}
- -filter {js-events}
- -filter {content-cookies}
- -filter {all-popups}
- -filter {banners-by-link}
- -filter {tiny-textforms}
- -filter {frameset-borders}
- -filter {demoronizer}
- -filter {shockwave-flash}
- -filter {quicktime-kioskmode}
- -filter {fun}
- -filter {crude-parental}
- -filter {site-specifics}
- -filter {js-annoyances}
- -filter {html-annoyances}
+filter {refresh-tags}
- -filter {unsolicited-popups}
+filter {img-reorder}
+filter {banners-by-size}
+filter {webbugs}
+filter {jumping-windows}
+filter {ie-exploits}
- -filter {google}
- -filter {yahoo}
- -filter {msn}
- -filter {blogspot}
- -filter {no-ping}
- -force-text-mode
- -handle-as-empty-document
- -handle-as-image
- -hide-accept-language
- -hide-content-disposition
+hide-forwarded-for-headers
+hide-from-header {block}
- -hide-if-modified-since
+hide-referrer {forge}
- -hide-user-agent
- -inspect-jpegs
- -kill-popups
- -limit-connect
- -overwrite-last-modified
- +prevent-compression
- -redirect
- -send-vanilla-wafer
- -send-wafer
- -server-header-filter{xml-to-html}
- -server-header-filter{html-to-xml}
+session-cookies-only
+set-image-blocker {pattern}
- -treat-forbidden-connects-like-blocks }
/
{ -session-cookies-only }
-crunch-server-header
+deanimate-gifs {last}
-downgrade-http-version
- +fast-redirects {check-decoded-url}
+ -fast-redirects
-filter {js-events}
-filter {content-cookies}
-filter {all-popups}
-kill-popups
-limit-connect
-overwrite-last-modified
- +prevent-compression
+ -prevent-compression
-redirect
-send-vanilla-wafer
-send-wafer
<para>
<emphasis>Remember to flush caches!</emphasis> Note that the
<literal>mail.google</literal> reference lacks the TLD portion (e.g.
- <quote>.com</quote>. This will effectively match any TLD with
- <literal>google</literal> in it, such as <literal>mail.google.de</literal>,
+ <quote>.com</quote>). This will effectively match any TLD with
+ <literal>google</literal> in it, such as <literal>mail.google.de.</literal>,
just as an example.
</para>
<para>
USA
$Log: user-manual.sgml,v $
+ Revision 2.57 2008/02/03 19:10:14 fabiankeil
+ Mention forward-socks5.
+
+ Revision 2.56 2008/01/31 19:11:35 fabiankeil
+ Let the +client-header-filter{hide-tor-exit-notation} example apply
+ to all requests as "tainted" Referers aren't limited to exit TLDs.
+
+ Revision 2.55 2008/01/19 21:26:37 hal9
+ Add IE7 to configuration section per Gerry.
+
+ Revision 2.54 2008/01/19 17:52:39 hal9
+ Re-commit to fix various minor issues for new release.
+
+ Revision 2.53 2008/01/19 15:03:05 hal9
+ Doc sources tagged for 3.0.8 release.
+
+ Revision 2.52 2008/01/17 01:49:51 hal9
+ Change copyright notice for docs s/2007/2008/. All these will be rebuilt soon
+ enough.
+
+ Revision 2.51 2007/12/23 16:48:24 fabiankeil
+ Use more precise example descriptions for the mysterious domain patterns.
+
+ Revision 2.50 2007/12/08 12:44:36 fabiankeil
+ - Remove already commented out pre-3.0.7 changes.
+ - Update the "new log defaults" paragraph.
+
+ Revision 2.49 2007/12/06 18:21:55 fabiankeil
+ Update hide-forwarded-for-headers description.
+
+ Revision 2.48 2007/11/24 19:07:17 fabiankeil
+ - Mention request rewriting.
+ - Enable the conditional-forge paragraph.
+ - Minor rewordings.
+
+ Revision 2.47 2007/11/18 14:59:47 fabiankeil
+ A few "Note to Upgraders" updates.
+
+ Revision 2.46 2007/11/17 17:24:44 fabiankeil
+ - Use new action defaults.
+ - Minor fixes and rewordings.
+
+ Revision 2.45 2007/11/16 11:48:46 hal9
+ Fix one typo, and add a couple of small refinements.
+
+ Revision 2.44 2007/11/15 03:30:20 hal9
+ Results of spell check.
+
+ Revision 2.43 2007/11/14 18:45:39 fabiankeil
+ - Mention some more contributors in the "New in this Release" list.
+ - Minor rewordings.
+
+ Revision 2.42 2007/11/12 03:32:40 hal9
+ Updates for "What's New" and "Notes to Upgraders". Various other changes in
+ preparation for new release. User Manual is almost ready.
+
+ Revision 2.41 2007/11/11 16:32:11 hal9
+ This is primarily syncing What's New and Note to Upgraders sections with the many
+ new features and changes (gleaned from memory but mostly from ChangeLog).
+
+ Revision 2.40 2007/11/10 17:10:59 fabiankeil
+ In the first third of the file, mention several times that
+ the action editor is disabled by default in 3.0.7 beta and later.
+
+ Revision 2.39 2007/11/05 02:34:49 hal9
+ Various changes in preparation for the upcoming release. Much yet to be done.
+
+ Revision 2.38 2007/09/22 16:01:42 fabiankeil
+ Update embedded show-url-info output.
+
+ Revision 2.37 2007/08/27 16:09:55 fabiankeil
+ Fix pre-chroot-nslookup description which I failed to
+ copy and paste properly. Reported by Stephen Gildea.
+
Revision 2.36 2007/08/26 16:47:14 fabiankeil
- Add Stephen Gildea's --pre-chroot-nslookup patch [#1276666],
+ Add Stephen Gildea's pre-chroot-nslookup patch [#1276666],
extensive comments moved to user manual.
Revision 2.35 2007/08/26 14:59:49 fabiankeil
Spell checked (only one typo this time!).
Revision 1.123.2.16 2002/08/09 19:20:54 david__schmidt
- Update to Mac OSX startup script name
+ Update to Mac OS X startup script name
Revision 1.123.2.15 2002/08/07 17:32:11 oes
Converted some internal links from ulink to link for PDF creation; no content changed
Revision 1.123.2.9 2002/07/11 03:40:28 david__schmidt
- Updated Mac OSX sections due to installation location change
+ Updated Mac OS X sections due to installation location change
Revision 1.123.2.8 2002/06/09 16:36:32 hal9
Clarifications on filtering and MIME. Hardcode 'latest release' in index.html.
Ooops missed something from David.
Revision 1.123.2.3 2002/05/27 03:23:17 hal9
- Fix FIXMEs for OS2 and OSX startup. Fix Redhat typos (should be Red Hat).
+ Fix FIXMEs for OS2 and Mac OS X startup. Fix Redhat typos (should be Red Hat).
That's a wrap, I think.
Revision 1.123.2.2 2002/05/26 19:02:09 hal9
Add AmigaOS install stuff.
Revision 1.87 2002/04/23 02:53:15 david__schmidt
- Updated OSX installation section
+ Updated Mac OS X installation section
Added a few English tweaks here an there
Revision 1.86 2002/04/21 01:46:32 hal9
projects / privoxy.git / blobdiff