3. Configuration

3.1. Where can I get updated Actions Files?

Based on your feedback and the continuing development, updates of default.action will be made available from time to time on the files section of our project page.

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.

3.2. Can I use my old config files?

The syntax and purpose of configuration files has remained the same throughout the 3.x series. Although each release contains updated, "improved" versions and it is recommended to use the newer configuration files. If upgrading from version prior to 3.0.4 the syntax for fast-redirects has changed. See the What's New section of the User Manual for details.

But all configuration files have substantially changed from the Junkbuster days, and early versions of Privoxy 2.x. The old files, like blocklist will not work at all.

Refer to the What's New page for information on configuration changes that may occur from one release to another.

3.3. What exactly is an "actions" file?

Actions files are where various actions that Privoxy could take while processing a certain request, are configured. Typically, you would define a set of default actions that apply to all URLs, then add exceptions to these defaults where needed. There is a wide array of actions available that give the user a high degree of control and flexibility on how to process each and every web page.

Actions can be defined on a URL pattern basis, i.e. for single URLs, whole web sites, groups or parts thereof etc. Actions can also be grouped together and then applied to requests matching one or more patterns. There are many possible actions that might apply to any given site. As an example, if you are blocking cookies as one of your default actions, but need to accept cookies from a given site, you would need to define an exception for this site in one of your actions files, preferably in user.action.

3.4. The "actions" concept confuses me. Please list some of these "actions".

For a comprehensive discussion of the actions concept, please refer to the actions file chapter in the user manual. It includes a list of all actions and an actions file tutorial to get you started.

3.5. How are actions files configured? What is the easiest way to do this?

Actions files are just text files in a special syntax and can be edited with a text editor. But probably the easiest way is to access Privoxy's user interface with your web browser at http://config.privoxy.org/ (Shortcut: http://p.p/) and then select "View & change the current configuration" from the menu.

3.6. There are several different "actions" files. What are the differences?

As of Privoxy v2.9.15, three actions files are being included, to be used for different purposes: These are default.action, the "main" actions file which is actively maintained by the Privoxy developers, user.action, where users are encouraged to make their private customizations, and standard.action, which is for internal Privoxy use only. Please see the actions chapter in the User Manual for a more detailed explanation.

Earlier versions included three different versions of the default.action file. The new scheme allows for greater flexibility of local configuration, and for browser based selection of pre-defined "aggressiveness" levels.

3.7. How can I make my Yahoo/Hotmail/Gmail account work?

The default configuration shouldn't impact the usability of any of these services. It will, however, make all cookies temporary, so that your browser will forget your login credentials in between browser sessions. If you would like not to have to log in manually each time you access those websites, simply turn off all cookie handling for them in the user.action file. An example for yahoo might look like:

# Allow all cookies for Yahoo login:
#
{ -crunch-incoming-cookies -crunch-outgoing-cookies -session-cookies-only }
.login.yahoo.com

These kinds of sites are often quite complex and heavy with Javascript and thus "fragile". So if still a problem, we have an alias just for such sticky situations:

# Gmail is a _fragile_ site:
#
{ fragile }
 mail.google.com

Be sure to flush your browser's caches whenever making these kinds of changes, just to make sure the changes "take".

Make sure the domain, host and path are appropriate as well. Your browser can tell you where you are specifically and you should use that information for your configuration settings. Note that above it is not referenced as gmail.com, which is a valid domain name.

3.8. What's the difference between the "Cautious", "Medium" and "Advanced" defaults?

Configuring Privoxy is not entirely trivial. To help you get started, we provide you with three different default action "profiles" in the web based actions file editor at http://config.privoxy.org/show-status. See the User Manual for a list of actions, and how the default profiles are set.

Where the defaults are likely to break some sites, exceptions for known popular "problem" sites are included, but in general, the more aggressive your default settings are, the more exceptions you will have to make later. See the User Manual for a more detailed discussion.

It should be noted that the "Advanced" profile (formerly known as the "Adventuresome" profile) is more aggressive, and will make use of some of Privoxy's advanced features. Use at your own risk!

3.9. Why can I change the configuration with a browser? Does that not raise security issues?

It may seem strange that regular users can edit the config files with their browsers, although the whole /etc/privoxy hierarchy belongs to the user "privoxy", with only 644 permissions.

When you use the browser-based editor, Privoxy itself is writing to the config files. Because Privoxy is running as the user "privoxy", it can update the config files.

If you run Privoxy for multiple untrusted users (e.g. in a LAN), you will probably want to turn the web-based editor and remote toggle features off by setting "enable-edit-actions 0" and "enable-remote-toggle 0" in the main configuration file.

