X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=fc78f12da39f682d1e3663f3c758e0de603a987c;hb=e22a8cad1bac2c28925823b91fa7099a411390e6;hp=a2981fb3f619da30e2734a8600ba4f9dde950053;hpb=20269c138d782591788097e1dbe0906788122145;p=privoxy.git
diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index a2981fb3..fc78f12d 100644
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -9,13 +9,15 @@
+
-
-
+
+
+
-
-
+
+
@@ -34,9 +36,9 @@
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.141 2011/11/20 12:41:22 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.217 2017/01/23 12:59:45 fabiankeil Exp $
- Copyright (C) 2001-2011 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2016 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
@@ -55,12 +57,12 @@
- Copyright &my-copy; 2001-2011 by
- Privoxy Developers
+ Copyright &my-copy; 2001-2016 by
+ Privoxy Developers
-$Id: user-manual.sgml,v 2.141 2011/11/20 12:41:22 fabiankeil Exp $
+$Id: user-manual.sgml,v 2.217 2017/01/23 12:59:45 fabiankeil Exp $
@@ -99,14 +101,11 @@ Hal.
You can find the latest version of the Privoxy User Manual at http://www.privoxy.org/user-manual/.
+ url="https://www.privoxy.org/user-manual/">https://www.privoxy.org/user-manual/.
Please see the Contact section on how to
contact the developers.
-
-
-
@@ -115,7 +114,7 @@ Hal.
Introduction
This documentation is included with the current &p-status; version of
- Privoxy, v.&p-version;Privoxy, &p-version;Privoxy is available both in convenient pre-compiled
packages for a wide range of operating systems, and as raw source code.
For most users, we recommend using the packages, which can be downloaded from our
- Privoxy Project
+ Privoxy Project
Page.
@@ -180,36 +179,6 @@ How to install the binary packages depends on your operating system:
-
-Red Hat and Fedora RPMs
-
-
- RPMs can be installed with rpm -Uvh privoxy-&p-version;-1.rpm,
- and will use /etc/privoxy for the location
- of configuration files.
-
-
-
- Note that on Red Hat, Privoxy will
- not be automatically started on system boot. You will
- need to enable that using chkconfig,
- ntsysv, or similar methods.
-
-
-
- If you have problems with failed dependencies, try rebuilding the SRC RPM:
- rpm --rebuild privoxy-&p-version;-1.src.rpm. This
- will use your locally installed libraries and RPM version.
-
-
-
- Also note that if you have a Junkbuster RPM installed
- on your system, you need to remove it first, because the packages conflict.
- Otherwise, RPM will try to remove Junkbuster
- automatically if found, before installing Privoxy.
-
-
-
Debian and Ubuntu
@@ -262,16 +231,6 @@ How to install the binary packages depends on your operating system:
-
-Solaris
-
-
- Create a new directory, cd to it, then unzip and
- untar the archive. For the most part, you'll have to figure out where
- things go.
-
-
-
OS/2
@@ -301,72 +260,83 @@ How to install the binary packages depends on your operating system:
Mac OS X
- 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.
+ Installation instructions for the OS X platform depend upon whether
+ you downloaded a ready-built installation package (.pkg or .mpkg) or have
+ downloaded the source code.
+
+
+Installation from ready-built package
- 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
- /Library/StartupItems/Privoxy.
+ The downloaded file will either be a .pkg (for OS X 10.5 upwards) or a bzipped
+ .mpkg file (for OS X 10.4). The former can be double-clicked as is and the
+ installation will start; double-clicking the latter will unzip the .mpkg file
+ which can then be double-clicked to commence the installation.
- 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).
+ The privoxy service will automatically start after a successful installation
+ (and thereafter every time your computer starts up) however you will need to
+ configure your web browser(s) to use it. To do so, configure them to use a
+ proxy for HTTP and HTTPS at the address 127.0.0.1:8118.
+
+
+ To prevent the privoxy service from automatically starting when your computer
+ starts up, remove or rename the file /Library/LaunchDaemons/org.ijbswa.privoxy.plist
+ (on OS X 10.5 and higher) or the folder named
+ /Library/StartupItems/Privoxy (on OS X 10.4 'Tiger').
-
-
-
-AmigaOS
- Copy and then unpack the lha archive to a suitable location.
- All necessary files will be installed into Privoxy
- directory, including all configuration and log files. To uninstall, just
- remove this directory.
+ To manually start or stop the privoxy service, use the scripts startPrivoxy.sh
+ and stopPrivoxy.sh supplied in /Applications/Privoxy. They must be run from an
+ administrator account, using sudo.
+
+
+ To uninstall, run /Applications/Privoxy/uninstall.command as sudo from an
+ administrator account.
-
-
-FreeBSD
-
+
+Installation from source
- Privoxy is part of FreeBSD's Ports Collection, you can build and install
- it with cd /usr/ports/www/privoxy; make install clean.
+ To build and install the Privoxy source code on OS X you will need to obtain
+ the macsetup module from the Privoxy Sourceforge CVS repository (refer to
+ Sourceforge help for details of how to set up a CVS client to have read-only
+ access to the repository). This module contains scripts that leverage the usual
+ open-source tools (available as part of Apple's free of charge Xcode
+ distribution or via the usual open-source software package managers for OS X
+ (MacPorts, Homebrew, Fink etc.) to build and then install the privoxy binary
+ and associated files. The macsetup module's README file contains complete
+ instructions for its use.
- If you don't use the ports, you can fetch and install
- the package with pkg_add -r privoxy.
+ The privoxy service will automatically start after a successful installation
+ (and thereafter every time your computer starts up) however you will need to
+ configure your web browser(s) to use it. To do so, configure them to use a
+ proxy for HTTP and HTTPS at the address 127.0.0.1:8118.
- The port skeleton and the package can also be downloaded from the
- File Release
- Page, but there's no reason to use them unless you're interested in the
- beta releases which are only available there.
+ To prevent the privoxy service from automatically starting when your computer
+ starts up, remove or rename the file /Library/LaunchDaemons/org.ijbswa.privoxy.plist
+ (on OS X 10.5 and higher) or the folder named
+ /Library/StartupItems/Privoxy (on OS X 10.4 'Tiger').
-
-
-
-Gentoo
- Gentoo source packages (Ebuilds) for Privoxy are
- contained in the Gentoo Portage Tree (they are not on the download page,
- but there is a Gentoo section, where you can see when a new
- Privoxy Version is added to the Portage Tree).
+ To manually start or stop the privoxy service, use the Privoxy Utility
+ for Mac OS X (also part of the macsetup module). This application can start
+ and stop the privoxy service and display its log and configuration files.
- Before installing Privoxy under Gentoo just do
- first emerge --sync to get the latest changes from the
- Portage tree. With emerge privoxy you install the latest
- version.
+ To uninstall, run the macsetup module's uninstall.sh as sudo from an
+ administrator account.
+
+
+
+FreeBSD
+
- Configuration files are in /etc/privoxy, the
- documentation is in /usr/share/doc/privoxy-&p-version;
- and the Log directory is in /var/log/privoxy.
+ Privoxy is part of FreeBSD's Ports Collection, you can build and install
+ it with cd /usr/ports/www/privoxy; make install clean.
@@ -378,14 +348,14 @@ How to install the binary packages depends on your operating system:
The most convenient way to obtain the Privoxy sources
is to download the source tarball from our
- project download
+ project download
page.
If you like to live on the bleeding edge and are not afraid of using
possibly unstable development versions, you can check out the up-to-the-minute
- version directly from the
+ version directly from the
CVS repository.
Keeping your Installation Up-to-Date
-
- As user feedback comes in and development continues, we will make updated versions
- of both the main actions file (as a separate
- package) and the software itself (including the actions file) available for
- download.
-
If you wish to receive an email notification whenever we release updates of
Privoxy or the actions file, subscribe
- to our announce mailing list, ijbswa-announce@lists.sourceforge.net.
+ url="https://lists.privoxy.org/mailman/listinfo/privoxy-announce">subscribe
+ to our announce mailing list, privoxy-announce@lists.privoxy.org.
@@ -436,1131 +399,155 @@ How to install the binary packages depends on your operating system:
What's New in this Release
+
+&changelog;
+
+
+
+
+Note to Upgraders
+
- Privoxy 3.0.18 is a stable release.
- The changes since 3.0.17 stable are:
+ A quick list of things to be aware of before upgrading from earlier
+ versions of Privoxy:
-
+
+
+
+ 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
+ diff and maybe patch.
+
+
+ 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.
+
+
+
+
+ Note that some installers remove earlier versions completely,
+ including configuration files, therefore you should really save
+ any important configuration files!
+
+
+
+
+ On the other hand, other installers don't overwrite existing configuration
+ files, thinking you will want to do that yourself.
+
+
+
+
+ In the default configuration only fatal errors are logged now.
+ You can change that in the debug section
+ 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.
+
+
+
+
+
+ Three other config file settings are now off by default:
+ enable-remote-toggle,
+ enable-remote-http-toggle,
+ and enable-edit-actions.
+ If you use or want these, you will need to explicitly enable them, and
+ be aware of the security issues involved.
+
+
+
+
+
+
+
+
-
-
-Note to Upgraders
-
-
- A quick list of things to be aware of before upgrading from earlier
- versions of Privoxy:
-
-
+Quickstart to Using Privoxy
- 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
- diff and maybe patch.
-
-
- 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.
-
-
-
-
- Note that some installers remove earlier versions completely,
- including configuration files, therefore you should really save
- any important configuration files!
-
-
-
-
- On the other hand, other installers don't overwrite existing configuration
- files, thinking you will want to do that yourself.
-
-
-
-
- standard.action has been merged into
- the default.action file.
-
-
-
-
- In the default configuration only fatal errors are logged now.
- You can change that in the debug section
- 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.
-
-
-
-
-
- Three other config file settings are now off by default:
- enable-remote-toggle,
- enable-remote-http-toggle,
- and enable-edit-actions.
- If you use or want these, you will need to explicitly enable them, and
- be aware of the security issues involved.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Quickstart to Using Privoxy
-
-
-
-
-
- Install Privoxy. See the Installation Section below for platform specific
- information.
-
-
-
-
+ Install Privoxy. See the Installation Section below for platform specific
+ information.
+
+
+
+
Advanced users and those who want to offer Privoxy
service to more than just their local machine should check the
-
-
Please see the section Contacting the
@@ -2073,39 +1048,40 @@ How to install the binary packages depends on your operating system:
directory. Except on Win32 where it will try config.txt.
-
-Red Hat and Fedora
+
+Debian
- A default Red Hat installation may not start &my-app; upon boot. It will use
- the file /etc/privoxy/config as its main configuration
+ We use a script. Note that Debian typically starts &my-app; upon booting per
+ default. It will use the file
+ /etc/privoxy/config as its main configuration
file.
- # /etc/rc.d/init.d/privoxy start
+ # /etc/init.d/privoxy start
+
+
+
+FreeBSD and ElectroBSD
- Or ...
+ To start Privoxy upon booting, add
+ "privoxy_enable='YES'" to /etc/rc.conf.
+ Privoxy will use
+ /usr/local/etc/privoxy/config as its main
+ configuration file.
-
- # service privoxy start
-
+ If you installed Privoxy into a jail, the
+ paths above are relative to the jail root.
-
-
-
-Debian
- We use a script. Note that Debian typically starts &my-app; upon booting per
- default. It will use the file
- /etc/privoxy/config as its main configuration
- file.
+ To start Privoxy manually, run:
- # /etc/init.d/privoxy start
+ # service privoxy onestart
@@ -2129,15 +1105,21 @@ Click on the &my-app; Icon to start Privoxy. If no co
-Solaris, NetBSD, FreeBSD, HP-UX and others
+Generic instructions for Unix derivates (Solaris, NetBSD, HP-UX etc.)
Example Unix startup command:
- # /usr/sbin/privoxy /etc/privoxy/config
+ # /usr/sbin/privoxy --user privoxy /etc/privoxy/config
+
+ Note that if you installed Privoxy through
+ a package manager, the package will probably contain a platform-specific
+ script or configuration file to start Privoxy
+ upon boot.
+
@@ -2153,71 +1135,24 @@ Example Unix startup command:
Mac OS X
- 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.
-
-
- The privoxy service will automatically start after a successful
- installation. In addition, the privoxy service will automatically
- start every time your computer starts up.
+ The privoxy service will automatically start after a successful installation
+ (and thereafter every time your computer starts up) however you will need to
+ configure your web browser(s) to use it. To do so, configure them to use a
+ proxy for HTTP and HTTPS at the address 127.0.0.1:8118.
- To prevent the privoxy service from automatically starting when your
- computer starts up, remove or rename the folder named
- /Library/StartupItems/Privoxy.
+ To prevent the privoxy service from automatically starting when your computer
+ starts up, remove or rename the file /Library/LaunchDaemons/org.ijbswa.privoxy.plist
+ (on OS X 10.5 and higher) or the folder named
+ /Library/StartupItems/Privoxy (on OS X 10.4 'Tiger').
- A simple application named Privoxy Utility has been created which
- enables administrators to easily start and stop the privoxy service.
-
-
- 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.
-
-
- An administrator username and password must be supplied in order for
- the Privoxy Utility to perform any of the tasks.
-
-
-
-
-
-AmigaOS
-
- Start Privoxy (with RUN <>NIL:) in your
- startnet script (AmiTCP), in
- s:user-startup (RoadShow), as startup program in your
- startup script (Genesis), or as startup action (Miami and MiamiDx).
- Privoxy will automatically quit when you quit your
- TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
- Privoxy is still running).
+ To manually start or stop the privoxy service, use the scripts startPrivoxy.sh
+ and stopPrivoxy.sh supplied in /Applications/Privoxy. They must be run from an
+ administrator account, using sudo.
-
-Gentoo
-
- A script is again used. It will use the file /etc/privoxy/config
- as its main configuration file.
-
-
-
- /etc/init.d/privoxy start
-
-
-
- Note that Privoxy is not automatically started at
- boot time by default. You can change this with the rc-update
- command.
-
-
-
- rc-update add privoxy default
-
-
-
-
-
-
-Privoxy Configuration
-
- All Privoxy configuration is stored
- in text files. These files can be edited with a text editor.
- Many important aspects of Privoxy can
- also be controlled easily with a web browser.
-
-
-
-
-
-
-Controlling Privoxy with Your Web Browser
-
- Privoxy's user interface can be reached through the special
- URL http://config.privoxy.org/
- (shortcut: http://p.p/),
- which is a built-in page and works without Internet access.
- You will see the following section:
-
-
-
-
-
-
- Privoxy Menu
-
-
-
- ▪ View & change the current configuration
-
-
- ▪ View the source code version numbers
-
-
- ▪ View the request headers.
-
-
- ▪ Look up which actions apply to a URL and why
-
-
- ▪ Toggle Privoxy on or off
-
-
- ▪ Documentation
-
-
-
-
-
-
-
- This should be self-explanatory. Note the first item leads to an editor for the
- actions files, which is where the ad, banner,
- cookie, and URL blocking magic is configured as well as other advanced features of
- Privoxy. This is an easy way to adjust various
- aspects of Privoxy configuration. The actions
- file, and other configuration files, are explained in detail below.
-
-
-
- Toggle Privoxy On or Off is handy for sites that might
- have problems with your current actions and filters. You can in fact use
- it as a test to see whether it is Privoxy
- causing the problem or not. Privoxy continues
- to run as a proxy in this case, but all manipulation is disabled, i.e.
- Privoxy acts like a normal forwarding proxy. There
- is even a toggle Bookmarklet offered, so
- that you can toggle Privoxy with one click from
- your browser.
-
-
-
- Note that several of the features described above are disabled by default
- in Privoxy 3.0.7 beta and later.
- Check the
- configuration file to learn why
- and in which cases it's safe to enable them again.
-
-
-
-
-
-
-
-
-
-
-
-
-Configuration Files Overview
-
- For Unix, *BSD and Linux, all configuration files are located in
- /etc/privoxy/ by default. For MS Windows, OS/2, and
- AmigaOS these are all in the same directory as the
- Privoxy executable.
-
-
-
- The installed defaults provide a reasonable starting point, though
- some settings may be aggressive by some standards. For the time being, the
- principle configuration files are:
-
-
-
-
-
-
-
- The main configuration file is named config
- on Linux, Unix, BSD, OS/2, and AmigaOS and config.txt
- on Windows. This is a required file.
-
-
-
-
-
- match-all.action is used to define which actions
- relating to banner-blocking, images, pop-ups, content modification, cookie handling
- etc should be applied by default. It should be the first actions file loaded.
-
-
- default.action defines many exceptions (both positive and negative)
- from the default set of actions that's configured in match-all.action.
- It should be the second actions file loaded and shouldn't be edited by the user.
-
-
- Multiple actions files may be defined in config. These
- are processed in the order they are defined. Local customizations and locally
- preferred exceptions to the default policies as defined in
- match-all.action (which you will most probably want
- to define sooner or later) are best applied in user.action,
- where you can preserve them across upgrades. The file isn't installed by all
- installers, but you can easily create it yourself with a text editor.
-
-
- There is also a web based editor that can be accessed from
- http://config.privoxy.org/show-status
- (Shortcut: http://p.p/show-status) for the
- various actions files.
-
-
-
-
-
- Filter files (the filter
- file) can be used to re-write the raw page content, including
- viewable text as well as embedded HTML and JavaScript, and whatever else
- lurks on any given web page. The filtering jobs are only pre-defined here;
- whether to apply them or not is up to the actions files.
- default.filter includes various filters made
- available for use by the developers. Some are much more intrusive than
- others, and all should be used with caution. You may define additional
- filter files in config as you can with
- actions files. We suggest user.filter for any
- locally defined filters or customizations.
-
-
-
-
-
-
-
- The syntax of the configuration and filter files may change between different
- Privoxy versions, unfortunately some enhancements cost backwards compatibility.
-
-
-
-
- All files use the # character to denote a
- comment (the rest of the line will be ignored) and understand line continuation
- through placing a backslash ("\") as the very last character
- in a line. If the # is preceded by a backslash, it looses
- its special function. Placing a # in front of an otherwise
- valid configuration line to prevent it from being interpreted is called "commenting
- out" that line. Blank lines are ignored.
-
-
-
- The actions files and filter files
- can use Perl style regular expressions for
- maximum flexibility.
-
-
-
- After making any changes, there is no need to restart
- Privoxy in order for the changes to take
- effect. Privoxy detects such changes
- automatically. Note, however, that it may take one or two additional
- requests for the change to take effect. When changing the listening address
- of Privoxy, these wake up requests
- must obviously be sent to the old listening address.
-
-
-
- While under development, the configuration content is subject to change.
- The below documentation may not be accurate by the time you read this.
- Also, what constitutes a default setting, may change, so
- please check all your configuration files on important issues.
-
-]]>
-
-
-
-
-
-
-
-
-
-
-
- &config;
-
-
-
-
-
-
-
-
-
-Actions Files
-
-
-
-
- The actions files are used to define what actions
- Privoxy takes for which URLs, and thus determines
- how ad images, cookies and various other aspects of HTTP content and
- transactions are handled, and on which sites (or even parts thereof).
- There are a number of such actions, with a wide range of functionality.
- Each action does something a little different.
- These actions give us a veritable arsenal of tools with which to exert
- our control, preferences and independence. Actions can be combined so that
- their effects are aggregated when applied against a given set of URLs.
-
-
- There
- are three action files included with Privoxy with
- differing purposes:
-
-
-
-
-
- match-all.action - is used to define which
- actions relating to banner-blocking, images, pop-ups,
- content modification, cookie handling etc should be applied by default.
- It should be the first actions file loaded
-
-
-
-
- default.action - defines many exceptions (both
- positive and negative) from the default set of actions that's configured
- in match-all.action. It is a set of rules that should
- work reasonably well as-is for most users. This file is only supposed to
- be edited by the developers. It should be the second actions file loaded.
-
-
-
-
- user.action - is intended to be for local site
- preferences and exceptions. As an example, if your ISP or your bank
- has specific requirements, and need special handling, this kind of
- thing should go here. This file will not be upgraded.
-
-
-
-
- EditSet to CautiousSet to MediumSet to Advanced
-
-
- These have increasing levels of aggressiveness and have no
- influence on your browsing unless you select them explicitly in the
- editor. A default installation should be pre-set to
- Cautious. New users should try this for a while before
- adjusting the settings to more aggressive levels. The more aggressive
- the settings, then the more likelihood there is of problems such as sites
- not working as they should.
-
-
- The Edit button allows you to turn each
- action on/off individually for fine-tuning. The Cautious
- button changes the actions list to low/safe settings which will activate
- ad blocking and a minimal set of &my-app;'s features, and subsequently
- there will be less of a chance for accidental problems. The
- Medium button sets the list to a medium level of
- other features and a low level set of privacy features. The
- Advanced button sets the list to a high level of
- ad blocking and medium level of privacy. See the chart below. The latter
- three buttons over-ride any changes via with the
- Edit button. More fine-tuning can be done in the
- lower sections of this internal page.
-
-
- While the actions file editor allows to enable these settings in all
- actions files, they are only supposed to be enabled in the first one
- to make sure you don't unintentionally overrule earlier rules.
-
-
- The default profiles, and their associated actions, as pre-defined in
- default.action are:
-
-
-
Default Configurations
-
-
-
-
-
-
-
- Feature
- Cautious
- Medium
- Advanced
-
-
-
-
-
-
-
-
-
-
-
-
-
- Ad-blocking Aggressiveness
- medium
- high
- high
-
-
-
- Ad-filtering by size
- no
- yes
- yes
-
-
-
- Ad-filtering by link
- no
- no
- yes
-
-
- Pop-up killing
- blocks only
- blocks only
- blocks only
-
-
-
- Privacy Features
- low
- medium
- medium/high
-
-
-
- Cookie handling
- none
- session-only
- kill
-
-
-
- Referer forging
- no
- yes
- yes
-
-
-
- GIF de-animation
- no
- yes
- yes
-
-
-
- Fast redirects
- no
- no
- yes
-
-
-
- HTML taming
- no
- no
- yes
-
-
-
- JavaScript taming
- no
- no
- yes
-
-
-
- Web-bug killing
- no
- yes
- yes
-
-
-
- Image tag reordering
- no
- yes
- yes
-
-
-
-
-
-
-
-
-
-
-
-
- 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.
- default.action is typically processed before
- user.action). The content of these can all be viewed and
- edited from http://config.privoxy.org/show-status.
- 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
- (defined in default.action),
- followed by any exceptions (typically also in
- default.action), which are then followed lastly by any
- local preferences (typically in user.action).
- Generally, user.action has the last word.
-
-
-
- An actions file typically has multiple sections. If you want to use
- aliases in an actions file, you have to place the (optional)
- alias section at the top of that file.
- Then comes the default set of rules which will apply universally to all
- sites and pages (be very careful with using such a
- universal set in user.action or any other actions file after
- default.action, because it will override the result
- from consulting any previous file). And then below that,
- exceptions to the defined universal policies. You can regard
- user.action as an appendix to default.action,
- with the advantage that it is a separate file, which makes preserving your
- personal settings across Privoxy upgrades easier.
-
-
-
- Actions can be used to block anything you want, including ads, banners, or
- 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, some JavaScripts tamed, user-tracking
- fooled, and much more. See below for a complete list
- of actions.
-
-
-
-
-Finding the Right Mix
-
- Note that some actions, like cookie suppression
- or script disabling, may render some sites unusable that rely on these
- techniques to work properly. Finding the right mix of actions is not always easy and
- certainly a matter of personal taste. And, things can always change, requiring
- refinements in the configuration. In general, it can be said that the more
- aggressive your default settings (in the top section of the
- actions file) are, the more exceptions for trusted sites you
- 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.
-
-
-
- We have tried to provide you with reasonable rules to start from in the
- distribution actions files. But there is no general rule of thumb on these
- things. There just are too many variables, and sites are constantly changing.
- Sooner or later you will want to change the rules (and read this chapter again :).
-
-
-
-
-
-How to Edit
-
- The easiest way to edit the actions files is with a browser by
- using our browser-based editor, which can be reached from http://config.privoxy.org/show-status.
- Note: the config file option enable-edit-actions 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 Cautious, Medium or
- Advanced. Warning: the Advanced setting is more
- aggressive, and will be more likely to cause problems for some sites.
- Experienced users only!
-
-
-
- If you prefer plain text editing to GUIs, you can of course also directly edit the
- the actions files with your favorite text editor. Look at
- default.action which is richly commented with many
- good examples.
-
-
-
-
-
-How Actions are Applied to Requests
-
- Actions files are divided into sections. There are special sections,
- like the alias 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 and tag patterns, each on a separate line.
-
-
-
- To determine which actions apply to a request, the URL of the request is
- compared to all URL patterns in each action file.
- 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.
-
-
-
- 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 {
- +handle-as-image },
- then later another one with just {
- +block }, resulting
- in both actions to apply. And there may well be
- cases where you will want to combine actions together. Such a section then
- might look like:
-
-
-
-
- { +handle-as-image +block{Banner ads.} }
- # Block these as if they were images. Send no block page.
- banners.example.com
- media.example.com/.*banners
- .example.com/images/ads/
-
-
-
- You can trace this process for URL patterns and any given URL by visiting http://config.privoxy.org/show-url-info.
-
-
-
- Examples and more detail on this is provided in the Appendix,
- Troubleshooting: Anatomy of an Action section.
-
-
-
-
-
-Patterns
-
- As mentioned, Privoxy uses patterns
- to determine what actions might apply to which sites and
- pages your browser attempts to access. These patterns use wild
- card type pattern matching to achieve a high degree of
- flexibility. This allows one expression to be expanded and potentially match
- against many similar patterns.
-
-
-
- Generally, an URL pattern has the form
- <domain><port>/<path>, where the
- <domain>, the <port>
- and the <path> are optional. (This is why the special
- / pattern matches all URLs). Note that the protocol
- portion of the URL pattern (e.g. http://) should
- not be included in the pattern. This is assumed already!
-
-
- 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 more flexible
- Regular
- Expressions (POSIX 1003.2).
-
-
- The port part of a pattern is a decimal port number preceded by a colon
- (:). If the domain part contains a numerical IPv6 address,
- it has to be put into angle brackets
- (<, >).
-
-
-
-
- www.example.com/
-
-
- is a domain-only pattern and will match any request to www.example.com,
- regardless of which document on that server is requested. So ALL pages in
- this domain would be covered by the scope of this action. Note that a
- simple example.com is different and would NOT match.
-
-
-
-
- www.example.com
-
-
- means exactly the same. For domain-only patterns, the trailing / may
- be omitted.
-
-
-
-
- www.example.com/index.html
-
-
- matches all the documents on www.example.com
- whose name starts with /index.html.
-
-
-
-
- www.example.com/index.html$
-
-
- matches only the single document /index.html
- on www.example.com.
-
-
-
-
- /index.html$
-
-
- matches the document /index.html, regardless of the domain,
- i.e. on any web server anywhere.
-
-
-
-
- /
-
-
- Matches any URL because there's no requirement for either the
- domain or the path to match anything.
-
-
-
-
- :8000/
-
-
- Matches any URL pointing to TCP port 8000.
-
-
-
-
- <2001:db8::1>/
-
-
- Matches any URL with the host address 2001:db8::1.
- (Note that the real URL uses plain brackets, not angle brackets.)
-
-
-
-
- index.html
-
-
- matches nothing, since it would be interpreted as a domain name and
- there is no top-level domain called .html. So its
- a mistake.
-
-
-
-
-
-
-
-The Domain Pattern
-
-
- The matching of the domain part offers some flexible options: if the
- domain starts or ends with a dot, it becomes unanchored at that end.
- For example:
-
-
-
-
- .example.com
-
-
- matches any domain with first-level domain com
- and second-level domain example.
- For example www.example.com,
- example.com and foo.bar.baz.example.com.
- Note that it wouldn't match if the second-level domain was another-example.
-
-
-
-
- www.
-
-
- matches any domain that STARTS with
- www. (It also matches the domain
- www but most of the time that doesn't matter.)
-
-
-
-
- .example.
-
-
- matches any domain that CONTAINS.example..
- And, by the way, also included would be any files or documents that exist
- within that domain since no path limitations are specified. (Correctly
- speaking: It matches any FQDN that contains example as
- a domain.) This might be www.example.com,
- news.example.de, or
- www.example.net/cgi/testing.pl for instance. All these
- cases are matched.
-
-
-
-
-
-
- Additionally, there are wild-cards that you can use in the domain names
- themselves. These work similarly to shell globbing type wild-cards:
- * represents zero or more arbitrary characters (this is
- equivalent to the
- Regular
- Expression based syntax of .*),
- ? represents any single character (this is equivalent to the
- regular expression syntax of a simple .), and you can define
- character classes in square brackets which is similar to
- the same regular expression technique. All of this can be freely mixed:
-
-
-
-
- ad*.example.com
-
-
- matches adserver.example.com,
- ads.example.com, etc but not sfads.example.com
-
-
-
-
- *ad*.example.com
-
-
- matches all of the above, and then some.
-
-
-
-
- .?pix.com
-
-
- matches www.ipix.com,
- pictures.epix.com, a.b.c.d.e.upix.com etc.
-
-
-
-
- www[1-9a-ez].example.c*
-
-
- matches www1.example.com,
- www4.example.cc, wwwd.example.cy,
- wwwz.example.com etc., but not
- wwww.example.com.
-
-
-
-
-
-
- While flexible, this is not the sophistication of full regular expression based syntax.
-
-
-
-
-
-
-
-
-The Path Pattern
-
-
- Privoxy uses modern POSIX 1003.2
- Regular
- Expressions for matching the path portion (after the slash),
- and is thus more flexible.
-
-
-
- There is an Appendix with a brief quick-start into regular
- expressions, you also might want to have a look at your operating system's documentation
- on regular expressions (try man re_format).
-
-
-
- Note that the path pattern is automatically left-anchored at the /,
- i.e. it matches as if it would start with a ^ (regular expression speak
- for the beginning of a line).
-
-
-
- Please also note that matching in the path is CASE INSENSITIVE
- by default, but you can switch to case sensitive at any point in the pattern by using the
- (?-i) switch: www.example.com/(?-i)PaTtErN.* will match
- only documents whose path starts with PaTtErN in
- exactly this capitalization.
-
-
-
-
- .example.com/.*
-
-
- Is equivalent to just .example.com, since any documents
- within that domain are matched with or without the .*
- regular expression. This is redundant
-
-
-
-
- .example.com/.*/index.html$
-
-
- Will match any page in the domain of example.com that is
- named index.html, and that is part of some path. For
- example, it matches www.example.com/testing/index.html but
- NOT www.example.com/index.html because the regular
- expression called for at least two /'s, thus the path
- requirement. It also would match
- www.example.com/testing/index_html, because of the
- special meta-character ..
-
-
-
-
- .example.com/(.*/)?index\.html$
-
-
- This regular expression is conditional so it will match any page
- named index.html regardless of path which in this case can
- have one or more /'s. And this one must contain exactly
- .html (but does not have to end with that!).
-
-
-
-
- .example.com/(.*/)(ads|banners?|junk)
-
-
- This regular expression will match any path of example.com
- that contains any of the words ads, banner,
- banners (because of the ?) or junk.
- The path does not have to end in these words, just contain them.
-
-
-
-
- .example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$
-
-
- This is very much the same as above, except now it must end in either
- .jpg, .jpeg, .gif or .png. So this
- one is limited to common image formats.
-
-
-
-
-
-
- There are many, many good examples to be found in default.action,
- and more tutorials below in Appendix on regular expressions.
-
-
-
-
-
-
-
-
-The Tag Pattern
-
-
- Tag patterns are used to change the applying actions based on the
- request's tags. Tags can be created with either the
- client-header-tagger
- or the server-header-tagger action.
-
-
-
- Tag patterns have to start with TAG:, 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 ^,
- you have to do it yourself if you need it).
-
-
-
- To match all requests that are tagged with foo
- your pattern line should be TAG:^foo$,
- TAG:foo would work as well, but it would also
- match requests whose tags contain foo somewhere.
- TAG: foo wouldn't work as it requires white space.
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- For example you could tag client requests which use the
- POST 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.
-
-
-
- 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.
-
-
-
-
-
-
-
-
-
-
-
-
-Actions
-
- All actions are disabled by default, until they are explicitly enabled
- somewhere in an actions file. Actions are turned on if preceded with a
- +, and turned off if preceded with a -. So a
- +action means do that action, e.g.
- +block means please block URLs that match the
- following patterns, and -block means don't
- block URLs that match the following patterns, even if +block
- previously applied.
-
-
-
-
- Again, actions are invoked by placing them on a line, enclosed in curly braces and
- separated by whitespace, like in
- {+some-action -some-other-action{some-parameter}},
- followed by a list of URL patterns, one per line, to which they apply.
- Together, the actions line and the following pattern lines make up a section
- of the actions file.
-
-
-
- Actions fall into three categories:
-
-
-
-
-
-
- Boolean, i.e the action can only be enabled or
- disabled. Syntax:
-
-
-
- +name # enable action name
- -name # disable action name
-
-
- Example: +handle-as-image
-
-
-
-
-
-
- Parameterized, where some value is required in order to enable this type of action.
- Syntax:
-
-
-
- +name{param} # enable action and set parameter to param,
- # overwriting parameter from previous match if necessary
- -name # disable action. The parameter can be omitted
-
-
- Note that if the URL matches multiple positive forms of a parameterized action,
- the last match wins, i.e. the params from earlier matches are simply ignored.
-
-
- Example: +hide-user-agent{Mozilla/5.0 (X11; U; FreeBSD i386; en-US; rv:1.8.1.4) Gecko/20070602 Firefox/2.0.0.4}
-
-
-
-
-
- Multi-value. These look exactly like parameterized actions,
- but they behave differently: If the action applies multiple times to the
- same URL, but with different parameters, all the parameters
- from all matches are remembered. This is used for actions
- that can be executed for the same request repeatedly, like adding multiple
- headers, or filtering through multiple filters. Syntax:
-
-
-
- +name{param} # enable action and add param to the list of parameters
- -name{param} # remove the parameter param from the list of parameters
- # If it was the last one left, disable the action.
- -name # disable this action completely and remove all parameters from the list
-
-
- Examples: +add-header{X-Fun-Header: Some text} and
- +filter{html-annoyances}
-
-
-
-
-
-
-
- If nothing is specified in any actions file, no actions are
- taken. So in this case Privoxy would just be a
- 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).
-
-
-
- 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 user.action). For multi-valued actions, the actions
- are applied in the order they are specified. Actions files are processed in
- the order they are defined in config (the default
- installation has three actions files). It also quite possible for any given
- URL to match more than one pattern (because of wildcards and
- regular expressions), and thus to trigger more than one set of actions! Last
- match wins.
-
-
-
-
- The list of valid Privoxy actions are:
-
-
-
-
-
-
-
-
-
-
-
-
-
-add-header
-
-
-
- Typical use:
-
- Confuse log analysis, custom applications
-
-
-
-
- Effect:
-
-
- Sends a user defined HTTP header to the web server.
-
-
-
-
-
- Type:
-
-
- Multi-value.
-
-
-
-
- Parameter:
-
-
- Any string value is possible. Validity of the defined HTTP headers is not checked.
- It is recommended that you use the X- prefix
- for custom headers.
-
-
-
-
-
- Notes:
-
-
- This action may be specified multiple times, in order to define multiple
- headers. This is rarely needed for the typical user. If you don't know what
- HTTP headers are, you definitely don't need to worry about this
- one.
-
-
- Headers added by this action are not modified by other actions.
-
-
-
-
-
- Example usage:
-
-
- +add-header{X-User-Tracking: sucks}
-
-
-
-
-
-
-
-
-
-block
-
-
-
- Typical use:
-
- Block ads or other unwanted content
-
-
-
-
- Effect:
-
-
- Requests for URLs to which this action applies are blocked, i.e. the
- requests are trapped by &my-app; and the requested URL is never retrieved,
- but is answered locally with a substitute page or image, as determined by
- the handle-as-image,
- set-image-blocker, and
- handle-as-empty-document actions.
-
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
- A block reason that should be given to the user.
-
-
-
-
- Notes:
-
-
- Privoxy sends a special BLOCKED page
- 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).
-
-
- A very important exception occurs if both
- block and handle-as-image,
- apply to the same request: it will then be replaced by an image. If
- set-image-blocker
- (see below) also applies, the type of image will be determined by its parameter,
- if not, the standard checkerboard pattern is sent.
-
-
- It is important to understand this process, in order
- to understand how Privoxy deals with
- ads and other unwanted content. Blocking is a core feature, and one
- upon which various other features depend.
-
-
- The filter
- action can perform a very similar task, by blocking
- banner images and other content through rewriting the relevant URLs in the
- document's HTML source, so they don't get requested in the first place.
- Note that this is a totally different technique, and it's easy to confuse the two.
-
-
-
-
-
- Example usage (section):
-
-
- {+block{No nasty stuff for you.}}
-# Block and replace with "blocked" page
- .nasty-stuff.example.com
-
-{+block{Doubleclick banners.} +handle-as-image}
-# Block and replace with image
- .ad.doubleclick.net
- .ads.r.us/banners/
-
-{+block{Layered ads.} +handle-as-empty-document}
-# Block and then ignore
- adserver.example.net/.*\.js$
-
-
-
-
-
-
-
-
-
-
-
-change-x-forwarded-for
-
-
-
- Typical use:
-
- Improve privacy by not forwarding the source of the request in the HTTP headers.
-
-
-
-
- Effect:
-
-
- Deletes the X-Forwarded-For: HTTP header from the client request,
- or adds a new one.
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
-
-
- block to delete the header.
-
-
-
- add to create the header (or append
- the client's IP address to an already existing one).
-
-
-
-
-
-
-
- Notes:
-
-
- It is safe and recommended to use block.
-
-
- Forwarding the source address of the request may make
- sense in some multi-user setups but is also a privacy risk.
-
-
-
-
- Example usage:
-
-
- +change-x-forwarded-for{block}
-
-
-
-
-
-
-
-
-client-header-filter
-
-
-
- Typical use:
-
-
- Rewrite or remove single client headers.
-
-
-
-
-
- Effect:
-
-
- All client headers to which this action applies are filtered on-the-fly through
- the specified regular expression based substitutions.
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
-
- The name of a client-header filter, as defined in one of the
- filter files.
-
-
-
-
-
- Notes:
-
-
- 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.
-
-
- Client-header filters are executed after the other header actions have finished
- and use their output as input.
-
-
- 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.
-
-
- Please refer to the filter file chapter
- to learn which client-header filters are available by default, and how to
- create your own.
-
-
-
-
-
-
- Example usage (section):
-
-
-
-# Hide Tor exit notation in Host and Referer Headers
-{+client-header-filter{hide-tor-exit-notation}}
-/
-
-
-
-
-
-
-
-
-
-
-
-client-header-tagger
-
-
-
- Typical use:
-
-
- Block requests based on their headers.
-
-
-
-
-
- Effect:
-
-
- 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.
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
-
- The name of a client-header tagger, as defined in one of the
- filter files.
-
-
-
-
-
- Notes:
-
-
- Client-header taggers are applied to each header on its own,
- and as the header isn't modified, each tagger sees
- the original.
-
-
- Client-header taggers are the first actions that are executed
- and their tags can be used to control every other action.
-
-
-
-
-
- Example usage (section):
-
-
-
-# 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/
-
-
-
-
-
-
-
-
-
-
-
-content-type-overwrite
-
-
-
- Typical use:
-
- Stop useless download menus from popping up, or change the browser's rendering mode
-
-
-
-
- Effect:
-
-
- Replaces the Content-Type: HTTP server header.
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
-
- Any string.
-
-
-
-
-
- Notes:
-
-
- The Content-Type: HTTP server header is used by the
- browser to decide what to do with the document. The value of this
- header can cause the browser to open a download menu instead of
- displaying the document by itself, even if the document's format is
- supported by the browser.
-
-
- The declared content type can also affect which rendering mode
- the browser chooses. If XHTML is delivered as text/html,
- many browsers treat it as yet another broken HTML document.
- If it is send as application/xml, browsers with
- XHTML support will only display it, if the syntax is correct.
-
-
- If you see a web site that proudly uses XHTML buttons, but sets
- Content-Type: text/html, you can use &my-app;
- to overwrite it with application/xml and validate
- the web master's claim inside your XHTML-supporting browser.
- If the syntax is incorrect, the browser will complain loudly.
-
-
- You can also go the opposite direction: if your browser prints
- error messages instead of rendering a document falsely declared
- as XHTML, you can overwrite the content type with
- text/html and have it rendered as broken HTML document.
-
-
- By default content-type-overwrite only replaces
- Content-Type: headers that look like some kind of text.
- If you want to overwrite it unconditionally, you have to combine it with
- force-text-mode.
- This limitation exists for a reason, think twice before circumventing it.
-
-
- Most of the time it's easier to replace this action with a custom
- server-header filter.
- 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.
-
-
- Of course you can apply content-type-overwrite
- to a whole site and then make URL based exceptions, but it's a lot
- more work to get the same precision.
-
-
-
-
-
- Example usage (sections):
-
-
- # Check if www.example.net/ really uses valid XHTML
-{ +content-type-overwrite{application/xml} }
-www.example.net/
-
-# but leave the content type unmodified if the URL looks like a style sheet
-{-content-type-overwrite}
-www.example.net/.*\.css$
-www.example.net/.*style
-
-
-
-
-
-
-
-
-
-
-
-crunch-client-header
-
-
-
- Typical use:
-
- Remove a client header Privoxy has no dedicated action for.
-
-
-
-
- Effect:
-
-
- Deletes every header sent by the client that contains the string the user supplied as parameter.
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
-
- Any string.
-
-
-
-
-
- Notes:
-
-
- This action allows you to block client headers for which no dedicated
- Privoxy action exists.
- Privoxy will remove every client header that
- contains the string you supplied as parameter.
-
-
- Regular expressions are not supported and you can't
- use this action to block different headers in the same request, unless
- they contain the same string.
-
-
- crunch-client-header is only meant for quick tests.
- If you have to block several different headers, or only want to modify
- parts of them, you should use a
- client-header filter.
-
-
-
- Don't block any header without understanding the consequences.
-
-
-
-
-
-
- Example usage (section):
-
-
- # Block the non-existent "Privacy-Violation:" client header
-{ +crunch-client-header{Privacy-Violation:} }
-/
-
-
-
-
-
-
-
-
-
-
-crunch-if-none-match
-
-
-
- Typical use:
-
- Prevent yet another way to track the user's steps between sessions.
-
-
-
-
- Effect:
-
-
- Deletes the If-None-Match: HTTP client header.
-
-
-
-
-
- Type:
-
-
- Boolean.
-
-
-
-
- Parameter:
-
-
- N/A
-
-
-
-
-
- Notes:
-
-
- Removing the If-None-Match: HTTP client header
- is useful for filter testing, where you want to force a real
- reload instead of getting status code 304 which
- would cause the browser to use a cached copy of the page.
-
-
- It is also useful to make sure the header isn't used as a cookie
- replacement (unlikely but possible).
-
-
- Blocking the If-None-Match: header shouldn't cause any
- caching problems, as long as the If-Modified-Since: header
- isn't blocked or missing as well.
-
-
- It is recommended to use this action together with
- hide-if-modified-since
- and
- overwrite-last-modified.
-
-
-
-
-
- Example usage (section):
-
-
- # 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}
-/
-
-
-
-
-
-
-
-
-
-crunch-incoming-cookies
-
-
-
- Typical use:
-
-
- Prevent the web server from setting HTTP cookies on your system
-
-
-
-
-
- Effect:
-
-
- Deletes any Set-Cookie: HTTP headers from server replies.
-
-
-
-
-
- Type:
-
-
- Boolean.
-
-
-
-
- Parameter:
-
-
- N/A
-
-
-
-
-
- Notes:
-
-
- This action is only concerned with incoming HTTP cookies. For
- outgoing HTTP cookies, use
- crunch-outgoing-cookies.
- Use both to disable HTTP cookies completely.
-
-
- It makes no sense at all to use this action in conjunction
- with the session-cookies-only action,
- since it would prevent the session cookies from being set. See also
- filter-content-cookies.
-
-
-
-
-
- Example usage:
-
-
- +crunch-incoming-cookies
-
-
-
-
-
-
-
-
-
-crunch-server-header
-
-
-
- Typical use:
-
- Remove a server header Privoxy has no dedicated action for.
-
-
-
-
- Effect:
-
-
- Deletes every header sent by the server that contains the string the user supplied as parameter.
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
-
- Any string.
-
-
-
-
-
- Notes:
-
-
- This action allows you to block server headers for which no dedicated
- Privoxy action exists. Privoxy
- will remove every server header that contains the string you supplied as parameter.
-
-
- Regular expressions are not supported and you can't
- use this action to block different headers in the same request, unless
- they contain the same string.
-
-
- crunch-server-header is only meant for quick tests.
- If you have to block several different headers, or only want to modify
- parts of them, you should use a custom
- server-header filter.
-
-
-
- Don't block any header without understanding the consequences.
-
-
-
-
-
-
- Example usage (section):
-
-
- # Crunch server headers that try to prevent caching
-{ +crunch-server-header{no-cache} }
-/
-
-
-
-
-
-
-
-
-
-crunch-outgoing-cookies
-
-
-
- Typical use:
-
-
- Prevent the web server from reading any HTTP cookies from your system
-
-
-
-
-
- Effect:
-
-
- Deletes any Cookie: HTTP headers from client requests.
-
-
-
-
-
- Type:
-
-
- Boolean.
-
-
-
-
- Parameter:
-
-
- N/A
-
-
-
-
-
- Notes:
-
-
- This action is only concerned with outgoing HTTP cookies. For
- incoming HTTP cookies, use
- crunch-incoming-cookies.
- Use both to disable HTTP cookies completely.
-
-
- It makes no sense at all to use this action in conjunction
- with the session-cookies-only action,
- since it would prevent the session cookies from being read.
-
-
-
-
-
- Example usage:
-
-
- +crunch-outgoing-cookies
-
-
-
-
-
-
-
-
-
-
-deanimate-gifs
-
-
-
- Typical use:
-
- Stop those annoying, distracting animated GIF images.
-
-
-
-
- Effect:
-
-
- De-animate GIF animations, i.e. reduce them to their first or last image.
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
-
- last or first
-
-
-
-
-
- Notes:
-
-
- This will also shrink the images considerably (in bytes, not pixels!). If
- the option first is given, the first frame of the animation
- is used as the replacement. If last is given, the last
- frame of the animation is used instead, which probably makes more sense for
- most banner animations, but also has the risk of not showing the entire
- last frame (if it is only a delta to an earlier frame).
-
-
- You can safely use this action with patterns that will also match non-GIF
- objects, because no attempt will be made at anything that doesn't look like
- a GIF.
-
-
-
-
-
- Example usage:
-
-
- +deanimate-gifs{last}
-
-
-
-
-
-
-
-
-downgrade-http-version
-
-
-
- Typical use:
-
- Work around (very rare) problems with HTTP/1.1
-
-
-
-
- Effect:
-
-
- Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
-
-
-
-
-
- Type:
-
-
- Boolean.
-
-
-
-
- Parameter:
-
-
- N/A
-
-
-
-
-
- Notes:
-
-
- This is a left-over from the time when Privoxy
- 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 HTTP/1.1 features and requirements are supported yet,
- so there is a chance you might need this action.
-
-
-
-
-
- Example usage (section):
-
-
- {+downgrade-http-version}
-problem-host.example.com
-
-
-
-
-
-
-
-
-
-fast-redirects
-
-
-
- Typical use:
-
- Fool some click-tracking scripts and speed up indirect links.
-
-
-
-
- Effect:
-
-
- Detects redirection URLs and redirects the browser without contacting
- the redirection server first.
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
-
-
-
- simple-check to just search for the string http://
- to detect redirection URLs.
-
-
-
-
- check-decoded-url to decode URLs (if necessary) before searching
- for redirection URLs.
-
-
-
-
-
-
-
- Notes:
-
-
- Many sites, like yahoo.com, don't just link to other sites. Instead, they
- will link to some script on their own servers, giving the destination as a
- parameter, which will then redirect you to the final target. URLs
- resulting from this scheme typically look like:
- http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/.
-
-
- Sometimes, there are even multiple consecutive redirects encoded in the
- URL. These redirections via scripts make your web browsing more traceable,
- since the server from which you follow such a link can see where you go
- to. Apart from that, valuable bandwidth and time is wasted, while your
- browser asks the server for one redirect after the other. Plus, it feeds
- the advertisers.
-
-
- This feature is currently not very smart and is scheduled for improvement.
- If it is enabled by default, you will have to create some exceptions to
- this action. It can lead to failures in several ways:
-
-
- Not every URLs with other URLs as parameters is evil.
- Some sites offer a real service that requires this information to work.
- For example a validation service needs to know, which document to validate.
- fast-redirects assumes that every URL parameter that
- looks like another URL is a redirection target, and will always redirect to
- the last one. Most of the time the assumption is correct, but if it isn't,
- the user gets redirected anyway.
-
-
- Another failure occurs if the URL contains other parameters after the URL parameter.
- The URL:
- http://www.example.org/?redirect=http%3a//www.example.net/&foo=bar.
- contains the redirection URL http://www.example.net/,
- followed by another parameter. fast-redirects doesn't know that
- and will cause a redirect to http://www.example.net/&foo=bar.
- Depending on the target server configuration, the parameter will be silently ignored
- or lead to a page not found error. You can prevent this problem by
- first using the redirect action
- to remove the last part of the URL, but it requires a little effort.
-
-
- To detect a redirection URL, fast-redirects only
- looks for the string http://, either in plain text
- (invalid but often used) or encoded as http%3a//.
- Some sites use their own URL encoding scheme, encrypt the address
- of the target server or replace it with a database id. In theses cases
- fast-redirects is fooled and the request reaches the
- redirection server where it probably gets logged.
-
-
-
-
-
- Example usage:
-
-
-
- { +fast-redirects{simple-check} }
- one.example.com
-
- { +fast-redirects{check-decoded-url} }
- another.example.com/testing
-
-
-
-
-
-
-
-
-
-
-filter
-
-
-
- Typical use:
-
- Get rid of HTML and JavaScript annoyances, banner advertisements (by size),
- do fun text replacements, add personalized effects, etc.
-
-
-
-
- Effect:
-
-
- 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
- text/plain MIME type for all files whose type they don't know.)
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
-
- The name of a content filter, as defined in the filter file.
- Filters can be defined in one or more files as defined by the
- filterfile
- option in the config file.
- default.filter is the collection of filters
- supplied by the developers. Locally defined filters should go
- in their own file, such as user.filter.
-
-
- When used in its negative form,
- and without parameters, all filtering is completely disabled.
-
-
-
-
-
- Notes:
-
-
- For your convenience, there are a number of pre-defined filters available
- in the distribution filter file that you can use. See the examples below for
- a list.
-
-
- Filtering requires buffering the page content, which may appear to
- slow down page rendering since nothing is displayed until all content has
- passed the filters. (The total time until the page is completely rendered
- doesn't change much, but it may be perceived as slower since the page is
- not incrementally displayed.)
- This effect will be more noticeable on slower connections.
-
-
- Rolling your own
- filters requires a knowledge of
- Regular
- Expressions and
- HTML.
- This is very powerful feature, and potentially very intrusive.
- Filters should be used with caution, and where an equivalent
- action is not available.
-
-
- The amount of data that can be filtered is limited to the
- buffer-limit
- option in the main config file. The
- default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered
- data, and all pending data, is passed through unfiltered.
-
-
- Inappropriate MIME types, such as zipped files, are not filtered at all.
- (Again, only text-based types except plain text). Encrypted SSL data
- (from HTTPS servers) cannot be filtered either, since this would violate
- the integrity of the secure transaction. In some situations it might
- be necessary to protect certain text, like source code, from filtering
- by defining appropriate -filter exceptions.
-
-
- Compressed content can't be filtered either, but if &my-app;
- is compiled with zlib support and a supported compression algorithm
- is used (gzip or deflate), &my-app; can first decompress the content
- and then filter it.
-
-
- 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 prevent-compression
- action in conjunction with filter.
-
-
- Content filtering can achieve some of the same effects as the
- block
- 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
- based on their size (see below), since many of these seem to be somewhat
- standardized.
-
-
- Feedback with suggestions for new or
- improved filters is particularly welcome!
-
-
- The below list has only the names and a one-line description of each
- predefined filter. There are more
- verbose explanations of what these filters do in the filter file chapter.
-
-
-
-
-
- Example usage (with filters from the distribution default.filter file).
- See the Predefined Filters section for
- more explanation on each:
-
-
-
- +filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse.
-
-
-
- +filter{js-events} # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites).
-
-
-
- +filter{html-annoyances} # Get rid of particularly annoying HTML abuse.
-
-
-
- +filter{content-cookies} # Kill cookies that come in the HTML or JS content.
-
-
-
- +filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups).
-
-
-
- +filter{unsolicited-popups} # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability.
-
-
-
- +filter{all-popups} # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability.
-
-
-
- +filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective.
-
-
-
- +filter{banners-by-size} # Kill banners by size.
-
-
-
- +filter{banners-by-link} # Kill banners by their links to known clicktrackers.
-
-
-
- +filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking).
-
-
-
- +filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap.
-
-
-
- +filter{jumping-windows} # Prevent windows from resizing and moving themselves.
-
-
-
- +filter{frameset-borders} # Give frames a border and make them resizable.
-
-
-
- +filter{demoronizer} # Fix MS's non-standard use of standard charsets.
-
-
-
- +filter{shockwave-flash} # Kill embedded Shockwave Flash objects.
-
-
-
- +filter{quicktime-kioskmode} # Make Quicktime movies saveable.
-
-
-
- +filter{fun} # Text replacements for subversive browsing fun!
-
-
-
- +filter{crude-parental} # Crude parental filtering. Note that this filter doesn't work reliably.
-
-
-
- +filter{ie-exploits} # Disable some known Internet Explorer bug exploits.
-
-
-
- +filter{site-specifics} # Cure for site-specific problems. Don't apply generally!
-
-
-
- +filter{no-ping} # Removes non-standard ping attributes in <a> and <area> tags.
-
-
-
- +filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement.
-
-
-
- +filter{yahoo} # CSS-based block for Yahoo text ads. Also removes a width limitation.
-
-
-
- +filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation.
-
-
-
- +filter{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this.
-
-
-
-
-
-
-
-
-
-force-text-mode
-
-
-
- Typical use:
-
- Force Privoxy to treat a document as if it was in some kind of text format.
-
-
-
-
- Effect:
-
-
- Declares a document as text, even if the Content-Type: isn't detected as such.
-
-
-
-
-
- Type:
-
-
- Boolean.
-
-
-
-
- Parameter:
-
-
- N/A
-
-
-
-
-
- Notes:
-
-
- As explained above,
- Privoxy tries to only filter files that are
- in some kind of text format. The same restrictions apply to
- content-type-overwrite.
- force-text-mode declares a document as text,
- without looking at the Content-Type: first.
-
-
-
- Think twice before activating this action. Filtering binary data
- with regular expressions can cause file damage.
-
-
-
-
-
-
- Example usage:
-
-
-
-+force-text-mode
-
-
-
-
-
-
+
+
+
+
+ On MS Windows only there are two additional
+ command-line options to allow Privoxy to install and
+ run as a service. See the
+Window Installation section
+for details.
+
+
+
+
+
+
+
-
-forward-override
-
-
-
- Typical use:
-
- Change the forwarding settings based on User-Agent or request origin
-
-
+Privoxy Configuration
+
+ All Privoxy configuration is stored
+ in text files. These files can be edited with a text editor.
+ Many important aspects of Privoxy can
+ also be controlled easily with a web browser.
+
-
- Effect:
-
-
- Overrules the forward directives in the configuration file.
-
-
-
-
- Type:
-
-
- Multi-value.
-
-
+
-
- Parameter:
-
-
-
- forward . to use a direct connection without any additional proxies.
-
-
-
- forward 127.0.0.1:8123 to use the HTTP proxy listening at 127.0.0.1 port 8123.
-
-
-
-
- forward-socks4a 127.0.0.1:9050 . to use the socks4a proxy listening at
- 127.0.0.1 port 9050. Replace forward-socks4a with forward-socks4
- to use a socks4 connection (with local DNS resolution) instead, use forward-socks5
- for socks5 connections (with remote DNS resolution).
-
-
-
-
- forward-socks4a 127.0.0.1:9050 proxy.example.org:8000 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 forward-socks4a with forward-socks4 to use a socks4 connection
- (with local DNS resolution) instead, use forward-socks5
- for socks5 connections (with remote DNS resolution).
-
-
-
-
-
+
+Controlling Privoxy with Your Web Browser
+
+ Privoxy's user interface can be reached through the special
+ URL http://config.privoxy.org/
+ (shortcut: http://p.p/),
+ which is a built-in page and works without Internet access.
+ You will see the following section:
-
- Notes:
-
-
- This action takes parameters similar to the
- forward 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.
-
-
-
- Please read the description for the forward directives before
- using this action. Forwarding to the wrong people will reduce your privacy and increase the
- chances of man-in-the-middle attacks.
-
-
- 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.
-
-
- Use the show-url-info CGI page
- to verify that your forward settings do what you thought the do.
-
-
-
-
+
-
- Example usage:
-
-
-
-# Always use direct connections for requests previously tagged as
-# User-Agent: fetch libfetch/2.0 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$
-
-
-
-
-
-
+
+
+
+ Privoxy Menu
+
+
+ ▪ View & change the current configuration
+
+
+ ▪ View the source code version numbers
+
+
+ ▪ View the request headers.
+
+
+ ▪ Look up which actions apply to a URL and why
+
+
+ ▪ Toggle Privoxy on or off
+
+
+ ▪ Documentation
+
+
+
+
-
-
-handle-as-empty-document
-
-
-
- Typical use:
-
- Mark URLs that should be replaced by empty documents if they get blocked
-
-
-
- Effect:
-
-
- This action alone doesn't do anything noticeable. It just marks URLs.
- If the block action also applies,
- the presence or absence of this mark decides whether an HTML BLOCKED
- page, or an empty document will be sent to the client as a substitute for the blocked content.
- The empty document isn't literally empty, but actually contains a single space.
-
-
-
+
+ This should be self-explanatory. Note the first item leads to an editor for the
+ actions files, which is where the ad, banner,
+ cookie, and URL blocking magic is configured as well as other advanced features of
+ Privoxy. This is an easy way to adjust various
+ aspects of Privoxy configuration. The actions
+ file, and other configuration files, are explained in detail below.
+
-
- Type:
-
-
- Boolean.
-
-
+
+ Toggle Privoxy On or Off is handy for sites that might
+ have problems with your current actions and filters. You can in fact use
+ it as a test to see whether it is Privoxy
+ causing the problem or not. Privoxy continues
+ to run as a proxy in this case, but all manipulation is disabled, i.e.
+ Privoxy acts like a normal forwarding proxy.
+
-
- Parameter:
-
-
- N/A
-
-
-
+
+ Note that several of the features described above are disabled by default
+ in Privoxy 3.0.7 beta and later.
+ Check the
+ configuration file to learn why
+ and in which cases it's safe to enable them again.
+
+
+
+
+
-
- Notes:
-
-
- Some browsers complain about syntax errors if JavaScript documents
- are blocked with Privoxy's
- default HTML page; this option can be used to silence them.
- And of course this action can also be used to eliminate the &my-app;
- BLOCKED message in frames.
-
-
- The content type for the empty document can be specified with
- content-type-overwrite{},
- but usually this isn't necessary.
-
-
-
-
- Example usage:
-
-
- # Block all documents on example.org that end with ".js",
-# but send an empty document instead of the usual HTML message.
-{+block{Blocked JavaScript} +handle-as-empty-document}
-example.org/.*\.js$
-
-
-
-
-
-
-
-handle-as-image
-
-
- Typical use:
-
- Mark URLs as belonging to images (so they'll be replaced by images if they do get blocked, rather than HTML pages)
-
-
+
+Configuration Files Overview
+
+ For Unix, *BSD and Linux, all configuration files are located in
+ /etc/privoxy/ by default. For MS Windows, OS/2, and
+ AmigaOS these are all in the same directory as the
+ Privoxy executable.
+
-
- Effect:
-
-
- This action alone doesn't do anything noticeable. It just marks URLs as images.
- If the block action also applies,
- the presence or absence of this mark decides whether an HTML blocked
- page, or a replacement image (as determined by the set-image-blocker action) will be sent to the
- client as a substitute for the blocked content.
-
-
-
+
+ The installed defaults provide a reasonable starting point, though
+ some settings may be aggressive by some standards. For the time being, the
+ principle configuration files are:
+
-
- Type:
-
-
- Boolean.
-
-
+
+
-
- Parameter:
- N/A
+ The main configuration file is named config
+ on Linux, Unix, BSD, OS/2, and AmigaOS and config.txt
+ on Windows. This is a required file.
-
-
- Notes:
- The below generic example section is actually part of default.action.
- It marks all URLs with well-known image file name extensions as images and should
- be left intact.
+ match-all.action is used to define which actions
+ relating to banner-blocking, images, pop-ups, content modification, cookie handling
+ etc should be applied by default. It should be the first actions file loaded.
- Users will probably only want to use the handle-as-image action in conjunction with
- block, to block sources of banners, whose URLs don't
- reflect the file type, like in the second example section.
+ default.action defines many exceptions (both positive and negative)
+ from the default set of actions that's configured in match-all.action.
+ It should be the second actions file loaded and shouldn't be edited by the user.
- Note that you cannot treat HTML pages as images in most cases. For instance, (in-line) ad
- frames require an HTML page to be sent, or they won't display properly.
- Forcing handle-as-image in this situation will not replace the
- ad frame with an image, but lead to error messages.
+ Multiple actions files may be defined in config. These
+ are processed in the order they are defined. Local customizations and locally
+ preferred exceptions to the default policies as defined in
+ match-all.action (which you will most probably want
+ to define sooner or later) are best applied in user.action,
+ where you can preserve them across upgrades. The file isn't installed by all
+ installers, but you can easily create it yourself with a text editor.
+
+
+ There is also a web based editor that can be accessed from
+ http://config.privoxy.org/show-status
+ (Shortcut: http://p.p/show-status) for the
+ various actions files.
-
-
- Example usage (sections):
- # Generic image extensions:
-#
-{+handle-as-image}
-/.*\.(gif|jpg|jpeg|png|bmp|ico)$
-
-# These don't look like images, but they're banners and should be
-# blocked as images:
-#
-{+block{Nasty banners.} +handle-as-image}
-nasty-banner-server.example.com/junk.cgi\?output=trash
-
+ Filter files (the filter
+ file) can be used to re-write the raw page content, including
+ viewable text as well as embedded HTML and JavaScript, and whatever else
+ lurks on any given web page. The filtering jobs are only pre-defined here;
+ whether to apply them or not is up to the actions files.
+ default.filter includes various filters made
+ available for use by the developers. Some are much more intrusive than
+ others, and all should be used with caution. You may define additional
+ filter files in config as you can with
+ actions files. We suggest user.filter for any
+ locally defined filters or customizations.
-
-
-
+
+
-
-
-hide-accept-language
-
-
-
- Typical use:
-
- Pretend to use different language settings.
-
-
+
+ The syntax of the configuration and filter files may change between different
+ Privoxy versions, unfortunately some enhancements cost backwards compatibility.
+
+
-
- Effect:
-
-
- Deletes or replaces the Accept-Language: HTTP header in client requests.
-
-
-
+
+ All files use the # character to denote a
+ comment (the rest of the line will be ignored) and understand line continuation
+ through placing a backslash ("\") as the very last character
+ in a line. If the # is preceded by a backslash, it looses
+ its special function. Placing a # in front of an otherwise
+ valid configuration line to prevent it from being interpreted is called "commenting
+ out" that line. Blank lines are ignored.
+
-
- Type:
-
-
- Parameterized.
-
-
+
+ The actions files and filter files
+ can use Perl style regular expressions for
+ maximum flexibility.
+
-
- Parameter:
-
-
- Keyword: block, or any user defined value.
-
-
-
+
+ After making any changes, there is no need to restart
+ Privoxy in order for the changes to take
+ effect. Privoxy detects such changes
+ automatically. Note, however, that it may take one or two additional
+ requests for the change to take effect. When changing the listening address
+ of Privoxy, these wake up requests
+ must obviously be sent to the old listening address.
+
-
- Notes:
-
-
- Faking the browser's language settings can be useful to make a
- foreign User-Agent set with
- hide-user-agent
- more believable.
-
-
- However some sites with content in different languages check the
- Accept-Language: to decide which one to take by default.
- Sometimes it isn't possible to later switch to another language without
- changing the Accept-Language: header first.
-
-
- Therefore it's a good idea to either only change the
- Accept-Language: header to languages you understand,
- or to languages that aren't wide spread.
-
-
- Before setting the Accept-Language: header
- to a rare language, you should consider that it helps to
- make your requests unique and thus easier to trace.
- If you don't plan to change this header frequently,
- you should stick to a common language.
-
-
-
+
+ While under development, the configuration content is subject to change.
+ The below documentation may not be accurate by the time you read this.
+ Also, what constitutes a default setting, may change, so
+ please check all your configuration files on important issues.
+
+]]>
-
- Example usage (section):
-
-
- # Pretend to use Canadian language settings.
-{+hide-accept-language{en-ca} \
-+hide-user-agent{Mozilla/5.0 (X11; U; OpenBSD i386; en-CA; rv:1.8.0.4) Gecko/20060628 Firefox/1.5.0.4} \
-}
-/
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+ &config;
+
+
+
+
+
+
+
+
+
+Actions Files
-
-
-hide-content-disposition
-
-
- Typical use:
-
- Prevent download menus for content you prefer to view inside the browser.
-
-
-
-
- Effect:
+
+ The actions files are used to define what actions
+ Privoxy takes for which URLs, and thus determines
+ how ad images, cookies and various other aspects of HTTP content and
+ transactions are handled, and on which sites (or even parts thereof).
+ There are a number of such actions, with a wide range of functionality.
+ Each action does something a little different.
+ These actions give us a veritable arsenal of tools with which to exert
+ our control, preferences and independence. Actions can be combined so that
+ their effects are aggregated when applied against a given set of URLs.
+
+
+ There
+ are three action files included with Privoxy with
+ differing purposes:
+
+
+
- Deletes or replaces the Content-Disposition: HTTP header set by some servers.
+ match-all.action - is used to define which
+ actions relating to banner-blocking, images, pop-ups,
+ content modification, cookie handling etc should be applied by default.
+ It should be the first actions file loaded
-
-
-
- Type:
-
- Parameterized.
+
+ default.action - defines many exceptions (both
+ positive and negative) from the default set of actions that's configured
+ in match-all.action. It is a set of rules that should
+ work reasonably well as-is for most users. This file is only supposed to
+ be edited by the developers. It should be the second actions file loaded.
+
-
-
-
- Parameter:
- Keyword: block, or any user defined value.
+ user.action - is intended to be for local site
+ preferences and exceptions. As an example, if your ISP or your bank
+ has specific requirements, and need special handling, this kind of
+ thing should go here. This file will not be upgraded.
-
-
-
- Notes:
- Some servers set the Content-Disposition: HTTP header for
- documents they assume you want to save locally before viewing them.
- The Content-Disposition: header contains the file name
- the browser is supposed to use by default.
+ EditSet to CautiousSet to MediumSet to Advanced
- In most browsers that understand this header, it makes it impossible to
- just view the document, without downloading it first,
- even if it's just a simple text file or an image.
+ These have increasing levels of aggressiveness and have no
+ influence on your browsing unless you select them explicitly in the
+ editor. A default installation should be pre-set to
+ Cautious. New users should try this for a while before
+ adjusting the settings to more aggressive levels. The more aggressive
+ the settings, then the more likelihood there is of problems such as sites
+ not working as they should.
- Removing the Content-Disposition: header helps
- to prevent this annoyance, but some browsers additionally check the
- Content-Type: header, before they decide if they can
- display a document without saving it first. In these cases, you have
- to change this header as well, before the browser stops displaying
- download menus.
+ The Edit button allows you to turn each
+ action on/off individually for fine-tuning. The Cautious
+ button changes the actions list to low/safe settings which will activate
+ ad blocking and a minimal set of &my-app;'s features, and subsequently
+ there will be less of a chance for accidental problems. The
+ Medium button sets the list to a medium level of
+ other features and a low level set of privacy features. The
+ Advanced button sets the list to a high level of
+ ad blocking and medium level of privacy. See the chart below. The latter
+ three buttons over-ride any changes via with the
+ Edit button. More fine-tuning can be done in the
+ lower sections of this internal page.
- It is also possible to change the server's file name suggestion
- to another one, but in most cases it isn't worth the time to set
- it up.
+ While the actions file editor allows to enable these settings in all
+ actions files, they are only supposed to be enabled in the first one
+ to make sure you don't unintentionally overrule earlier rules.
- This action will probably be removed in the future,
- use server-header filters instead.
+ The default profiles, and their associated actions, as pre-defined in
+ default.action are:
+
+
Default Configurations
+
+
+
+
+
+
+
+ Feature
+ Cautious
+ Medium
+ Advanced
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Ad-blocking Aggressiveness
+ medium
+ high
+ high
+
+
+
+ Ad-filtering by size
+ no
+ yes
+ yes
+
+
+
+ Ad-filtering by link
+ no
+ no
+ yes
+
+
+ Pop-up killing
+ blocks only
+ blocks only
+ blocks only
+
+
+
+ Privacy Features
+ low
+ medium
+ medium/high
+
+
+
+ Cookie handling
+ none
+ session-only
+ kill
+
+
+
+ Referer forging
+ no
+ yes
+ yes
+
+
+
+ GIF de-animation
+ no
+ yes
+ yes
+
+
+
+ Fast redirects
+ no
+ no
+ yes
+
+
+
+ HTML taming
+ no
+ no
+ yes
+
+
+
+ JavaScript taming
+ no
+ no
+ yes
+
+
+
+ Web-bug killing
+ no
+ yes
+ yes
+
+
+
+ Image tag reordering
+ no
+ yes
+ yes
+
+
+
+
+
+
+ Notes:
+
- http://config.privoxy.org/
+ The URLs for the built-in images are http://config.privoxy.org/send-banner?type=type, where type is
+ either blank or pattern.
-
-
- There is a shortcut: http://p.p/ (But it
- doesn't provide a fall-back to a real page, in case the request is not
- sent through Privoxy)
-
-
-
-
-
- Show information about the current configuration, including viewing and
- editing of actions files:
-
-
- http://config.privoxy.org/show-status
+ There is a third (advanced) type, called auto. It is NOT to be
+ used in set-image-blocker, but meant for use from filters.
+ Auto will select the type of image that would have applied to the referring page, had it been an image.
-
-
+
+
-
-
- Show the source code version numbers:
-
-
-
-
-
-
- Show which actions apply to a URL and why:
-
-
- http://config.privoxy.org/show-url-info
+ Redirect to the BSD daemon:
-
-
-
-
-
- Toggle Privoxy on or off. This feature can be turned off/on in the main
- config file. When toggled off, Privoxy
- continues to run, but only as a pass-through proxy, with no actions taking
- place:
-
-
+
+ There is a shortcut: http://p.p/ (But it
+ doesn't provide a fall-back to a real page, in case the request is not
+ sent through Privoxy)
+
+
- Revision 1.77 2002/04/17 13:51:23 oes
- Proofreading, part one
+
+
+ Show information about the current configuration, including viewing and
+ editing of actions files:
+
+
+
+ http://config.privoxy.org/show-status
+
+
+
- Revision 1.76 2002/04/16 04:25:51 hal9
- -Added 'Note to Upgraders' and re-ordered the 'Quickstart' section.
- -Note about proxy may need requests to re-read config files.
+
+
+ Show the source code version numbers:
+
+
+
+ http://config.privoxy.org/show-version
+
+
+
- Revision 1.75 2002/04/12 02:08:48 david__schmidt
- Remove OS/2 building info... it is already in the developer-manual
+
+
+ Show the browser's request headers:
+
+
+
+ http://config.privoxy.org/show-request
+
+
+
- Revision 1.74 2002/04/11 00:54:38 hal9
- Add small section on submitting actions.
+
+
+ Show which actions apply to a URL and why:
+
+
+
+ http://config.privoxy.org/show-url-info
+
+
+
- Revision 1.73 2002/04/10 18:45:15 swa
- generated
+
+
+ Toggle Privoxy on or off. This feature can be turned off/on in the main
+ config file. When toggled off, Privoxy
+ continues to run, but only as a pass-through proxy, with no actions taking
+ place:
+
+
+
- Revision 1.72 2002/04/10 04:06:19 hal9
- Added actions feedback to Bookmarklets section
+
+
- Revision 1.71 2002/04/08 22:59:26 hal9
- Version update. Spell chkconfig correctly :)
+
- Revision 1.70 2002/04/08 20:53:56 swa
- ?
- Revision 1.69 2002/04/06 05:07:29 hal9
- -Add privoxy-man-page.sgml, for man page.
- -Add authors.sgml for AUTHORS (and p-authors.sgml)
- -Reworked various aspects of various docs.
- -Added additional comments to sub-docs.
+
+
+Chain of Events
+
+ Let's take a quick look at how some of Privoxy's
+ core features are triggered, and the ensuing sequence of events when a web
+ page is requested by your browser:
+
- Revision 1.68 2002/04/04 18:46:47 swa
- consistent look. reuse of copyright, history et. al.
+
+
+
+
+ First, your web browser requests a web page. The browser knows to send
+ the request to Privoxy, which will in turn,
+ relay the request to the remote web server after passing the following
+ tests:
+
+
+
+
+ Privoxy traps any request for its own internal CGI
+ pages (e.g http://p.p/) and sends the CGI page back to the browser.
+
+
+
+
+ Next, Privoxy checks to see if the URL
+ matches any +block patterns. If
+ so, the URL is then blocked, and the remote web server will not be contacted.
+ +handle-as-image
+ and
+ +handle-as-empty-document
+ are then checked, and if there is no match, an
+ HTML BLOCKED page is sent back to the browser. Otherwise, if
+ it does match, an image is returned for the former, and an empty text
+ document for the latter. The type of image would depend on the setting of
+ +set-image-blocker
+ (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
+
+
+
+
+ Untrusted URLs are blocked. If URLs are being added to the
+ trust file, then that is done.
+
+
+
+
+ If the URL pattern matches the +fast-redirects action,
+ it is then processed. Unwanted parts of the requested URL are stripped.
+
+
+
+
+ Now the rest of the client browser's request headers are processed. If any
+ of these match any of the relevant actions (e.g. +hide-user-agent,
+ etc.), headers are suppressed or forged as determined by these actions and
+ their parameters.
+
+
+
+
+ Now the web server starts sending its response back (i.e. typically a web
+ page).
+
+
+
+
+ First, the server headers are read and processed to determine, among other
+ things, the MIME type (document type) and encoding. The headers are then
+ filtered as determined by the
+ +crunch-incoming-cookies,
+ +session-cookies-only,
+ and +downgrade-http-version
+ actions.
+
+
+
+
+ If any +filter action
+ or +deanimate-gifs
+ action applies (and the document type fits the action), the rest of the page is
+ read into memory (up to a configurable limit). Then the filter rules (from
+ default.filter and any other filter files) are
+ processed against the buffered content. Filters are applied in the order
+ they are specified in one of the filter files. Animated GIFs, if present,
+ are reduced to either the first or last frame, depending on the action
+ setting.The entire page, which is now filtered, is then sent by
+ Privoxy back to your browser.
+
+
+ If neither a +filter action
+ or +deanimate-gifs
+ matches, then Privoxy passes the raw data through
+ to the client browser as it becomes available.
+
+
+
+
+ As the browser receives the now (possibly filtered) page content, it
+ reads and then requests any URLs that may be embedded within the page
+ source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
+ frames), sounds, etc. For each of these objects, the browser issues a
+ separate request (this is easily viewable in Privoxy's
+ logs). And each such request is in turn processed just as above. Note that a
+ complex web page will have many, many such embedded URLs. If these
+ secondary requests are to a different server, then quite possibly a very
+ differing set of actions is triggered.
+
+
- Revision 1.67 2002/04/04 17:27:57 swa
- more single file to be included at multiple points. make maintaining easier
+
+
+
+ NOTE: This is somewhat of a simplistic overview of what happens with each URL
+ request. For the sake of brevity and simplicity, we have focused on
+ Privoxy's core features only.
+
- Revision 1.66 2002/04/04 06:48:37 hal9
- Structural changes to allow for conditional inclusion/exclusion of content
- based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
- definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
- eventually be set by Makefile.
- More boilerplate text for use across multiple docs.
+
- Revision 1.65 2002/04/03 19:52:07 swa
- enhance squid section due to user suggestion
- Revision 1.64 2002/04/03 03:53:43 hal9
- A few minor bug fixes, and touch ups. Ready for review.
+
+
+Troubleshooting: Anatomy of an Action
- Revision 1.63 2002/04/01 16:24:49 hal9
- Define entities to include boilerplate text. See doc/source/*.
+
+ The way Privoxy applies
+ actions and filters
+ to any given URL can be complex, and not always so
+ easy to understand what is happening. And sometimes we need to be able to
+ see just what Privoxy is
+ doing. Especially, if something Privoxy is doing
+ is causing us a problem inadvertently. It can be a little daunting to look at
+ the actions and filters files themselves, since they tend to be filled with
+ regular expressions whose consequences are not
+ always so obvious.
+
- Revision 1.62 2002/03/30 04:15:53 hal9
- - Fix privoxy.org/config links.
- - Paste in Bookmarklets from Toggle page.
- - Move Quickstart nearer top, and minor rework.
+
+ One quick test to see if Privoxy is causing a problem
+ or not, is to disable it temporarily. This should be the first troubleshooting
+ step (be sure to flush caches afterward!). Looking at the
+ logs is a good idea too. (Note that both the toggle feature and logging are
+ enabled via config file settings, and may need to be
+ turned on.)
+
+
+ Another easy troubleshooting step to try is if you have done any
+ customization of your installation, revert back to the installed
+ defaults and see if that helps. There are times the developers get complaints
+ about one thing or another, and the problem is more related to a customized
+ configuration issue.
+
- Revision 1.61 2002/03/29 01:31:08 hal9
- Minor update.
+
+ Privoxy also provides the
+ http://config.privoxy.org/show-url-info
+ page that can show us very specifically how actions
+ are being applied to any given URL. This is a big help for troubleshooting.
+
- Revision 1.60 2002/03/27 01:57:34 hal9
- Added more to Anatomy section.
+
+ First, enter one URL (or partial URL) at the prompt, and then
+ Privoxy will tell us
+ how the current configuration will handle it. This will not
+ help with filtering effects (i.e. the +filter action) from
+ one of the filter files since this is handled very
+ differently and not so easy to trap! It also will not tell you about any other
+ URLs that may be embedded within the URL you are testing. For instance, images
+ such as ads are expressed as URLs within the raw page source of HTML pages. So
+ you will only get info for the actual URL that is pasted into the prompt area
+ -- not any sub-URLs. If you want to know about embedded URLs like ads, you
+ will have to dig those out of the HTML source. Use your browser's View
+ Page Source option for this. Or right click on the ad, and grab the
+ URL.
+
- Revision 1.59 2002/03/27 00:54:33 hal9
- Touch up intro for new name.
+
+ Let's try an example, google.com,
+ and look at it one section at a time in a sample configuration (your real
+ configuration may vary):
+
- Revision 1.58 2002/03/26 22:29:55 swa
- we have a new homepage!
+
+
+ Matches for http://www.google.com:
- Revision 1.57 2002/03/24 20:33:30 hal9
- A few minor catch ups with name change.
+ In file: default.action [ View ][ Edit ]
- Revision 1.56 2002/03/24 16:17:06 swa
- configure needs to be generated.
+ {+change-x-forwarded-for{block}
+ +deanimate-gifs {last}
+ +fast-redirects {check-decoded-url}
+ +filter {refresh-tags}
+ +filter {img-reorder}
+ +filter {banners-by-size}
+ +filter {webbugs}
+ +filter {jumping-windows}
+ +filter {ie-exploits}
+ +hide-from-header {block}
+ +hide-referrer {forge}
+ +session-cookies-only
+ +set-image-blocker {pattern}
+/
- Revision 1.55 2002/03/24 16:08:08 swa
- we are too lazy to make a block-built
- privoxy logo. hence removed the option.
+ { -session-cookies-only }
+ .google.com
- Revision 1.54 2002/03/24 15:46:20 swa
- name change related issue.
+ { -fast-redirects }
+ .google.com
- Revision 1.53 2002/03/24 11:51:00 swa
- name change. changed filenames.
+In file: user.action [ View ][ Edit ]
+(no matches in this file)
+
+
- Revision 1.52 2002/03/24 11:01:06 swa
- name change
+
+ This is telling us how we have defined our
+ actions, and
+ which ones match for our test case, google.com.
+ Displayed is all the actions that are available to us. Remember,
+ the + sign denotes on. -
+ denotes off. So some are on here, but many
+ are off. Each example we try may provide a slightly different
+ end result, depending on our configuration directives.
+
+
+ The first listing
+ is for our default.action file. The large, multi-line
+ listing, is how the actions are set to match for all URLs, i.e. our default
+ settings. If you look at your actions file, this would be the
+ section just below the aliases section near the top. This
+ will apply to all URLs as signified by the single forward slash at the end
+ of the listing -- / .
+
- Revision 1.51 2002/03/23 15:13:11 swa
- renamed every reference to the old name with foobar.
- fixed "application foobar application" tag, fixed
- "the foobar" with "foobar". left junkbustser in cvs
- comments and remarks to history untouched.
+
+ But we have defined additional actions that would be exceptions to these general
+ rules, and then we list specific URLs (or patterns) that these exceptions
+ would apply to. Last match wins. Just below this then are two explicit
+ matches for .google.com. The first is negating our previous
+ cookie setting, which was for +session-cookies-only
+ (i.e. not persistent). So we will allow persistent cookies for google, at
+ least that is how it is in this example. The second turns
+ off any +fast-redirects
+ action, allowing this to take place unmolested. Note that there is a leading
+ dot here -- .google.com. This will match any hosts and
+ sub-domains, in the google.com domain also, such as
+ www.google.com or mail.google.com. But it would not
+ match www.google.de! So, apparently, we have these two actions
+ defined as exceptions to the general rules at the top somewhere in the lower
+ part of our default.action file, and
+ google.com is referenced somewhere in these latter sections.
+
- Revision 1.50 2002/03/23 05:06:21 hal9
- Touch up.
+
+ Then, for our user.action file, we again have no hits.
+ So there is nothing google-specific that we might have added to our own, local
+ configuration. If there was, those actions would over-rule any actions from
+ previously processed files, such as default.action.
+ user.action typically has the last word. This is the
+ best place to put hard and fast exceptions,
+
- Revision 1.49 2002/03/21 17:01:05 hal9
- New section in Appendix.
+
+ And finally we pull it all together in the bottom section and summarize how
+ Privoxy is applying all its actions
+ to google.com:
- Revision 1.48 2002/03/12 06:33:01 hal9
- Catching up to Andreas and re_filterfile changes.
+
- Revision 1.47 2002/03/11 13:13:27 swa
- correct feedback channels
+
+
- Revision 1.46 2002/03/10 00:51:08 hal9
- Added section on JB internal pages in Appendix.
+ Final results:
- Revision 1.45 2002/03/09 17:43:53 swa
- more distros
+ -add-header
+ -block
+ +change-x-forwarded-for{block}
+ -client-header-filter{hide-tor-exit-notation}
+ -content-type-overwrite
+ -crunch-client-header
+ -crunch-if-none-match
+ -crunch-incoming-cookies
+ -crunch-outgoing-cookies
+ -crunch-server-header
+ +deanimate-gifs {last}
+ -downgrade-http-version
+ -fast-redirects
+ -filter {js-events}
+ -filter {content-cookies}
+ -filter {all-popups}
+ -filter {banners-by-link}
+ -filter {tiny-textforms}
+ -filter {frameset-borders}
+ -filter {demoronizer}
+ -filter {shockwave-flash}
+ -filter {quicktime-kioskmode}
+ -filter {fun}
+ -filter {crude-parental}
+ -filter {site-specifics}
+ -filter {js-annoyances}
+ -filter {html-annoyances}
+ +filter {refresh-tags}
+ -filter {unsolicited-popups}
+ +filter {img-reorder}
+ +filter {banners-by-size}
+ +filter {webbugs}
+ +filter {jumping-windows}
+ +filter {ie-exploits}
+ -filter {google}
+ -filter {yahoo}
+ -filter {msn}
+ -filter {blogspot}
+ -filter {no-ping}
+ -force-text-mode
+ -handle-as-empty-document
+ -handle-as-image
+ -hide-accept-language
+ -hide-content-disposition
+ +hide-from-header {block}
+ -hide-if-modified-since
+ +hide-referrer {forge}
+ -hide-user-agent
+ -limit-connect
+ -overwrite-last-modified
+ -prevent-compression
+ -redirect
+ -server-header-filter{xml-to-html}
+ -server-header-filter{html-to-xml}
+ -session-cookies-only
+ +set-image-blocker {pattern}
+
- Revision 1.44 2002/03/09 17:08:48 hal9
- New section on Jon's actions file editor, and move some stuff around.
+
+ Notice the only difference here to the previous listing, is to
+ fast-redirects and session-cookies-only,
+ which are activated specifically for this site in our configuration,
+ and thus show in the Final Results.
+
- Revision 1.43 2002/03/08 00:47:32 hal9
- Added imageblock{pattern}.
+
+ Now another example, ad.doubleclick.net:
+
- Revision 1.42 2002/03/07 18:16:55 swa
- looks better
+
+
- Revision 1.41 2002/03/07 16:46:43 hal9
- Fix a few markup problems for jade.
+ { +block{Domains starts with "ad"} }
+ ad*.
- Revision 1.40 2002/03/07 16:28:39 swa
- provide correct feedback channels
+ { +block{Domain contains "ad"} }
+ .ad.
- Revision 1.39 2002/03/06 16:19:28 hal9
- Note on perceived filtering slowdown per FR.
+ { +block{Doubleclick banner server} +handle-as-image }
+ .[a-vx-z]*.doubleclick.net
+
+
- Revision 1.38 2002/03/05 23:55:14 hal9
- Stupid I did it again. Double hyphen in comment breaks jade.
+
+ We'll just show the interesting part here - the explicit matches. It is
+ matched three different times. Two +block{} sections,
+ and a +block{} +handle-as-image,
+ which is the expanded form of one of our aliases that had been defined as:
+ +block-as-image. (Aliases are defined in
+ the first section of the actions file and typically used to combine more
+ than one action.)
+
- Revision 1.37 2002/03/05 23:53:49 hal9
- jade barfs on '- -' embedded in comments. - -user option broke it.
+
+ Any one of these would have done the trick and blocked this as an unwanted
+ image. This is unnecessarily redundant since the last case effectively
+ would also cover the first. No point in taking chances with these guys
+ though ;-) Note that if you want an ad or obnoxious
+ URL to be invisible, it should be defined as ad.doubleclick.net
+ is done here -- as both a +block{}
+ and an
+ +handle-as-image.
+ The custom alias +block-as-image just
+ simplifies the process and make it more readable.
+
- Revision 1.36 2002/03/05 22:53:28 hal9
- Add new - - user option.
+
+ One last example. Let's try http://www.example.net/adsl/HOWTO/.
+ This one is giving us problems. We are getting a blank page. Hmmm ...
+
- Revision 1.35 2002/03/05 00:17:27 hal9
- Added section on command line options.
+
+
- Revision 1.34 2002/03/04 19:32:07 oes
- Changed default port to 8118
+ Matches for http://www.example.net/adsl/HOWTO/:
- Revision 1.33 2002/03/03 19:46:13 hal9
- Emphasis on where/how to report bugs, etc
+ In file: default.action [ View ][ Edit ]
- Revision 1.32 2002/03/03 09:26:06 joergs
- AmigaOS changes, config is now loaded from PROGDIR: instead of
- AmiTCP:db/junkbuster/ if no configuration file is specified on the
- command line.
+ {-add-header
+ -block
+ +change-x-forwarded-for{block}
+ -client-header-filter{hide-tor-exit-notation}
+ -content-type-overwrite
+ -crunch-client-header
+ -crunch-if-none-match
+ -crunch-incoming-cookies
+ -crunch-outgoing-cookies
+ -crunch-server-header
+ +deanimate-gifs
+ -downgrade-http-version
+ +fast-redirects {check-decoded-url}
+ -filter {js-events}
+ -filter {content-cookies}
+ -filter {all-popups}
+ -filter {banners-by-link}
+ -filter {tiny-textforms}
+ -filter {frameset-borders}
+ -filter {demoronizer}
+ -filter {shockwave-flash}
+ -filter {quicktime-kioskmode}
+ -filter {fun}
+ -filter {crude-parental}
+ -filter {site-specifics}
+ -filter {js-annoyances}
+ -filter {html-annoyances}
+ +filter {refresh-tags}
+ -filter {unsolicited-popups}
+ +filter {img-reorder}
+ +filter {banners-by-size}
+ +filter {webbugs}
+ +filter {jumping-windows}
+ +filter {ie-exploits}
+ -filter {google}
+ -filter {yahoo}
+ -filter {msn}
+ -filter {blogspot}
+ -filter {no-ping}
+ -force-text-mode
+ -handle-as-empty-document
+ -handle-as-image
+ -hide-accept-language
+ -hide-content-disposition
+ +hide-from-header{block}
+ +hide-referer{forge}
+ -hide-user-agent
+ -overwrite-last-modified
+ +prevent-compression
+ -redirect
+ -server-header-filter{xml-to-html}
+ -server-header-filter{html-to-xml}
+ +session-cookies-only
+ +set-image-blocker{blank} }
+ /
- Revision 1.31 2002/03/02 22:45:52 david__schmidt
- Just tweaking
+ { +block{Path contains "ads".} +handle-as-image }
+ /ads
+
+
- Revision 1.30 2002/03/02 22:00:14 hal9
- Updated 'New Features' list. Ran through spell-checker.
+
+ Ooops, the /adsl/ is matching /ads in our
+ configuration! But we did not want this at all! Now we see why we get the
+ blank page. It is actually triggering two different actions here, and
+ the effects are aggregated so that the URL is blocked, and &my-app; is told
+ to treat the block as if it were an image. But this is, of course, all wrong.
+ We could now add a new action below this (or better in our own
+ user.action file) that explicitly
+ un blocks (
+ {-block}) paths with
+ adsl in them (remember, last match in the configuration
+ wins). There are various ways to handle such exceptions. Example:
+
- Revision 1.29 2002/03/02 20:34:07 david__schmidt
- Update OS/2 build section
+
+
- Revision 1.28 2002/02/24 14:34:24 jongfoster
- Formatting changes. Now changing the doctype to DocBook XML 4.1
- will work - no other changes are needed.
+ { -block }
+ /adsl
+
+
- Revision 1.27 2002/01/11 14:14:32 hal9
- Added a very short section on Templates
+
+ Now the page displays ;-)
+ Remember to flush your browser's caches when making these kinds of changes to
+ your configuration to insure that you get a freshly delivered page! Or, try
+ using Shift+Reload.
+
- Revision 1.26 2002/01/09 20:02:50 hal9
- Fix bug re: auto-detect config file changes.
+
+ But now what about a situation where we get no explicit matches like
+ we did with:
+
- Revision 1.25 2002/01/09 18:20:30 hal9
- Touch ups for *.action files.
+
+
- Revision 1.24 2001/12/02 01:13:42 hal9
- Fix typo.
+ { +block{Path starts with "ads".} +handle-as-image }
+ /ads
+
+
- Revision 1.23 2001/12/02 00:20:41 hal9
- Updates for recent changes.
+
+ That actually was very helpful and pointed us quickly to where the problem
+ was. If you don't get this kind of match, then it means one of the default
+ rules in the first section of default.action is causing
+ the problem. This would require some guesswork, and maybe a little trial and
+ error to isolate the offending rule. One likely cause would be one of the
+ +filter actions.
+ These tend to be harder to troubleshoot.
+ Try adding the URL for the site to one of aliases that turn off
+ +filter:
+
- Revision 1.22 2001/11/05 23:57:51 hal9
- Minor update for startup now daemon mode.
+
+
- Revision 1.21 2001/10/31 21:11:03 hal9
- Correct 2 minor errors
+ { shop }
+ .quietpc.com
+ .worldpay.com # for quietpc.com
+ .jungle.com
+ .scan.co.uk
+ .forbes.com
+
+
- Revision 1.18 2001/10/24 18:45:26 hal9
- *** empty log message ***
+
+ { shop } is an alias that expands to
+ { -filter -session-cookies-only }.
+ Or you could do your own exception to negate filtering:
- Revision 1.17 2001/10/24 17:10:55 hal9
- Catching up with Jon's recent work, and a few other things.
+
- Revision 1.16 2001/10/21 17:19:21 swa
- wrong url in documentation
+
+
- Revision 1.15 2001/10/14 23:46:24 hal9
- Various minor changes. Fleshed out SEE ALSO section.
+ { -filter }
+ # Disable ALL filter actions for sites in this section
+ .forbes.com
+ developer.ibm.com
+ localhost
+
+
- Revision 1.13 2001/10/10 17:28:33 hal9
- Very minor changes.
+
+ This would turn off all filtering for these sites. This is best
+ put in user.action, for local site
+ exceptions. Note that when a simple domain pattern is used by itself (without
+ the subsequent path portion), all sub-pages within that domain are included
+ automatically in the scope of the action.
+
- Revision 1.12 2001/09/28 02:57:04 hal9
- Ditto :/
+
+ Images that are inexplicably being blocked, may well be hitting the
++filter{banners-by-size}
+ rule, which assumes
+ that images of certain sizes are ad banners (works well
+ most of the time since these tend to be standardized).
+
- Revision 1.11 2001/09/28 02:25:20 hal9
- Ditto.
+
+ { fragile } is an alias that disables most
+ actions that are the most likely to cause trouble. This can be used as a
+ last resort for problem sites.
+
+
+
- Revision 1.9 2001/09/27 23:50:29 hal9
- A few changes. A short section on regular expression in appendix.
+ { fragile }
+ # Handle with care: easy to break
+ mail.google.
+ mybank.example.com
+
- Revision 1.8 2001/09/25 00:34:59 hal9
- Some additions, and re-arranging.
- Revision 1.7 2001/09/24 14:31:36 hal9
- Diddling.
+
+ Remember to flush caches! Note that the
+ mail.google reference lacks the TLD portion (e.g.
+ .com). This will effectively match any TLD with
+ google in it, such as mail.google.de.,
+ just as an example.
+
+
+ If this still does not work, you will have to go through the remaining
+ actions one by one to find which one(s) is causing the problem.
+
- Revision 1.6 2001/09/24 14:10:32 hal9
- Including David's OS/2 installation instructions.
+
- Revision 1.2 2001/09/13 15:27:40 swa
- cosmetics
+
- Revision 1.1 2001/09/12 15:36:41 swa
- source files for junkbuster documentation
+