Sample Configuration File for Privoxy v3.0.9
$Id: config,v 1.65 2008/06/13 15:41:42 fabiankeil Exp $
Copyright (C) 2001-2008 Privoxy Developers http://www.privoxy.org/
Table of Contents
I. INTRODUCTION
II. FORMAT OF THE CONFIGURATION FILE
1. LOCAL SET-UP DOCUMENTATION
2. CONFIGURATION AND LOG FILE LOCATIONS
3. DEBUGGING
4. ACCESS CONTROL AND SECURITY
5. FORWARDING
6. WINDOWS GUI OPTIONS
I. INTRODUCTION
===============
This file holds Privoxy's main configuration. Privoxy detects
configuration changes automatically, so you don't have to restart
it unless you want to load a different configuration file.
The configuration will be reloaded with the first request after
the change was done, this request itself will still use the old
configuration, though. In other words: it takes two requests before
you see the result of your changes. Requests that are dropped due
to ACL don't trigger reloads.
When starting Privoxy on Unix systems, give the location of this
file as last argument. On Windows systems, Privoxy will look for
this file with the name 'config.txt' in the current working directory
of the Privoxy process.
II. FORMAT OF THE CONFIGURATION FILE
====================================
Configuration lines consist of an initial keyword followed by a
list of values, all separated by whitespace (any number of spaces
or tabs). For example,
actionsfile default.action
Indicates that the actionsfile is named 'default.action'.
The ' ' indicates a comment. Any part of a line following a ' '
is ignored, except if the ' ' is preceded by a '\'.
Thus, by placing a at the start of an existing configuration
line, you can make it a comment and it will be treated as if it
weren't there. This is called "commenting out" an option and can
be useful. Removing the again is called "uncommenting".
Note that commenting out an option and leaving it at its default
are two completely different things! Most options behave very
differently when unset. See the "Effect if unset" explanation in
each option's description for details.
Long lines can be continued on the next line by using a `\' as the
last character.
1. LOCAL SET-UP DOCUMENTATION
==============================
If you intend to operate Privoxy for more users than just yourself,
it might be a good idea to let them know how to reach you, what
you block and why you do that, your policies, etc.
1.1. user-manual
=================
Specifies:
Location of the Privoxy User Manual.
Type of value:
A fully qualified URI
Default value:
Unset
Effect if unset:
http://www.privoxy.org/version/user-manual/ will be used,
where version is the Privoxy version.
Notes:
The User Manual URI is the single best source of information on
Privoxy, and is used for help links from some of the internal
CGI pages. The manual itself is normally packaged with the
binary distributions, so you probably want to set this to a
locally installed copy.
Examples:
The best all purpose solution is simply to put the full local
PATH to where the User Manual is located:
user-manual /usr/share/doc/privoxy/user-manual
The User Manual is then available to anyone with
access to Privoxy, by following the built-in URL:
http://config.privoxy.org/user-manual/ (or the shortcut:
http://p.p/user-manual/).
If the documentation is not on the local system, it can be
accessed from a remote server, as:
user-manual http://example.com/privoxy/user-manual/
WARNING!!!
If set, this option should be the first option in the config
file, because it is used while the config file is being read.
user-manual http://www.privoxy.org/user-manual/
1.2. trust-info-url
====================
Specifies:
A URL to be displayed in the error page that users will see if
access to an untrusted page is denied.
Type of value:
URL
Default value:
Two example URLs are provided
Effect if unset:
No links are displayed on the "untrusted" error page.
Notes:
The value of this option only matters if the experimental trust
mechanism has been activated. (See trustfile below.)
If you use the trust mechanism, it is a good idea to write
up some on-line documentation about your trust policy and to
specify the URL(s) here. Use multiple times for multiple URLs.
The URL(s) should be added to the trustfile as well, so users
don't end up locked out from the information on why they were
locked out in the first place!
trust-info-url http://www.example.com/why_we_block.html
trust-info-url http://www.example.com/what_we_allow.html
1.3. admin-address
===================
Specifies:
An email address to reach the Privoxy administrator.
Type of value:
Email address
Default value:
Unset
Effect if unset:
No email address is displayed on error pages and the CGI user
interface.
Notes:
If both admin-address and proxy-info-url are unset, the whole
"Local Privoxy Support" box on all generated pages will not
be shown.
admin-address privoxy-admin@example.com
1.4. proxy-info-url
====================
Specifies:
A URL to documentation about the local Privoxy setup,
configuration or policies.
Type of value:
URL
Default value:
Unset
Effect if unset:
No link to local documentation is displayed on error pages and
the CGI user interface.
Notes:
If both admin-address and proxy-info-url are unset, the whole
"Local Privoxy Support" box on all generated pages will not
be shown.
This URL shouldn't be blocked ;-)
proxy-info-url http://www.example.com/proxy-service.html
2. CONFIGURATION AND LOG FILE LOCATIONS
========================================
Privoxy can (and normally does) use a number of other files for
additional configuration, help and logging. This section of the
configuration file tells Privoxy where to find those other files.
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 and actions files.
2.1. confdir
=============
Specifies:
The directory where the other configuration files are located.
Type of value:
Path name
Default value:
/etc/privoxy (Unix) or Privoxy installation dir (Windows)
Effect if unset:
Mandatory
Notes:
No trailing "/", please.
confdir .
2.2. templdir
==============
Specifies:
An alternative directory where the templates are loaded from.
Type of value:
Path name
Default value:
unset
Effect if unset:
The templates are assumed to be located in confdir/template.
Notes:
Privoxy's original templates are usually overwritten with each
update. Use this option to relocate customized templates that
should be kept. As template variables might change between
updates, you shouldn't expect templates to work with Privoxy
releases other than the one they were part of, though.
templdir .
2.3. logdir
============
Specifies:
The directory where all logging takes place (i.e. where logfile
and jarfile are located).
Type of value:
Path name
Default value:
/var/log/privoxy (Unix) or Privoxy installation dir (Windows)
Effect if unset:
Mandatory
Notes:
No trailing "/", please.
logdir .
2.4. actionsfile
=================
Specifies:
The actions file(s) to use
Type of value:
Complete file name, relative to confdir
Default values:
standard.action Internal purposes, no editing recommended
default.action Main actions file
user.action User customizations
Effect if unset:
No actions are taken at all. More or less neutral proxying.
Notes:
Multiple actionsfile lines are permitted, and are in fact
recommended!
The default values include standard.action, which is used
for internal purposes and should be loaded, default.action,
which is the "main" actions file maintained by the developers,
and user.action, where you can make your personal additions.
Actions files contain all the per site and per URL configuration
for ad blocking, cookie management, privacy considerations,
etc. There is no point in using Privoxy without at least one
actions file.
Note that since Privoxy 3.0.7, the complete filename, including
the ".action" extension has to be specified. The syntax change
was necessary to be consistent with the other file options and
to allow previously forbidden characters.
actionsfile standard.action Internal purpose, recommended
actionsfile default.action Main actions file
actionsfile user.action User customizations
2.5. filterfile
================
Specifies:
The filter file(s) to use
Type of value:
File name, relative to confdir
Default value:
default.filter (Unix) or default.filter.txt (Windows)
Effect if unset:
No textual content filtering takes place, i.e. all +filter{name}
actions in the actions files are turned neutral.
Notes:
Multiple filterfile lines are permitted.
The filter files contain content modification rules that use
regular expressions. These rules permit powerful changes on the
content of Web pages, and optionally the headers as well, e.g.,
you could try to disable your favorite JavaScript annoyances,
re-write the actual displayed text, or just have some fun
playing buzzword bingo with web pages.
The +filter{name} actions rely on the relevant filter (name)
to be defined in a filter file!
A pre-defined filter file called default.filter that contains a
number of useful filters for common problems is included in the
distribution. See the section on the filter action for a list.
It is recommended to place any locally adapted filters into a
separate file, such as user.filter.
filterfile default.filter
filterfile user.filter User customizations
2.6. logfile
=============
Specifies:
The log file to use
Type of value:
File name, relative to logdir
Default value:
Unset (commented out). When activated: logfile (Unix) or
privoxy.log (Windows).
Effect if unset:
No logfile is written.
Notes:
The logfile is where all logging and error messages are
written. The level of detail and number of messages are set with
the debug option (see below). The logfile can be useful for
tracking down a problem with Privoxy (e.g., it's not blocking
an ad you think it should block) and it can help you to monitor
what your browser is doing.
Depending on the debug options below, the logfile may be a
privacy risk if third parties can get access to it. As most
users will never look at it, Privoxy 3.0.7 and later only log
fatal errors by default.
For most troubleshooting purposes, you will have to change that,
please refer to the debugging section for details.
Your logfile will grow indefinitely, and you will probably
want to periodically remove it. On Unix systems, you can do
this with a cron job (see "man cron"). For Red Hat based Linux
distributions, a logrotate script has been included.
Any log files must be writable by whatever user Privoxy is
being run as (on Unix, default user id is "privoxy").
logfile privoxy.log
2.7. jarfile
=============
Specifies:
The file to store intercepted cookies in
Type of value:
File name, relative to logdir
Default value:
Unset (commented out). When activated: jarfile (Unix) or
privoxy.jar (Windows).
Effect if unset:
Intercepted cookies are not stored in a dedicated log file.
Notes:
The jarfile may grow to ridiculous sizes over time.
If debug 8 (show header parsing) is enabled, cookies are also
written to the logfile with the rest of the headers. Therefore
this option isn't very useful and may be removed in future
releases. Please report to the developers if you are still
using it.
jarfile jar.log
2.8. trustfile
===============
Specifies:
The name of the trust file to use
Type of value:
File name, relative to confdir
Default value:
Unset (commented out). When activated: trust (Unix) or trust.txt
(Windows)
Effect if unset:
The entire trust mechanism is disabled.
Notes:
The trust mechanism is an experimental feature for building
white-lists and should be used with care. It is NOT recommended
for the casual user.
If you specify a trust file, Privoxy will only allow access to
sites that are specified in the trustfile. Sites can be listed
in one of two ways:
Prepending a ~ character limits access to this site only (and
any sub-paths within this site), e.g. ~www.example.com allows
access to ~www.example.com/ features/news.html, etc.
Or, you can designate sites as trusted referrers, by prepending
the name with a + character. The effect is that access to
untrusted sites will be granted -- but only if