X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fsource%2Fuser-manual.sgml;h=dc9c3d8ea36ced3dcffbeb49bbd8b4fc6d353b62;hb=3032d1aecd9453c12fb2163c6477034ee327934e;hp=68673ad8fc7390fd6c75276359f24b9f10c42a22;hpb=4ca1b3964ffd8d2ac27cf2a9f4de9bb7ac67259e;p=privoxy.git
diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index 68673ad8..dc9c3d8e 100644
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -9,13 +9,15 @@
+
-
-
+
+
+
-
-
+
+
@@ -28,15 +30,11 @@
Privoxy">
]>
- Copyright &my-copy; 2001-2011 by
- Privoxy Developers
+ Copyright &my-copy; 2001-2020 by
+ Privoxy Developers
-$Id: user-manual.sgml,v 2.145 2011/12/26 17:04:19 fabiankeil Exp $
-
@@ -99,14 +95,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 +108,7 @@ Hal.
Introduction
This documentation is included with the current &p-status; version of
- Privoxy, v.&p-version;Privoxy, &p-version;
Since this is a &p-status; version, not all new features are well tested. This
documentation may be slightly out of sync as a result (especially with
- CVS sources). And there may be bugs, though hopefully
+ git sources).
+ And there may be bugs, though hopefully
not many!
]]>
@@ -160,7 +154,7 @@ Hal.
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 +174,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 +226,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
@@ -282,7 +236,6 @@ How to install the binary packages depends on your operating system:
system. Check that no Junkbuster
or Privoxy objects are in
your startup folder.
-
@@ -301,72 +254,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').
+
+
+ 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.
-
-
-
-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 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.
@@ -376,45 +340,163 @@ How to install the binary packages depends on your operating system:
Building from Source
- The most convenient way to obtain the Privoxy sources
- is to download the source tarball from our
- 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
- CVS repository.
-
+ The most convenient way to obtain the Privoxy source
+ code is to download the source tarball from our
+
+ project download page,
+ or you can get the up-to-the-minute, possibly unstable, development version from
+ https://www.privoxy.org/.
&buildsource;
+
+ Windows
+
+ Setup
+
+ Install the Cygwin utilities needed to build Privoxy.
+ If you have a 64 bit CPU (which most people do by now), get the
+ Cygwin setup-x86_64.exe program here
+ (the .sig file is here).
+
+
+ Run the setup program and from View / Category select:
+
+
+ Devel
+ autoconf 2.5
+ automake 1.15
+ binutils
+ cmake
+ gcc-core
+ gcc-g++
+ git
+ make
+ mingw64-i686-gcc-core
+ mingw64-i686-zlib
+ Editors
+ vim
+ Libs
+ libxslt: GNOME XSLT library (runtime)
+ Net
+ curl
+ openssh
+ Text
+ docbook-dssl
+ docbook-sgml31
+ docbook-utils
+ openjade
+ Utils
+ gnupg
+ Web
+ w3m
+
+
+
+ If you haven't already downloaded the Privoxy source code, get it now:
+
+
+ mkdir <root-dir>
+ cd <root-dir>
+ git clone https://www.privoxy.org/git/privoxy.git
+
+
+
+ Get the source code (.zip or .tar.gz) for tidy from
+
+ https://github.com/htacg/tidy-html5/releases,
+ unzip into <root-dir> and build the software:
+
+
+ cd <root-dir>
+ cd tidy-html5-x.y.z/build/cmake
+ cmake ../.. -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIB:BOOL=OFF -DCMAKE_INSTALL_PREFIX=/usr/local
+ make && make install
+
+
+
+ If you want to be able to make a Windows release package, get the NSIS .zip file from
+
+
+ https://sourceforge.net/projects/nsis/files/NSIS%203/
+ and extract the NSIS directory to privoxy/windows.
+ Then edit the windows/GNUmakefile to set the location of the NSIS executable - eg:
+
+
+# Path to NSIS
+MAKENSIS = ./nsis/makensis.exe
+
+
+
+
+ Build
+
+
+ To build just the Privoxy executable and not the whole installation package, do:
+
+
+ cd <root-dir>/privoxy
+ ./windows/MYconfigure && make
+
+
+
+ Privoxy uses the GNU Autotools
+ for building software, so the process is:
+
+
+ $ autoheader # creates config.h.in
+ $ autoconf # uses config.h.in to create the configure shell script
+ $ ./configure [options] # creates GNUmakefile
+ $ make [options] # builds the program
+
+
+
+ The usual configure options for building a native Windows application under cygwin are
+
+
+
+ --host=i686-w64-mingw32
+ --enable-mingw32
+ --enable-zlib
+ --enable-static-linking
+ --disable-pthread
+ --disable-dynamic-pcre
+
+
+
+ You can set the CFLAGS and LDFLAGS envars before
+ running configure to set compiler and linker flags. For example:
+
+
+
+ $ export CFLAGS="-O2" # set gcc optimization level
+ $ export LDFLAGS="-Wl,--nxcompat" # Enable DEP
+ $ ./configure --host=i686-w64-mingw32 --enable-mingw32 --enable-zlib \
+ > --enable-static-linking --disable-pthread --disable-dynamic-pcre
+ $ make # build Privoxy
+
+
+
+ See the Developer's Manual
+ for building a Windows release package.
+
+
+
+
+
+
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,5487 +518,2153 @@ How to install the binary packages depends on your operating system:
What's New in this Release
+
+&changelog;
+
+
+
+
+Note to Upgraders
+
- Privoxy 3.0.19 is a stable release.
- The changes since 3.0.18 stable are:
+ A quick list of things to be aware of before upgrading from earlier
+ versions of Privoxy:
-
-
-
- Bug fixes:
-
-
-
- Prevent a segmentation fault when de-chunking buffered content.
- It could be triggered by malicious web servers if Privoxy was
- configured to filter the content and running on a platform
- where SIZE_T_MAX isn't larger than UINT_MAX, which probably
- includes most 32-bit systems. On those platforms, all Privoxy
- versions before 3.0.19 appear to be affected.
- To be on the safe side, this bug should be presumed to allow
- code execution as proving that it doesn't seems unrealistic.
-
-
-
-
- Do not expect a response from the SOCKS4/4A server until it
- got something to respond to. This regression was introduced
- in 3.0.18 and prevented the SOCKS4/4A negotiation from working.
- Reported by qqqqqw in #3459781.
-
-
-
-
+
+
+
+ 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:
-
-
-
-
-
-
-
- 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.
-
-
-
-
-
- Advanced users and those who want to offer Privoxy
- service to more than just their local machine should check the main config file, especially the security-relevant options. These are
- off by default.
-
-
-
-
-
- Start Privoxy, if the installation program has
- not done this already (may vary according to platform). See the section
- Starting Privoxy.
-
-
-
-
-
- Set your browser to use Privoxy as HTTP and
- HTTPS (SSL) proxy
- by setting the proxy configuration for address of
- 127.0.0.1 and port 8118.
- DO NOT activate proxying for FTP or
- any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
- browser from using these protocols.
-
-
-
-
-
- Flush your browser's disk and memory caches, to remove any cached ad images.
- If using Privoxy to manage
- cookies,
- you should remove any currently stored cookies too.
-
-
-
-
-
- A default installation should provide a reasonable starting point for
- most. There will undoubtedly be occasions where you will want to adjust the
- configuration, but that can be dealt with as the need arises. Little
- to no initial configuration is required in most cases, you may want
- to enable the
- web-based action editor though.
- Be sure to read the warnings first.
-
-
- See the Configuration section for more
- configuration options, and how to customize your installation.
- You might also want to look at the next section for a quick
- introduction to how Privoxy blocks ads and
- banners.
-
-
-
-
-
- If you experience ads that slip through, innocent images that are
- blocked, or otherwise feel the need to fine-tune
- Privoxy's behavior, take a look at the actions files. As a quick start, you might
- find the richly commented examples
- helpful. You can also view and edit the actions files through the web-based user interface. The
- Appendix Troubleshooting: Anatomy of an
- Action has hints on how to understand and debug actions that
- misbehave.
-
-
-
-
-
-
-
- Please see the section Contacting the
- Developers on how to report bugs, problems with websites or to get
- help.
-
-
-
-
-
- Now enjoy surfing with enhanced control, comfort and privacy!
-
-
-
-
-
-
-
-
-
-
-Quickstart to Ad Blocking
-
-
- Ad blocking is but one of Privoxy's
- array of features. Many of these features are for the technically minded advanced
- user. But, ad and banner blocking is surely common ground for everybody.
-
-
- This section will provide a quick summary of ad blocking so
- you can get up to speed quickly without having to read the more extensive
- information provided below, though this is highly recommended.
-
-
- First a bit of a warning ... blocking ads is much like blocking SPAM: the
- more aggressive you are about it, the more likely you are to block
- things that were not intended. And the more likely that some things
- may not work as intended. So there is a trade off here. If you want
- extreme ad free browsing, be prepared to deal with more
- problem sites, and to spend more time adjusting the
- configuration to solve these unintended consequences. In short, there is
- not an easy way to eliminate all ads. Either take
- the easy way and settle for most ads blocked with the
- default configuration, or jump in and tweak it for your personal surfing
- habits and preferences.
-
-
- Secondly, a brief explanation of Privoxy's
- actions. Actions in this context, are
- the directives we use to tell Privoxy to perform
- some task relating to HTTP transactions (i.e. web browsing). We tell
- Privoxy to take some action. Each
- action has a unique name and function. While there are many potential
- actions in Privoxy's
- arsenal, only a few are used for ad blocking. Actions, and action
- configuration files, are explained in depth below.
-
-
- Actions are specified in Privoxy's configuration,
- followed by one or more URLs to which the action should apply. URLs
- can actually be URL type patterns that use
- wildcards so they can apply potentially to a range of similar URLs. The
- actions, together with the URL patterns are called a section.
-
-
- When you connect to a website, the full URL will either match one or more
- of the sections as defined in Privoxy's configuration,
- or not. If so, then Privoxy will perform the
- respective actions. If not, then nothing special happens. Furthermore, web
- pages may contain embedded, secondary URLs that your web browser will
- use to load additional components of the page, as it parses the
- original page's HTML content. An ad image for instance, is just an URL
- embedded in the page somewhere. The image itself may be on the same server,
- or a server somewhere else on the Internet. Complex web pages will have many
- such embedded URLs. &my-app; can deal with each URL individually, so, for
- instance, the main page text is not touched, but images from such-and-such
- server are blocked.
-
-
-
- The most important actions for basic ad blocking are: block, handle-as-image,
- handle-as-empty-document,and
- set-image-blocker:
-
-
-
-
-
-
-
- block - this is perhaps
- the single most used action, and is particularly important for ad blocking.
- This action stops any contact between your browser and any URL patterns
- that match this action's configuration. It can be used for blocking ads,
- but also anything that is determined to be unwanted. By itself, it simply
- stops any communication with the remote server and sends
- Privoxy's own built-in BLOCKED page instead to
- let you now what has happened (with some exceptions, see below).
-
-
-
-
-
- handle-as-image -
- tells Privoxy to treat this URL as an image.
- Privoxy's default configuration already does this
- for all common image types (e.g. GIF), but there are many situations where this
- is not so easy to determine. So we'll force it in these cases. This is particularly
- important for ad blocking, since only if we know that it's an image of
- some kind, can we replace it with an image of our choosing, instead of the
- Privoxy BLOCKED page (which would only result in
- a broken image icon). There are some limitations to this
- though. For instance, you can't just brute-force an image substitution for
- an entire HTML page in most situations.
-
-
-
-
-
- handle-as-empty-document -
- sends an empty document instead of Privoxy's
- normal BLOCKED HTML page. This is useful for file types that are neither
- HTML nor images, such as blocking JavaScript files.
-
-
-
-
-
- set-image-blocker - tells
- Privoxy what to display in place of an ad image that
- has hit a block rule. For this to come into play, the URL must match a
- block action somewhere in the
- configuration, and, it must also match an
- handle-as-image action.
-
-
- The configuration options on what to display instead of the ad are:
-
-
-
- pattern - a checkerboard pattern, so that an ad
- replacement is obvious. This is the default.
-
-
-
-
- blank - A very small empty GIF image is displayed.
- This is the so-called invisible configuration option.
-
-
-
-
- http://<URL> - A redirect to any image anywhere
- of the user's choosing (advanced usage).
-
-
-
-
-
-
-
-
- Advanced users will eventually want to explore &my-app;
- filters as well. Filters
- are very different from blocks.
- A block blocks a site, page, or unwanted contented. Filters
- are a way of filtering or modifying what is actually on the page. An example
- filter usage: a text replacement of no-no for
- nasty-word. That is a very simple example. This process can be
- used for ad blocking, but it is more in the realm of advanced usage and has
- some pitfalls to be wary off.
-
-
-
- The quickest way to adjust any of these settings is with your browser through
- the special Privoxy editor at http://config.privoxy.org/show-status
- (shortcut: http://p.p/show-status). This
- is an internal page, and does not require Internet access.
-
-
-
- Note that as of Privoxy 3.0.7 beta the
- action editor is disabled by default. Check the
- enable-edit-actions
- section in the configuration file to learn why and in which
- cases it's safe to enable again.
-
-
-
- If you decided to enable the action editor, select the appropriate
- actions file, and click
- Edit. It is best to put personal or
- local preferences in user.action since this is not
- meant to be overwritten during upgrades, and will over-ride the settings in
- other files. Here you can insert new actions, and URLs for ad
- blocking or other purposes, and make other adjustments to the configuration.
- Privoxy will detect these changes automatically.
-
-
-
- A quick and simple step by step example:
-
-
-
-
-
-
-
- Right click on the ad image to be blocked, then select
- Copy Link Location from the
- pop-up menu.
-
-
-
-
- Set your browser to
- http://config.privoxy.org/show-status
-
-
-
-
- Find user.action in the top section, and click
- on Edit:
-
-
-
-
-
-
-
-
-
-
- You should have a section with only
- block listed under
- Actions:.
- If not, click a Insert new section below
- button, and in the new section that just appeared, click the
- Edit button right under the word Actions:.
- This will bring up a list of all actions. Find
- block near the top, and click
- in the Enabled column, then Submit
- just below the list.
-
-
-
-
- Now, in the block actions section,
- click the Add button, and paste the URL the
- browser got from Copy Link Location.
- Remove the http:// at the beginning of the URL. Then, click
- Submit (or
- OK if in a pop-up window).
-
-
-
-
- Now go back to the original page, and press SHIFT-Reload
- (or flush all browser caches). The image should be gone now.
-
-
-
-
-
-
-
- This is a very crude and simple example. There might be good reasons to use a
- wildcard pattern match to include potentially similar images from the same
- site. For a more extensive explanation of patterns, and
- the entire actions concept, see the Actions
- section.
-
-
-
- For advanced users who want to hand edit their config files, you might want
- to now go to the Actions Files Tutorial.
- The ideas explained therein also apply to the web-based editor.
-
-
- There are also various
- filters that can be used for ad blocking
- (filters are a special subset of actions). These
- fall into the advanced usage category, and are explained in
- depth in later sections.
-
-
-
-
-
-
-
-
-
-
-
-Starting Privoxy
-
- Before launching Privoxy for the first time, you
- will want to configure your browser(s) to use
- Privoxy as a HTTP and HTTPS (SSL)
- proxy. The default is
- 127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions
- used port 8000). This is the one configuration step that must be done
-!
-
-
- Please note that Privoxy can only proxy HTTP and
- HTTPS traffic. It will not work with FTP or other protocols.
-
-
-
-
-
-
-
-
-
- With Firefox, this is typically set under:
-
-
-
- Tools -> Options -> Advanced -> Network ->Connection -> Settings
-
-
-
-
- Or optionally on some platforms:
-
-
-
- Edit -> Preferences -> General -> Connection Settings -> Manual Proxy Configuration
-
-
-
-
-
- With Netscape (and
- Mozilla), this can be set under:
-
-
-
-
-
-
- Edit -> Preferences -> Advanced -> Proxies -> HTTP Proxy
-
-
-
-
- For Internet Explorer v.5-7:
-
-
-
- Tools -> Internet Options -> Connections -> LAN Settings
-
-
-
- Then, check Use Proxy and fill in the appropriate info
- (Address: 127.0.0.1, Port: 8118). Include HTTPS (SSL), if you want HTTPS
- proxy support too (sometimes labeled Secure). Make sure any
- checkboxes like Use the same proxy server for all protocols is
- UNCHECKED. You want only HTTP and HTTPS (SSL)!
-
-
-
-
-
-
-
-
-
- After doing this, flush your browser's disk and memory caches to force a
- re-reading of all pages and to get rid of any ads that may be cached. Remove
- any cookies,
- if you want Privoxy to manage that. You are now
- ready to start enjoying the benefits of using
- Privoxy!
-
-
-
- Privoxy itself is typically started by specifying the
- main configuration file to be used on the command line. If no configuration
- file is specified on the command line, Privoxy
- will look for a file named config in the current
- directory. Except on Win32 where it will try config.txt.
-
-
-
-Red Hat and Fedora
-
- A default Red Hat installation may not start &my-app; upon boot. It will use
- the file /etc/privoxy/config as its main configuration
- file.
-
-
-
- # /etc/rc.d/init.d/privoxy start
-
-
-
- Or ...
-
-
-
- # service privoxy start
-
-
-
-
-
-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.
-
-
-
- # /etc/init.d/privoxy start
-
-
-
-
-
-Windows
-
-Click on the &my-app; Icon to start Privoxy. If no configuration file is
- specified on the command line, Privoxy will look
- for a file named config.txt. Note that Windows will
- automatically start &my-app; when the system starts if you chose that option
- when installing.
-
-
- Privoxy can run with full Windows service functionality.
- On Windows only, the &my-app; program has two new command line arguments
- to install and uninstall &my-app; as a service. See the
- Windows Installation
- instructions for details.
-
-
-
-
-Solaris, NetBSD, FreeBSD, HP-UX and others
-
-Example Unix startup command:
-
-
-
- # /usr/sbin/privoxy /etc/privoxy/config
-
-
-
-
-
-OS/2
-
- During installation, Privoxy is configured to
- start automatically when the system restarts. You can start it manually by
- double-clicking on the Privoxy icon in the
- Privoxy folder.
-
-
-
-
-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.
-
-
- To prevent the privoxy service from automatically starting when your
- computer starts up, remove or rename the folder named
- /Library/StartupItems/Privoxy.
-
-
- 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).
-
-
-
-
-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
-
-
-
-
-
-
-
-
-Command Line Options
-
- Privoxy may be invoked with the following
- command-line options:
-
-
-
-
-
-
-
- --version
-
-
- Print version info and exit. Unix only.
-
-
-
-
- --help
-
-
- Print short usage info and exit. Unix only.
-
-
-
-
- --no-daemon
-
-
- Don't become a daemon, i.e. don't fork and become process group
- leader, and don't detach from controlling tty. Unix only.
-
-
-
-
- --pidfile FILE
-
-
- On startup, write the process ID to FILE. Delete the
- FILE on exit. Failure to create or delete the
- FILE is non-fatal. If no FILE
- option is given, no PID file will be used. Unix only.
-
-
-
-
- --user USER[.GROUP]
-
-
- After (optionally) writing the PID file, assume the user ID of
- USER, and if included the GID of GROUP. Exit if the
- privileges are not sufficient to do so. Unix only.
-
-
-
-
- --chroot
-
-
- Before changing to the user ID given in the --user option,
- chroot to that user's home directory, i.e. make the kernel pretend to the &my-app;
- process that the directory tree starts there. If set up carefully, this can limit
- the impact of possible vulnerabilities in &my-app; to the files contained in that hierarchy.
- Unix only.
-
-
-
-
- --pre-chroot-nslookup hostname
-
-
- Specifies a hostname to look up before doing a chroot. On some systems, initializing the
- resolver library involves reading config files from /etc and/or loading additional shared
- libraries from /lib. On these systems, doing a hostname lookup before the chroot reduces
- the number of files that must be copied into the chroot tree.
-
-
- For fastest startup speed, a good value is a hostname that is not in /etc/hosts but that
- your local name server (listed in /etc/resolv.conf) can resolve without recursion
- (that is, without having to ask any other name servers). The hostname need not exist,
- but if it doesn't, an error message (which can be ignored) will be output.
-
-
-
-
-
- configfile
-
-
- If no configfile is included on the command line,
- Privoxy will look for a file named
- config in the current directory (except on Win32
- where it will look for config.txt instead). Specify
- full path to avoid confusion. If no config file is found,
- Privoxy will fail to start.
-
-
-
-
-
-
-
- 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.
-
-
-
-
-
-
-
-
-
-
-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/
-
-
+
+ Also, session-cookies-only is
+ off by default now. If you've liked this feature in the past, you may want
+ to turn it back on in user.action now.
+
-
-
-
-
-
-
-content-type-overwrite
-
-
-
- Typical use:
- Stop useless download menus from popping up, or change the browser's rendering mode
-
-
+
+ Some installers may not automatically start
+ Privoxy after installation.
+
+
+-->
-
- Effect:
-
-
- Replaces the Content-Type: HTTP server header.
-
-
-
+
-
- Type:
-
-
- Parameterized.
-
-
+
+
-
- Parameter:
-
-
- Any string.
-
-
-
+
+Quickstart to Using Privoxy
-
- 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/
+
+
+ Install Privoxy. See the Installation Section below for platform specific
+ information.
+
+
-# 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
-
-
-
-
-
-
+
+
+ Advanced users and those who want to offer Privoxy
+ service to more than just their local machine should check the main config file, especially the security-relevant options. These are
+ off by default.
+
+
+
+
+ Start Privoxy, if the installation program has
+ not done this already (may vary according to platform). See the section
+ Starting Privoxy.
+
+
-
-
-
-crunch-client-header
+
+
+ Set your browser to use Privoxy as HTTP and
+ HTTPS (SSL) proxy
+ by setting the proxy configuration for address of
+ 127.0.0.1 and port 8118.
+ DO NOT activate proxying for FTP or
+ any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
+ browser from using these protocols.
+
+
-
-
- Typical use:
-
- Remove a client header Privoxy has no dedicated action for.
-
-
+
+
+ Flush your browser's disk and memory caches, to remove any cached ad images.
+ If using Privoxy to manage
+ cookies,
+ you should remove any currently stored cookies too.
+
+
-
- Effect:
-
-
- Deletes every header sent by the client that contains the string the user supplied as parameter.
-
-
-
+
+
+ A default installation should provide a reasonable starting point for
+ most. There will undoubtedly be occasions where you will want to adjust the
+ configuration, but that can be dealt with as the need arises. Little
+ to no initial configuration is required in most cases, you may want
+ to enable the
+ web-based action editor though.
+ Be sure to read the warnings first.
+
+
+ See the Configuration section for more
+ configuration options, and how to customize your installation.
+ You might also want to look at the next section for a quick
+ introduction to how Privoxy blocks ads and
+ banners.
+
+
-
- Type:
-
-
- Parameterized.
-
-
+
+
+ If you experience ads that slip through, innocent images that are
+ blocked, or otherwise feel the need to fine-tune
+ Privoxy's behavior, take a look at the actions files. As a quick start, you might
+ find the richly commented examples
+ helpful. You can also view and edit the actions files through the web-based user interface. The
+ Appendix Troubleshooting: Anatomy of an
+ Action has hints on how to understand and debug actions that
+ misbehave.
+
+
-
- Parameter:
-
-
- Any string.
-
-
-
+
+
+ Please see the section Contacting the
+ Developers on how to report bugs, problems with websites or to get
+ help.
+
+
-
- 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.
-
-
-
-
+
+
+ Now enjoy surfing with enhanced control, comfort and privacy!
+
+
-
- Example usage (section):
-
-
- # Block the non-existent "Privacy-Violation:" client header
-{ +crunch-client-header{Privacy-Violation:} }
-/
-
-
-
-
-
-
+
-
-crunch-if-none-match
+
+
+Quickstart to Ad Blocking
-
-
- Typical use:
-
- Prevent yet another way to track the user's steps between sessions.
-
-
+
+ Ad blocking is but one of Privoxy's
+ array of features. Many of these features are for the technically minded advanced
+ user. But, ad and banner blocking is surely common ground for everybody.
+
+
+ This section will provide a quick summary of ad blocking so
+ you can get up to speed quickly without having to read the more extensive
+ information provided below, though this is highly recommended.
+
+
+ First a bit of a warning ... blocking ads is much like blocking SPAM: the
+ more aggressive you are about it, the more likely you are to block
+ things that were not intended. And the more likely that some things
+ may not work as intended. So there is a trade off here. If you want
+ extreme ad free browsing, be prepared to deal with more
+ problem sites, and to spend more time adjusting the
+ configuration to solve these unintended consequences. In short, there is
+ not an easy way to eliminate all ads. Either take
+ the easy way and settle for most ads blocked with the
+ default configuration, or jump in and tweak it for your personal surfing
+ habits and preferences.
+
+
+ Secondly, a brief explanation of Privoxy's
+ actions. Actions in this context, are
+ the directives we use to tell Privoxy to perform
+ some task relating to HTTP transactions (i.e. web browsing). We tell
+ Privoxy to take some action. Each
+ action has a unique name and function. While there are many potential
+ actions in Privoxy's
+ arsenal, only a few are used for ad blocking. Actions, and action
+ configuration files, are explained in depth below.
+
+
+ Actions are specified in Privoxy's configuration,
+ followed by one or more URLs to which the action should apply. URLs
+ can actually be URL type patterns that use
+ wildcards so they can apply potentially to a range of similar URLs. The
+ actions, together with the URL patterns are called a section.
+
+
+ When you connect to a website, the full URL will either match one or more
+ of the sections as defined in Privoxy's configuration,
+ or not. If so, then Privoxy will perform the
+ respective actions. If not, then nothing special happens. Furthermore, web
+ pages may contain embedded, secondary URLs that your web browser will
+ use to load additional components of the page, as it parses the
+ original page's HTML content. An ad image for instance, is just an URL
+ embedded in the page somewhere. The image itself may be on the same server,
+ or a server somewhere else on the Internet. Complex web pages will have many
+ such embedded URLs. &my-app; can deal with each URL individually, so, for
+ instance, the main page text is not touched, but images from such-and-such
+ server are blocked.
+
-
- Effect:
-
-
- Deletes the If-None-Match: HTTP client header.
-
-
-
+
+ The most important actions for basic ad blocking are: block, handle-as-image,
+ handle-as-empty-document,and
+ set-image-blocker:
+
-
- Type:
-
-
- Boolean.
-
-
+
-
- Parameter:
-
-
- N/A
-
-
-
+
+
+ block - this is perhaps
+ the single most used action, and is particularly important for ad blocking.
+ This action stops any contact between your browser and any URL patterns
+ that match this action's configuration. It can be used for blocking ads,
+ but also anything that is determined to be unwanted. By itself, it simply
+ stops any communication with the remote server and sends
+ Privoxy's own built-in BLOCKED page instead to
+ let you now what has happened (with some exceptions, see below).
+
+
-
- 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.
-
+
+
+ handle-as-image -
+ tells Privoxy to treat this URL as an image.
+ Privoxy's default configuration already does this
+ for all common image types (e.g. GIF), but there are many situations where this
+ is not so easy to determine. So we'll force it in these cases. This is particularly
+ important for ad blocking, since only if we know that it's an image of
+ some kind, can we replace it with an image of our choosing, instead of the
+ Privoxy BLOCKED page (which would only result in
+ a broken image icon). There are some limitations to this
+ though. For instance, you can't just brute-force an image substitution for
+ an entire HTML page in most situations.
+
+
+
+
+
+ handle-as-empty-document -
+ sends an empty document instead of Privoxy's
+ normal BLOCKED HTML page. This is useful for file types that are neither
+ HTML nor images, such as blocking JavaScript files.
+
+
+
+
+
+ set-image-blocker - tells
+ Privoxy what to display in place of an ad image that
+ has hit a block rule. For this to come into play, the URL must match a
+ block action somewhere in the
+ configuration, and, it must also match an
+ handle-as-image action.
+
+
+ The configuration options on what to display instead of the ad are:
+
+
+
+ pattern - a checkerboard pattern, so that an ad
+ replacement is obvious. This is the default.
+
+
+
+
+ blank - A very small empty GIF image is displayed.
+ This is the so-called invisible configuration option.
+
+
+
+
+ http://<URL> - A redirect to any image anywhere
+ of the user's choosing (advanced usage).
+
+
-
-
- 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}
-/
-
-
-
-
-
+
+
+ Advanced users will eventually want to explore &my-app;
+ filters as well. Filters
+ are very different from blocks.
+ A block blocks a site, page, or unwanted contented. Filters
+ are a way of filtering or modifying what is actually on the page. An example
+ filter usage: a text replacement of no-no for
+ nasty-word. That is a very simple example. This process can be
+ used for ad blocking, but it is more in the realm of advanced usage and has
+ some pitfalls to be wary off.
+
-
-
-crunch-incoming-cookies
+
+ The quickest way to adjust any of these settings is with your browser through
+ the special Privoxy editor at http://config.privoxy.org/show-status
+ (shortcut: http://p.p/show-status). This
+ is an internal page, and does not require Internet access.
+
-
-
- Typical use:
-
-
- Prevent the web server from setting HTTP cookies on your system
-
-
-
+
+ Note that as of Privoxy 3.0.7 beta the
+ action editor is disabled by default. Check the
+ enable-edit-actions
+ section in the configuration file to learn why and in which
+ cases it's safe to enable again.
+
-
- Effect:
-
-
- Deletes any Set-Cookie: HTTP headers from server replies.
-
-
-
+
+ If you decided to enable the action editor, select the appropriate
+ actions file, and click
+ Edit. It is best to put personal or
+ local preferences in user.action since this is not
+ meant to be overwritten during upgrades, and will over-ride the settings in
+ other files. Here you can insert new actions, and URLs for ad
+ blocking or other purposes, and make other adjustments to the configuration.
+ Privoxy will detect these changes automatically.
+
-
- Type:
-
-
- Boolean.
-
-
+
+ A quick and simple step by step example:
+
+
+
-
- Parameter:
- N/A
+ Right click on the ad image to be blocked, then select
+ Copy Link Location from the
+ pop-up menu.
-
-
-
- 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.
+ Set your browser to
+ http://config.privoxy.org/show-status
-
-
-
- Example usage:
- +crunch-incoming-cookies
+ Find user.action in the top section, and click
+ on Edit:
-
-
-
-
+
+
+
-
-
-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.
-
-
-
+
+
+ You should have a section with only
+ block listed under
+ Actions:.
+ If not, click a Insert new section below
+ button, and in the new section that just appeared, click the
+ Edit button right under the word Actions:.
+ This will bring up a list of all actions. Find
+ block near the top, and click
+ in the Enabled column, then Submit
+ just below the list.
+
+
+
+
+ Now, in the block actions section,
+ click the Add button, and paste the URL the
+ browser got from Copy Link Location.
+ Remove the http:// at the beginning of the URL. Then, click
+ Submit (or
+ OK if in a pop-up window).
+
+
+
+
+ Now go back to the original page, and press SHIFT-Reload
+ (or flush all browser caches). The image should be gone now.
+
+
-
- Type:
-
-
- Parameterized.
-
-
+
-
- Parameter:
-
-
- Any string.
-
-
-
+
+ This is a very crude and simple example. There might be good reasons to use a
+ wildcard pattern match to include potentially similar images from the same
+ site. For a more extensive explanation of patterns, and
+ the entire actions concept, see the Actions
+ section.
+
-
- 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.
-
-
-
-
+
+ For advanced users who want to hand edit their config files, you might want
+ to now go to the Actions Files Tutorial.
+ The ideas explained therein also apply to the web-based editor.
+
+
+ There are also various
+ filters that can be used for ad blocking
+ (filters are a special subset of actions). These
+ fall into the advanced usage category, and are explained in
+ depth in later sections.
+
-
- Example usage (section):
-
-
- # Crunch server headers that try to prevent caching
-{ +crunch-server-header{no-cache} }
-/
-
-
-
-
-
+
+
+
+
+
-
-crunch-outgoing-cookies
+
+Starting Privoxy
+
+ Before launching Privoxy for the first time, you
+ will want to configure your browser(s) to use
+ Privoxy as a HTTP and HTTPS (SSL)
+ proxy. The default is
+ 127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions
+ used port 8000). This is the one configuration step that must be done
+!
+
+
+ Please note that Privoxy can only proxy HTTP and
+ HTTPS traffic. It will not work with FTP or other protocols.
+
-
-
- 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.
-
-
+
+ With Firefox, this is typically set under:
+
-
- Parameter:
-
-
- N/A
-
-
-
+
+ Tools -> Options -> Advanced -> Network ->Connection -> Settings
+
-
- 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.
-
-
-
+
+ Or optionally on some platforms:
+
-
- Example usage:
-
-
- +crunch-outgoing-cookies
-
-
-
+
+ Edit -> Preferences -> General -> Connection Settings -> Manual Proxy Configuration
+
-
-
+
+ With Netscape (and
+ Mozilla), this can be set under:
+
-
-
-deanimate-gifs
-
-
- Typical use:
-
- Stop those annoying, distracting animated GIF images.
-
-
+
+
+
+ Edit -> Preferences -> Advanced -> Proxies -> HTTP Proxy
+
-
- Effect:
-
-
- De-animate GIF animations, i.e. reduce them to their first or last image.
-
-
-
+
+ For Internet Explorer v.5-7:
+
-
- Type:
-
-
- Parameterized.
-
-
+
+ Tools -> Internet Options -> Connections -> LAN Settings
+
-
- Parameter:
-
-
- last or first
-
-
-
+
+ Then, check Use Proxy and fill in the appropriate info
+ (Address: 127.0.0.1, Port: 8118). Include HTTPS (SSL), if you want HTTPS
+ proxy support too (sometimes labeled Secure). Make sure any
+ checkboxes like Use the same proxy server for all protocols is
+ UNCHECKED. You want only HTTP and HTTPS (SSL)!
+
-
- 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
+
+ After doing this, flush your browser's disk and memory caches to force a
+ re-reading of all pages and to get rid of any ads that may be cached. Remove
+ any cookies,
+ if you want Privoxy to manage that. You are now
+ ready to start enjoying the benefits of using
+ Privoxy!
+
-
-
- Typical use:
-
- Work around (very rare) problems with HTTP/1.1
-
-
+
+ Privoxy itself is typically started by specifying the
+ main configuration file to be used on the command line. If no configuration
+ file is specified on the command line, Privoxy
+ will look for a file named config in the current
+ directory. Except on Win32 where it will try config.txt.
+
-
- Effect:
-
-
- Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
-
-
-
+
+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.
+
+
+ # /etc/init.d/privoxy start
+
+
-
- Type:
-
-
- Boolean.
-
-
+
+FreeBSD and ElectroBSD
+
+ 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.
+
+
+ If you installed Privoxy into a jail, the
+ paths above are relative to the jail root.
+
+
+ To start Privoxy manually, run:
+
+
+ # service privoxy onestart
+
+
-
- Parameter:
-
-
- N/A
-
-
-
+
+Windows
+
+Click on the &my-app; Icon to start Privoxy. If no configuration file is
+ specified on the command line, Privoxy will look
+ for a file named config.txt. Note that Windows will
+ automatically start &my-app; when the system starts if you chose that option
+ when installing.
+
+
+ Privoxy can run with full Windows service functionality.
+ On Windows only, the &my-app; program has two new command line arguments
+ to install and uninstall &my-app; as a service. See the
+ Windows Installation
+ instructions for details.
+
+
-
- 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.
-
-
- Note that enabling this action is only a workaround. It should not
- be enabled for sites that work without it. While it shouldn't break
- any pages, it has an (usually negative) performance impact.
-
-
- If you come across a site where enabling this action helps, please report it,
- so the cause of the problem can be analyzed. If the problem turns out to be
- caused by a bug in Privoxy it should be
- fixed so the following release works without the work around.
-
-
-
+
+Generic instructions for Unix derivates (Solaris, NetBSD, HP-UX etc.)
+
+Example Unix startup command:
+
+
+ # /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.
+
+
-
- Example usage (section):
-
-
- {+downgrade-http-version}
-problem-host.example.com
-
-
-
+
+OS/2
+
+ During installation, Privoxy is configured to
+ start automatically when the system restarts. You can start it manually by
+ double-clicking on the Privoxy icon in the
+ Privoxy folder.
+
+
-
-
+
+Mac OS X
+
+ 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').
+
+
+ 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.
+
+
-
-
-fast-redirects
-
-
- Typical use:
-
- Fool some click-tracking scripts and speed up indirect links.
-
-
+
-
- Parameterized.
-
-
+must find a better place for this paragraph
-
- 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.
-
-
-
-
-
+
+ The included default configuration files should give a reasonable starting
+ point. Most of the per site configuration is done in the
+ actions files. These are
+ where various cookie actions are defined, ad and banner blocking, and other
+ aspects of Privoxy configuration. There are several
+ such files included, with varying levels of aggressiveness.
+
-
- 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.
-
-
-
+
+ You will probably want to keep an eye out for sites for which you may prefer
+ persistent cookies, and add these to your actions configuration as needed. By
+ default, most of these will be accepted only during the current browser
+ session (aka session cookies), unless you add them to the
+ configuration. If you want the browser to handle this instead, you will need
+ to edit user.action (or through the web based interface)
+ and disable this feature. If you use more than one browser, it would make
+ more sense to let Privoxy handle this. In which
+ case, the browser(s) should be set to accept all cookies.
+
-
- Example usage:
-
-
-
- { +fast-redirects{simple-check} }
- one.example.com
+
+ Another feature where you will probably want to define exceptions for trusted
+ sites is the popup-killing (through +filter{popups}),
+ because your favorite shopping, banking, or leisure site may need
+ popups (explained below).
+
- { +fast-redirects{check-decoded-url} }
- another.example.com/testing
-
-
-
+
+ Privoxy does not support all of the optional HTTP/1.1
+ features yet. In the unlikely event that you experience inexplicable problems
+ with browsers that use HTTP/1.1 per default
+ (like Mozilla or recent versions of I.E.), you might
+ try to force HTTP/1.0 compatibility. For Mozilla, look under Edit ->
+ Preferences -> Debug -> Networking.
+ Alternatively, set the +downgrade-http-version config option in
+ default.action which will downgrade your browser's HTTP
+ requests from HTTP/1.1 to HTTP/1.0 before processing them.
+
+
+
+ After running Privoxy for a while, you can
+ start to fine tune the configuration to suit your personal, or site,
+ preferences and requirements. There are many, many aspects that can
+ be customized. Actions
+ can be adjusted by pointing your browser to
+ http://config.privoxy.org/
+ (shortcut: http://p.p/),
+ and then follow the link to View & Change the Current Configuration.
+ (This is an internal page and does not require Internet access.)
+
-
-
+
+ In fact, various aspects of Privoxy
+ configuration can be viewed from this page, including
+ current configuration parameters, source code version numbers,
+ the browser's request headers, and actions that apply
+ to a given URL. In addition to the actions file
+ editor mentioned above, Privoxy can also
+ be turned on and off (toggled) from this page.
+
+
+ If you encounter problems, try loading the page without
+ Privoxy. If that helps, enter the URL where
+ you have the problems into the browser
+ based rule tracing utility. See which rules apply and why, and
+ then try turning them off for that site one after the other, until the problem
+ is gone. When you have found the culprit, you might want to turn the rest on
+ again.
+
-
-
-filter
+
+ If the above paragraph sounds gibberish to you, you might want to read more about the actions concept
+ or even dive deep into the Appendix
+ on actions.
+
-
-
- Typical use:
-
- Get rid of HTML and JavaScript annoyances, banner advertisements (by size),
- do fun text replacements, add personalized effects, etc.
-
-
+
+ If you can't get rid of the problem at all, think you've found a bug in
+ Privoxy, want to propose a new feature or smarter rules, please see the
+ section Contacting the
+ Developers below.
+
-
- 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.
-
-
+
+
+Command Line Options
+
+ Privoxy may be invoked with the following
+ command-line options:
+
-
- 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.
+
+
+
+
+ --config-test
-
-
+
+ Exit after loading the configuration files before binding to
+ the listen address. The exit code signals whether or not the
+ configuration files have been successfully loaded.
+
+
+ If the exit code is 1, at least one of the configuration files
+ is invalid, if it is 0, all the configuration files have been
+ successfully loaded (but may still contain errors that can
+ currently only be detected at run time).
+
+
+ This option doesn't affect the log setting, combination with
+ --no-daemon is recommended if a configured
+ log file shouldn't be used.
+
+
+
+
+ --version
+
+
+ Print version info and exit. Unix only.
+
+
+
+
+ --help
+
+
+ Print short usage info and exit. Unix only.
+
+
+
+
+ --no-daemon
+
+
+ Don't become a daemon, i.e. don't fork and become process group
+ leader, and don't detach from controlling tty. Unix only.
+
+
+
+
+ --pidfile FILE
+
+
+ On startup, write the process ID to FILE. Delete the
+ FILE on exit. Failure to create or delete the
+ FILE is non-fatal. If no FILE
+ option is given, no PID file will be used. Unix only.
+
+
+
+
+ --user USER[.GROUP]
+
+
+ After (optionally) writing the PID file, assume the user ID of
+ USER, and if included the GID of GROUP. Exit if the
+ privileges are not sufficient to do so. Unix only.
+
+
+
+
+ --chroot
+
+
+ Before changing to the user ID given in the --user option,
+ chroot to that user's home directory, i.e. make the kernel pretend to the &my-app;
+ process that the directory tree starts there. If set up carefully, this can limit
+ the impact of possible vulnerabilities in &my-app; to the files contained in that hierarchy.
+ Unix only.
+
+
+
+
+ --pre-chroot-nslookup hostname
+
+
+ Specifies a hostname (for example www.privoxy.org) to look up before doing a chroot.
+ On some systems, initializing the resolver library involves reading config files from
+ /etc and/or loading additional shared libraries from /lib.
+ On these systems, doing a hostname lookup before the chroot reduces
+ the number of files that must be copied into the chroot tree.
+
+
+ For fastest startup speed, a good value is a hostname that is not in /etc/hosts but that
+ your local name server (listed in /etc/resolv.conf) can resolve without recursion
+ (that is, without having to ask any other name servers). The hostname need not exist,
+ but if it doesn't, an error message (which can be ignored) will be output.
+
+
-
- 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.
-
-
-
+
+
+ configfile
+
+
+ If no configfile is included on the command line,
+ Privoxy will look for a file named
+ config in the current directory (except on Win32
+ where it will look for config.txt instead). Specify
+ full path to avoid confusion. If no config file is found,
+ Privoxy will fail to start.
+
+
-
- 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.
-
-
-
-
-
+
+
+
+ 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.
+
+
+
+
+
+
+
-
-force-text-mode
-
-
-
- Typical use:
-
- Force Privoxy to treat a document as if it was in some kind of text format.
-
-
+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:
-
-
- Declares a document as text, even if the Content-Type: isn't detected as such.
-
-
-
-
- Type:
-
-
- Boolean.
-
-
+
-
- Parameter:
-
-
- N/A
-
-
-
+
+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 or toggle the tags that can be set based on the clients address
+
+
+ ▪ 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.
+
+
+
+ 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:
-
-
- 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
-
-
-
-
-
-
-
-forward-override
-
-
-
- Typical use:
-
- Change the forwarding settings based on User-Agent or request origin
-
-
-
- Effect:
-
-
- Overrules the forward directives in the configuration file.
-
-
-
+
+Configuration Files Overview
+
+ For Unix, *BSD and GNU/Linux, all configuration files are located in
+ /etc/privoxy/ by default. For MS Windows and OS/2
+ these are all in the same directory as the
+ Privoxy executable.
+
-
- Type:
-
-
- Multi-value.
-
-
+
+ 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:
+
-
- 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).
-
-
-
-
-
+
-
- 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.
+ The main configuration file is named config
+ on GNU/Linux, Unix, BSD, and OS/2, and config.txt
+ on Windows. This is a required file.
-
-
- 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$
-
+ 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.
-
-
-
-
-
-
-
-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.
+ 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.
-
-
- Type:
-
-
- Boolean.
-
-
+
-
- Parameter:
+
+ 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:
+
+
- N/A
+ 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
-
-
-
- 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.
+ 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.
-
-
-
- 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$
-
+ 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.
-
-
-
-
-
-
-
-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)
-
-
-
-
- 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.
+ EditSet to CautiousSet to MediumSet to Advanced
-
-
-
-
- Type:
-
-
- Boolean.
-
-
-
-
- Parameter:
-
- N/A
+ 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.
-
-
-
-
- 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.
+ 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.
- 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.
+ 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.
- 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.
+ The default profiles, and their associated actions, as pre-defined in
+ default.action are:
-
-
+
Default Configurations
+
+
+
+
+
+
+
+ Feature
+ Cautious
+ Medium
+ Advanced
+
+
+
+
+
+
+
+
+
+
+
-
- Example usage (sections):
-
-
- # Generic image extensions:
-#
-{+handle-as-image}
-/.*\.(gif|jpg|jpeg|png|bmp|ico)$
+
+ 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
+
+
+
+
+
+
+
+ Typical use:
+
- http://config.privoxy.org/
+ Allow only temporary session cookies (for the current
+ browser session only).
-
-
- 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:
-
-
+
+ Effect:
+
- http://config.privoxy.org/show-status
+ Deletes the expires field from Set-Cookie:
+ server headers. Most browsers will not store such cookies permanently and
+ forget them in between sessions.
-
-
+
+
-
-
- Show the source code version numbers:
-
-
-
+
+
-
-
- Show the browser's request headers:
-
-
+
+ Notes:
+
- http://config.privoxy.org/show-request
+ This is less strict than crunch-incoming-cookies /
+ crunch-outgoing-cookies and allows you to browse
+ websites that insist or rely on setting cookies, without compromising your privacy too badly.
-
-
-
-
-
- Show which actions apply to a URL and why:
-
-
- http://config.privoxy.org/show-url-info
+ Most browsers will not permanently store cookies that have been processed by
+ session-cookies-only and will forget about them between sessions.
+ This makes profiling cookies useless, but won't break sites which require cookies so
+ that you can log in for transactions. This is generally turned on for all
+ sites, and is the recommended setting.
-
-
-
-
-
- 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:
-
-
- http://config.privoxy.org/toggle
+ It makes no sense at all to use session-cookies-only
+ together with crunch-incoming-cookies or
+ crunch-outgoing-cookies. If you do, cookies
+ will be plainly killed.
-
-
- Short cuts. Turn off, then on:
-
-
- http://config.privoxy.org/toggle?set=disable
+ Note that it is up to the browser how it handles such cookies without an expires
+ field. If you use an exotic browser, you might want to try it out to be sure.
-
-
- http://config.privoxy.org/toggle?set=enable
+ This setting also has no effect on cookies that may have been stored
+ previously by the browser before starting Privoxy.
+ These would have to be removed manually.
-
+
+ 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.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.
+
+
+ View and toggle client tags:
+
+
+
+ http://config.privoxy.org/client-tags
+
+
+
- Revision 1.68 2002/04/04 18:46:47 swa
- consistent look. reuse of copyright, history et. al.
+
+
+ Show information about the current configuration, including viewing and
+ editing of actions files:
+
+
+
+ http://config.privoxy.org/show-status
+
+
+
- Revision 1.67 2002/04/04 17:27:57 swa
- more single file to be included at multiple points. make maintaining easier
+
+
+ Show the browser's request headers:
+
+
+
+ http://config.privoxy.org/show-request
+
+
+
- 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.
+
+
+ Show which actions apply to a URL and why:
+
+
+
+ http://config.privoxy.org/show-url-info
+
+
+
- Revision 1.65 2002/04/03 19:52:07 swa
- enhance squid section due to user suggestion
+
+
+ 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.64 2002/04/03 03:53:43 hal9
- A few minor bug fixes, and touch ups. Ready for review.
+
- Revision 1.63 2002/04/01 16:24:49 hal9
- Define entities to include boilerplate text. See doc/source/*.
+
- 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.
- Revision 1.61 2002/03/29 01:31:08 hal9
- Minor update.
+
+
+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.60 2002/03/27 01:57:34 hal9
- Added more to Anatomy section.
+
+
+
+ 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.59 2002/03/27 00:54:33 hal9
- Touch up intro for new name.
+
- Revision 1.58 2002/03/26 22:29:55 swa
- we have a new homepage!
+
+ 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.57 2002/03/24 20:33:30 hal9
- A few minor catch ups with name change.
+
- Revision 1.56 2002/03/24 16:17:06 swa
- configure needs to be generated.
- 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.
+
+
+Troubleshooting: Anatomy of an Action
- Revision 1.54 2002/03/24 15:46:20 swa
- name change related issue.
+
+ 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.53 2002/03/24 11:51:00 swa
- name change. changed filenames.
+
+ 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.52 2002/03/24 11:01:06 swa
- name change
+
+ 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.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.
+
+ 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.50 2002/03/23 05:06:21 hal9
- Touch up.
+
+ 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.49 2002/03/21 17:01:05 hal9
- New section in Appendix.
+
+ Matches for http://www.google.com:
- Revision 1.48 2002/03/12 06:33:01 hal9
- Catching up to Andreas and re_filterfile changes.
+ In file: default.action [ View ][ Edit ]
- Revision 1.47 2002/03/11 13:13:27 swa
- correct feedback channels
+ {+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.46 2002/03/10 00:51:08 hal9
- Added section on JB internal pages in Appendix.
+ { -session-cookies-only }
+ .google.com
- Revision 1.45 2002/03/09 17:43:53 swa
- more distros
+ { -fast-redirects }
+ .google.com
- Revision 1.44 2002/03/09 17:08:48 hal9
- New section on Jon's actions file editor, and move some stuff around.
+In file: user.action [ View ][ Edit ]
+(no matches in this file)
+
- Revision 1.43 2002/03/08 00:47:32 hal9
- Added imageblock{pattern}.
+
+ 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.42 2002/03/07 18:16:55 swa
- looks better
+
+ 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.41 2002/03/07 16:46:43 hal9
- Fix a few markup problems for jade.
+
+ 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.40 2002/03/07 16:28:39 swa
- provide correct feedback channels
+
+ 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.39 2002/03/06 16:19:28 hal9
- Note on perceived filtering slowdown per FR.
+
+ Final results:
- Revision 1.38 2002/03/05 23:55:14 hal9
- Stupid I did it again. Double hyphen in comment breaks jade.
+ -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.37 2002/03/05 23:53:49 hal9
- jade barfs on '- -' embedded in comments. - -user option broke it.
+
+ 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.36 2002/03/05 22:53:28 hal9
- Add new - - user option.
+
+ Now another example, ad.doubleclick.net:
+
- Revision 1.35 2002/03/05 00:17:27 hal9
- Added section on command line options.
+
+ { +block{Domains starts with "ad"} }
+ ad*.
- Revision 1.34 2002/03/04 19:32:07 oes
- Changed default port to 8118
+ { +block{Domain contains "ad"} }
+ .ad.
- Revision 1.33 2002/03/03 19:46:13 hal9
- Emphasis on where/how to report bugs, etc
+ { +block{Doubleclick banner server} +handle-as-image }
+ .[a-vx-z]*.doubleclick.net
+
- 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.
+
+ 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.31 2002/03/02 22:45:52 david__schmidt
- Just tweaking
+
+ 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.30 2002/03/02 22:00:14 hal9
- Updated 'New Features' list. Ran through spell-checker.
+
+ 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.29 2002/03/02 20:34:07 david__schmidt
- Update OS/2 build section
+
+ Matches for http://www.example.net/adsl/HOWTO/:
- 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.
+ In file: default.action [ View ][ Edit ]
- Revision 1.27 2002/01/11 14:14:32 hal9
- Added a very short section on Templates
+ {-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.26 2002/01/09 20:02:50 hal9
- Fix bug re: auto-detect config file changes.
+ { +block{Path contains "ads".} +handle-as-image }
+ /ads
+
- Revision 1.25 2002/01/09 18:20:30 hal9
- Touch ups for *.action files.
+
+ 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.24 2001/12/02 01:13:42 hal9
- Fix typo.
+
+ { -block }
+ /adsl
+
- Revision 1.23 2001/12/02 00:20:41 hal9
- Updates for recent changes.
+
+ 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.22 2001/11/05 23:57:51 hal9
- Minor update for startup now daemon mode.
+
+ But now what about a situation where we get no explicit matches like
+ we did with:
+
- Revision 1.21 2001/10/31 21:11:03 hal9
- Correct 2 minor errors
+
+ { +block{Path starts with "ads".} +handle-as-image }
+ /ads
+
- Revision 1.18 2001/10/24 18:45:26 hal9
- *** empty log message ***
+
+ 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.17 2001/10/24 17:10:55 hal9
- Catching up with Jon's recent work, and a few other things.
+
+ { shop }
+ .quietpc.com
+ .worldpay.com # for quietpc.com
+ .jungle.com
+ .scan.co.uk
+ .forbes.com
+
- Revision 1.16 2001/10/21 17:19:21 swa
- wrong url in documentation
+
+ { shop } is an alias that expands to
+ { -filter -session-cookies-only }.
+ Or you could do your own exception to negate filtering:
+
- 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
+