untrusted sites will be granted -- but only if a link from
this trusted referrer was used to get there. The link target
will then be added to the "trustfile" so that future, direct
accesses will be granted. Sites added via this mechanism do
not become trusted referrers themselves (i.e. they are added
with a ~ designation). There is a limit of 512 such entries,
after which new entries will not be made.
If you use the + operator in the trust file, it may grow
considerably over time.
It is recommended that Privoxy be compiled with the
--disable-force, --disable-toggle and --disable-editor options,
if this feature is to be used.
Possible applications include limiting Internet access for
children.
trustfile trust.txt
3. DEBUGGING
=============
These options are mainly useful when tracing a problem. Note that
you might also want to invoke Privoxy with the --no-daemon command
line option when debugging.
3.1. debug
===========
Specifies:
Key values that determine what information gets logged.
Type of value:
Integer values
Default value:
0 (i.e.: only fatal errors (that cause Privoxy to exit) are logged)
Effect if unset:
Default value is used (see above).
Notes:
The available debug levels are:
log each request destination (and the crunch reason if Privoxy intercepted the request)
debug 2 show each connection status
debug 4 show I/O status
debug 8 show header parsing
debug 16 log all data written to the network into the logfile
debug 32 debug force feature
debug 64 debug regular expression filters
debug 128 debug redirects
debug 256 debug GIF de-animation
debug 512 Common Log Format
debug 1024 Unused
debug 2048 CGI user interface
debug 4096 Startup banner and warnings.
debug 8192 Non-fatal errors
To select multiple debug levels, you can either add them or
use multiple debug lines.
A debug level of 1 is informative because it will show you each
request as it happens. 1, 4096 and 8192 are recommended so that
you will notice when things go wrong. The other levels are
probably only of interest if you are hunting down a specific
problem. They can produce a hell of an output (especially 16).
Privoxy used to ship with the debug levels recommended above
enabled by default, but due to privacy concerns 3.0.7 and later
are configured to only log fatal errors.
If you are used to the more verbose settings, simply enable
the debug lines below again.
If you want to use pure CLF (Common Log Format), you should set
"debug 512" ONLY and not enable anything else.
Privoxy has a hard-coded limit for the length of log messages. If
it's reached, messages are logged truncated and marked with
"... [too long, truncated]".
Please don't file any support requests without trying to
reproduce the problem with increased debug level first. Once
you read the log messages, you may even be able to solve the
problem on your own.
log each request destination (and the crunch reason if Privoxy intercepted the request)
debug 4096 Startup banner and warnings
debug 8192 Non-fatal errors
3.2. single-threaded
=====================
Specifies:
Whether to run only one server thread.
Type of value:
None
Default value:
Unset
Effect if unset:
Multi-threaded (or, where unavailable: forked) operation,
i.e. the ability to serve multiple requests simultaneously.
Notes:
This option is only there for debugging purposes. It will
drastically reduce performance.
single-threaded
3.3. hostname
==============
Specifies:
The hostname shown on the CGI pages.
Type of value:
Text
Default value:
Unset
Effect if unset:
The hostname provided by the operating system is used.
Notes:
On some misconfigured systems resolving the hostname fails or
takes too much time and slows Privoxy down. Setting a fixed
hostname works around the problem.
In other circumstances it might be desirable to show a hostname
other than the one returned by the operating system. For example
if the system has several different hostnames and you don't
want to use the first one.
Note that Privoxy does not validate the specified hostname value.
hostname hostname.example.org
4. ACCESS CONTROL AND SECURITY
===============================
This section of the config file controls the security-relevant
aspects of Privoxy's configuration.
4.1. listen-address
====================
Specifies:
The IP address and TCP port on which Privoxy will listen for
client requests.
Type of value:
[IP-Address]:Port
Default value:
127.0.0.1:8118
Effect if unset:
Bind to 127.0.0.1 (localhost), port 8118. This is suitable and
recommended for home users who run Privoxy on the same machine
as their browser.
Notes:
You will need to configure your browser(s) to this proxy address
and port.
If you already have another service running on port 8118, or
if you want to serve requests from other machines (e.g. on your
local network) as well, you will need to override the default.
If you leave out the IP address, Privoxy will bind to all
interfaces (addresses) on your machine and may become reachable
from the Internet. In that case, consider using access control
lists (ACL's, see below), and/or a firewall.
If you open Privoxy to untrusted users, you will also
want to make sure that the following actions are disabled:
enable-edit-actions and enable-remote-toggle
Example:
Suppose you are running Privoxy on a machine which has the
address 192.168.0.1 on your local private network (192.168.0.0)
and has another outside connection with a different address. You
want it to serve requests from inside only:
listen-address 192.168.0.1:8118
listen-address 127.0.0.1:8118
4.2. toggle
============
Specifies:
Initial state of "toggle" status
Type of value:
1 or 0
Default value:
1
Effect if unset:
Act as if toggled on
Notes:
If set to 0, Privoxy will start in "toggled off" mode,
i.e. mostly behave like a normal, content-neutral proxy
with both ad blocking and content filtering disabled. See
enable-remote-toggle below.
The windows version will only display the toggle icon in the
system tray if this option is present.
toggle 1
4.3. enable-remote-toggle
==========================
Specifies:
Whether or not the web-based toggle feature may be used
Type of value:
0 or 1
Default value:
0
Effect if unset:
The web-based toggle feature is disabled.
Notes:
When toggled off, Privoxy mostly acts like a normal,
content-neutral proxy, i.e. doesn't block ads or filter content.
Access to the toggle feature can not be controlled separately by
"ACLs" or HTTP authentication, so that everybody who can access
Privoxy (see "ACLs" and listen-address above) can toggle it
for all users. So this option is not recommended for multi-user
environments with untrusted users.
Note that malicious client side code (e.g Java) is also capable
of using this option.
As a lot of Privoxy users don't read documentation, this feature
is disabled by default.
Note that you must have compiled Privoxy with support for this
feature, otherwise this option has no effect.
enable-remote-toggle 0
4.4. enable-remote-http-toggle
===============================
Specifies:
Whether or not Privoxy recognizes special HTTP headers to change
its behaviour.
Type of value:
0 or 1
Default value:
0
Effect if unset:
Privoxy ignores special HTTP headers.
Notes:
When toggled on, the client can change Privoxy's behaviour by
setting special HTTP headers. Currently the only supported
special header is "X-Filter: No", to disable filtering for
the ongoing request, even if it is enabled in one of the
action files.
This feature is disabled by default. If you are using Privoxy in
a environment with trusted clients, you may enable this feature
at your discretion. Note that malicious client side code (e.g
Java) is also capable of using this feature.
This option will be removed in future releases as it has been
obsoleted by the more general header taggers.
enable-remote-http-toggle 0
4.5. enable-edit-actions
=========================
Specifies:
Whether or not the web-based actions file editor may be used
Type of value:
0 or 1
Default value:
0
Effect if unset:
The web-based actions file editor is disabled.
Notes:
Access to the editor can not be controlled separately by
"ACLs" or HTTP authentication, so that everybody who can access
Privoxy (see "ACLs" and listen-address above) can modify its
configuration for all users.
This option is not recommended for environments with untrusted
users and as a lot of Privoxy users don't read documentation,
this feature is disabled by default.
Note that malicious client side code (e.g Java) is also capable
of using the actions editor and you shouldn't enable this
options unless you understand the consequences and are sure
your browser is configured correctly.
Note that you must have compiled Privoxy with support for this
feature, otherwise this option has no effect.
enable-edit-actions 0
4.6. enforce-blocks
====================
Specifies:
Whether the user is allowed to ignore blocks and can "go there
anyway".
Type of value:
0 or 1
Default value:
0
Effect if unset:
Blocks are not enforced.
Notes:
Privoxy is mainly used to block and filter requests as a service
to the user, for example to block ads and other junk that clogs
the pipes. Privoxy's configuration isn't perfect and sometimes
innocent pages are blocked. In this situation it makes sense to
allow the user to enforce the request and have Privoxy ignore
the block.
In the default configuration Privoxy's "Blocked" page contains
a "go there anyway" link to adds a special string (the force
prefix) to the request URL. If that link is used, Privoxy
will detect the force prefix, remove it again and let the
request pass.
Of course Privoxy can also be used to enforce a network
policy. In that case the user obviously should not be able to
bypass any blocks, and that's what the "enforce-blocks" option
is for. If it's enabled, Privoxy hides the "go there anyway"
link. If the user adds the force prefix by hand, it will not
be accepted and the circumvention attempt is logged.
Examples:
enforce-blocks 1
enforce-blocks 0
4.7. ACLs: permit-access and deny-access
=========================================
Specifies:
Who can access what.
Type of value:
src_addr[/src_masklen] [dst_addr[/dst_masklen]]
Where src_addr and dst_addr are IP addresses in dotted decimal
notation or valid DNS names, and src_masklen and dst_masklen are
subnet masks in CIDR notation, i.e. integer values from 2 to 30
representing the length (in bits) of the network address. The
masks and the whole destination part are optional.
Default value:
Unset
Effect if unset:
Don't restrict access further than implied by listen-address
Notes:
Access controls are included at the request of ISPs and systems
administrators, and are not usually needed by individual
users. For a typical home user, it will normally suffice to
ensure that Privoxy only listens on the localhost (127.0.0.1)
or internal (home) network address by means of the listen-address
option.
Please see the warnings in the FAQ that Privoxy is not intended
to be a substitute for a firewall or to encourage anyone to
defer addressing basic security weaknesses.
Multiple ACL lines are OK. If any ACLs are specified, Privoxy
only talks to IP addresses that match at least one permit-access
line and don't match any subsequent deny-access line. In other
words, the last match wins, with the default being deny-access.
If Privoxy is using a forwarder (see forward below) for a
particular destination URL, the dst_addr that is examined is
the address of the forwarder and NOT the address of the ultimate
target. This is necessary because it may be impossible for the
local Privoxy to determine the IP address of the ultimate target
(that's often what gateways are used for).
You should prefer using IP addresses over DNS names, because
the address lookups take time. All DNS names must resolve! You
can not use domain patterns like "*.org" or partial domain
names. If a DNS name resolves to multiple IP addresses, only
the first one is used.
Denying access to particular sites by ACL may have undesired
side effects if the site in question is hosted on a machine
which also hosts other sites (most sites are).
Examples:
Explicitly define the default behavior if no ACL and
listen-address are set: "localhost" is OK. The absence of a
dst_addr implies that all destination addresses are OK:
permit-access localhost
Allow any host on the same class C subnet as www.privoxy.org
access to nothing but www.example.com (or other domains hosted
on the same system):
permit-access www.privoxy.org/24 www.example.com/32
Allow access from any host on the 26-bit subnet 192.168.45.64 to
anywhere, with the exception that 192.168.45.73 may not access
the IP addre