Privoxy User Manual
Prev		Next

4. Quickstart to Using Privoxy

4.1. Note to Upgraders

There are very significant changes from older versions of - Junkbuster to the current - Privoxy. Configuration is substantially - changed. Junkbuster 2.0.x and earlier - configuration files will not migrate. The functionality of the old - blockfile, cookiefile and - imagelist, are now combined into the - "actions file" (default.action - for most installations).

A "filter file" (typically default.filter) - is new as of Privoxy 2.9.x, and provides some - of the new sophistication (explained below). config is - much the same as before.

If upgrading from a 2.0.x version, you will have to use the new config - files, and possibly adapt any personal rules from your older files. - When porting personal rules over from the old blockfile - to the new actions file, please note that even the pattern syntax has - changed. If upgrading from 2.9.x development versions, it is still - recommended to use the new configuration files.

A quick list of things to be aware of before upgrading:

The default listening port is now 8118 due to a conflict with another - service (NAS). -
- Some installers may remove earlier versions completely. Save any - important configuration files! -
Privoxy is controllable with a web browser - at the special URL: http://config.privoxy.org/ - (Shortcut: http://p.p/). Many - aspects of configuration can be done here, including temporarily disabling - Privoxy. -
The primary configuration file for cookie management, ad and banner - blocking, and many other aspects of Privoxy - configuration is default.action. It is strongly - recommended to become familiar with the new actions concept below, - before modifying this file. -
- Some installers may not automatically start - Privoxy after installation. -

4.2. 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 proxy. The default is 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: - localhost, Port: 8118). Include if 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 now ready to start enjoying the benefits of using - Privoxy!

Privoxy is typically started by specifying the - main configuration file to be used on the command line. Example Unix startup - command:

- # /usr/sbin/privoxy /etc/privoxy/config - -

See below for other command line options.

An init script is provided for SuSE and Red Hat.

For for SuSE: rcprivoxy start

For Red Hat and Debian: /etc/rc.d/init.d/privoxy start

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. If no file is specified on the - command line and no default configuration file can be found, - Privoxy will fail to start.

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.

You will probably want to keep an eye out for sites that require persistent - cookies, and add these to default.action as needed. By - default, most of these will be accepted only during the current browser - session (aka "session cookies"), until you add them to the - configuration. If you want the browser to handle this instead, you will need - to edit default.action 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.

Another feature where you will probably want to define exceptions for trusted - sites is the popup-killing (through the +popup and - +filter{popups} actions), because your favorite shopping, - banking, or leisure site may need popups.

Privoxy is HTTP/1.1 compliant, but not all of - the optional 1.1 features are as yet supported. In the unlikely event that - you experience inexplicable problems with browsers that use HTTP/1.1 per default - (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" 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" (as specified in default.action) - can be adjusted by pointing your browser to - http://config.privoxy.org/ - (shortcut: http://p.p/), - and then follow the link to "edit the actions list". - (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 default.action 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.

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.

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 - chapter "Contacting the Developers, .." below.

4.3. 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. -
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. -

Privoxy 3.0.27 User Manual
Prev		Next

4. 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!
+

4.1. 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. Privoxy 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 Privoxy 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":
+
+ +
Figure 1. Actions Files in Use
+
+
+
+
+
+
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.