<!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.9">
<!entity p-status "UNRELEASED">
<!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc -->
<!entity % p-not-stable "INCLUDE">
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.42 2007/11/12 03:32:40 hal9 Exp $
+ $Id: user-manual.sgml,v 2.66 2008/03/06 16:33:47 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.42 2007/11/12 03:32:40 hal9 Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.66 2008/03/06 16:33:47 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
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-mac"><title>Mac OSX</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).
- Then, double-click on the package installer icon named
- <literal>Privoxy.pkg</literal>
- and follow the installation process.
- <application>Privoxy</application> will be installed in the folder
- <literal>/Library/Privoxy</literal>.
- It will start automatically whenever you start up. To prevent it from
- starting automatically, remove or rename the folder
- <literal>/Library/StartupItems/Privoxy</literal>.
-</para>
+<sect3 id="installation-mac"><title>Mac OS X</title>
<para>
- To start Privoxy by hand, double-click on
- <literal>StartPrivoxy.command</literal> in the
- <literal>/Library/Privoxy</literal> folder.
- Or, type this command in the Terminal:
+ Unzip the downloaded file (you can either double-click on the zip file
+ icon from the Finder, or from the desktop if you downloaded it there).
+ Then, double-click on the package installer icon and follow the
+ installation process.
</para>
<para>
- <screen>
- /Library/Privoxy/StartPrivoxy.command
- </screen>
+ The privoxy service will automatically start after a successful
+ installation (in addition to every time your computer starts up). To
+ prevent the privoxy service from automatically starting when your
+ computer starts up, remove or rename the folder named
+ <literal>/Library/StartupItems/Privoxy</literal>.
</para>
<para>
- You will be prompted for the administrator password.
+ To manually start or stop the privoxy service, use the Privoxy Utility
+ for Mac OS X. This application controls the privoxy service (e.g.
+ starting and stopping the service as well as uninstalling the software).
</para>
</sect3>
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 actions used for the current request,
- greatly increasing &my-app;'s flexibity and selectivity. See <link
+ 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>
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
<para>
<link
linkend="templdir">templdir</link>
- to designate an alternate location for Privoxy's own CGI templates
- to make sure any locally customized templates aren't overwritten
- during upgrades.
+ to designate an alternate location for &my-app;'s
+ locally customized CGI templates so that
+ these are not overwritten during upgrades.
</para>
</listitem>
</itemizedlist>
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 User-Agent, or the request origin.
+ client headers like the <literal>User-Agent</literal>, or the request origin.
</para>
</listitem>
<listitem>
<para>
Many bugfixes, memory leaks addressed, code improvements, and logging
- improvments.
- </para>
- </listitem>
-
-
-<!-- pre-3.0.6 changes:
- <listitem>
- <para>
- There are a number of new <link linkend="actions-file">actions</link>:
- </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>
-
- </itemizedlist>
- </para>
- <para>
- In addition, <literal><link linkend="fast-redirects">fast-redirects</link></literal>
- has been significantly improved with enhanced syntax.
- </para>
- <para>
- And <literal><link linkend="hide-referrer">hide-referrer</link></literal>
- has a new option, <literal>conditional block</literal>.
- </para>
-
- </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>.
- </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.
- </para>
- </listitem>
-
- <listitem>
- <para>
- There are six new <link linkend="FILTER">filters</link>.
- </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.
+ improvements.
</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.
- </para>
- </listitem>
--->
</itemizedlist>
</para>
<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>
Not all actions as before.
</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>
-
- </listitem>
- -->
- <listitem>
- <para>
- Logging is off by default now. If you need logging, it can be turned on
- in the <link linkend="logfile">config file</link>.
- </para>
- </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>
<para>
<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 the content filters to
- the headers as, well have been removed and replaced with new actions.
+ <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>
</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
</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>
+ 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.
+</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.
+</para>
+<para>
+ An administrator username and password must be supplied in order for
+ the Privoxy Utility to perform any of the tasks.
+</para>
<para>
During installation, <application>Privoxy</application> is configured to
start automatically when the system restarts. To start &my-app; manually,
<para>
Another feature where you will probably want to define exceptions for trusted
- sites is the popup-killing (through the <ulink
- url="actions-file.html#KILL-POPUPS"><quote>+kill-popups</quote></ulink> and
- <ulink
- url="actions-file.html#FILTER-POPUPS"><quote>+filter{popups}</quote></ulink>
- actions), because your favorite shopping, banking, or leisure site may need
+ sites is the popup-killing (through <ulink
+ url="actions-file.html#FILTER-POPUPS"><quote>+filter{popups}</quote></ulink>),
+ because your favorite shopping, banking, or leisure site may need
popups (explained below).
</para>
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>.
Note: the config file option <link
- linkend="enable-edit-actions">enale-edit-actions</link> must be enabled for
+ 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
<para>
<screen>
- { +<literal>handle-as-image</literal> +<literal>block</literal> }
+ { +<literal>handle-as-image</literal> +<literal>block{Banner ads.}</literal> }
# Block these as if they were images. Send no block page.
banners.example.com
media.example.com/.*banners
<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>
-<replaceable class="function">name</replaceable> # disable action <replaceable class="parameter">name</replaceable></screen>
</para>
<para>
- Example: <literal>+block</literal>
+ Example: <literal>+handle-as-image</literal>
</para>
</listitem>
<term>Type:</term>
<!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>Boolean.</para>
+ <para>Parameterized.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Parameter:</term>
<listitem>
- <para>N/A</para>
+ <para>A block reason that should be given to the user.</para>
</listitem>
</varlistentry>
<listitem>
<para>
<application>Privoxy</application> sends a special <quote>BLOCKED</quote> page
- for requests to blocked pages. This page contains links to find out why the request
- was blocked, and a click-through to the blocked content (the latter only if compiled with the
- force feature enabled). The <quote>BLOCKED</quote> page adapts to the available
+ for requests to blocked pages. This page contains the block reason given as
+ parameter, a link to find out why the block action applies, and a click-through
+ to the blocked content (the latter only if the force feature is available and
+ enabled).
+ </para>
+<!--
+This doesn't actually work in all browser configuration and the user probably doesn't care anyway.
+ <para>
+ The <quote>BLOCKED</quote> page adapts to the available
screen space -- it displays full-blown if space allows, or miniaturized and text-only
if loaded into a small frame or window. If you are using <application>Privoxy</application>
right now, you can take a look at the
<ulink url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
page</ulink>.
</para>
+-->
<para>
A very important exception occurs if <emphasis>both</emphasis>
<literal>block</literal> and <literal><link linkend="handle-as-image">handle-as-image</link></literal>,
<term>Example usage (section):</term>
<listitem>
<para>
- <screen>{+block}
+ <screen>{+block{No nasty stuff for you.}}
# Block and replace with "blocked" page
.nasty-stuff.example.com
-{+block +handle-as-image}
+{+block{Doubleclick banners.} +handle-as-image}
# Block and replace with image
.ad.doubleclick.net
.ads.r.us/banners/
-{+block +handle-as-empty-document}
+{+block{Layered ads.} +handle-as-empty-document}
# Block and then ignore
- adserver.exampleclick.net/.*\.js$</screen>
+ adserver.example.net/.*\.js$</screen>
</para>
</listitem>
</varlistentry>
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>
<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>
<screen># Block all documents on example.org that end with ".js",
# but send an empty document instead of the usual HTML message.
-{+block +handle-as-empty-document}
+{+block{Blocked JavaScript} +handle-as-empty-document}
example.org/.*\.js$
</screen>
</para>
# These don't look like images, but they're banners and should be
# blocked as images:
#
-{+block +handle-as-image}
-some.nasty-banner-server.com/junk.cgi\?output=trash
-
-# Banner source! Who cares if they also have non-image content?
-ad.doubleclick.net
+{+block{Nasty banners.} +handle-as-image}
+nasty-banner-server.example.com/junk.cgi\?output=trash
</screen>
</para>
</listitem>
</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>
</sect3>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="kill-popups">
-<title>kill-popups<anchor id="kill-popup"></title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Eliminate those annoying pop-up windows (deprecated)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- While loading the document, replace JavaScript code that opens
- pop-up windows with (syntactically neutral) dummy code on the fly.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Boolean.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- N/A
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- This action is basically a built-in, hardwired special-purpose filter
- action, but there are important differences: For <literal>kill-popups</literal>,
- the document need not be buffered, so it can be incrementally rendered while
- downloading. But <literal>kill-popups</literal> doesn't catch as many pop-ups as
- <literal><link
- linkend="FILTER-ALL-POPUPS">filter{<replaceable>all-popups</replaceable>}</link></literal>
- does and is not as smart as <literal><link
- linkend="FILTER-UNSOLICITED-POPUPS">filter{<replaceable>unsolicited-popups</replaceable>}</link>
- </literal>is.
- </para>
- <para>
- Think of it as a fast and efficient replacement for a filter that you
- can use if you don't want any filtering at all. Note that it doesn't make
- sense to combine it with any <literal><link linkend="filter">filter</link></literal> action,
- since as soon as one <literal><link linkend="filter">filter</link></literal> applies,
- the whole document needs to be buffered anyway, which destroys the advantage of
- the <literal>kill-popups</literal> action over its filter equivalent.
- </para>
- <para>
- Killing all pop-ups unconditionally is problematic. Many shops and banks rely on
- pop-ups to display forms, shopping carts etc, and the <literal><link
- linkend="FILTER-UNSOLICITED-POPUPS">filter{<replaceable>unsolicited-popups</replaceable>}</link>
- </literal> does a better job of catching only the unwanted ones.
- </para>
- <para>
- If the only kind of pop-ups that you want to kill are exit consoles (those
- <emphasis>really nasty</emphasis> windows that appear when you close an other
- one), you might want to use
- <literal><link
- linkend="filter">filter</link>{<replaceable>js-annoyances</replaceable>}</literal>
- instead.
- </para>
- <para>
- 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.
- </para>
- -->
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para><screen>+kill-popups</screen></para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="limit-connect">
<title>limit-connect</title>
<listitem>
<para>
By default, i.e. if no <literal>limit-connect</literal> action applies,
- <application>Privoxy</application> only allows HTTP CONNECT
- requests to port 443 (the standard, secure HTTPS port). Use
- <literal>limit-connect</literal> if more fine-grained control is desired
- for some or all destinations.
+ <application>Privoxy</application> allows HTTP CONNECT requests to all
+ ports. Use <literal>limit-connect</literal> if fine-grained control
+ is desired for some or all destinations.
</para>
<para>
The CONNECT methods exists in HTTP to allow access to secure websites
(<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
the decoded content. Websites can leverage this limitation to circumvent &my-app;'s
filters. By specifying an invalid port range you can disable HTTPS entirely.
- If you plan to disable SSL by default, consider enabling
- <literal><link linkend="treat-forbidden-connects-like-blocks ">treat-forbidden-connects-like-blocks</link></literal>
- as well, to be able to quickly create exceptions.
</para>
</listitem>
</varlistentry>
<!-- I probably have the wrong font setup, bollocks. -->
<!-- Apparently the emphasis tag uses a proportional font no matter what -->
<para>
- <screen>+limit-connect{443} # This is the default and need not be specified.
+ <screen>+limit-connect{443} # Port 443 is OK.
+limit-connect{80,443} # Ports 80 and 443 are OK.
+limit-connect{-3, 7, 20-100, 500-} # Ports less than 3, 7, 20 to 100 and above 500 are OK.
+limit-connect{-} # All ports are OK
<para>
More and more websites send their content compressed by default, which
is generally a good idea and saves bandwidth. But the <literal><link
- linkend="filter">filter</link></literal>, <literal><link linkend="deanimate-gifs">deanimate-gifs</link></literal>
- and <literal><link linkend="kill-popups">kill-popups</link></literal> actions need
- access to the uncompressed data.
+ linkend="filter">filter</link></literal> and
+ <literal><link linkend="deanimate-gifs">deanimate-gifs</link></literal>
+ actions need access to the uncompressed data.
</para>
<para>
When compiled with zlib support (available since &my-app; 3.0.7), content that should be
</sect3>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="treat-forbidden-connects-like-blocks">
-<title>treat-forbidden-connects-like-blocks</title>
-<!--
-new action
--->
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Block forbidden connects with an easy to find error message.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- If this action is enabled, <application>Privoxy</application> no longer
- makes a difference between forbidden connects and ordinary blocks.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Boolean</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>N/A</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- By default <application>Privoxy</application> answers
- <link linkend="limit-connect">forbidden <quote>Connect</quote> requests</link>
- with a short error message inside the headers. If the browser doesn't display
- headers (most don't), you just see an empty page.
- </para>
- <para>
- With this action enabled, <application>Privoxy</application> displays
- the message that is used for ordinary blocks instead. If you decide
- to make an exception for the page in question, you can do so by
- following the <quote>See why</quote> link.
- </para>
- <para>
- For <quote>Connect</quote> requests the clients tell
- <application>Privoxy</application> which host they are interested
- in, but not which document they plan to get later. As a result, the
- <quote>Go there anyway</quote> wouldn't work and is therefore suppressed.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen>+treat-forbidden-connects-like-blocks</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
<!-- ~~~~~ New section ~~~~~ -->
<sect3>
<title>Summary</title>
#
+crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
-crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
- +block-as-image = +block +handle-as-image
+ +block-as-image = +block{Blocked image.} +handle-as-image
allow-all-cookies = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
# These aliases define combinations of actions
# that are useful for certain types of sites:
#
- fragile = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link> -<link linkend="KILL-POPUPS">kill-popups</link> -<link linkend="PREVENT-COMPRESSION">prevent-compression</link>
+ fragile = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link> -<link linkend="PREVENT-COMPRESSION">prevent-compression</link>
- shop = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link> -<link linkend="KILL-POPUPS">kill-popups</link>
+ shop = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link>
# Short names for other aliases, for really lazy people ;-)
#
# These shops require pop-ups:
#
- {-kill-popups -filter{all-popups} -filter{unsolicited-popups}}
+ {-filter{all-popups} -filter{unsolicited-popups}}
.dabs.com
.overclockers.co.uk</screen>
</para>
#
+crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
-crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
- +block-as-image = +block +handle-as-image
+ +block-as-image = +block{Blocked image.} +handle-as-image
mercy-for-cookies = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
# These aliases define combinations of actions
# that are useful for certain types of sites:
#
- fragile = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link> -<link linkend="KILL-POPUPS">kill-popups</link>
- shop = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link> -<link linkend="KILL-POPUPS">kill-popups</link></screen>
+ fragile = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link>
+ shop = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link></screen>
</para>
<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>
now. <ulink url="http://www.mozilla.org/">Mozilla</ulink> users, who
can turn on smart handling of unwanted pop-ups in their browsers, can
safely choose
- -<literal><link linkend="FILTER-ALL-POPUPS">filter{popups}</link></literal> (and
- -<literal><link linkend="KILL-POPUPS">kill-popups</link></literal>) above
+ -<literal><link linkend="FILTER-ALL-POPUPS">filter{popups}</link></literal> above
and hence don't need this section. Anyway, disabling an already disabled
action doesn't hurt, so we'll define our exceptions regardless of what was
chosen in the defaults section:
<screen>
# These sites require pop-ups too :(
#
-{ -<link linkend="KILL-POPUPS">kill-popups</link> -<link linkend="FILTER-ALL-POPUPS">filter{popups}</link> }
+{ -<link linkend="FILTER-ALL-POPUPS">filter{popups}</link> }
.dabs.com
.overclockers.co.uk
.deutsche-bank-24.de</screen>
##########################################################################
# Block these fine banners:
##########################################################################
-{ <link linkend="BLOCK">+block</link> }
+{ <link linkend="BLOCK">+block{Banner ads.}</link> }
# Generic patterns:
#
<para>
<screen>
-# My user.action file. <fred@foobar.com></screen>
+# My user.action file. <fred@example.com></screen>
</para>
<para>
+crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
-crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
allow-all-cookies = -crunch-all-cookies -session-cookies-only
- allow-popups = -filter{all-popups} -kill-popups
-+block-as-image = +block +handle-as-image
+ allow-popups = -filter{all-popups}
++block-as-image = +block{Blocked as image.} +handle-as-image
-block-as-image = -block
# These aliases define combinations of actions that are useful for
# certain types of sites:
#
-fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer -kill-popups
+fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer
shop = -crunch-all-cookies allow-popups
# Allow ads for selected useful free sites:
seen an ad on your favourite page on example.com that you want to get rid of.
You have right-clicked the image, selected <quote>copy image location</quote>
and pasted the URL below while removing the leading http://, into a
- <literal>{ +block }</literal> section. Note that <literal>{ +handle-as-image
+ <literal>{ +block{} }</literal> section. Note that <literal>{ +handle-as-image
}</literal> need not be specified, since all URLs ending in
<literal>.gif</literal> will be tagged as images by the general rules as set
in default.action anyway:
<para>
<screen>
-{ +<link linkend="BLOCK">block</link> }
+{ +<link linkend="BLOCK">block</link>{Nasty ads.} }
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.
actions.
</para>
</listitem>
- <listitem>
- <para>
- If the <link linkend="KILL-POPUPS"><quote>+kill-popups</quote></link>
- action applies, and it is an HTML or JavaScript document, the popup-code in the
- response is filtered on-the-fly as it is received.
- </para>
- </listitem>
<listitem>
<para>
If any <link linkend="FILTER"><quote>+filter</quote></link> action
+hide-referrer {forge}
-hide-user-agent
-inspect-jpegs
- -kill-popups
-limit-connect
-overwrite-last-modified
-prevent-compression
-server-header-filter{xml-to-html}
-server-header-filter{html-to-xml}
-session-cookies-only
- +set-image-blocker {pattern}
- -treat-forbidden-connects-like-blocks </screen>
+ +set-image-blocker {pattern} </screen>
</para>
<para>
<para>
<screen>
- { +block }
+ { +block{Domains starts with "ad"} }
ad*.
- { +block }
+ { +block{Domain contains "ad"} }
.ad.
- { +block +handle-as-image }
+ { +block{Doubleclick banner server} +handle-as-image }
.[a-vx-z]*.doubleclick.net
</screen>
</para>
<para>
We'll just show the interesting part here - the explicit matches. It is
- matched three different times. Two <quote>+block</quote> sections,
- and a <quote>+block +handle-as-image</quote>,
+ matched three different times. Two <quote>+block{}</quote> sections,
+ and a <quote>+block{} +handle-as-image</quote>,
which is the expanded form of one of our aliases that had been defined as:
<quote>+block-as-image</quote>. (<link
linkend="ALIASES"><quote>Aliases</quote></link> are defined in
though ;-) Note that if you want an ad or obnoxious
URL to be invisible, it should be defined as <quote>ad.doubleclick.net</quote>
is done here -- as both a <link
- linkend="BLOCK"><quote>+block</quote></link>
+ linkend="BLOCK"><quote>+block{}</quote></link>
<emphasis>and</emphasis> an
<link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>.
The custom alias <quote><literal>+block-as-image</literal></quote> just
+hide-referer{forge}
-hide-user-agent
-inspect-jpegs
- -kill-popups
-overwrite-last-modified
+prevent-compression
-redirect
-server-header-filter{xml-to-html}
-server-header-filter{html-to-xml}
+session-cookies-only
- +set-image-blocker{blank}
- -treat-forbidden-connects-like-blocks }
+ +set-image-blocker{blank} }
/
- { +block +handle-as-image }
+ { +block{Path contains "ads".} +handle-as-image }
/ads
</screen>
</para>
<para>
<screen>
- { +block +handle-as-image }
+ { +block{Path starts with "ads".} +handle-as-image }
/ads
</screen>
</para>
<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.66 2008/03/06 16:33:47 fabiankeil
+ If limit-connect isn't used, don't limit CONNECT requests to port 443.
+
+ Revision 2.65 2008/03/04 18:30:40 fabiankeil
+ Remove the treat-forbidden-connects-like-blocks action. We now
+ use the "blocked" page for forbidden CONNECT requests by default.
+
+ Revision 2.64 2008/03/01 14:10:28 fabiankeil
+ Use new block syntax. Still needs some polishing.
+
+ Revision 2.63 2008/02/22 05:50:37 markm68k
+ fix merge problem
+
+ Revision 2.62 2008/02/11 11:52:23 hal9
+ Fix entity ... s/&/&
+
+ Revision 2.61 2008/02/11 03:41:47 markm68k
+ more updates for mac os x
+
+ Revision 2.60 2008/02/11 03:40:25 markm68k
+ more updates for mac os x
+
+ Revision 2.59 2008/02/11 00:52:34 markm68k
+ reflect new changes for mac os x
+
+ Revision 2.58 2008/02/03 21:37:40 hal9
+ Apply patch from Mark: s/OSX/OS X/
+
+ 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.
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