Note that in the default configuration, only local users (i.e. those on "localhost") can connect to Privoxy, so this is not (normally) a security problem.

3.10. What is the default.filter file? What is a "filter"?

The default.filter file is where filters as supplied by the developers are defined. Filters are a special subset of actions that can be used to modify or remove, web page content on the fly. Filters apply to anything in the page source (and optionally both client and server headers), including HTML tags, and JavaScript. Regular expressions are used to accomplish this. There are a number of pre-defined filters to deal with common annoyances. The filters are only defined here, to invoke them, you need to use the filter action in one of the actions files. Filtering is automatically disabled for inappropriate MIME types.

If you are familiar with regular expressions, and HTML, you can look at the provided default.filter with a text editor and define your own filters. This is potentially a very powerful feature, but requires some expertise in both regular expressions and HTML/HTTP. You should place any modifications to the default filters, or any new ones you create in a separate file, such as user.filter, so they won't be overwritten during upgrades. The ability to define multiple filter files in config is a new feature as of v. 3.0.4.

There is no GUI editor option for this part of the configuration, but you can disable/enable the various pre-defined filters of the included default.filter file with the web-based actions file editor.

3.11. How can I set up Privoxy to act as a proxy for my LAN?

By default, Privoxy only responds to requests from 127.0.0.1 (localhost). To have it act as a server for a network, this needs to be changed in the main configuration file. Look for the listen-address option, which may be commented out with a "#" symbol. Make sure it is uncommented, and assign it the address of the LAN gateway interface, and port number to use. Assuming your LAN address is 192.168.1.1 and you wish to run Privoxy on port 8118, this line should look like:

  listen-address  192.168.1.1:8118

Save the file, and restart Privoxy. Configure all browsers on the network then to use this address and port number.

Alternately, you can have Privoxy listen on all available interfaces:

  listen-address    :8118

And then use Privoxy's permit-access feature to limit connections. A firewall in this situation is recommended as well.

The above steps should be the same for any TCP network, regardless of operating system.

If you run Privoxy on a LAN with untrusted users, we recommend that you double-check the access control and security options!

3.12. Instead of ads, now I get a checkerboard pattern. I don't want to see anything.

The replacement for blocked images can be controlled with the set-image-blocker action. You have the choice of a checkerboard pattern, a transparent 1x1 GIF image (aka "blank"), or a redirect to a custom image of your choice. Note that this choice only has effect for images which are blocked as images, i.e. whose URLs match both a handle-as-image and block action.

If you want to see nothing, then change the set-image-blocker action to "blank". This can be done by editing the default.action file, or trough the web-based actions file editor.

3.13. Why would anybody want to see a checkerboard pattern?

Remember that telling which image is an ad and which isn't, is mostly guesswork. While we hope that the standard configuration is rather smart, it can and will make errors. The checkerboard image is visually decent, but it shows you that and where images were blocked, which can be very helpful in case some navigation aid or otherwise innocent image was erroneously blocked. Some people might also enjoy seeing how many banners they don't have to see..

3.14. I see some images being replaced by a text instead of the checkerboard image. Why and how do I get rid of this?

This happens when the banners are not embedded in the HTML code of the page itself, but in separate HTML (sub)documents that are loaded into (i)frames or (i)layers, and these external HTML documents are blocked. Being non-images they get replaced by a substitute HTML page rather than a substitute image, which wouldn't work out technically, since the browser expects and accepts only HTML when it has requested an HTML document.

The substitute page adapts to the available space and shows itself as a miniature two-liner if loaded into small frames, or full-blown with a large red "BLOCKED" banner if space allows.

If you prefer the banners to be blocked by images, you must see to it that the HTML documents in which they are embedded are not blocked. Clicking the "See why" link offered in the substitute page will show you which rule blocked the page. After changing the rule and un-blocking the HTML documents, the browser will try to load the actual banner images and the usual image blocking will (hopefully!) kick in.

3.15. Can Privoxy run as a service on Win2K/NT/XP?

Yes. Version 3.0.4 introduces full Windows service functionality. See the User Manual for details on how to install and configure Privoxy as a service.

Earlier 3.x versions could run as a system service using srvany.exe. See the discussion at http://sourceforge.net/tracker/?func=detail&atid=361118&aid=485617&group_id=11118, for details, and a sample configuration.

3.16. How can I make Privoxy work with other proxies like Squid or Tor?

