<!entity p-authors SYSTEM "p-authors.sgml">
<!entity config SYSTEM "p-config.sgml">
<!entity p-version "3.0.4">
-<!entity p-status "BETA">
+<!entity p-status "beta">
<!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc -->
<!entity % p-not-stable "INCLUDE">
<!entity % p-stable "IGNORE">
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.13 2006/08/22 11:04:59 hal9 Exp $
+ $Id: user-manual.sgml,v 2.17 2006/09/05 13:25:12 david__schmidt Exp $
Copyright (C) 2001- 2006 Privoxy Developers <developers@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 - 2004 by
+ <link linkend="copyright">Copyright</link> &my-copy; 2001 - 2006 by
<ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
</subscript>
</pubdate>
-<pubdate>$Id: user-manual.sgml,v 2.13 2006/08/22 11:04:59 hal9 Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.17 2006/09/05 13:25:12 david__schmidt Exp $</pubdate>
<!--
<application>Privoxy</application>, v.&p-version;<![%p-not-stable;[,
and is mostly complete at this point. The most up to date reference for the
time being is still the comments in the source files and in the individual
- configuration files. Development of version 3.0 is currently nearing
- completion, and includes many significant changes and enhancements over
- earlier versions. The target release date for
- stable v3.0 is <quote>soon</quote> ;-)]]>.
+ configuration files. Development of a new version is currently nearing
+ completion, and includes significant changes and enhancements over
+ earlier versions. ]]>.
</para>
<!-- include only in non-stable versions -->
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="features"><title>Features</title>
<para>
- In addition to <application>Internet Junkbuster's</application> traditional
- features of ad and banner blocking and cookie management,
- <application>Privoxy</application> provides new features<![%p-not-stable;[,
- some of them currently under development]]>:
+ In addition to the core
+ features of ad blocking and cookie management,
+ <application>Privoxy</application> provides many supplemental
+ features<![%p-not-stable;[, some of them currently under development]]>,
+ that give the end-user more control, more privacy and more freedom:
</para>
<!-- Include newfeatures.sgml boilerplate here: -->
&newfeatures;
</para>
<para>
- Note: If you have a previous <application>Junkbuster</application> or
- <application>Privoxy</application> installation on your system, you
- will need to remove it. On some platforms, this may be done for you as part
- of their installation procedure. (See below for your platform). In any case
- <emphasis>be sure to backup your old configuration if it is valuable to
- you.</emphasis> See the <link linkend="upgradersnote">note to
- upgraders</link> section below.
+ Note:
+ On some platforms, the installer may remove previously installed versions, if
+ found. (See below for your platform). In any case <emphasis>be sure to backup
+ your old configuration if it is valuable to you.</emphasis> See the <link
+ linkend="upgradersnote">note to upgraders</link> section below.
</para>
<!-- ~~~~~ New section ~~~~~ -->
Also note that if you have a <application>Junkbuster</application> RPM installed
on your system, you need to remove it first, because the packages conflict.
Otherwise, RPM will try to remove <application>Junkbuster</application>
- automatically, before installing <application>Privoxy</application>.
+ automatically
if found, before installing <application>Privoxy</application>.
</para>
</sect3>
<para>
Just double-click the installer, which will guide you through
the installation process. You will find the configuration files
- in the same directory as you installed Privoxy in.
+ in the same directory as you installed <application>Privoxy</application> in.
</para>
+<para>
+ Version 3.0.4 introduces 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>.
+</para>
+ <variablelist>
+ <varlistentry>
+ <term>Arguments:</term>
+ <listitem>
+ <para>
+ <replaceable class="parameter">--install</replaceable>[:<replaceable class="parameter">service_name</replaceable>]
+ </para>
+ <para>
+ <replaceable class="parameter">--uninstall</replaceable>[:<replaceable class="parameter">service_name</replaceable>]
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ After invoking <application>Privoxy</application> with
+ <command>--install</command>, you will need to bring up the
+ <application>Windows</application> service console to assign the user you
+ want <application>Privoxy</application> to run under, and whether or not you
+ want it to run whenever the system starts. You can start the
+ <application>Windows</application> services console with the following
+ command: <command>services.msc</command> If you do not take the manual step
+ of modifying <application>Privoxy's</application> service settings, it will
+ not start. Note too that you will need to give Privoxy a user account that
+ actually exists, or it will not be permitted to
+ write to its log and configuration files.
+</para>
+
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
<para>
In order not to lose your personal changes and adjustments when updating
to the latest <literal>default.action</literal> file we <emphasis>strongly
- recommend</emphasis> that you use <literal>user.action</literal> for your
- customization of <application>Privoxy</application>. See the <link
+ recommend</emphasis> that you use <literal>user.action</literal> and
+ <literal>user.filter</literal> for your local
+ customizations of <application>Privoxy</application>. See the <link
linkend="actions-file">Chapter on actions files</link> for details.
</para>
<sect1 id="whatsnew">
<title>What's New in this Release</title>
<para>
- There are many new features in <application>Privoxy</application> &p-version;
+ There are many
improvements and new features in <application>Privoxy</application> &p-version;
:
</para>
<itemizedlist>
<listitem>
<para>
- Mulitiple <link linkend="filter-file">filter files</link> can now be specifed in <filename>config</filename>.
+ Mulitiple <link linkend="filter-file">filter files</link> can now be specifed in <filename>config</filename>. This allows for
+ locally defined filters that can be maintained separately from the filters as
+ supplied by the developers.
</para>
</listitem>
</listitem>
<listitem>
<para>
- <literal><link linkend="fast-redirects">fast-redirects</link></literal>
+ <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>
<literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
</para>
</listitem>
- <listitem>
- <para>
- <literal><link linkend="hide-referrer">hide-referrer</link></literal>
- </para>
- </listitem>
- <listitem>
+ <listitem>
<para>
<literal><link linkend="inspect-jpegs">inspect-jpegs</link></literal>
</para>
</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 installed and
- started as a <emphasis>service</emphasis>.
+ <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>
- In addition, there are various bug fixes and enhancements, including
- error pages are no longer cached, better DNS error handling, and logging
- improvements.
+ <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>
+ 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ In addition, there are various bug fixes and significant enhancements, including
+ error pages should no longer be cached if the problem is fixed, better DNS
+ error handling, and various logging improvements.
</para>
</listitem>
configuration files. Save any important configuration files!
</para>
</listitem>
+ <listitem>
+ <para>
+ On the other hand, some 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ See the full documentation on
+ <literal><link linkend="fast-redirects">fast-redirects</link></literal>
+ which has changed syntax, and may require adjustments to local configs.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>jarfile</filename>, cookie logger, is off by default now.
+ </para>
+ </listitem>
+
<listitem>
<para>
What constitutes a <quote>default</quote> configuration has changed,
Set your browser to use <application>Privoxy</application> as HTTP and
HTTPS (SSL) proxy by setting the proxy configuration for address of
<literal>127.0.0.1</literal> and port <literal>8118</literal>.
- (<application>Junkbuster</application> and earlier versions of
- <application>Privoxy</application> used port 8000.) See the section <link
- linkend="startup">Starting <application>Privoxy</application></link> below
- for more details on this.
+ <emphasis>DO NOT</emphasis> activate proxying for <literal>FTP</literal> or
+ any protocols besides HTTP and HTTPS (SSL)! It won't work!
</para>
</listitem>
<listitem>
<para>
Please see the section <link linkend="contact">Contacting the
- Developers</link> on how to report bugs or problems with websites or to get
+ Developers</link> on how to report bugs, problems with websites or to get
help.
</para>
</listitem>
<sect2 id="start-windows">
<title>Windows</title>
<para>
-Click on the Privoxy Icon to start Privoxy. If no configuration file is
+Click on the Privoxy Icon to start <application>Privoxy</application>. If no configuration file is
specified on the command line, <application>Privoxy</application> will look
for a file named <filename>config.txt</filename>. Note that Windows will
- automatically start Privoxy upon booting you PC.
+ automatically start Privoxy when the system starts if you chose that option
+ when installing.
+</para>
+<para>
+ <application>Privoxy</application> can run with full Windows service functionality.
+ On Windows only, the Privoxy program has two new command line arguments
+ to install and uninstall Privoxy as a service. See the
+ <link linkend="installation-pack-win">Windows Installation
+ instructions</link> for details.
</para>
</sect2>
</itemizedlist>
</para>
+<para>
+ On <application>MS Windows</application> only there are two addition
+ options to allow <application>Privoxy</application> to install and
+ run as a <emphasis>service</emphasis>. See the
+<link linkend="installation-pack-win">Window Installation section</link>
+for details.
+</para>
+
</sect2>
</sect1>
</itemizedlist>
</para>
+<para>
+ The syntax of all configuration files has remained the same throughout the
+ 3.x series. There have been enhancements, but no changes that would preclude
+ the use of any configuration file from one version to the next.
+</para>
+
<para>
All files use the <quote><literal>#</literal></quote> character to denote a
comment (the rest of the line will be ignored) and understand line continuation
<sect1 id="actions-file"><title>Actions Files</title>
<para>
- The actions files are used to define what actions
- <application>Privoxy</application> takes for which URLs, and thus determine
+ The actions files are used to define what <emphasis>actions</emphasis>
+ <application>Privoxy</application> takes for which URLs, and thus determines
how ad images, cookies and various other aspects of HTTP content and
- transactions are handled, and on which sites (or even parts thereof). There
- are three such files included with <application>Privoxy</application>
- with differing purposes:
+ transactions are handled, and on which sites (or even parts thereof).
+ There are a number of such actions, with a wide range of functionality.
+ Each action does something a little different.
+ These actions give us a veritable arsenal of tools with which to exert
+ our control, preferences and independence.
+</para>
+<para>
+ There
+ are three action files included with <application>Privoxy</application> with
+ differing purposes:
</para>
<para>
at <ulink url="http://www.pcre.org/man.txt">http://www.pcre.org/man.txt</ulink>.
You might also find the Perl man page on regular expressions (<literal>man perlre</literal>)
useful, which is available on-line at <ulink
- url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>.
+ url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>.
</para>
<para>
<!--
new action
-->
-<title>crunch-server-header</title>
+<title>crunch-client-header</title>
<variablelist>
<varlistentry>
<term>Effect:</term>
<listitem>
<para>
- Deletes every header send by the client that contains the string the user supplied as parameter.
+ Deletes every header sent by the client that contains the string the user supplied as parameter.
</para>
</listitem>
</varlistentry>
based substitutions. (Note: as of version 3.0.3 plain text documents
are exempted from filtering, because web servers often use the
<literal>text/plain</literal> MIME type for all files whose type they
- don't know.)
+ don't know.) By default, filtering works only on the document content
+ itself, not the headers.
</para>
</listitem>
</varlistentry>
</sect3>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="filter-client-headers">
+<title>filter-client-headers</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ To apply filtering to the client's (browser's) headers
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ By default, <application>Privoxy's</application> filters only apply
+ to the document content itself. This will extend those filters to
+ include the client's headers as well.
+ </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>
+ Regular expressions can be used to filter headers as well. Check your
+ filters closely before activating this action, as it can easily lead to broken
+ requests.
+ </para>
+ <para>
+ These filters are applied to each header on its own, not to them
+ all at once. This makes it easier to diagnose problems, but on the downside
+ you can't write filters that only change header x if header y's value is
+ z.
+ </para>
+ <para>
+ The filters are used after the other header actions have finished and can
+ use their output as input.
+ </para>
+
+ <para>
+ Whenever possible one should specify <literal>^</literal>,
+ <literal>$</literal>, the whole header name and the colon, to make sure
+ the filter doesn't cause havoc to other headers or the
+ page itself. For example if you want to transform
+ <application>Galeon</application> User-Agents to
+ <application>Firefox</application> User-Agents you
+ shouldn't use:
+</para>
+<para>
+<screen>
+s@Galeon/\d\.\d\.\d @@
+</screen>
+</para><para>
+ but:
+</para><para>
+<screen>
+s@^(User-Agent:.*) Galeon/\d\.\d\.\d (Firefox/\d\.\d\.\d\.\d)$@$1 $2@
+</screen>
+</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen>
+{+filter-client-headers +filter{test_filter}}
+problem-host.example.com
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="filter-server-headers">
+<title>filter-server-headers</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ To apply filtering to the server's headers
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ By default, <application>Privoxy's</application> filters only apply
+ to the document content itself. This will extend those filters to
+ include the server's headers as well.
+ </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>
+ Similar to <literal>filter-client-headers</literal>, but works on
+ the server instead. To filter both server and client, use both.
+ </para>
+ <para>
+ As with <literal>filter-client-headers</literal>, check your
+ filters before activating this action, as it can easily lead to broken
+ requests.
+ </para>
+ <para>
+ These filters are applied to each header on its own, not to them
+ all at once. This makes it easier to diagnose problems, but on the downside
+ you can't write filters that only change header x if header y's value is
+ z.
+ </para>
+ <para>
+ The filters are used after the other header actions have finished and can
+ use their output as input.
+ </para>
+ <para>
+ Remember too, whenever possible one should specify <literal>^</literal>,
+ <literal>$</literal>, the whole header name and the colon, to make sure
+ the filter doesn't cause havoc to other headers or the
+ page itself. See above for example.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen>
+{+filter-server-headers +filter{test_filter}}
+problem-host.example.com
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="force-text-mode">
<title>force-text-mode</title>
<term>Effect:</term>
<listitem>
<para>
- To protect against a known exploit
+ Protect against a known exploit
</para>
</listitem>
</varlistentry>
<listitem>
<para>
This action is useful to replace whole documents with your own
- ones. For that to work, they have to be available on another server.
+ ones. For that to work, they have to be available on another server,
+ and both should resolve.
</para>
<para>
You can do the same by combining the actions
<para>
If you previously configured <application>Privoxy</application> to do the
request through a SSL tunnel, everything will work. Most likely you haven't
- and the server will responds with an error message because it is expecting
+ and the server will respond with an error message because it is expecting
HTTPS.
</para>
</listitem>
{ \
-<link linkend="ADD-HEADER">add-header</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</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-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-CLIENT-HEADERS">filter-client-headers</link> \
+ -<link linkend="FILTER-SERVER-HEADERS">filter-server-headers</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="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>
One of the most important jobs of <application>Privoxy</application>
- is to block banners. A huge bunch of them are already <quote>blocked</quote>
+ is to block banners. A huge bunch of them can be <quote>blocked</quote>
by the <literal><link linkend="filter">filter</link>{banners-by-size}</literal>
action, which we enabled above, and which deletes the references to banner
images from the pages while they are loaded, so the browser doesn't request
</para>
<para>
- The actual <filename>default.action</filename> is of course more
+ The actual <filename>default.action</filename> is of course much more
comprehensive, but we hope this example made clear how it works.
</para>
# Allow ads for selected useful free sites:
#
-allow-ads = -block -filter{banners-by-size} -filter{banners-by-link}</screen>
+allow-ads = -block -filter{banners-by-size} -filter{banners-by-link}
+
+# Alias for specific file types that are text, but might have conflicting
+# MIME types. We want the browser to force these to be text documents.
+handle-as-text = -<link linkend="FILTER">filter</link> +-<link linkend="content-type-overwrite">content-type-overwrite{text/plain}</link> +-<link linkend="FORCE-TEXT-MODE">force-text-mode</link> -<link linkend="HIDE-CONTENT-DISPOSITION">hide-content-disposition</link></screen>
-
</para>
<para>
<literal>-<link linkend="filter-banners-by-link">filter{banners-by-link}</link></literal> above.
</para>
+<para>
+ Invoke another alias here to force an over-ride of the MIME type <literal>
+ application/x-sh</literal> which typically would open a download type
+ dialog. In my case, I want to look at the shell script, and then I can save
+ it should I choose to.
+</para>
+
+<para>
+<screen>
+{ handle-as-text }
+/.*\.sh$</screen>
+</para>
+
<para>
<filename>user.action</filename> is generally the best place to define
exceptions and additions to the default policies of
<title>Filter Files</title>
<para>
- All text substitutions that can be invoked through the
- <literal><link linkend="filter">filter</link></literal> action which
- must first be defined in a <quote>filter file</quote>, such as
- <filename>default.filter</filename>. Mulitple filter files can be
- defined through the <literal>
- <link linkend="filterfile">filterfile</link></literal> config
- option. The filters as supplied by the developers will be found in
+ On-the-fly text substitutions that can be invoked through the
+ <literal><link linkend="filter">filter</link></literal> action need
+ to be defined in a <quote>filter file</quote>. Once defined, they
+ can then be invoked as an <quote>action</quote>. Mulitple 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
<filename>default.filter</filename>. It is recommended that any locally
- defined or modified filters go in a separately defined file such as
+ defined or modified filters go in a separately defined file such as
<filename>user.filter</filename>.
</para>
HTML, JavaScript, CSS etc. (all <literal>text/*</literal>
MIME types, <emphasis>except</emphasis> <literal>text/plain</literal>).
Substitutions are made at the source level, so if you want to <quote>roll
- your own</quote> filters, you should be familiar with HTML syntax.
+ your own</quote> filters, you should first be familiar with HTML syntax,
+ and, of course, regular expressions. By default, filters are only applied
+ to the document content, but can be extended to the headers with
+ the supplemental actions:
+ <link linkend="filter-client-headers">filter-client-headers</link> and
+ <link linkend="filter-server-headers">filter-server-headers</link>.
</para>
<para>
<para>
If you are new to regular expressions, you might want to take a look at
the <link linkend="regex">Appendix on regular expressions</link>, and
- see the <ulink url="http://perldoc.com/perl5.6.1/pod/perl.html">Perl
+ see the <ulink url="http://perldoc.perl.org/perlre.html">Perl
manual</ulink> for
- <ulink url="http://perldoc.com/perl5.6.1/pod/perlop.html#s-PATTERN-REPLACEMENT-egimosx">the
+ <ulink url="http://perldoc.perl.org/perlop.html">the
<literal>s///</literal> operator's syntax</ulink> and <ulink
- url="http://perldoc.com/perl5.6.1/pod/perlre.html">Perl-style regular
+ url="http://perldoc.perl.org/perlre.html">Perl-style regular
expressions</ulink> in general.
The below examples might also help to get you started.
</para>
</listitem>
</varlistentry>
- <varlistentry id="filter-server-headers">
- <term><emphasis>filter-server-headers</emphasis></term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="filter-client-headers">
- <term><emphasis>filter-client-headers</emphasis></term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
<!--
<varlistentry>
<term><emphasis> </emphasis></term>
<para><simplelist>
<member>
- <emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
+ <emphasis>[ ]</emphasis> - Characters enclosed in brackets will be matched if
any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
matches any numeric digit (zero through nine). As an example, we can combine
this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.
<para><simplelist>
<member>
- <emphasis>()</emphasis> - parentheses are used to group a sub-expression,
+ <emphasis>( )</emphasis> - parentheses are used to group a sub-expression,
or multiple sub-expressions.
</member>
</simplelist></para>
</para>
<para>
- A now something a little more complex:
+ And now something a little more complex:
</para>
<para>
<para>
<emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
another path statement with forward slashes. Anything in the square brackets
- <quote>[]</quote> can be matched. This is using <quote>0-9</quote> as a
+ <quote>[ ]</quote> can be matched. This is using <quote>0-9</quote> as a
shorthand expression to mean any digit one through nine. It is the same as
saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
means one or more of the preceding expression must be included. The preceding
<para>
More reading on Perl Compatible Regular expressions:
- <ulink url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>
+ <ulink url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>
</para>
<para>
<listitem>
<para>
<application>Privoxy</application> traps any request for its own internal CGI
- pages (e.g http://p.p/) and sends the CGI page back to the browser.
+ pages (e.g <ulink url="http://p.p/">http://p.p/</ulink>) and sends the CGI page back to the browser.
</para>
</listitem>
<listitem>
linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
action applies (and the document type fits the action), the rest of the page is
read into memory (up to a configurable limit). Then the filter rules (from
- <filename>default.filter</filename>) are processed against the buffered
- content. Filters are applied in the order they are specified in one of the
- filter files. Animated GIFs, if present, are
- reduced to either the first or last frame, depending on the action
+ <filename>default.filter</filename> and any other filter files) are
+ processed against the buffered content. Filters are applied in the order
+ they are specified in one of the filter files. Animated GIFs, if present,
+ are reduced to either the first or last frame, depending on the action
setting.The entire page, which is now filtered, is then sent by
<application>Privoxy</application> back to your browser.
</para>
</listitem>
<listitem>
<para>
- As the browser receives the now (probably filtered) page content, it
+ As the browser receives the now (possibly filtered) page content, it
reads and then requests any URLs that may be embedded within the page
source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
frames), sounds, etc. For each of these objects, the browser issues a new
<para>
Let's try an example, <ulink url="http://google.com">google.com</ulink>,
- and look at it one section at a time:
+ and look at it one section at a time in a sample configuration (your real
+ configuration may vary):
</para>
<para>
In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
-{-add-header
- -block
- -crunch-outgoing-cookies
- -crunch-incoming-cookies
- +deanimate-gifs{last}
- -downgrade-http-version
- +fast-redirects
- -filter{popups}
- -filter{fun}
- -filter{shockwave-flash}
- -filter{crude-parental}
- +filter{html-annoyances}
- +filter{js-annoyances}
- +filter{content-cookies}
- +filter{webbugs}
- +filter{refresh-tags}
- +filter{nimda}
- +filter{banners-by-size}
- +hide-forwarded-for-headers
- +hide-from-header{block}
- +hide-referer{forge}
- -hide-user-agent
- -handle-as-image
- -kill-popups
- -limit-connect
- +prevent-compression
- -send-vanilla-wafer
- -send-wafer
- +session-cookies-only
- +set-image-blocker{pattern} }
+ {-add-header
+ -block
+ -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
+ +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-client-headers
+ -filter-server-headers
+ -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
+ +session-cookies-only
+ +set-image-blocker {pattern}
+ -treat-forbidden-connects-like-blocks }
/
-
+
{ -session-cookies-only }
.google.com
</para>
<para>
- This tells us how we have defined our
+ This is telling us how we have defined our
<link linkend="ACTIONS"><quote>actions</quote></link>, and
- which ones match for our example, <quote>google.com</quote>. The first listing
+ which ones match for our test case, <quote>google.com</quote>.
+ Displayed is all the actions that are available to us. Remember,
+ the <literal>+</literal> sign denotes <quote>on</quote>. <literal>-</literal>
+ denotes <quote>off</quote>. So some are <quote>on</quote> here, but many
+ are <quote>off</quote>. Each example we try may provide a slightly different
+ end result, depending on our configuration directives.
+</para>
+<para>
+ The first listing
is any matches for the <filename>standard.action</filename> file. No hits at
all here on <quote>standard</quote>. Then next is <quote>default</quote>, or
our <filename>default.action</filename> file. The large, multi-line listing,
<quote>.google.com</quote>. The first is negating our previous cookie setting,
which was for <link
linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>
- (i.e. not persistent). So we will allow persistent cookies for google. The
- second turns <emphasis>off</emphasis> any
+ (i.e. not persistent). So we will allow persistent cookies for google, at
+ least that is how it is in this example. The second turns
+ <emphasis>off</emphasis> any
<link
linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link>
action, allowing this to take place unmolested. Note that there is a leading
<para>
Then, for our <filename>user.action</filename> file, we again have no hits.
+ So there is nothing google-specific that we might have added to our own, local
+ configuration.
</para>
<para>
Final results:
- -add-header
- -block
- -crunch-outgoing-cookies
- -crunch-incoming-cookies
- +deanimate-gifs{last}
- -downgrade-http-version
- -fast-redirects
- -filter{popups}
- -filter{fun}
- -filter{shockwave-flash}
- -filter{crude-parental}
- +filter{html-annoyances}
- +filter{js-annoyances}
- +filter{content-cookies}
- +filter{webbugs}
- +filter{refresh-tags}
- +filter{nimda}
- +filter{banners-by-size}
- +hide-forwarded-for-headers
- +hide-from-header{block}
- +hide-referer{forge}
- -hide-user-agent
- -handle-as-image
- -kill-popups
- -limit-connect
- +prevent-compression
- -send-vanilla-wafer
+ -add-header
+ -block
+ -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
+ -fast-redirects
+ +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-client-headers
+ -filter-server-headers
+ -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
- -session-cookies-only
- +set-image-blocker{pattern}
-</screen>
+ -session-cookies-only
+ +set-image-blocker {pattern}
+ -treat-forbidden-connects-like-blocks </screen>
</para>
<para>
Notice the only difference here to the previous listing, is to
<quote>fast-redirects</quote> and <quote>session-cookies-only</quote>,
- which are actived specifically for this site in our configuration.
+ which are activated specifically for this site in our configuration,
+ and thus show in the <quote>Final Results</quote>.
</para>
<para>
</para>
<para>
- One last example. Let's try <quote>http://www.rhapsodyk.net/adsl/HOWTO/</quote>.
+ One last example. Let's try <quote>http://www.example.net/adsl/HOWTO/</quote>.
This one is giving us problems. We are getting a blank page. Hmmm ...
</para>
<para>
<screen>
- Matches for http://www.rhapsodyk.net/adsl/HOWTO/:
+ Matches for http://www.example.net/adsl/HOWTO/:
In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
{-add-header
- -block
- -crunch-incoming-cookies
- -crunch-outgoing-cookies
+ -block
+ -content-type-overwrite
+ -crunch-client-header
+ -crunch-if-none-match
+ -crunch-incoming-cookies
+ -crunch-outgoing-cookies
+ -crunch-server-header
+deanimate-gifs
-downgrade-http-version
- +fast-redirects
+ +fast-redirects{check-decoded-url}
+filter{html-annoyances}
+filter{js-annoyances}
+filter{kill-popups}
+filter{banners-by-size}
+filter{hal}
+filter{fun}
+ -filter-client-headers
+ -filter-server-headers
+ -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-referer{forge}
-hide-user-agent
- -handle-as-image
+ -inspect-jpegs
+kill-popups
+ -overwrite-last-modified
+prevent-compression
+ -redirect
-send-vanilla-wafer
-send-wafer
+session-cookies-only
- +set-image-blocker{blank} }
+ +set-image-blocker{blank}
+ -treat-forbidden-connects-like-blocks }
/
{ +block +handle-as-image }
</para>
<para>
- Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote>! But
- we did not want this at all! Now we see why we get the blank page. We could
- now add a new action below this that explicitly does <emphasis>not</emphasis>
- block (<quote>{-block}</quote>) paths with <quote>adsl</quote>. There are
- various ways to handle such exceptions. Example:
+ Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote> in our
+ configuration! But we did not want this at all! Now we see why we get the
+ blank page. We could now add a new action below this that explicitly
+ <emphasis>un</emphasis> blocks (<quote>{-block}</quote>) paths with
+ <quote>adsl</quote> in them (remember, last match in the configuration wins).
+ There are various ways to handle such exceptions. Example:
</para>
<para>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: user-manual.sgml,v $
+ Revision 2.17 2006/09/05 13:25:12 david__schmidt
+ Add Windows service invocation stuff (duplicated) in FAQ and in user manual under Windows startup. One probably ought to reference the other.
+
+ Revision 2.16 2006/09/02 12:49:37 hal9
+ Various small updates for new actions, filterfiles, etc.
+
+ Revision 2.15 2006/08/30 11:15:22 hal9
+ More work on the new actions, especially filter-*-headers, and What's New
+ section. User Manual is close to final form for 3.0.4 release. Some tinkering
+ and proof reading left to do.
+
+ Revision 2.14 2006/08/29 10:59:36 hal9
+ Add a "Whats New in this release" Section. Further work on multiple filter
+ files, and assorted other minor changes.
+
Revision 2.13 2006/08/22 11:04:59 hal9
Silence warnings and errors. This should build now. New filters were only
stubbed in. More to be done.
projects / privoxy.git / blobdiff