-Privoxy User Manual
+Privoxy 3.1.1 User Manual
Copyright © 2001, 2002 by Privoxy Developers
-$Id: user-manual.sgml,v 1.117 2002/05/17 13:56:16 oes Exp $
+$Id: user-manual.sgml,v 2.2 2002/09/05 05:45:30 hal9 Exp $
-The user manual gives users information on how to install, configure and use
+The User Manual gives users information on how to install, configure and use
Privoxy.
Privoxy is a web proxy with advanced filtering capabilities for protecting
Privoxy is based on Internet Junkbuster (tm).
-You can find the latest version of the user manual at http://www.privoxy.org/
+You can find the latest version of the User Manual at http://www.privoxy.org/
user-manual/. Please see the Contact section on how to contact the developers.
-------------------------------------------------------------------------------
2.1. Binary Packages
- 2.1.1. Red Hat, SuSE RPMs and Conectiva
+ 2.1.1. Red Hat, SuSE and Conectiva RPMs
2.1.2. Debian
2.1.3. Windows
2.1.4. Solaris, NetBSD, FreeBSD, HP-UX
2.1.5. OS/2
- 2.1.6. Max OSX
+ 2.1.6. Mac OSX
2.1.7. AmigaOS
+ 2.1.8. Gentoo
2.2. Building from Source
+ 2.3. Keeping your Installation Up-to-Date
3. Note to Upgraders
4. Quickstart to Using Privoxy
5. Starting Privoxy
- 5.1. RedHat, Conectiva and Debian
- 5.2. SuSE
- 5.3. Windows
- 5.4. Solaris, NetBSD, FreeBSD, HP-UX and others
- 5.5. OS/2
- 5.6. MAX OSX
- 5.7. AmigaOS
- 5.8. Command Line Options
+ 5.1. Red Hat and Conectiva
+ 5.2. Debian
+ 5.3. SuSE
+ 5.4. Windows
+ 5.5. Solaris, NetBSD, FreeBSD, HP-UX and others
+ 5.6. OS/2
+ 5.7. Mac OSX
+ 5.8. AmigaOS
+ 5.9. Gentoo
+ 5.10. Command Line Options
6. Privoxy Configuration
1. Introduction
-This documentation is included with the current beta version of Privoxy,
-v.2.9.15, and is mostly complete at this point. The most up to date reference
+This documentation is included with the current alpha version of Privoxy,
+v.3.1.1, and is mostly complete at this point. The most up to date reference
for the time being is still the comments in the source files and in the
individual configuration files. Development of version 3.0 is currently nearing
completion, and includes many significant changes and enhancements over earlier
versions. The target release date for stable v3.0 is "soon" ;-).
-Since this is a beta version, not all new features are well tested. This
+Since this is a alpha 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 not many!
-------------------------------------------------------------------------------
-2.1.1. Red Hat, SuSE RPMs and Conectiva
+2.1.1. Red Hat, SuSE and Conectiva RPMs
-RPMs can be installed with rpm -Uvh privoxy-2.9.15-1.rpm, and will use /etc/
+RPMs can be installed with rpm -Uvh privoxy-3.1.1-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.
that SuSE will automatically start Privoxy in the boot process.
If you have problems with failed dependencies, try rebuilding the SRC RPM: rpm
---rebuild privoxy-2.9.15-1.src.rpm;. This will use your locally installed
+--rebuild privoxy-3.1.1-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
2.1.2. Debian
-FIXME.
+DEBs can be installed with dpkg -i privoxy_3.1.1-1.deb, and will use /etc/
+privoxy for the location of configuration files.
-------------------------------------------------------------------------------
2.1.4. Solaris, NetBSD, FreeBSD, HP-UX
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. FIXME.
+most part, you'll have to figure out where things go.
-------------------------------------------------------------------------------
2.1.5. OS/2
First, make sure that no previous installations of Junkbuster and / or Privoxy
-are left on your system. You can do this by
+are left on your system. Check that no Junkbuster or Privoxy objects are in
+your startup folder.
Then, just double-click the WarpIN self-installing archive, which will guide
you through the installation process. A shadow of the Privoxy executable will
-------------------------------------------------------------------------------
-2.1.6. Max OSX
+2.1.6. Mac OSX
+
+Unzip the downloaded file (you can either double-click on the file from the
+finder, or from the desktop if you downloaded it there). Then, double-click on
+the package installer icon named Privoxy.pkg and follow the installation
+process. Privoxy will be installed in the folder /Library/Privoxy. It will
+start automatically whenever you start up. To prevent it from starting
+automatically, remove or rename the folder /Library/StartupItems/Privoxy.
+
+To start Privoxy by hand, double-click on StartPrivoxy.command in the /Library/
+Privoxy folder. Or, type this command in the Terminal:
+
+ /Library/Privoxy/StartPrivoxy.command
+
-Unzip the downloaded package (you can either double-click on the file in the
-finder, or on the desktop if you downloaded it there). Then, double-click on
-the package installer icon and follow the installation process. Privoxy will be
-installed in the subdirectory /Applications/Privoxy.app. Privoxy will set
-itself up to start automatically on system bring-up via /System/Library/
-StartupItems/Privoxy.
+You will be prompted for the administrator password.
-------------------------------------------------------------------------------
files will be installed into Privoxy directory, including all configuration and
log files. To uninstall, just remove this directory.
-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).
+-------------------------------------------------------------------------------
+
+2.1.8. 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).
+
+Before installing Privoxy under Gentoo just do first emerge rsync to get the
+latest changes from the Portage tree. With emerge privoxy you install the
+latest version.
+
+Configuration files are in /etc/privoxy, the documentation is in /usr/share/doc
+/privoxy-3.1.1 and the Log directory is in /var/log/privoxy.
-------------------------------------------------------------------------------
When building from a source tarball (either release version or nightly CVS
tarball), first unpack the source:
- tar xzvf privoxy-2.9.15-beta-src* [.tgz or .tar.gz]
- cd privoxy-2.9.15-beta
+ tar xzvf privoxy-3.1.1-beta-src* [.tgz or .tar.gz]
+ cd privoxy-3.1.1-beta
For retrieving the current CVS sources, you'll need CVS installed. Note that
sources from CVS are development quality, and may not be stable, or well
make -n install # (to see where all the files will go)
make install # (to really install)
++-----------------------------------------------------------------------------+
+| Warning |
+|-----------------------------------------------------------------------------|
+|The "make install" target is temporary quite broken! It is recommended to use|
+|a binary package, or do a source build, and manually install the components. |
+|Sorry. |
++-----------------------------------------------------------------------------+
+
If you have gnu make, you can have the first four steps automatically done for
you by just typing:
-------------------------------------------------------------------------------
+2.3. 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.
+
+In order not to loose your personal changes and adjustments when updating to
+the latest default.action file we strongly recommend that you use user.action
+for your customization of Privoxy. See the Chapter on actions files for
+details.
+
+-------------------------------------------------------------------------------
+
3. Note to Upgraders
There are very significant changes from earlier Junkbuster versions to the
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 recommeneded.
+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
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.
-
-When you connect to a website, the full path of the URL will either match one
-of the "actions" as defined in Privoxy's configuration, or not. If so, then
-Privoxy will perform the action accordingly. If not, then nothing special
-happens. Futhermore, web pages may contain embedded, secondary URLs that your
-web browser will display as it parses the original page's HTML content. An ad
-image for instance, is just a 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.
+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.
The actions we need to know about for ad blocking are: block, handle-as-image,
and set-image-blocker:
* block - 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. If this
- is the only action that matches for this particular URL, then Privoxy will
- display its own BLOCKED page to let you now what has happened.
-
- * handle-as-image - forces Privoxy to treat this URL as if it were an image.
- Privoxy knows about common image types (e.g. GIF), but there are many
- situations where this does not apply. So we'll force it. This is
- particularly important for ad blocking, since once we can treat it as an
- image, we can make more intelligent decisisions on how to handle it. There
- are some limitations to this though. For instance, you can't just force an
- image substituion for an entire HTML page in most situations.
+ 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.
+
+ * 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.
* 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 either be of
- a known image type, or match an handle-as-image action.
+ 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 checkboard pattern, so that an ad replacement is obvious.
+ 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 URL of the user's choosing (advanced
- usage).
+ http://<URL> - A redirect to any image anywhere of the user's choosing
+ (advanced usage).
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:
Figure 1. Actions Files in Use
- Screenshot of Files in Use
+ [files-in-u]
- * You should have an Actions section labeled +block. If not, click the "Edit"
- button just 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.
+ * 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
+ * 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".
+ 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.
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.
+now go to the Actions Files Tutorial. The ideas explained therein also apply to
+the web-based editor.
-------------------------------------------------------------------------------
(or localhost) for the proxy address, and port 8118 (earlier versions used port
8000). This is the one configuration step that must be done!
-With Netscape (and Mozilla), this can be set under Edit -> Preferences ->
-Advanced -> Proxies -> HTTP Proxy. For Internet Explorer: Tools -> Internet
-Properties -> Connections -> LAN Setting. Then, check "Use Proxy" and fill in
-the appropriate info (Address: 127.0.0.1, Port: 8118). Include if HTTPS proxy
-support too.
+Please note that Privoxy can only proxy HTTP and HTTPS traffic. It will not
+work with FTP or other protocols.
+
+Figure 2. Proxy Configuration (Mozilla)
+
+[proxy_setu]
+
+With Netscape (and Mozilla), this can be set under:
+
+ Edit
+ |_
+ Preferences
+ |_
+ Advanced
+ |_
+ Proxies
+ |_
+ HTTP Proxy
+
+For Internet Explorer:
+
+ Tools
+ |_
+ Internet Properties
+ |_
+ 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.
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. You are
-------------------------------------------------------------------------------
-5.1. RedHat, Conectiva and Debian
+5.1. Red Hat and Conectiva
-We use a script. Note that RedHat does not start Privoxy upon booting per
+We use a script. Note that Red Hat does not start Privoxy upon booting per
default. It will use the file /etc/privoxy/config as its main configuration
-file. FIXME: Debian??
+file.
# /etc/rc.d/init.d/privoxy start
-------------------------------------------------------------------------------
-5.2. SuSE
+5.2. Debian
+
+We use a script. Note that Debian starts Privoxy upon booting per default. It
+will use the file /etc/privoxy/config as its main configuration file.
+
+ # /etc/init.d/privoxy start
+
+-------------------------------------------------------------------------------
+
+5.3. SuSE
We use a script. It will use the file /etc/privoxy/config as its main
configuration file. Note that SuSE starts Privoxy upon booting your PC.
-------------------------------------------------------------------------------
-5.3. Windows
+5.4. Windows
Click on the Privoxy Icon to start Privoxy. If no configuration file is
specified on the command line, Privoxy will look for a file named config.txt.
-------------------------------------------------------------------------------
-5.4. Solaris, NetBSD, FreeBSD, HP-UX and others
+5.5. Solaris, NetBSD, FreeBSD, HP-UX and others
Example Unix startup command:
-------------------------------------------------------------------------------
-5.5. OS/2
+5.6. OS/2
-FIXME.
+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.
-------------------------------------------------------------------------------
-5.6. MAX OSX
+5.7. Mac OSX
+
+During installation, Privoxy is configured to start automatically when the
+system restarts. To start Privoxy by hand, double-click on the
+StartPrivoxy.command icon in the /Library/Privoxy folder. Or, type this command
+in the Terminal:
-FIXME.
+ /Library/Privoxy/StartPrivoxy.command
+
+
+You will be prompted for the administrator password.
-------------------------------------------------------------------------------
-5.7. AmigaOS
+5.8. AmigaOS
-FIXME.
+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).
-------------------------------------------------------------------------------
-5.8. Command Line Options
+5.9. 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
+
+
+-------------------------------------------------------------------------------
+
+5.10. Command Line Options
Privoxy may be invoked with the following command-line options:
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
+ 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
The user running Privoxy, must have read permission for all configuration
files, and write permission to any files that would be modified, such as log
-files.
+files and actions files.
-------------------------------------------------------------------------------
Effect if unset:
- No log file is used, all log messages go to the console (stderr).
+ No log file is used, all log messages go to the console (STDERR).
Notes:
Unix, in local filesystem:
- user-manual file:///usr/share/doc/privoxy-2.9.15/user-manual/
+ user-manual file:///usr/share/doc/privoxy-3.1.1/user-manual/
Any platform, on local webserver (called "local-webserver"):
debug 256 # debug GIF de-animation
debug 512 # Common Log Format
debug 1024 # debug kill pop-ups
+ debug 2048 # CGI user interface
debug 4096 # Startup banner and warnings.
debug 8192 # Non-fatal errors
If you leave out the IP address, Privoxy will bind to all interfaces
(addresses) on your machine and may become reachable from the Internet. In
- that case, consider using access control lists (ACL's) (see "ACLs" below),
- or a firewall.
+ that case, consider using access control lists (ACL's, see below), and/or a
+ firewall.
+
+ If you open Privoxy to untrusted users, you will also want to turn off the
+ enable-edit-actions and enable-remote-toggle options!
Example:
Type of value:
- target_domain[:port] http_parent[/port]
+ target_pattern http_parent[:port]
- Where target_domain is a domain name pattern (see the chapter on domain
- matching in the default.action file), http_parent is the address of the
- parent HTTP proxy as an IP addresses in dotted decimal notation or as a
- valid DNS name (or "." to denote "no forwarding", and the optional port
- parameters are TCP ports, i.e. integer values from 1 to 64535
+ where target_pattern is a URL pattern that specifies to which requests
+ (i.e. URLs) this forward rule shall apply. Use / to denote "all URLs".
+ http_parent[:port] is the DNS name or IP address of the parent HTTP proxy
+ through which the requests should be forwarded, optionally followed by its
+ listening port (default: 8080). Use a single dot (.) to denote "no
+ forwarding".
Default value:
Everything goes to an example anonymizing proxy, except SSL on port 443
(which it doesn't handle):
- forward .* anon-proxy.example.org:8080
+ forward / anon-proxy.example.org:8080
forward :443 .
Everything goes to our example ISP's caching proxy, except for requests to
that ISP's sites:
- forward .*. caching-proxy.example-isp.net:8000
+ forward / caching-proxy.example-isp.net:8000
forward .example-isp.net .
-------------------------------------------------------------------------------
Type of value:
- target_domain[:port] socks_proxy[/port] http_parent[/port]
+ target_pattern socks_proxy[:port] http_parent[:port]
- Where target_domain is a domain name pattern (see the chapter on domain
- matching in the default.action file), http_parent and socks_proxy are IP
- addresses in dotted decimal notation or valid DNS names (http_parent may be
- "." to denote "no HTTP forwarding"), and the optional port parameters are
- TCP ports, i.e. integer values from 1 to 64535
+ where target_pattern is a URL pattern that specifies to which requests
+ (i.e. URLs) this forward rule shall apply. Use / to denote "all URLs".
+ http_parent and socks_proxy are IP addresses in dotted decimal notation or
+ valid DNS names (http_parent may be "." to denote "no HTTP forwarding"),
+ and the optional port parameters are TCP ports, i.e. integer values from 1
+ to 64535
Default value:
domains, but everything outbound goes through their ISP's proxy by way of
example.com's corporate SOCKS 4A gateway to the Internet.
- forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080
+ forward-socks4a / socks-gw.example.com:1080 www-cache.example-isp.net:8080
forward .example.com .
A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent
looks like this:
- forward-socks4 .*. socks-gw.example.com:1080 .
+ forward-socks4 / socks-gw.example.com:1080 .
-------------------------------------------------------------------------------
host-a:
- forward .*. .
+ forward / .
forward .isp-b.net host-b:8118
host-b:
- forward .*. .
+ forward / .
forward .isp-a.net host-a:8118
Now, your users can set their browser's proxy to use either host-a or host-b
and port. Squid normally uses port 3128. If unsure consult http_port in
squid.conf.
+You could just as well decide to only forward requests for Windows executables
+through a virus-scanning parent proxy, say, on antivir.example.com, port 8010:
+
+ forward / .
+ forward /.*\.(exe|com|dll|zip)$ antivir.example.com:8010
+
-------------------------------------------------------------------------------
7.6. Windows GUI Options
list of applicable actions for the URL is incrementally updated, using the
heading of the section in which the pattern is located. If multiple matches for
the same URL set the same action differently, the last match wins. If not, the
-effects are aggregated (e.g. a URL might match both the "+handle-as-image" and
-"+block" actions).
+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.
You can trace this process for any given URL by visiting http://
config.privoxy.org/show-url-info.
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
+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.
Parameter:
The name of a filter, as defined in the filter file (typically
- default.filter, set by the filterfile option in the config file)
+ default.filter, set by the filterfile option in the config file). Filtering
+ can be completely disabled without the use of parameters.
Notes:
- For your convenience, there are a bunch of pre-defined filters available in
- the distribution filter file that you can use. See the example below for a
- list.
+ 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.
This is potentially a very powerful feature! But "rolling your own" filters
requires a knowledge of regular expressions and HTML.
page is not incrementally displayed.) This effect will be more noticeable
on slower connections.
+ 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 are not filtered.
+
At this time, Privoxy cannot (yet!) uncompress compressed documents. If you
want filtering to work on all documents, even those that would normally be
sent compressed, use the prevent-compression action in conjunction with
filter.
- Filtering can achieve some of the effects as the block action, i.e. it can
- be used to block ads and banners.
+ 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!
+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse
- +filter{banners-by-size} # Kill banners by size (very efficient!)
+ +filter{banners-by-size} # Kill banners based on their size for this page (very efficient!)
+
+ +filter{banners-by-link} # Kill banners based on the link they are contained in (experimental)
+
+ +filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective
+filter{content-cookies} # Kill cookies that come sneaking in the HTML or JS content
+filter{crude-parental} # Kill all web pages that contain the words "sex" or "warez"
+ +filter{js-events} # Kill all JS event bindings (Radically destructive! Only for extra nasty sites)
+
-------------------------------------------------------------------------------
8.5.9. handle-as-image
reflect the file type, like in the second example section.
Note that you cannot treat HTML pages as images in most cases. For
- instance, (inline) ad frames require an HTML page to be sent, or they won't
- display properly. Forcing handle-as-image in this situation will not
+ 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.
Example usage (sections):
starts, so we have to explicitly enable the ones we want.
The first regular section is probably the most important. It has only one
-pattern, "/", but this pattern matches all URLs.. Therefore, the set of actions
+pattern, "/", but this pattern matches all URLs. Therefore, the set of actions
used in this "default" section will be applied to all requests as a start. It
can be partly or wholly overridden by later matches further down this file, or
in user.action, but it will still be largely responsible for your overall
Again, at the start of matching, all actions are disabled, so there is no real
need to disable any actions here, but we will do that nonetheless, to have a
-complete listing for your reference. (Remember: A "+" preceding the action name
+complete listing for your reference. (Remember: a "+" preceding the action name
enables the action, a "-" disables!). Also note how this long line has been
made more readable by splitting it into multiple lines with line continuation.
-filter{fun} \
+filter{nimda} \
+filter{banners-by-size} \
+ -filter{banners-by-link} \
+ -filter{img-reorder} \
-filter{shockwave-flash} \
-filter{crude-parental} \
+ -filter{js-events} \
-handle-as-image \
+hide-forwarded-for-headers \
+hide-from-header{block} \
8.7.2. user.action
So far we are painting with a broad brush by setting general policies, which
-would be a reasonable starting point for many people. Now, you'd maybe want to
-be more specific and have customized rules that are more suitable to your
-personal habits and preferences. These would be for narrowly defined situations
-like your ISP or your bank, and should be placed in user.action, which is
-parsed after all other actions files and hence has the last word, over-riding
-any previously defined actions. user.action is also a safe place for your
-personal settings, since default.action is actively maintained by the Privoxy
-developers and you'll probably want to install updated versions from time to
-time.
+would be a reasonable starting point for many people. Now, you might want to be
+more specific and have customized rules that are more suitable to your personal
+habits and preferences. These would be for narrowly defined situations like
+your ISP or your bank, and should be placed in user.action, which is parsed
+after all other actions files and hence has the last word, over-riding any
+previously defined actions. user.action is also a safe place for your personal
+settings, since default.action is actively maintained by the Privoxy developers
+and you'll probably want to install updated versions from time to time.
So let's look at a few examples of things that one might typically do in
user.action:
# The status bar is for displaying link targets, not pointless blahblah
#
-s/window\.status\s*=\s*['"].*?['"]/dUmMy=1/ig
+s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig
\s stands for whitespace characters (space, tab, newline, carriage return, form
feed), so that \s* means: "zero or more whitespace". The ? in .*? makes this
matching of arbitrary text ungreedy. (Note that the U option is not set). The
-['"] construct means: "a single or a double quote".
+['"] construct means: "a single or a double quote". Finally, \1 is a
+backreference to the first parenthesis just like $1 above, with the difference
+that in the pattern, a backslash indicates a backreference, whereas in the
+substitute, it's the dollar.
So what does this job do? It replaces assignments of single- or double-quoted
strings to the "window.status" object with a dummy assignment (using a variable
# Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html
#
-s/(<body .*)onunload(.*>)/$1never$2/iU
+s/(<body [^>]*)onunload(.*>)/$1never$2/iU
Including the OnUnload event binding in the HTML DOM was a CRIME. When I close
a browser window, I want it to close and die. Basta. This job replaces the
"onunload" attribute in "<body>" tags with the dummy word never. Note that the
-i option makes the pattern matching case-insensitive.
+i option makes the pattern matching case-insensitive. Also note that ungreedy
+matching alone doesn't always guarantee a minimal match: In the first
+parenthesis, we had to use [^>]* instead of .* to prevent the match from
+exceeding the <body> tag if it doesn't contain "OnUnload", but the page's
+content does.
The last example is from the fun department:
Note the (?!\.com) part (a so-called negative lookahead) in the job's pattern,
which means: Don't match, if the string ".com" appears directly following
"microsoft" in the page. This prevents links to microsoft.com from being
-messed, while still replacing the word everywhere else.
+trashed, while still replacing the word everywhere else.
# Buzzword Bingo (example for extended regex syntax)
#
s* industry[ -]leading \
| cutting[ -]edge \
+| customer[ -]focused \
+| market[ -]driven \
| award[ -]winning # Comments are OK, too! \
| high[ -]performance \
| solutions[ -]based \
All Privoxy built-in pages, i.e. error pages such as the "404 - No Such Domain"
error page, the "BLOCKED" page and all pages of its web-based user interface,
are generated from templates. (Privoxy must be running for the above links to
-work as intended)
+work as intended.)
These templates are stored in a subdirectory of the configuration directory
-called templates. On unixish platforms, this is typically /etc/privoxy/
+called templates. On Unixish platforms, this is typically /etc/privoxy/
templates/.
The templates are basically normal HTML files, but with place-holders (called
tracker/?group_id=11118&atid=111118.
Before doing so, please make sure that the bug has not already been submitted
-and observe the aditional hints at the top of the submit form.
+and observe the additional hints at the top of the submit form.
Please try to verify that it is a Privoxy bug, and not a browser or site bug
first. If unsure, try toggling off Privoxy, and see if the problem persists.
New, improved default.action files will occasionally be made available based on
your feedback. These will be announced on the ijbswa-announce list and
-available from our project page.
+available from our the files section of our project page.
-------------------------------------------------------------------------------
For any other issues, feel free to use the mailing lists. Technically
interested users and people who wish to contribute to the project are also
-welcome on the developers list! You can find an overview of all Prixoxy-related
+welcome on the developers list! You can find an overview of all Privoxy-related
mailing lists, including list archives, at: http://sourceforge.net/mail/?
group_id=11118.
inside out, upside down, and then reassembled it, adding many new features
along the way.
-The result of this is Privoxy, whose first stable release, 3.0, is due in May
-2002.
+The result of this is Privoxy, whose first stable release, 3.0, was released
+August, 2002.
-------------------------------------------------------------------------------
Current Project Contributors:
Rodrigo Barbosa (RPM specfiles)
+ Moritz Barsnick
Hal Burgiss (docs)
+ Karsten Hopp (Red Hat)
Alexander Lazic
Gábor Lipták
Guy
Haroon Rafique
+ Roland Rosenfeld (Debian)
+ Georg Sauthoff (Gentoo)
David Schmidt (OS/2, Mac OSX ports)
- Joerg Strohmayer
+ Joerg Strohmayer (Amiga)
Sarantis Paskalis
-Originally developed by:
+Based in part on code originally developed by:
Junkbusters Corp.
Anonymous Coders
suggestions. These include (in alphabetical order):
Ken Arromdee
+ Devin Bayer
Reiner Buehl
Andrew J. Caines
Clifford Caoile
+ Michael T. Davis
Peter E
Aaron Hamid
Magnus Holmgren
+ Daniel Leite
Paul Lieverse
+ David Mediavilla
Roberto Ragusa
+ Maynard Riley
Bart Schelstraete
Darren Wiebe
+ Jamie Zawinski
-------------------------------------------------------------------------------
http://www.privoxy.org/actions/, to submit "misses" to the developers.
+http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/contrib/, cool and fun
+ideas from Privoxy users.
+
http://www.junkbusters.com/ht/en/cookies.html, an explanation how cookies are
used to track web users.
More reading on Perl Compatible Regular expressions: http://www.perldoc.com/
perl5.6/pod/perlre.html
-For information on regular expression based substititions and their
+For information on regular expression based substitutions and their
applications in filters, please see the filter file tutorial in this manual.
-------------------------------------------------------------------------------
http://config.privoxy.org/
- There is a shortcut: http://p.p/ (But it doesn't provide a fallback to a
+ 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
* Privoxy - Submit Actions File Feedback
+ * Privoxy - Why?
+
Credit: The site which gave us the general idea for these bookmarklets is
www.bookmarklets.com. They have more information about bookmarklets.
* 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 deterimed by the "+crunch-incoming-cookies",
+ filtered as determined by the "+crunch-incoming-cookies",
"+session-cookies-only", and "+downgrade-http-version" actions.
* If the "+kill-popups" action applies, and it is an HTML or JavaScript
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. See the
Bookmarklets section on a quick and easy way to do this (be sure to flush
-caches afterward!).
+caches afterward!). Looking at the logs is a good idea too.
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
and make it more readable.
One last example. Let's try "http://www.rhapsodyk.net/adsl/HOWTO/". This one is
-giving us problems. We are getting a blank page. Hmmm...
+giving us problems. We are getting a blank page. Hmmm ...
Matches for http://www.rhapsodyk.net/adsl/HOWTO/:
If you don't get this kind of match, then it means one of the default rules in
the first section 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. Try adding the URL for the site
-to one of aliases that turn off "+filter":
+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":
{shop}
.quietpc.com
{-filter}
.forbes.com
-This would probably be most appropriately put in user.action, for local site
-exceptions.
+This would turn off all filtering for that site. This would probably be most
+appropriately put in user.action, for local site exceptions.
+
+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).
"{fragile}" is an alias that disables most actions. This can be used as a last
resort for problem sites. Remember to flush caches! If this still does not
projects / privoxy.git / blobdiff