This can be done and is often useful to combine the benefits of Privoxy with those of a another proxy. See the forwarding chapter in the User Manual which describes how to do this, and the How do I use Privoxy together with Tor section below.

3.17. Can I just set Privoxy to use port 80 and thus avoid individual browser configuration?

No, its more complicated than that. This only works with special kinds of proxies known as "transparent" proxies (see below).

3.18. Can Privoxy run as a "transparent" proxy?

No, Privoxy currently does not have this ability, though it may be added in a future release. Transparent proxies require special handling of the request headers beyond what Privoxy is now capable of.

Chaining Privoxy behind another proxy that has this ability should work though. See the forwarding chapter in the User Manual. As a transparent proxy to be used for chaining we recommend Transproxy (http://transproxy.sourceforge.net/).

3.19. How can I configure Privoxy for use with Outlook Express?

Outlook Express uses Internet Explorer components to both render HTML, and fetch any HTTP requests that may be embedded in an HTML email. So however you have Privoxy configured to work with IE, this configuration should automatically be shared.

3.20. How can I have separate rules just for HTML mail?

The short answer is, you can't. Privoxy has no way of knowing which particular application makes a request, so there is no way to distinguish between web pages and HTML mail. Privoxy just blindly proxies all requests. In the case of Outlook Express (see above), OE uses IE anyway, and there is no way for Privoxy to ever be able to distinguish between them (nor could any other proxy type application for that matter).

For a good discussion of some of the issues involved (including privacy and security issues), see http://sourceforge.net/tracker/?func=detail&atid=211118&aid=629518&group_id=11118.

3.21. I sometimes notice cookies sneaking through. How?

Cookies can be set in several ways. The classic method is via the Set-Cookie HTTP header. This is straightforward, and an easy one to manipulate, such as the Privoxy concept of session-cookies-only. There is also the possibility of using Javascript to set cookies (Privoxy calls these content-cookies). This is trickier because the syntax can vary widely, and thus requires a certain amount of guesswork. It is not realistic to catch all of these short of disabling Javascript, which would break many sites. And lastly, if the cookies are embedded in a HTTPS/SSL secure session via Javascript, they are beyond Privoxy's reach.

All in all, Privoxy can help manage cookies in general, can help minimize the loss of privacy posed by cookies, but can't realistically stop all cookies.

3.22. Are all cookies bad? Why?

No, in fact there are many beneficial uses of cookies. Cookies are just a method that browsers can use to store data between pages, or between browser sessions. Sometimes there is a good reason for this, and the user's life is a bit easier as a result. But there is a long history of some websites taking advantage of this layer of trust, and using the data they glean from you and your browsing habits for their own purposes, and maybe to your potential detriment. Such sites are using you and storing their data on your system. That is why the security conscious watch from whom those cookies come, and why they really need to be there.

See the Wikipedia cookie definition for more.

3.23. How can I allow permanent cookies for my trusted sites?

There are several actions that relate to cookies. The default behavior is to allow only "session cookies", which means the cookies only last for the current browser session. This eliminates most kinds of abuse related to cookies. But there may be cases where we want cookies to last.

To disable all cookie actions, so that cookies are allowed unrestricted, both in and out, for example.com:

 { -crunch-incoming-cookies -crunch-outgoing-cookies -session-cookies-only -filter{content-cookies} }
  .example.com

Place the above in user.action. Note some of these may be off by default anyway, so this might be redundant, but there is no harm being explicit in what you want to happen. user.action includes an alias for this situation, called allow-all-cookies.

3.24. Can I have separate configurations for different users?

Each instance of Privoxy has its own configuration, including such attributes as the TCP port that it listens on. What you can do is run multiple instances of Privoxy, each with a unique listen-address and configuration path, and then each of these can have their own configurations. Think of it as per-port configuration.

Simple enough for a few users, but for large installations, consider having groups of users that might share like configurations.

3.25. Can I set-up Privoxy as a whitelist of "good" sites?

Sure. There are a couple of things you can do for simple whitelisting. Here's one real easy one:

 ############################################################
 # Blacklist
 ############################################################
 { +block }
 / # Block *all* URLs
 
 ############################################################
 # Whitelist
 ############################################################
 { -block }
  kids.example.com
  toys.example.com
  games.example.com

This allows access to only those three sites.

A more interesting approach is Privoxy's trustfile concept, which incorporates the notion of "trusted referrers". See the User Manual Trust documentation.

These are fairly simple approaches and are not completely foolproof. There are various other configuration options that should be disabled (described elsewhere here and in the User Manual) so that users can't modify their own configuration and easily circumvent the whitelist.