If upgrading, from versions before 2.9.16, please back up any configuration files. See the Note to Upgraders Section.
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 proxy by setting the proxy configuration for address of 127.0.0.1 and port 8118. (Junkbuster and earlier versions of Privoxy used port 8000.) See the section Starting Privoxy below for more details on this.
Flush your browser's disk and memory caches, to remove any cached ad images.
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.
See the Configuration section for more configuration options, and how to customize your installation.
If you experience ads that slipped through, innocent images that are blocked, or otherwise feel the need to fine-tune Privoxy's behaviour, 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 "Anatomy of an Action" has hints how to debug actions that "misbehave".
Please see the section Contacting the Developers on how to report bugs or problems with websites or to get help.
Now enjoy surfing with enhanced comfort and privacy!
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 recommeneded.
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. 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.
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.
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.
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.
The configuration options on what to display instead of the ad are:
pattern - a checkboard 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). |
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. 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 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.
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".
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.