Quickstart to Using Privoxy

Privoxy 3.0.11 User Manual4. Quickstart to Using Privoxy4. 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). +> 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.
- Some installers may remove earlier versions completely. Save any - important configuration files! +> 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 is controllable with a web browser - at the special URL: as HTTP and + HTTPS (SSL) http://config.privoxy.org/proxy - (Shortcut: http://p.p/). Many - aspects of configuration can be done here, including temporarily disabling + 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.
The primary configuration file for cookie management, ad and banner - blocking, and many other aspects of 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 - configuration is default.action. It is strongly - recommended to become familiar with the new actions concept below, - before modifying this file. + 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".
- Some installers may not automatically start - Privoxy after installation. +> 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.2. Starting Privoxy4.1. Quickstart to Ad Blocking

Before launching Privoxy for the first time, you - will want to configure your browser(s) to use Ad blocking is but one of PrivoxyPrivoxy's - 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

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 Netscape (and +>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 Mozilla), this can be set under 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: Edit - -> Preferences -> Advanced -> Proxies -> HTTP Proxy. - For 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 + Internet Explorer: Privoxy's own built-in BLOCKED page instead to + let you now what has happened (with some exceptions, see below). +
Tools -> - Internet Properties -> Connections -> LAN Setting. Then, - check 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 "Use Proxy" and fill in the appropriate info (Address: - localhost, Port: 8118). Include if HTTPS proxy support too.
"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. +
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 - handle-as-empty-document - + sends an empty document instead of Privoxy!
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 is typically started by specifying the - main configuration file to be used on the command line. Example Unix startup - command:
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: +

Privoxy User Manual
Prev	Next

pattern - a checkerboard pattern, so that an ad + replacement is obvious. This is the default. +

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

See below for other command line options.

An init script is provided for SuSE and Red Hat.

blank - A very small empty GIF image is displayed. + This is the so-called "invisible" configuration option. +

For for SuSE: rcprivoxy start

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

http://<URL> - A redirect to any image anywhere + of the user's choosing (advanced usage). +

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 - Advanced users will eventually want to explore 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 filters as well. Filters + are very different from Edit -> - Preferences -> Debug -> Networkingblocks. - 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.

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

After running The quickest way to adjust any of these settings is with your browser through + the special 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 - editor at http://config.privoxy.org/http://config.privoxy.org/show-status (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.)

http://p.p/show-status). This + is an internal page, and does not require Internet access.

In fact, various aspects of Note that as of Privoxy - configuration can be viewed from this page, including - current configuration parameters, source code version numbers, - the browser's request headers, and 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" that apply - to a given URL. In addition to the default.action file - editor mentioned above, Privoxy can also - be turned file, and click + "on" and "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 "off" (toggled) from this page.

If you encounter problems, try loading the page without +>"actions", and URLs for ad + blocking or other purposes, and make other adjustments to the configuration. 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

will detect these changes automatically.

Privoxy may be invoked with the following - command-line options:

A quick and simple step by step example:

--version -
Print version info and exit. Unix only. -
Right click on the ad image to be blocked, then select + "Copy Link Location" from the + pop-up menu. +
--help Set your browser to + http://config.privoxy.org/show-status -
Print short usage info and exit. Unix only. -
--no-daemon -
Find user.action in the top section, and click + on "Edit": +

Don't become a daemon, i.e. don't fork and become process group - leader, and don't detach from controlling tty. Unix only. -
Figure 1. Actions Files in Use
+
--pidfile FILE You should have a section with only + block listed under + "Actions:". + If not, click a "Insert new section below" - -
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 FILEEdit 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" - option is given, no PID file will be used. Unix only. + just below the list.
--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. +> 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).
configfile Now go back to the original page, and press SHIFT-Reload -
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. + (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.