<!entity license SYSTEM "license.sgml">
<!entity p-authors SYSTEM "p-authors.sgml">
<!entity config SYSTEM "p-config.sgml">
-<!entity p-version "3.0.6">
-<!entity p-status "stable">
+<!entity p-version "3.0.11">
+<!entity p-status "UNRELEASED">
<!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc -->
-<!entity % p-not-stable "IGNORE">
-<!entity % p-stable "INCLUDE">
+<!entity % p-not-stable "INCLUDE">
+<!entity % p-stable "IGNORE">
<!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
<!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
<!entity % p-readme "IGNORE">
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.27 2006/11/14 01:57:47 hal9 Exp $
+ $Id: user-manual.sgml,v 2.86 2008/08/16 10:12:23 fabiankeil Exp $
- Copyright (C) 2001- 2006 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 - 2006 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.27 2006/11/14 01:57:47 hal9 Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.86 2008/08/16 10:12:23 fabiankeil Exp $</pubdate>
<!--
How to install the binary packages depends on your operating system:
</para>
+<!-- XXX: The installation sections should be sorted -->
+
<!-- ~~~~~ New section ~~~~~ -->
<sect3 id="installation-pack-rpm"><title>Red Hat and Fedora RPMs</title>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-deb"><title>Debian</title>
+<sect3 id="installation-deb"><title>Debian and Ubuntu</title>
<para>
DEBs can be installed with <literal>apt-get install privoxy</literal>,
and will use <filename>/etc/privoxy</filename> for the location of
in the same directory as you installed <application>Privoxy</application> in.
</para>
<para>
- Version 3.0.
4 introduced full <application>Windows</application> service
+ Version 3.0.
5 beta introduced full <application>Windows</application> service
functionality. On Windows only, the <application>Privoxy</application>
program has two new command line arguments to install and uninstall
<application>Privoxy</application> as a <emphasis>service</emphasis>.
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, FreeBSD, HP-UX</title>
+<sect3 id="installation-pack-bintgz"><title>Solaris <!--, NetBSD, HP-UX--></title>
<para>
Create a new directory, <literal>cd</literal> to it, then unzip and
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-mac"><title>Mac OSX</title>
-<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>
</para>
</sect3>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-tbz"><title>FreeBSD</title>
+
+<para>
+ Privoxy is part of FreeBSD's Ports Collection, you can build and install
+ it with <literal>cd /usr/ports/www/privoxy; make install clean</literal>.
+</para>
+<para>
+ If you don't use the ports, you can fetch and install
+ the package with <literal>pkg_add -r privoxy</literal>.
+</para>
+<para>
+ The port skeleton and the package can also be downloaded from the
+ <ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">File Release
+ Page</ulink>, but there's no reason to use them unless you're interested in the
+ beta releases which are only available there.
+</para>
+</sect3>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect3 id="installattion-gentoo"><title>Gentoo</title>
<para>
<sect1 id="whatsnew">
<title>What's New in this Release</title>
<para>
- There are many improvements and new features since <application>Privoxy 3.0.3</application>, the last stable release:
+ There are many improvements and new features since <application>Privoxy 3.0.8</application>, the last stable release:
</para>
<para>
<itemizedlist>
<listitem>
<para>
- Multiple <link linkend="filter-file">filter files</link> can now be specified in <filename>config</filename>. This allows for
- locally defined filters that can be maintained separately from the filters as
- supplied by the developers, i.e. <filename>default.filter</filename>.
+ Added SOCKS5 support (with address resolution done by
+ the SOCKS5 server). Patch provided by Eric M. Hopper.
</para>
</listitem>
-
- <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>
+ <listitem>
<para>
- And <literal><link linkend="hide-referrer">hide-referrer</link></literal>
- has a new option, <literal>conditional block</literal>.
+ The "blocked" CGI pages include a block reason that was
+ provided as argument to the last-applying block action.
</para>
-
- </listitem>
-
+ </listitem>
<listitem>
<para>
- <application>MS-Windows</application> versions can now be
- <link
- linkend="installation-pack-win">installed and
- started as a <emphasis>Windows service</emphasis></link>.
+ If enable-edit-actions is disabled (the default since 3.0.7 beta)
+ the show-status page hides the edit buttons and explains why.
+ Previously the user would get the "this feature has been disabled"
+ message after using the edit button.
</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>.
+ Forbidden CONNECT requests are treated like blocks by default.
+ The now-pointless treat-forbidden-connects-like-blocks action
+ has been removed.
</para>
+ </listitem>
+ <listitem>
<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.
+ Not enabling limit-connect now allows CONNECT requests to all ports.
+ In previous versions it would only allow CONNECT requests to port 443.
+ Use +limit-connect{443} if you think you need the old default behaviour.
</para>
</listitem>
-
<listitem>
<para>
- There are six new <link linkend="FILTER">filters</link>.
+ The CGI editor gets turned off after three edit requests with invalid
+ file modification timestamps. This makes life harder for attackers
+ who can leverage browser bugs to send fake Referers and intend to
+ brute-force edit URLs.
</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.
+ Action settings for multiple patterns in the same section are
+ shared in memory. As a result these sections take up less space
+ (and are loaded slightly faster). Problem reported by Franz Schwartau.
</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.
+ Linear white space in HTTP headers will be normalized to single
+ spaces before parsing the header's content, headers split across
+ multiple lines get merged first.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Host information is gathered outside the main thread so it's less
+ likely to delay other incoming connections if the host is misconfigured.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ New config option "hostname" to use a hostname other than
+ the one returned by the operating system. Useful to speed-up responses
+ for CGI requests on misconfigured systems. Requested by Max Khon.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The CGI editor supports the "disable all filters of this type"
+ directives "-client-header-filter", "-server-header-filter",
+ "-client-header-tagger" and "-server-header-tagger".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Fixed false-positives with the link-by-url filter and URLs that
+ contain the pattern "/jump/".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The less-download-windows filter no longer messes
+ "Content-Type: application/x-shockwave-flash" headers up.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In the show-url-info page's "Final results" section active and
+ inactive actions are listed separately. Patch provided by Lee.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The GNUmakefile supports the DESTDIR variable. Patch for
+ the install target submitted by Radoslaw Zielinski.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Embedding the content of configuration files in the show-status
+ page is significantly faster now. For a largish action file (1 MB)
+ a speedup of about 2450 times has been measured. This is mostly
+ interesting if you are using large action files or regularly use
+ Privoxy-Regression-Test while running Privoxy through Valgrind,
+ for stock configuration files it doesn't really matter.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If zlib support is unavailable and there are content
+ filters active but the prevent-compression action is disabled,
+ the show-url-info page includes a warning that compression
+ might prevent filtering.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The show-url-info page provides an OpenSearch Description that
+ allows to access the page through browser search plugins.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The obsolete kill-popups action has been removed as the
+ PCRS-based popup filters can do the same and are slightly
+ less unreliable.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The inspect-jpegs action has been removed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The send-wafer and send-vanilla-wafer actions have been removed.
+ They weren't particular useful and their behaviour could be emulated
+ with add-header anyway.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Privoxy-Regression-Test has been significantly improved.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Most sections in the default.action file contain tests for
+ Privoxy-Regression-Test to verify that they are working as intended.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Parts of Privoxy have been refactored to increase maintainability.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Building with zlib (if available) is done by default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Ordinary configuration file changes no longer cause program
+ termination on OS/2 if the name of the logfile hasn't been
+ changed as well. This regression probably crept in with the
+ logging improvements in 3.0.7. Reported by Maynard.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The img-reorder filter is less likely to mess up JavaScript code in
+ img tags. Problem and solution reported by Glenn Washburn in #2014552.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The source tar ball now includes Privoxy-Log-Parser,
+ a syntax-highlighter for Privoxy logs. Documentation is available
+ through perldoc(1), for fancy screenshots see:
+ <ulink url="http://www.fabiankeil.de/sourcecode/privoxy-log-parser/"
+ >http://www.fabiankeil.de/sourcecode/privoxy-log-parser/</ulink>.
</para>
</listitem>
-
-
</itemizedlist>
</para>
+<para>
+ For a more detailed list of changes please have a look at the ChangeLog.
+</para>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="upgradersnote">
<para>
<itemizedlist>
+ <listitem>
+ <para>
+ The recommended way to upgrade &my-app; is to backup your old
+ configuration files, install the new ones, verify that &my-app;
+ is working correctly and finally merge back your changes using
+ <application>diff</application> and maybe <application>patch</application>.
+ </para>
+ <para>
+ There are a number of new features in each &my-app; release and
+ most of them have to be explicitly enabled in the configuration
+ files. Old configuration files obviously don't do that and due
+ to syntax changes using old configuration files with a new
+ &my-app; isn't always possible anyway.
+ </para>
+ </listitem>
<listitem>
<para>
- Some installers may remove earlier versions completely, including
- configuration files. Save any important configuration files!
+ Note that some installers remove earlier versions completely,
+ including configuration files, therefore you should really save
+ any important configuration files!
</para>
</listitem>
<listitem>
<para>
- On the other hand, other installers may not overwrite any existing configuration
- files, thinking you will want to do that. You may want to manually check
- your saved files against the newer versions to see if the improvements have
- merit, or whether there are new options that you may want to consider.
- There are a number of new features, but most won't be available unless
- these features are incorporated into your configuration somehow.
+ On the other hand, other installers don't overwrite existing configuration
+ files, thinking you will want to do that yourself.
</para>
</listitem>
<listitem>
- <para>
- See the full documentation on
- <literal><link linkend="fast-redirects">fast-redirects</link></literal>
- which has changed syntax, and will require adjustments to local configs,
- such as <filename>user.action</filename>. You must reference the new
- syntax:
- </para>
- <para>
- <screen>
- { +fast-redirects{check-decoded-url} }
- .example.com
- mybank.com
- .google.</screen>
-</para>
+ <para>
+ <filename>standard.action</filename> now only includes the enabled actions.
+ Not all actions as before.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In the default configuration only fatal errors are logged now.
+ You can change that in the <link linkend="DEBUG">debug section</link>
+ of the configuration file. You may also want to enable more verbose
+ logging until you verified that the new &my-app; version is working
+ as expected.
+ </para>
+ </listitem>
- </listitem>
<listitem>
<para>
- The <filename>jarfile</filename>,
- <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookie</ulink> logger, is off by default now.
+ Three other config file settings are now off by default:
+ <link linkend="enable-remote-toggle">enable-remote-toggle</link>,
+ <link linkend="enable-remote-http-toggle">enable-remote-http-toggle</link>,
+ and <link linkend="enable-edit-actions">enable-edit-actions</link>.
+ If you use or want these, you will need to explicitly enable them, and
+ be aware of the security issues involved.
</para>
</listitem>
+ <listitem>
+ <para>
+ The <quote>filter-client-headers</quote> and
+ <quote>filter-server-headers</quote> actions that were introduced with
+ <application>Privoxy 3.0.5</application> to apply content filters to
+ the headers have been removed and replaced with new actions.
+ See the <link
+ linkend="whatsnew">What's New section</link> above.
+ </para>
+ </listitem>
+
+
+<!--
<listitem>
<para>
What constitutes a <quote>default</quote> configuration has changed,
settings as yet (see above).
</para>
</listitem>
-
+-->
+<!--
<listitem>
<para>
The default actions setting is now <literal>Cautious</literal>. Previous
<listitem>
<para>
-<!-- I think it is best to keep this somewhat vague, in case -->
-<!-- the situation changes under our feet. -->
Some installers may not automatically start
<application>Privoxy</application> after installation.
</para>
</listitem>
-
+-->
</itemizedlist>
</para>
+
</sect2>
</sect1>
by setting the proxy configuration for address of
<literal>127.0.0.1</literal> and port <literal>8118</literal>.
<emphasis>DO NOT</emphasis> activate proxying for <literal>FTP</literal> or
- any protocols besides HTTP and HTTPS (SSL)! It won't work!
+ any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
+ browser from using these protocols.
</para>
</listitem>
A default installation should provide a reasonable starting point for
most. There will undoubtedly be occasions where you will want to adjust the
configuration, but that can be dealt with as the need arises. Little
- to no initial configuration is required in most cases.
+ to no initial configuration is required in most cases, you may want
+ to enable the
+ <ulink url="config.html#ENABLE-EDIT-ACTIONS">web-based action editor</ulink> though.
+ Be sure to read the warnings first.
</para>
<para>
See the <link linkend="configuration">Configuration section</link> for more
</para>
</listitem>
+<!--
+ Did anyone test these lately?
+ fk 2007-11-10
<listitem>
<para>
For easy access to &my-app;'s most important controls, drag the provided
personal toolbar.
</para>
</listitem>
+-->
<listitem>
<para>
Now enjoy surfing with enhanced control, comfort and privacy!
</para>
</listitem>
-
+
</itemizedlist>
</para>
Secondly, a brief explanation of <application>Privoxy's </application>
<quote>actions</quote>. <quote>Actions</quote> in this context, are
the directives we use to tell <application>Privoxy</application> to perform
- some task relating to WWW transactions (i.e. web browsing). We tell
+ some task relating to HTTP transactions (i.e. web browsing). We tell
<application>Privoxy</application> to take some <quote>action</quote>. Each
action has a unique name and function. While there are many potential
<application>actions</application> in <application>Privoxy's</application>
</itemizedlist>
</para>
+<para>
+ Advanced users will eventually want to explore &my-app;
+ <literal><link linkend="filter">filters</link></literal> as well. Filters
+ are very different from <literal><link
+ linkend="block">blocks</link></literal>.
+ A <quote>block</quote> blocks a site, page, or unwanted contented. Filters
+ are a way of filtering or modifying what is actually on the page. An example
+ filter usage: a text replacement of <quote>no-no</quote> for
+ <quote>nasty-word</quote>. That is a very simple example. This process can be
+ used for ad blocking, but it is more in the realm of advanced usage and has
+ some pitfalls to be wary off.
+</para>
+
<para>
The quickest way to adjust any of these settings is with your browser through
the special <application>Privoxy</application> editor at <ulink
url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
(shortcut: <ulink url="http://p.p/">http://p.p/show-status</ulink>). This
- is an internal page, and does not require Internet access. Select the
- appropriate <quote>actions</quote> file, and click
+ is an internal page, and does not require Internet access.
+</para>
+
+<para>
+ Note that as of <application>Privoxy</application> 3.0.7 beta the
+ action editor is disabled by default. Check the
+ <ulink url="config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions
+ section in the configuration file</ulink> to learn why and in which
+ cases it's safe to enable again.
+</para>
+
+<para>
+ If you decided to enable the action editor, select the appropriate
+ <quote>actions</quote> file, and click
<quote><guibutton>Edit</guibutton></quote>. It is best to put personal or
local preferences in <filename>user.action</filename> since this is not
meant to be overwritten during upgrades, and will over-ride the settings in
</para>
<literallayout>
- <guibutton>Tools</guibutton> -> <guibutton>Options</guibutton> -> <guibutton>General</guibutton> -> <guibutton>Connection Settings</guibutton> -> <guibutton>Manual Proxy Configuration</guibutton>
+ <guibutton>Tools</guibutton> -> <guibutton>Options</guibutton> -> <guibutton>Advanced</guibutton> -> <guibutton>Network</guibutton> -><guibutton>Connection</guibutton> -> <guibutton>Settings</guibutton>
</literallayout>
</literallayout>
<para>
- For <application>Internet Explorer v.5-6</application>:
+ For <application>Internet Explorer v.5-7</application>:
</para>
<literallayout>
</para>
</sect2>
-<!--
- omitting 10/31/06 HB
-
-<sect2 id="start-suse">
-<title>SuSE</title>
-<para>
-We use a script. It will use the file <filename>/etc/privoxy/config</filename>
-as its main configuration file. Note that SuSE starts Privoxy upon booting
-your PC.
-</para>
-<para>
- <screen>
- # rcprivoxy start
-</screen>
-</para>
-</sect2>
--->
<sect2 id="start-windows">
<title>Windows</title>
<para>
</sect2>
<sect2 id="start-macosx">
-<title>Mac OSX</title>
+<title>Mac OS X</title>
<para>
- During installation, <application>Privoxy</application> is configured to
- start automatically when the system restarts. To start &my-app; manually,
- double-click on the <literal>StartPrivoxy.command</literal> icon in the
- <literal>/Library/Privoxy</literal> folder. Or, type this command
- in the Terminal:
+ 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>
- <screen>
- /Library/Privoxy/StartPrivoxy.command
- </screen>
+ A simple application named Privoxy Utility has been created which
+ enables administrators to easily start and stop the privoxy service.
</para>
<para>
- You will be prompted for the administrator password.
+ 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>
</sect2>
<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>
<para>
- <application>Privoxy</application> is HTTP/1.1 compliant, but not all of
- the optional 1.1 features are as yet supported. In the unlikely event that
- you experience inexplicable problems with browsers that use HTTP/1.1 per default
+ <application>Privoxy</application> does not support all of the optional HTTP/1.1
+ features yet. In the unlikely event that you experience inexplicable problems
+ with browsers that use HTTP/1.1 per default
(like <application>Mozilla</application> or recent versions of I.E.), you might
try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit ->
Preferences -> Debug -> Networking</literal>.
<listitem>
<para>
<emphasis>--pidfile FILE</emphasis>
-
</para>
<para>
On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
<listitem>
<para>
<emphasis>--user USER[.GROUP]</emphasis>
-
</para>
<para>
After (optionally) writing the PID file, assume the user ID of
privileges are not sufficient to do so. Unix only.
</para>
</listitem>
- <listitem>
+ <listitem>
<para>
<emphasis>--chroot</emphasis>
-
</para>
<para>
Before changing to the user ID given in the <emphasis>--user</emphasis> option,
Unix only.
</para>
</listitem>
+ <listitem>
+ <para>
+ <emphasis>--pre-chroot-nslookup hostname</emphasis>
+ </para>
+ <para>
+ Specifies a hostname to look up before doing a chroot. On some systems, initializing the
+ resolver library involves reading config files from /etc and/or loading additional shared
+ libraries from /lib. On these systems, doing a hostname lookup before the chroot reduces
+ the number of files that must be copied into the chroot tree.
+ </para>
+ <para>
+ For fastest startup speed, a good value is a hostname that is not in /etc/hosts but that
+ your local name server (listed in /etc/resolv.conf) can resolve without recursion
+ (that is, without having to ask any other name servers). The hostname need not exist,
+ but if it doesn't, an error message (which can be ignored) will be output.
+ </para>
+ </listitem>
+
<listitem>
<para>
<emphasis>configfile</emphasis>
▪ <ulink url="http://config.privoxy.org/toggle">Toggle Privoxy on or off</ulink>
</member>
<member>
- ▪ <ulink url="http://www.privoxy.org/
- &p-version;/user-manual/">Documentation</ulink>
+ ▪ <ulink
+ url="http://www.privoxy.org/&p-version;/user-manual/">Documentation</ulink>
</member>
</simplelist>
</msgtext>
your browser.
</para>
+<para>
+ Note that several of the features described above are disabled by default
+ in <application>Privoxy</application> 3.0.7 beta and later.
+ Check the
+ <ulink url="config.html">configuration file</ulink> to learn why
+ and in which cases it's safe to enable them again.
+</para>
+
</sect2>
<!-- ~ End section ~ -->
</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. (There is
- one exception: <link linkend="FAST-REDIRECTS">+fast-redirects</link> which
- has enhanced syntax and will require updating any local configs from earlier
- versions.)
+ The syntax of the configuration and filter files may change between different
+ Privoxy versions, unfortunately some enhancements cost backwards compatibility.
+ <!-- Add link to documentation-->
</para>
<para>
<row>
<entry>Image tag reordering</entry>
<entry>no</entry>
- <entry>no</entry>
+ <entry>yes</entry>
<entry>yes</entry>
</row>
<para>
The list of actions files to be used are defined in the main configuration
file, and are processed in the order they are defined (e.g.
- <filename>default.action</filename> is typically process before
+ <filename>default.action</filename> is typically processed before
<filename>user.action</filename>). The content of these can all be viewed and
edited from <ulink
url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
The over-riding principle when applying actions, is that the last action that
- matches a given URL, wins. The broadest, most general rules go first
+ matches a given URL wins. The broadest, most general rules go first
(defined in <filename>default.action</filename>),
followed by any exceptions (typically also in
<filename>default.action</filename>), which are then followed lastly by any
from consulting any previous file). And then below that,
exceptions to the defined universal policies. You can regard
<filename>user.action</filename> as an appendix to <filename>default.action</filename>,
- with the advantage that is a separate file, which makes preserving your
+ with the advantage that it is a separate file, which makes preserving your
personal settings across <application>Privoxy</application> upgrades easier.
</para>
<para>
Actions can be used to block anything you want, including ads, banners, or
- just some obnoxious URL that you would rather not see. Cookies can be accepted
+ just some obnoxious URL whose content you would rather not see. Cookies can be accepted
or rejected, or accepted only during the current browser session (i.e. not
- written to disk), content can be modified, JavaScripts tamed, user-tracking
+ written to disk), content can be modified, some JavaScripts tamed, user-tracking
fooled, and much more. See below for a <link linkend="actions">complete list
of actions</link>.
</para>
will have to make later. If, for example, you want to crunch all cookies per
default, you'll have to make exceptions from that rule for sites that you
regularly use and that require cookies for actually useful purposes, like maybe
- your bank, favorite shop, or newspaper.
+ your bank, favorite shop, or newspaper.
</para>
<para>
The easiest way to edit the actions files is with a browser by
using our browser-based editor, which can be reached from <ulink
url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
- The editor allows both fine-grained control over every single feature on a
- per-URL basis, and easy choosing from wholesale sets of defaults like
- <quote>Cautious</quote>, <quote>Medium</quote> or <quote>Advanced</quote>.
- Warning: the <quote>Advanced</quote> setting is more aggressive, and
- will be more likely to cause problems for some sites. Experienced users only!
-</para>
+ Note: the config file option <link
+ linkend="enable-edit-actions">enable-edit-actions</link> must be enabled for
+ this to work. The editor allows both fine-grained control over every single
+ feature on a per-URL basis, and easy choosing from wholesale sets of defaults
+ like <quote>Cautious</quote>, <quote>Medium</quote> or
+ <quote>Advanced</quote>. Warning: the <quote>Advanced</quote> setting is more
+ aggressive, and will be more likely to cause problems for some sites.
+ Experienced users only!
+ </para>
<para>
If you prefer plain text editing to GUIs, you can of course also directly edit the
<sect2 id="actions-apply">
-<title>How Actions are Applied to URLs</title>
+<title>How Actions are Applied to Requests</title>
<para>
Actions files are divided into sections. There are special sections,
like the <quote><link linkend="aliases">alias</link></quote> sections which will
be discussed later. For now let's concentrate on regular sections: They have a
heading line (often split up to multiple lines for readability) which consist
of a list of actions, separated by whitespace and enclosed in curly braces.
- Below that, there is a list of URL patterns, each on a separate line.
+ Below that, there is a list of URL and tag patterns, each on a separate line.
</para>
<para>
To determine which actions apply to a request, the URL of the request is
- compared to all patterns in each <quote>action file</quote> file. Every time it matches, the list of
- applicable actions for the URL is incrementally updated, using the heading
- of the section in which the pattern is located. If multiple matches for
- the same URL set the same action differently, the last match wins. If not,
- the effects are aggregated. E.g. a URL might match a regular section with
- a heading line of <literal>{
+ compared to all URL patterns in each <quote>action file</quote>.
+ Every time it matches, the list of applicable actions for the request is
+ incrementally updated, using the heading of the section in which the
+ pattern is located. The same is done again for tags and tag patterns later on.
+</para>
+
+<para>
+ If multiple applying sections set the same action differently,
+ the last match wins. If not, the effects are aggregated.
+ E.g. a URL might match a regular section with a heading line of <literal>{
+<link linkend="handle-as-image">handle-as-image</link> }</literal>,
then later another one with just <literal>{
+<link linkend="block">block</link> }</literal>, resulting
<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
</para>
<para>
- You can trace this process for any given URL by visiting <ulink
+ You can trace this process for
URL patterns and any given URL by visiting <ulink
url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
</para>
</para>
<para>
- Generally, a <application>Privoxy</application> pattern has the form
+ Generally, an URL pattern has the form
<literal><domain>/<path></literal>, where both the
<literal><domain></literal> and <literal><path></literal> are
optional. (This is why the special <literal>/</literal> pattern matches all
<para>
The pattern matching syntax is different for the domain and path parts of
the URL. The domain part uses a simple globbing type matching technique,
- while the path part uses a more flexible
+ while the path part uses more flexible
<ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
- Expressions (PCRE)</quote></ulink> based syntax.
+ Expressions</quote></ulink> (POSIX 1003.2).
</para>
<variablelist>
</varlistentry>
<varlistentry>
<term><literal>www.example.com/index.html</literal></term>
+ <listitem>
+ <para>
+ matches all the documents on <literal>www.example.com</literal>
+ whose name starts with <literal>/index.html</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>www.example.com/index.html$</literal></term>
<listitem>
<para>
matches only the single document <literal>/index.html</literal>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>/index.html</literal></term>
+ <term><literal>/index.html$</literal></term>
<listitem>
<para>
matches the document <literal>/index.html</literal>, regardless of the domain,
<term><literal>index.html</literal></term>
<listitem>
<para>
- matches nothing, since it would be interpreted as a domain name and
+ matches nothing, since it would be interpreted as a domain name and
there is no top-level domain called <literal>.html</literal>. So its
a mistake.
</para>
<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>
<sect3><title>The Path Pattern</title>
<para>
- <application>Privoxy</application> uses Perl compatible (PCRE)
+ <application>Privoxy</application> uses <quote>modern</quote> POSIX 1003.2
<ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
- Expression</quote></ulink> based syntax
- (through the <ulink url="http://www.pcre.org/">PCRE</ulink> library) for
- matching the path portion (after the slash), and is thus more flexible.
+ Expressions</quote></ulink> for matching the path portion (after the slash),
+ and is thus more flexible.
</para>
<para>
There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
- expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
- 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://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>.
+ expressions, you also might want to have a look at your operating system's documentation
+ on regular expressions (try <literal>man re_format</literal>).
</para>
<para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>.example.com/.*/index.html</literal></term>
+ <term><literal>.example.com/.*/index.html$</literal></term>
<listitem>
<para>
Will match any page in the domain of <quote>example.com</quote> that is
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>.example.com/(.*/)?index\.html</literal></term>
+ <term><literal>.example.com/(.*/)?index\.html$</literal></term>
<listitem>
<para>
This regular expression is conditional so it will match any page
</sect3>
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="tag-pattern"><title>The Tag Pattern</title>
+
+<para>
+ Tag patterns are used to change the applying actions based on the
+ request's tags. Tags can be created with either the
+ <link linkend="CLIENT-HEADER-TAGGER">client-header-tagger</link>
+ or the <link linkend="SERVER-HEADER-TAGGER">server-header-tagger</link> action.
+</para>
+
+<para>
+ Tag patterns have to start with <quote>TAG:</quote>, so &my-app;
+ 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 (&my-app; doesn't silently add a <quote>^</quote>,
+ you have to do it yourself if you need it).
+</para>
+
+<para>
+ To match all requests that are tagged with <quote>foo</quote>
+ your pattern line should be <quote>TAG:^foo$</quote>,
+ <quote>TAG:foo</quote> would work as well, but it would also
+ match requests whose tags contain <quote>foo</quote> somewhere.
+ <quote>TAG: foo</quote> wouldn't work as it requires white space.
+</para>
+
+<para>
+ Sections can contain URL and tag patterns at the same time,
+ but tag patterns are checked after the URL patterns and thus
+ always overrule them, even if they are located before the URL patterns.
+</para>
+
+<para>
+ Once a new tag is added, Privoxy checks right away if it's matched by one
+ of the tag patterns and updates the action settings accordingly. As a result
+ tags can be used to activate other tagger actions, as long as these other
+ taggers look for headers that haven't already be parsed.
+</para>
+
+<para>
+ 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.
+</para>
+
+<para>
+ While this is a limitation you should be aware of, this kind of
+ indirection is seldom needed anyway and even the example doesn't
+ make too much sense.
+</para>
+
+</sect3>
+
</sect2>
<!-- ~ End section ~ -->
-<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>
the last match wins, i.e. the params from earlier matches are simply ignored.
</para>
<para>
- Example: <literal>+hide-user-agent{ Mozilla 1.0 }</literal>
+ Example: <literal>+hide-user-agent{Mozilla/5.0 (X11; U; FreeBSD i386; en-US; rv:1.8.1.4) Gecko/20070602 Firefox/2.0.0.4}</literal>
</para>
</listitem>
<para>
If nothing is specified in any actions file, no <quote>actions</quote> are
taken. So in this case <application>Privoxy</application> would just be a
- normal, non-blocking, non-anonymizing proxy. You must specifically enable the
+ normal, non-blocking, non-filtering proxy. You must specifically enable the
privacy and blocking features you need (although the provided default actions
files will give a good starting point).
</para>
<para>
- Later defined actions always over-ride earlier ones. So exceptions
- to any rules you make, should come in the latter part of the file (or
+ Later defined action sections always over-ride earlier ones of the same type.
+ So exceptions to any rules you make, should come in the latter part of the file (or
in a file that is processed later when using multiple actions files such
as <filename>user.action</filename>). For multi-valued actions, the actions
are applied in the order they are specified. Actions files are processed in
<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
- 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>.
+ 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>
<para>
A very important exception occurs if <emphasis>both</emphasis>
<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>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="content-type-overwrite">
-<!--
-new action
--->
-<title>content-type-overwrite</title>
+<sect3 renderas="sect4" id="client-header-filter">
+<title>client-header-filter</title>
<variablelist>
<varlistentry>
<term>Typical use:</term>
<listitem>
- <para>Stop useless download menus from popping up, or change the browser's rendering mode</para>
+ <para>
+ Rewrite or remove single client headers.
+ </para>
</listitem>
</varlistentry>
<term>Effect:</term>
<listitem>
<para>
- Replaces the <quote>Content-Type:</quote> HTTP server header.
+ All client headers to which this action applies are filtered on-the-fly through
+ the specified regular expression based substitutions.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ The name of a client-header filter, as defined in one of the
+ <link linkend="filter-file">filter files</link>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Client-header filters are applied to each header on its own, not to
+ 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.
+ You can do that by using tags though.
+ </para>
+ <para>
+ Client-header filters are executed after the other header actions have finished
+ and use their output as input.
+ </para>
+ <para>
+ If the request URL gets changed, &my-app; will detect that and use the new
+ one. This can be used to rewrite the request destination behind the client's
+ back, for example to specify a Tor exit relay for certain requests.
+ </para>
+ <para>
+ Please refer to the <link linkend="filter-file">filter file chapter</link>
+ to learn which client-header filters are available by default, and how to
+ create your own.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen>
+# Hide Tor exit notation in Host and Referer Headers
+{+client-header-filter{hide-tor-exit-notation}}
+/
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="client-header-tagger">
+<title>client-header-tagger</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ Block requests based on their headers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Client headers to which this action applies are filtered on-the-fly through
+ the specified regular expression based substitutions, the result is used as
+ tag.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ The name of a client-header tagger, as defined in one of the
+ <link linkend="filter-file">filter files</link>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Client-header taggers are applied to each header on its own,
+ and as the header isn't modified, each tagger <quote>sees</quote>
+ the original.
+ </para>
+ <para>
+ Client-header taggers are the first actions that are executed
+ and their tags can be used to control every other action.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen>
+# Tag every request with the User-Agent header
+{+client-header-tagger{user-agent}}
+/
+
+# Tagging itself doesn't change the action
+# settings, sections with TAG patterns do:
+#
+# If it's a download agent, use a different forwarding proxy,
+# show the real User-Agent and make sure resume works.
+{+forward-override{forward-socks5 10.0.0.2:2222 .} \
+ -hide-if-modified-since \
+ -overwrite-last-modified \
+ -hide-user-agent \
+ -filter \
+ -deanimate-gifs \
+}
+TAG:^User-Agent: NetBSD-ftp/
+TAG:^User-Agent: Novell ZYPP Installer
+TAG:^User-Agent: RPM APT-HTTP/
+TAG:^User-Agent: fetch libfetch/
+TAG:^User-Agent: Ubuntu APT-HTTP/
+TAG:^User-Agent: MPlayer/
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="content-type-overwrite">
+<title>content-type-overwrite</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Stop useless download menus from popping up, or change the browser's rendering mode</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Replaces the <quote>Content-Type:</quote> HTTP server header.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
<listitem>
<para>Parameterized.</para>
</listitem>
This limitation exists for a reason, think twice before circumventing it.
</para>
<para>
- Most of the time it's easier to enable
- <literal><link linkend="filter-server-headers">filter-server-headers</link></literal>
- and replace this action with a custom regular expression. It allows you
- to activate it for every document of a certain site and it will still
+ Most of the time it's easier to replace this action with a custom
+ <literal><link linkend="server-header-filter">server-header filter</link></literal>.
+ It allows you to activate it for every document of a certain site and it will still
only replace the content types you aimed at.
</para>
<para>
<para>
<literal>crunch-client-header</literal> is only meant for quick tests.
If you have to block several different headers, or only want to modify
- parts of them, you should enable
- <literal><link linkend="filter-client-headers">filter-client-headers</link></literal>
- and create your own filter.
+ parts of them, you should use a
+ <literal><link linkend="client-header-filter">client-header filter</link></literal>.
</para>
<warning>
<para>
</para>
<para>
It is also useful to make sure the header isn't used as a cookie
- replacement.
+ replacement (unlikely but possible).
</para>
<para>
Blocking the <quote>If-None-Match:</quote> header shouldn't cause any
caching problems, as long as the <quote>If-Modified-Since:</quote> header
- isn't blocked as well.
+ isn't blocked or missing as well.
</para>
<para>
It is recommended to use this action together with
<term>Example usage (section):</term>
<listitem>
<para>
- <screen># Let the browser revalidate cached documents without being tracked across sessions
-{ +hide-if-modified-since{-60} \
+ <screen># Let the browser revalidate cached documents but don't
+# allow the server to use the revalidation headers for user tracking.
+{+hide-if-modified-since{-60} \
+overwrite-last-modified{randomize} \
+crunch-if-none-match}
/ </screen>
<term>Typical use:</term>
<listitem>
<para>
- Prevent the web server from setting any cookies on your system
+ Prevent the web server from setting HTTP cookies on your system
</para>
</listitem>
</varlistentry>
<term>Notes:</term>
<listitem>
<para>
- This action is only concerned with <emphasis>incoming</emphasis> cookies. For
- <emphasis>outgoing</emphasis> cookies, use
+ This action is only concerned with <emphasis>incoming</emphasis> HTTP cookies. For
+ <emphasis>outgoing</emphasis> HTTP cookies, use
<literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>.
- Use <emphasis>both</emphasis> to disable cookies completely.
+ Use <emphasis>both</emphasis> to disable HTTP cookies completely.
</para>
<para>
It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
<para>
<literal>crunch-server-header</literal> is only meant for quick tests.
If you have to block several different headers, or only want to modify
- parts of them, you should enable
- <literal><link linkend="filter-server-headers">filter-server-headers</link></literal>
- and create your own filter.
+ parts of them, you should use a custom
+ <literal><link linkend="server-header-filter">server-header filter</link></literal>.
</para>
<warning>
<para>
<term>Typical use:</term>
<listitem>
<para>
- Prevent the web server from reading any cookies from your system
+ Prevent the web server from reading any HTTP cookies from your system
</para>
</listitem>
</varlistentry>
<term>Notes:</term>
<listitem>
<para>
- This action is only concerned with <emphasis>outgoing</emphasis> cookies. For
- <emphasis>incoming</emphasis> cookies, use
+ This action is only concerned with <emphasis>outgoing</emphasis> HTTP cookies. For
+ <emphasis>incoming</emphasis> HTTP cookies, use
<literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>.
- Use <emphasis>both</emphasis> to disable cookies completely.
+ Use <emphasis>both</emphasis> to disable HTTP cookies completely.
</para>
<para>
It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
This is a left-over from the time when <application>Privoxy</application>
didn't support important HTTP/1.1 features well. It is left here for the
unlikely case that you experience HTTP/1.1 related problems with some server
- out there. Not all (optional) HTTP/1.1 features are supported yet, so there
- is a chance you might need this action.
+ out there. Not all HTTP/1.1 features and requirements are supported yet,
+ so there is a chance you might need this action.
</para>
</listitem>
</varlistentry>
followed by another parameter. <literal>fast-redirects</literal> doesn't know that
and will cause a redirect to <quote>http://www.example.net/&foo=bar</quote>.
Depending on the target server configuration, the parameter will be silently ignored
- or lead to a <quote>page not found</quote> error. It is possible to fix these redirected
- requests with <literal><link linkend="filter-client-headers">filter-client-headers</link></literal>
- but it requires a little effort.
+ or lead to a <quote>page not found</quote> error. You can prevent this problem by
+ first using the <literal><link linkend="redirect">redirect</link></literal> action
+ to remove the last part of the URL, but it requires a little effort.
</para>
<para>
To detect a redirection URL, <literal>fast-redirects</literal> only
<para>
<screen>
{ +fast-redirects{simple-check} }
- .example.com
+ one.example.com
{ +fast-redirects{check-decoded-url} }
another.example.com/testing</screen>
<term>Effect:</term>
<listitem>
<para>
- All files of text-based type, most notably HTML and
- JavaScript, to which this action applies, can be filtered on-the-fly
- through the specified regular expression 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.) By default, filtering works only on the
- raw document content itself (that which can be seen with <literal>View
- Source</literal>),
- not the headers.
+ All instances of text-based type, most notably HTML and JavaScript, to which
+ this action applies, can be filtered on-the-fly through the specified regular
+ expression 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.)
</para>
</listitem>
</varlistentry>
<term>Parameter:</term>
<listitem>
<para>
- The name of a filter, as defined in the <link linkend="filter-file">filter file</link>.
+ The name of a content filter, as defined in the <link linkend="filter-file">filter file</link>.
Filters can be defined in one or more files as defined by the
<literal><link linkend="filterfile">filterfile</link></literal>
option in the <link linkend="config">config file</link>.
by defining appropriate <literal>-filter</literal> exceptions.
</para>
<para>
- At this time, <application>Privoxy</application> cannot uncompress compressed
- documents. If you want filtering to work on all documents, even those that
- would normally be sent compressed, you must use the
- <literal><link linkend="prevent-compression">prevent-compression</link></literal>
+ Compressed content can't be filtered either, unless &my-app;
+ is compiled with zlib support (requires at least &my-app; 3.0.7),
+ in which case &my-app; will decompress the content before filtering
+ it.
+ </para>
+ <para>
+ If you use a &my-app; version without zlib support, but want filtering to work on
+ as much documents as possible, even those that would normally be sent compressed,
+ you must use the <literal><link linkend="prevent-compression">prevent-compression</link></literal>
action in conjunction with <literal>filter</literal>.
</para>
<para>
- Filtering can achieve some of the same effects as the
+ Content filtering can achieve some of the same effects as the
<literal><link linkend="block">block</link></literal>
action, i.e. it can be used to block ads and banners. But the mechanism
works quite differently. One effective use, is to block ad banners
<listitem>
<para>
<anchor id="filter-js-annoyances">
- <screen>+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse</screen>
+ <screen>+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse.</screen>
</para>
<para>
<anchor id="filter-js-events">
- <screen>+filter{js-events} # Kill all JS event bindings (Radically destructive! Only for extra nasty sites)</screen>
+ <screen>+filter{js-events} # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites).</screen>
</para>
<para>
<anchor id="filter-html-annoyances">
- <screen>+filter{html-annoyances} # Get rid of particularly annoying HTML abuse</screen>
+ <screen>+filter{html-annoyances} # Get rid of particularly annoying HTML abuse.</screen>
</para>
<para>
<anchor id="filter-content-cookies">
- <screen>+filter{content-cookies} # Kill cookies that come in the HTML or JS content</screen>
+ <screen>+filter{content-cookies} # Kill cookies that come in the HTML or JS content.</screen>
</para>
<para>
<anchor id="filter-refresh-tags">
- <screen>+filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups)</screen>
+ <screen>+filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups).</screen>
</para>
<para>
<anchor id="filter-unsolicited-popups">
</para>
<para>
<anchor id="filter-img-reorder">
- <screen>+filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective</screen>
+ <screen>+filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective.</screen>
</para>
<para>
<anchor id="filter-banners-by-size">
- <screen>+filter{banners-by-size} # Kill banners by size</screen>
+ <screen>+filter{banners-by-size} # Kill banners by size.</screen>
</para>
<para>
<anchor id="filter-banners-by-link">
- <screen>+filter{banners-by-link} # Kill banners by their links to known clicktrackers</screen>
+ <screen>+filter{banners-by-link} # Kill banners by their links to known clicktrackers.</screen>
</para>
<para>
<anchor id="filter-webbugs">
- <screen>+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking)</screen>
+ <screen>+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking).</screen>
</para>
<para>
<anchor id="filter-tiny-textforms">
- <screen>+filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap</screen>
+ <screen>+filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap.</screen>
</para>
<para>
<anchor id="filter-jumping-windows">
- <screen>+filter{jumping-windows} # Prevent windows from resizing and moving themselves</screen>
+ <screen>+filter{jumping-windows} # Prevent windows from resizing and moving themselves.</screen>
</para>
<para>
<anchor id="filter-frameset-borders">
- <screen>+filter{frameset-borders} # Give frames a border and make them resizeable</screen>
+ <screen>+filter{frameset-borders} # Give frames a border and make them resizable.</screen>
</para>
<para>
<anchor id="filter-demoronizer">
- <screen>+filter{demoronizer} # Fix MS's non-standard use of standard charsets</screen>
+ <screen>+filter{demoronizer} # Fix MS's non-standard use of standard charsets.</screen>
</para>
<para>
<anchor id="filter-shockwave-flash">
- <screen>+filter{shockwave-flash} # Kill embedded Shockwave Flash objects</screen>
+ <screen>+filter{shockwave-flash} # Kill embedded Shockwave Flash objects.</screen>
</para>
<para>
<anchor id="filter-quicktime-kioskmode">
- <screen>+filter{quicktime-kioskmode} # Make Quicktime movies savable</screen>
+ <screen>+filter{quicktime-kioskmode} # Make Quicktime movies saveable.</screen>
</para>
<para>
<anchor id="filter-fun">
</para>
<para>
<anchor id="filter-crude-parental">
- <screen>+filter{crude-parental} # Crude parental filtering (demo only)</screen>
+ <screen>+filter{crude-parental} # Crude parental filtering. Note that this filter doesn't work reliably.</screen>
</para>
<para>
<anchor id="filter-ie-exploits">
- <screen>+filter{ie-exploits} # Disable some known Internet Explorer bug exploits</screen>
+ <screen>+filter{ie-exploits} # Disable some known Internet Explorer bug exploits.</screen>
</para>
<para>
<anchor id="filter-site-specifics">
- <screen>+filter{site-specifics} # Custom filters for specific site related problems</screen>
+ <screen>+filter{site-specifics} # Cure for site-specific problems. Don't apply generally!</screen>
+ </para>
+ <para>
+ <anchor id="filter-no-ping">
+ <screen>+filter{no-ping} # Removes non-standard ping attributes in <a> and <area> tags.</screen>
</para>
<para>
<anchor id="filter-google">
- <screen>+filter{google} # Removes text ads and other Google specific improvements</screen>
+ <screen>+filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement.</screen>
</para>
<para>
<anchor id="filter-yahoo">
- <screen>+filter{yahoo} # Removes text ads and other Yahoo specific improvements</screen>
+ <screen>+filter{yahoo} # CSS-based block for Yahoo text ads. Also removes a width limitation.</screen>
</para>
<para>
<anchor id="filter-msn">
- <screen>+filter{msn} # Removes text ads and other MSN specific improvements</screen>
+ <screen>+filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation.</screen>
</para>
<para>
<anchor id="filter-blogspot">
- <screen>+filter{blogspot} # Cleans up Blogspot blogs</screen>
- </para>
- <para>
- <anchor id="filter-html-to-xml">
- <screen>+filter{html-to-xml} # Header filter to change the Content-Type from html to xml</screen>
- </para>
- <para>
- <anchor id="filter-xml-to-html">
- <screen>+filter{xml-to-html} # Header filter to change the Content-Type from xml to html</screen>
- </para>
- <para>
- <anchor id="filter-no-ping">
- <screen>+filter{no-ping} # Removes non-standard ping attributes from anchor and area tags</screen>
- </para>
- <para>
- <anchor id="filter-hide-tor-exit-notation">
- <screen>+filter{hide-tor-exit-notation} # Header filter to remove the Tor exit node notation in Host and Referer headers</screen>
+ <screen>+filter{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this.</screen>
</para>
</listitem>
</varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="filter-client-headers">
-<title>filter-client-headers</title>
-
+<sect3 renderas="sect4" id="force-text-mode">
+<title>force-text-mode</title>
+<!--
+new action
+-->
<variablelist>
<varlistentry>
<term>Typical use:</term>
<listitem>
- <para>
- To apply filtering to the client's (browser's) headers
- </para>
+ <para>Force <application>Privoxy</application> to treat a document as if it was in some kind of <emphasis>text</emphasis> format. </para>
</listitem>
</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>
+ Declares a document as text, even if the <quote>Content-Type:</quote> isn't detected as such.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type:</term>
- <!-- boolean, parameterized, Multi-value -->
+ <!-- Boolean, Parameterized, Multi-value -->
<listitem>
<para>Boolean.</para>
</listitem>
</para>
</listitem>
</varlistentry>
-
-<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.
+ As explained <literal><link linkend="filter">above</link></literal>,
+ <application>Privoxy</application> tries to only filter files that are
+ in some kind of text format. The same restrictions apply to
+ <literal><link linkend="content-type-overwrite">content-type-overwrite</link></literal>.
+ <literal>force-text-mode</literal> declares a document as text,
+ without looking at the <quote>Content-Type:</quote> first.
</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>
+ <warning>
<para>
- <screen>
-{+filter-client-headers +filter{test_filter}}
-problem-host.example.com
- </screen>
+ Think twice before activating this action. Filtering binary data
+ with regular expressions can cause file damage.
</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>
+ </warning>
</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>
+ <term>Example usage:</term>
<listitem>
+ <para>
<screen>
-{+filter-server-headers +filter{test_filter}}
-problem-host.example.com
- </screen>
- </para>
++force-text-mode
+ </screen>
+ </para>
</listitem>
</varlistentry>
-
</variablelist>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="force-text-mode">
-<title>force-text-mode</title>
+<sect3 renderas="sect4" id="forward-override">
+<title>forward-override</title>
<!--
new action
-->
<varlistentry>
<term>Typical use:</term>
<listitem>
- <para>Force <application>Privoxy</application> to treat a document as if it was in some kind of <emphasis>text</emphasis> format. </para>
+ <para>Change the forwarding settings based on User-Agent or request origin</para>
</listitem>
</varlistentry>
<term>Effect:</term>
<listitem>
<para>
- Declares a document as text, even if the <quote>Content-Type:</quote> isn't detected as such.
+ Overrules the forward directives in the configuration file.
</para>
</listitem>
</varlistentry>
<term>Type:</term>
<!-- Boolean, Parameterized, Multi-value -->
<listitem>
- <para>Boolean.</para>
+ <para>Multi-value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Parameter:</term>
<listitem>
- <para>
- N/A
- </para>
+ <itemizedlist>
+ <listitem>
+ <para><quote>forward .</quote> to use a direct connection without any additional proxies.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <quote>forward 127.0.0.1:8123</quote> to use the HTTP proxy listening at 127.0.0.1 port 8123.
+ </para>
+ </listitem>
+ <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, use <quote>forward-socks5</quote>
+ for socks5 connections (with remote DNS resolution).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <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, use <quote>forward-socks5</quote>
+ for socks5 connections (with remote DNS resolution).
+ </para>
+ </listitem>
+ </itemizedlist>
</listitem>
</varlistentry>
<term>Notes:</term>
<listitem>
<para>
- As explained <literal><link linkend="filter">above</link></literal>,
- <application>Privoxy</application> tries to only filter files that are
- in some kind of text format. The same restrictions apply to
- <literal><link linkend="content-type-overwrite">content-type-overwrite</link></literal>.
- <literal>force-text-mode</literal> declares a document as text,
- without looking at the <quote>Content-Type:</quote> first.
+ 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.
</para>
<warning>
<para>
- Think twice before activating this action. Filtering binary data
- with regular expressions can cause file damage.
+ Please read the description for the <link linkend="forwarding">forward</link> directives before
+ using this action. Forwarding to the wrong people will reduce your privacy and increase the
+ chances of man-in-the-middle attacks.
+ </para>
+ <para>
+ If the ports are missing or invalid, default values will be used. This might change
+ in the future and you shouldn't rely on it. Otherwise incorrect syntax causes Privoxy
+ to exit.
+ </para>
+ <para>
+ Use the <ulink url="http://config.privoxy.org/show-url-info">show-url-info CGI page</ulink>
+ to verify that your forward settings do what you thought the do.
</para>
</warning>
</listitem>
<listitem>
<para>
<screen>
-+force-text-mode
+# Always use direct connections for requests previously tagged as
+# <quote>User-Agent: fetch libfetch/2.0</quote> and make sure
+# resuming downloads continues to work.
+# This way you can continue to use Tor for your normal browsing,
+# without overloading the Tor network with your FreeBSD ports updates
+# or downloads of bigger files like ISOs.
+# Note that HTTP headers are easy to fake and therefore their
+# values are as (un)trustworthy as your clients and users.
+{+forward-override{forward .} \
+ -hide-if-modified-since \
+ -overwrite-last-modified \
+}
+TAG:^User-Agent: fetch libfetch/2\.0$
</screen>
</para>
</listitem>
<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>
to another one, but in most cases it isn't worth the time to set
it up.
</para>
+ <para>
+ This action will probably be removed in the future,
+ use server-header filters instead.
+ </para>
</listitem>
</varlistentry>
</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>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="hide-forwarded-for-headers">
<title>hide-forwarded-for-headers</title>
-<!--
-new action
--->
<variablelist>
<varlistentry>
<term>Typical use:</term>
<listitem>
- <para>Improve privacy by hiding the true source of the request</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 fairly safe to leave this on.
- </para>
- <para>
- This action is scheduled for improvement: It should be able to generate forged
- <quote>X-Forwarded-for:</quote> headers using random IP addresses from a specified network,
- to make successive requests from the same client look like requests from a pool of different
- users sharing the same proxy.
+ 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>
browsers will access the same <application>Privoxy</application> is
<emphasis>not recommended</emphasis>. In single-user, single-browser
setups, you might use it to delete your OS version information from
- the headers, because it is an invitation to exploit known bugs for your
- OS. It is also occasionally useful to forge this in order to access
- sites that won't let you in otherwise (though there may be a good
- reason in some cases). Example of this: some MSN sites will not
- let <application>Mozilla</application> enter, yet forging to a
- <application>Netscape 6.1</application> user-agent works just fine.
- (Must be just a silly MS goof, I'm sure :-).
- </para>
- <para>
- This action is scheduled for improvement.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen>+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ 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>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Protect against a known exploit
- </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>
- See Microsoft Security Bulletin MS04-028. JPEG images are one of the most
- common image types found across the Internet. The exploit as described can
- 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 unwanted intrusion.
- </para>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para><screen>+inspect-jpegs</screen></para>
- </listitem>
- </varlistentry>
-</variablelist>
-</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.
+ the headers, because it is an invitation to exploit known bugs for your
+ OS. It is also occasionally useful to forge this in order to access
+ sites that won't let you in otherwise (though there may be a good
+ reason in some cases). Example of this: some MSN sites will not
+ let <application>Mozilla</application> enter, yet forging to a
+ <application>Netscape 6.1</application> user-agent works just fine.
+ (Must be just a silly MS goof, I'm sure :-).
</para>
-
- <!--
<para>
- An alternate spelling is <literal>+kill-popup</literal>, which is
- interchangeable.
+ More information on known user-agent strings can be found at
+ <ulink url="http://www.user-agents.org/">http://www.user-agents.org/</ulink>
+ and
+ <ulink url="http://en.wikipedia.org/wiki/User_agent">http://en.wikipedia.org/wiki/User_agent</ulink>.
</para>
- -->
- </listitem>
+ </listitem>
</varlistentry>
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para><screen>+kill-popups</screen></para>
+ <para>
+ <screen>+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}</screen>
+ </para>
</listitem>
</varlistentry>
</variablelist>
<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
<listitem>
<para>
More and more websites send their content compressed by default, which
- is generally a good idea and saves bandwidth. But for 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 to work,
- <application>Privoxy</application> needs access to the uncompressed data.
- Unfortunately, <application>Privoxy</application> can't yet(!) uncompress, filter, and
- re-compress the content on the fly. So if you want to ensure that all websites, including
- those that normally compress, can be filtered, you need to use this action.
+ is generally a good idea and saves bandwidth. But the <literal><link
+ 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
+ filtered is decompressed on-the-fly and you don't have to worry about this action.
+ If you are using an older &my-app; version, or one that hasn't been compiled with zlib
+ support, this action can be used to convince the server to send the content uncompressed.
</para>
<para>
- This will slow down transfers from those websites, though. If you use any of the above-mentioned
- actions, you will typically want to use <literal>prevent-compression</literal> in conjunction
- with them.
+ Most text-based instances compress very well, the size is seldom decreased by less than 50%,
+ for markup-heavy instances like news feeds saving more than 90% of the original size isn't
+ unusual.
+ </para>
+ <para>
+ Not using compression will therefore slow down the transfer, and you should only
+ enable this action if you really need it. As of &my-app; 3.0.7 it's disabled in all
+ predefined action settings.
</para>
<para>
Note that some (rare) ill-configured sites don't handle requests for uncompressed
- documents correctly (they send an empty document body). If you use <literal>prevent-compression</literal>
- per default, you'll have to add exceptions for those sites. See the example for how to do that.
+ documents correctly. Broken PHP applications tend to send an empty document body,
+ some IIS versions only send the beginning of the content. If you enable
+ <literal>prevent-compression</literal> per default, you might want to add
+ exceptions for those sites. See the example for how to do that.
</para>
</listitem>
</varlistentry>
{ +prevent-compression }
/ # Match all sites
-# Then maybe make exceptions for ill-behaved sites:
+# Then maybe make exceptions for broken sites:
#
{ -prevent-compression }
- .debianhelp.org
- www.pclinuxonline.com</screen>
+.compusa.com/</screen>
</para>
</listitem>
</varlistentry>
<term>Parameter:</term>
<listitem>
<para>
- Any URL.
+ An absolute URL or a single pcrs command.
</para>
</listitem>
</varlistentry>
<term>Notes:</term>
<listitem>
<para>
- This action is useful to replace whole documents with ones of your
- choosing. This can be used to enforce safe surfing, or just as a simple
- convenience.
- </para>
- <para>
- You can do the same by combining the actions
- <literal><link linkend="block">block</link></literal>,
- <literal><link linkend="handle-as-image">handle-as-image</link></literal> and
- <literal><link linkend="set-image-blocker">set-image-blocker{URL}</link></literal>.
- It doesn't sound right for non-image documents, and that's why this action
- was created.
+ Requests to which this action applies are answered with a
+ HTTP redirect to URLs of your choosing. The new URL is
+ either provided as parameter, or derived by applying a
+ single pcrs command to the original URL.
</para>
<para>
This action will be ignored if you use it together with
<literal><link linkend="block">block</link></literal>.
+ It can be combined with
+ <literal><link linkend="fast-redirects">fast-redirects{check-decoded-url}</link></literal>
+ to redirect to a decoded version of a rewritten URL.
+ </para>
+ <para>
+ Use this action carefully, make sure not to create redirection loops
+ and be aware that using your own redirects might make it
+ possible to fingerprint your requests.
+ </para>
+ <para>
+ In case of problems with your redirects, or simply to watch
+ them working, enable <link linkend="DEBUG">debug 128</link>.
</para>
</listitem>
</varlistentry>
example.com/stylesheet\.css
# Create a short, easy to remember nickname for a favorite site
+# (relies on the browser accept and forward invalid URLs to &my-app;)
{ +redirect{http://www.privoxy.org/user-manual/actions-file.html} }
- a</screen>
+ a
+
+# Always use the expanded view for Undeadly.org articles
+# (Note the $ at the end of the URL pattern to make sure
+# the request for the rewritten URL isn't redirected as well)
+{+redirect{s@$@&mode=expanded@}}
+undeadly.org/cgi\?action=article&sid=\d*$
+
+# Redirect Google search requests to MSN
+{+redirect{s@^http://[^/]*/search\?q=([^&]*).*@http://search.msn.com/results.aspx?q=$1@}}
+.google.com/search
+
+# Redirect MSN search requests to Yahoo
+{+redirect{s@^http://[^/]*/results\.aspx\?q=([^&]*).*@http://search.yahoo.com/search?p=$1@}}
+search.msn.com//results\.aspx\?q=
+
+# Redirect remote requests for this manual
+# to the local version delivered by Privoxy
+{+redirect{s@^http://www@http://config@}}
+www.privoxy.org/user-manual/</screen>
</para>
</listitem>
</varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="send-vanilla-wafer">
-<title>send-vanilla-wafer</title>
+<sect3 renderas="sect4" id="server-header-filter">
+<title>server-header-filter</title>
<variablelist>
<varlistentry>
<term>Typical use:</term>
<listitem>
<para>
- Feed log analysis scripts with useless data.
+ Rewrite or remove single server headers.
</para>
</listitem>
</varlistentry>
<term>Effect:</term>
<listitem>
<para>
- Sends a cookie with each request stating that you do not accept any copyright
- on cookies sent to you, and asking the site operator not to track you.
+ All server headers to which this action applies are filtered on-the-fly
+ through the specified regular expression based substitutions.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
+ <!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>Boolean.</para>
+ <para>Parameterized.</para>
</listitem>
</varlistentry>
<term>Parameter:</term>
<listitem>
<para>
- N/A
+ The name of a server-header filter, as defined in one of the
+ <link linkend="filter-file">filter files</link>.
</para>
</listitem>
</varlistentry>
<term>Notes:</term>
<listitem>
<para>
- The vanilla wafer is a (relatively) unique header and could conceivably be used to track you.
+ Server-header filters are applied to each header on its own, not to
+ 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.
+ You can do that by using tags though.
</para>
<para>
- This action is rarely used and not enabled in the default configuration.
+ Server-header filters are executed after the other header actions have finished
+ and use their output as input.
</para>
- </listitem>
+ <para>
+ Please refer to the <link linkend="filter-file">filter file chapter</link>
+ to learn which server-header filters are available by default, and how to
+ create your own.
+ </para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>Example usage:</term>
+ <term>Example usage (section):</term>
<listitem>
- <para>
- <screen>+send-vanilla-wafer</screen>
- </para>
+ <para>
+ <screen>
+{+server-header-filter{html-to-xml}}
+example.org/xml-instance-that-is-delivered-as-html
+
+{+server-header-filter{xml-to-html}}
+example.org/instance-that-is-delivered-as-xml-but-is-not
+ </screen>
+ </para>
</listitem>
</varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="send-wafer">
-<title>send-wafer</title>
+<sect3 renderas="sect4" id="server-header-tagger">
+<title>server-header-tagger</title>
<variablelist>
<varlistentry>
<term>Typical use:</term>
<listitem>
<para>
- Send custom cookies or feed log analysis scripts with even more useless data.
+ Enable or disable filters based on the Content-Type header.
</para>
</listitem>
</varlistentry>
<term>Effect:</term>
<listitem>
<para>
- Sends a custom, user-defined cookie with each request.
+ Server headers to which this action applies are filtered on-the-fly through
+ the specified regular expression based substitutions, the result is used as
+ tag.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
+ <!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>Multi-value.</para>
+ <para>Parameterized.</para>
</listitem>
</varlistentry>
<term>Parameter:</term>
<listitem>
<para>
- A string of the form <quote><replaceable class="option">name</replaceable>=<replaceable
- class="parameter">value</replaceable></quote>.
+ The name of a server-header tagger, as defined in one of the
+ <link linkend="filter-file">filter files</link>.
</para>
</listitem>
</varlistentry>
<term>Notes:</term>
<listitem>
<para>
- Being multi-valued, multiple instances of this action can apply to the same request,
- resulting in multiple cookies being sent.
+ Server-header taggers are applied to each header on its own,
+ and as the header isn't modified, each tagger <quote>sees</quote>
+ the original.
</para>
<para>
- This action is rarely used and not enabled in the default configuration.
+ Server-header taggers are executed before all other header actions
+ that modify server headers. Their tags can be used to control
+ all of the other server-header actions, the content filters
+ and the crunch actions (<link linkend="redirect">redirect</link>
+ and <link linkend="block">block</link>).
</para>
- </listitem>
+ <para>
+ Obviously crunching based on tags created by server-header taggers
+ doesn't prevent the request from showing up in the server's log file.
+ </para>
+
+ </listitem>
</varlistentry>
+
<varlistentry>
<term>Example usage (section):</term>
<listitem>
- <para>
- <screen>{+send-wafer{UsingPrivoxy=true}}
-my-internal-testing-server.void</screen>
- </para>
+ <para>
+ <screen>
+# Tag every request with the content type declared by the server
+{+server-header-tagger{content-type}}
+/
+ </screen>
+ </para>
</listitem>
</varlistentry>
+
</variablelist>
</sect3>
<screen>+set-image-blocker{pattern}</screen>
</para>
<para>
- Redirect to the BSD devil:
+ Redirect to the BSD daemon:
</para>
<para>
<screen>+set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif}</screen>
</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> link becomes rather useless:
- it lets the client request the home page of the forbidden host
- through unencrypted HTTP, still using the port of the last request.
- </para>
- <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 respond with an error message because it is expecting
- HTTPS (SSL).
- </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="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-CLIENT-HEADERS">filter-client-headers</link> \
- -<link linkend="FILTER-SERVER-HEADERS">filter-server-headers</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-XML-TO-HTML">filter-xml-to-html</link> \
- -<link linkend="FILTER-HTML-TO-XML">filter-html-to-xml</link> \
- -<link linkend="FILTER-NO-PING">filter-no-ping</link> \
- -<link linkend="FILTER-HIDE-TOR-EXIT-NOTATION">filter-hide-tor-exit-notation</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>
- 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>
<title>Filter Files</title>
<para>
- On-the-fly text substitutions that can be invoked through the
- <literal><link linkend="filter">filter</link></literal> action need
+ On-the-fly text substitutions need
to be defined in a <quote>filter file</quote>. Once defined, they
- can then be invoked as an <quote>action</quote>. Multiple filter files can be
- defined through the <literal> <link
+ can then be invoked as an <quote>action</quote>.
+</para>
+
+<para>
+ &my-app; supports three different filter actions:
+ <literal><link linkend="filter">filter</link></literal> to
+ rewrite the content that is send to the client,
+ <literal><link linkend="client-header-filter">client-header-filter</link></literal>
+ 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.
+</para>
+
+<para>
+ &my-app; also supports two tagger actions:
+ <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 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>
+
+
+<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>
- Typical reasons for doing these kinds of substitutions are to eliminate
- common annoyances in HTML and JavaScript, such as pop-up windows,
+ 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
width and height attributes (standard banner sizes or web-bugs),
- or just to have fun. The possibilities are endless.
+ or just to have fun.
+</para>
+
+<para>
+ 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>
- 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>).
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. By default, filters are only applied
- to the raw document content, but can be extended to the HTTP headers with
- the supplemental actions:
- <link linkend="filter-client-headers">filter-client-headers</link> and
- <link linkend="filter-server-headers">filter-server-headers</link>.
+ and, of course, regular expressions.
</para>
<para>
Just like the <link linkend="actions-file">actions files</link>, the
filter file is organized in sections, which are called <emphasis>filters</emphasis>
- here. Each filter consists of a heading line, that starts with the
- <emphasis>keyword</emphasis> <literal>FILTER:</literal>, followed by
- the filter's <emphasis>name</emphasis>, and a short (one line)
+ here. Each filter consists of a heading line, that starts with one of the
+ <emphasis>keywords</emphasis> <literal>FILTER:</literal>,
+ <literal>CLIENT-HEADER-FILTER:</literal> or <literal>SERVER-HEADER-FILTER:</literal>
+ followed by the filter's <emphasis>name</emphasis>, and a short (one line)
<emphasis>description</emphasis> of what it does. Below that line
come the <emphasis>jobs</emphasis>, i.e. lines that define the actual
text substitutions. By convention, the name of a filter
</para>
<para>
- A filter header line for a filter called <quote>foo</quote> could look
+ Filter definitions start with a header line that contains the filter
+ type, the filter name and the filter description.
+ A content filter header line for a filter called <quote>foo</quote> could look
like this:
</para>
<sect2><title>Filter File Tutorial</title>
<para>
- Now, let's complete our <quote>foo</quote> filter. We have already defined
+ Now, let's complete our <quote>foo</quote> content filter. We have already defined
the heading, but the jobs are still missing. Since all it does is to replace
<quote>foo</quote> with <quote>bar</quote>, there is only one (trivial) job
needed:
<term><emphasis>xml-to-html</emphasis></term>
<listitem>
<para>
- Header filter to change the Content-Type from xml to html.
+ Server-header filter to change the Content-Type from xml to html.
</para>
</listitem>
</varlistentry>
<term><emphasis>html-to-xml</emphasis></term>
<listitem>
<para>
- Header filter to change the Content-Type from html to xml.
+ Server-header filter to change the Content-Type from html to xml.
</para>
</listitem>
</varlistentry>
<term><emphasis>hide-tor-exit-notation</emphasis></term>
<listitem>
<para>
- Header filter to remove the <command>Tor</command> exit node notation
+ Client-header filter to remove the <command>Tor</command> exit node notation
found in Host and Referer headers.
</para>
+ <para>
+ If &my-app; and <command>Tor</command> are chained and &my-app;
+ is configured to use socks4a, one can use <quote>http://www.example.org.foobar.exit/</quote>
+ to access the host <quote>www.example.org</quote> through the
+ <command>Tor</command> exit node <quote>foobar</quote>.
+ </para>
+ <para>
+ As the HTTP client isn't aware of this notation, it treats the
+ whole string <quote>www.example.org.foobar.exit</quote> as host and uses it
+ for the <quote>Host</quote> and <quote>Referer</quote> headers. From the
+ server's point of view the resulting headers are invalid and can cause problems.
+ </para>
+ <para>
+ An invalid <quote>Referer</quote> header can trigger <quote>hot-linking</quote>
+ protections, an invalid <quote>Host</quote> header will make it impossible for
+ the server to find the right vhost (several domains hosted on the same IP address).
+ </para>
+ <para>
+ This client-header filter removes the <quote>foo.exit</quote> part in those headers
+ to prevent the mentioned problems. Note that it only modifies
+ the HTTP headers, it doesn't make it impossible for the server
+ to detect your <command>Tor</command> exit node based on the IP address
+ the request is coming from.
+ </para>
</listitem>
</varlistentry>
<para>
The templates are basically normal HTML files, but with place-holders (called symbols
- or exports), which <application>Privoxy</application> fills at run time. You can
- edit the templates with a normal text editor, should you want to customize them.
- (<emphasis>Not recommended for the casual user</emphasis>). Note that
- just like in configuration files, lines starting with <literal>#</literal> are
- ignored when the templates are filled in.
+ or exports), which <application>Privoxy</application> fills at run time. It
+ is possible to edit the templates with a normal text editor, should you want
+ to customize them. (<emphasis>Not recommended for the casual
+ user</emphasis>). Should you create your own custom templates, you should use
+ the <filename>config</filename> setting <link linkend="templdir">templdir</link>
+ to specify an alternate location, so your templates do not get overwritten
+ during upgrades.
+ </para>
+ <para>
+ Note that just like in configuration files, lines starting
+ with <literal>#</literal> are ignored when the templates are filled in.
</para>
<para>
<listitem>
<para>
- Toggle Privoxy on or off. In this case, <quote>Privoxy</quote> continues
- to run, but only as a pass-through proxy, with no actions taking place:
+ Toggle Privoxy on or off. This feature can be turned off/on in the main
+ <filename>config</filename> file. When toggled <quote>off</quote>, <quote>Privoxy</quote>
+ continues to run, but only as a pass-through proxy, with no actions taking
+ place:
</para>
<blockquote>
<para>
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
or not, is to disable it temporarily. This should be the first troubleshooting
step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick
and easy way to do this (be sure to flush caches afterward!). Looking at the
- logs is a good idea too.
+ logs is a good idea too. (Note that both the toggle feature and logging are
+ enabled via <filename>config</filename> file settings, and may need to be
+ turned <quote>on</quote>.)
</para>
<para>
Another easy troubleshooting step to try is if you have done any
<para>
<screen>
- Matches for http://google.com:
+ Matches for http://www.google.com:
In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
- {-add-header
- -block
- -content-type-overwrite
- -crunch-client-header
- -crunch-if-none-match
- -crunch-incoming-cookies
- -crunch-outgoing-cookies
- -crunch-server-header
- +deanimate-gifs {last}
- -downgrade-http-version
+ {+deanimate-gifs {last}
+fast-redirects {check-decoded-url}
- -filter {js-events}
- -filter {content-cookies}
- -filter {all-popups}
- -filter {banners-by-link}
- -filter {tiny-textforms}
- -filter {frameset-borders}
- -filter {demoronizer}
- -filter {shockwave-flash}
- -filter {quicktime-kioskmode}
- -filter {fun}
- -filter {crude-parental}
- -filter {site-specifics}
- -filter {js-annoyances}
- -filter {html-annoyances}
+filter {refresh-tags}
- -filter {unsolicited-popups}
+filter {img-reorder}
+filter {banners-by-size}
+filter {webbugs}
+filter {jumping-windows}
+filter {ie-exploits}
- -filter {google}
- -filter {yahoo}
- -filter {msn}
- -filter {blogspot}
- -filter {xml-to-html}
- -filter {html-to-xml}
- -filter {no-ping}
- -filter{hide-tor-exit-notation}
- -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 }
-add-header
-block
+ -client-header-filter{hide-tor-exit-notation}
-content-type-overwrite
-crunch-client-header
-crunch-if-none-match
-crunch-server-header
+deanimate-gifs {last}
-downgrade-http-version
- +fast-redirects {check-decoded-url}
+ -fast-redirects
-filter {js-events}
-filter {content-cookies}
-filter {all-popups}
-filter {yahoo}
-filter {msn}
-filter {blogspot}
- -filter {xml-to-html}
- -filter {html-to-xml}
-filter {no-ping}
- -filter{hide-tor-exit-notation}
- -filter-client-headers
- -filter-server-headers
-force-text-mode
-handle-as-empty-document
-handle-as-image
-hide-if-modified-since
+hide-referrer {forge}
-hide-user-agent
- -inspect-jpegs
- -kill-popups
-limit-connect
-overwrite-last-modified
- +prevent-compression
+ -prevent-compression
-redirect
- -send-vanilla-wafer
- -send-wafer
+ -server-header-filter{xml-to-html}
+ -server-header-filter{html-to-xml}
-session-cookies-only
- +set-image-blocker {pattern}
- -treat-forbidden-connects-like-blocks </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
{-add-header
-block
+ -client-header-filter{hide-tor-exit-notation}
-content-type-overwrite
-crunch-client-header
-crunch-if-none-match
-filter {yahoo}
-filter {msn}
-filter {blogspot}
- -filter {xml-to-html}
- -filter {html-to-xml}
-filter {no-ping}
- -filter{hide-tor-exit-notation}
- -filter-client-headers
- -filter-server-headers
-force-text-mode
-handle-as-empty-document
-handle-as-image
+hide-from-header{block}
+hide-referer{forge}
-hide-user-agent
- -inspect-jpegs
- -kill-popups
-overwrite-last-modified
+prevent-compression
-redirect
- -send-vanilla-wafer
- -send-wafer
+ -server-header-filter{xml-to-html}
+ -server-header-filter{html-to-xml}
+session-cookies-only
- +set-image-blocker{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.86 2008/08/16 10:12:23 fabiankeil
+ Merge two sentences and move the URL to the end of the item.
+
+ Revision 2.85 2008/08/16 10:04:59 fabiankeil
+ Some more syntax fixes. This version actually builds.
+
+ Revision 2.84 2008/08/16 09:42:45 fabiankeil
+ Turns out building docs works better if the syntax is valid.
+
+ Revision 2.83 2008/08/16 09:32:02 fabiankeil
+ Mention changes since 3.0.9 beta.
+
+ Revision 2.82 2008/08/16 09:00:52 fabiankeil
+ Fix example URL pattern (once more with feeling).
+
+ Revision 2.81 2008/08/16 08:51:28 fabiankeil
+ Update version-related entities.
+
+ Revision 2.80 2008/07/18 16:54:30 fabiankeil
+ Remove erroneous whitespace in documentation link.
+ Reported by John Chronister in #2021611.
+
+ Revision 2.79 2008/06/27 18:00:53 markm68k
+ remove outdated startup information for mac os x
+
+ Revision 2.78 2008/06/21 17:03:03 fabiankeil
+ Fix typo.
+
+ Revision 2.77 2008/06/14 13:45:22 fabiankeil
+ Re-add a colon I unintentionally removed a few revisions ago.
+
+ Revision 2.76 2008/06/14 13:21:28 fabiankeil
+ Prepare for the upcoming 3.0.9 beta release.
+
+ Revision 2.75 2008/06/13 16:06:48 fabiankeil
+ Update the "What's New in this Release" section with
+ the ChangeLog entries changelog2doc.pl could handle.
+
+ Revision 2.74 2008/05/26 15:55:46 fabiankeil
+ - Update "default profiles" table.
+ - Add some more pcrs redirect examples and note that
+ enabling debug 128 helps to get redirects working.
+
+ Revision 2.73 2008/05/23 14:43:18 fabiankeil
+ Remove previously out-commented block that caused syntax problems.
+
+ Revision 2.72 2008/05/12 10:26:14 fabiankeil
+ Synchronize content filter descriptions with the ones in default.filter.
+
+ Revision 2.71 2008/04/10 17:37:16 fabiankeil
+ Actually we use "modern" POSIX 1003.2 regular
+ expressions in path patterns, not PCRE.
+
+ Revision 2.70 2008/04/10 15:59:12 fabiankeil
+ Add another section to the client-header-tagger example that shows
+ how to actually change the action settings once the tag is created.
+
+ Revision 2.69 2008/03/29 12:14:25 fabiankeil
+ Remove send-wafer and send-vanilla-wafer actions.
+
+ Revision 2.68 2008/03/28 15:13:43 fabiankeil
+ Remove inspect-jpegs action.
+
+ Revision 2.67 2008/03/27 18:31:21 fabiankeil
+ Remove kill-popups action.
+
+ 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.
+
+ Revision 2.41 2007/11/11 16:32:11 hal9
+ This is primarily syncing What's New and Note to Upgraders sections with the many
+ new features and changes (gleaned from memory but mostly from ChangeLog).
+
+ Revision 2.40 2007/11/10 17:10:59 fabiankeil
+ In the first third of the file, mention several times that
+ the action editor is disabled by default in 3.0.7 beta and later.
+
+ Revision 2.39 2007/11/05 02:34:49 hal9
+ Various changes in preparation for the upcoming release. Much yet to be done.
+
+ Revision 2.38 2007/09/22 16:01:42 fabiankeil
+ Update embedded show-url-info output.
+
+ Revision 2.37 2007/08/27 16:09:55 fabiankeil
+ Fix pre-chroot-nslookup description which I failed to
+ copy and paste properly. Reported by Stephen Gildea.
+
+ Revision 2.36 2007/08/26 16:47:14 fabiankeil
+ Add Stephen Gildea's pre-chroot-nslookup patch [#1276666],
+ extensive comments moved to user manual.
+
+ Revision 2.35 2007/08/26 14:59:49 fabiankeil
+ Minor rewordings and fixes.
+
+ Revision 2.34 2007/08/05 15:19:50 fabiankeil
+ - Don't claim HTTP/1.1 compliance.
+ - Use $ in some of the path pattern examples.
+ - Use a hide-user-agent example argument without
+ leading and trailing space.
+ - Make it clear that the cookie actions work with
+ HTTP cookies only.
+ - Rephrase the inspect-jpegs text to underline
+ that it's only meant to protect against a single
+ exploit.
+
+ Revision 2.33 2007/07/27 10:57:35 hal9
+ Add references for user-agent strings for hide-user-agenet
+
+ Revision 2.32 2007/06/07 12:36:22 fabiankeil
+ Apply Roland's 29_usermanual.dpatch to fix a bunch
+ of syntax errors I collected over the last months.
+
+ Revision 2.31 2007/06/02 14:01:37 fabiankeil
+ Start to document forward-override{}.
+
+ Revision 2.30 2007/04/25 15:10:36 fabiankeil
+ - Describe installation for FreeBSD.
+ - Start to document taggers and tag patterns.
+ - Don't confuse devils and daemons.
+
+ Revision 2.29 2007/04/05 11:47:51 fabiankeil
+ Some updates regarding header filtering,
+ handling of compressed content and redirect's
+ support for pcrs commands.
+
+ Revision 2.28 2006/12/10 23:42:48 hal9
+ Fix various typos reported by Adam P. Thanks.
+
Revision 2.27 2006/11/14 01:57:47 hal9
Dump all docs prior to 3.0.6 release. Various minor changes to faq and user
manual.
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