From: hal9 <hal9@users.sourceforge.net>
Date: Thu, 7 Sep 2006 02:02:56 +0000 (+0000)
Subject: - This includes Fabian two new options for config.
X-Git-Tag: v_3_0_5~80
X-Git-Url: http://www.privoxy.org/gitweb/%22https:/faq/@default-cgi@/developer-manual/static/gitweb.js?a=commitdiff_plain;h=c9257b900217d4093558af0eadb1fce311ce92cf;p=privoxy.git
- This includes Fabian two new options for config.
- User manual config option is now first option in config so that path can
be seen during program start up. Required moving the first two sections
around.
---
diff --git a/config b/config
index b3bee1ee..06fac21b 100644
--- a/config
+++ b/config
@@ -1,6 +1,6 @@
# Sample Configuration File for Privoxy v3.0.4
#
-# $Id: config,v 1.51 2006/09/04 18:09:05 hal9 Exp $
+# $Id: p-config.sgml,v 2.9 2006/09/06 11:38:33 fabiankeil Exp $
#
# Copyright (C) 2001-2006 Privoxy Developers http://privoxy.org
#
@@ -11,8 +11,8 @@
# I. INTRODUCTION #
# II. FORMAT OF THE CONFIGURATION FILE #
# #
-# 1. CONFIGURATION AND LOG FILE LOCATIONS #
-# 2. LOCAL SET-UP DOCUMENTATION #
+# 1. LOCAL SET-UP DOCUMENTATION #
+# 2. CONFIGURATION AND LOG FILE LOCATIONS #
# 3. DEBUGGING #
# 4. ACCESS CONTROL AND SECURITY #
# 5. FORWARDING #
@@ -62,7 +62,169 @@
#
#
-# 1. CONFIGURATION AND LOG FILE LOCATIONS
+# 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. For multi-user setups, you could
+# provide a copy on a local webserver for all your users and use
+# the corresponding URL here.
+#
+# 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 the proxy, 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 URL 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 above.)
+#
+# 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 proxy 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
@@ -75,7 +237,7 @@
#
#
-# 1.1. confdir
+# 2.1. confdir
# ============
#
# Specifies:
@@ -107,7 +269,7 @@
confdir .
#
-# 1.2. logdir
+# 2.2. logdir
# ===========
#
# Specifies:
@@ -134,7 +296,7 @@ confdir .
logdir .
#
-# 1.3. actionsfile
+# 2.3. actionsfile
# ================
#
# Specifies:
@@ -177,7 +339,7 @@ actionsfile default # Main actions file
actionsfile user # User customizations
#
-# 1.4. filterfile
+# 2.4. filterfile
# ===============
#
# Specifies:
@@ -199,7 +361,7 @@ actionsfile user # User customizations
#
# Notes:
#
-# Multiple filterfiles lines are permitted.
+# Multiple filterfile lines are permitted.
#
# The filter files contain content modification rules that use
# regular expressions. These rules permit powerful changes on
@@ -222,7 +384,7 @@ filterfile default.filter
#filterfile user.filter # User customizations
#
-# 1.5. logfile
+# 2.5. logfile
# ============
#
# Specifies:
@@ -266,7 +428,7 @@ filterfile default.filter
logfile logfile
#
-# 1.6. jarfile
+# 2.6. jarfile
# ============
#
# Specifies:
@@ -296,7 +458,7 @@ logfile logfile
#jarfile jarfile
#
-# 1.7. trustfile
+# 2.7. trustfile
# ==============
#
# Specifies:
@@ -349,169 +511,6 @@ logfile logfile
#
#trustfile trust
-#
-# 2. 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.
-#
-
-#
-# 2.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 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. For multi-user setups, you could
-# provide a copy on a local webserver for all your users and use
-# the corresponding URL here.
-#
-# Examples:
-#
-# Unix, in local filesystem:
-#
-# user-manual file:///usr/share/doc/privoxy-3.0.4/user-manual/
-#
-# Windows, in local filesystem, must use forward slash notation:
-#
-# user-manual file:/c:/some-dir/privoxy-3.0.4/user-manual/
-#
-# Windows, UNC notation (with forward slashes):
-#
-# user-manual
-# file://///some-server/some-path/privoxy-3.0.4/user-manual/
-#
-# Any platform, on local webserver (called "local-webserver"):
-#
-# user-manual http://local-webserver/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/
-
-#
-# 2.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 URL 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 above.)
-#
-# 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
-
-#
-# 2.3. admin-address
-# ==================
-#
-# Specifies:
-#
-# An email address to reach the proxy 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
-
-#
-# 2.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
-
#
# 3. DEBUGGING
# ============
@@ -545,21 +544,21 @@ trust-info-url http://www.example.com/what_we_allow.html
# Notes:
#
# The available debug levels are:
-#
-# debug 1 # show each GET/POST/CONNECT request
-# debug 2 # show each connection status
-# debug 4 # show I/O status
-# debug 8 # show header parsing
-# debug 16 # log all data into the logfile
-# debug 32 # debug force feature
-# debug 64 # debug regular expression filter
-# debug 128 # debug fast redirects
-# debug 256 # debug GIF de-animation
-# debug 512 # Common Log Format
-# debug 1024 # debug kill pop-ups
-# debug 2048 # CGI user interface
-# debug 4096 # Startup banner and warnings.
-# debug 8192 # Non-fatal errors
+#
+# debug 1 # show each GET/POST/CONNECT request
+# debug 2 # show each connection status
+# debug 4 # show I/O status
+# debug 8 # show header parsing
+# debug 16 # log all data into the logfile
+# debug 32 # debug force feature
+# debug 64 # debug regular expression filter
+# debug 128 # debug fast redirects
+# debug 256 # debug GIF de-animation
+# debug 512 # Common Log Format
+# debug 1024 # debug kill pop-ups
+# 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.
@@ -739,7 +738,42 @@ toggle 1
enable-remote-toggle 1
#
-# 4.4. enable-edit-actions
+# 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:
+#
+# 1
+#
+# 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.
+#
+# If you are using Privoxy in a multi-user environment or with
+# untrustworthy clients and want to enforce filtering, you will
+# have to disable this option, otherwise you can ignore it.
+#
+enable-remote-http-toggle 1
+
+#
+# 4.5. enable-edit-actions
# ========================
#
# Specifies:
@@ -772,7 +806,7 @@ enable-remote-toggle 1
enable-edit-actions 1
#
-# 4.5. ACLs: permit-access and deny-access
+# 4.6. ACLs: permit-access and deny-access
# ========================================
#
# Specifies:
@@ -844,7 +878,7 @@ enable-edit-actions 1
# Allow any host on the same class C subnet as www.privoxy.org
# access to nothing but www.example.com:
#
-# permit-access www.privoxy.org/24 www.example.com/32
+# 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
@@ -855,7 +889,7 @@ enable-edit-actions 1
#
#
-# 4.6. buffer-limit
+# 4.7. buffer-limit
# =================
#
# Specifies:
@@ -1006,36 +1040,79 @@ buffer-limit 4096
# ISP's proxy by way of example.com's corporate SOCKS 4A gateway
# to the Internet.
#
-# forward-socks4a / socks-gw.example.com:1080 www-cache.example-isp.net:8080
-# forward .example.com .
-#
+# forward-socks4a / socks-gw.example.com:1080 www-cache.example-isp.net:8080
+# forward .example.com .
+#
# A rule that uses a SOCKS 4 gateway for all destinations but no
# HTTP parent looks like this:
-#
-# forward-socks4 / socks-gw.example.com:1080 .
+#
+# forward-socks4 / socks-gw.example.com:1080 .
#
# To chain Privoxy and Tor, both running on the same system,
# you should use the rule:
-#
-# forward-socks4 / 127.0.0.1:9050 .
+#
+# forward-socks4a / 127.0.0.1:9050 .
#
# The public Tor network can't be used to reach your local network,
# therefore it's a good idea to make some exceptions:
#
-# forward 192.168.*.*/ .
-# forward 10.*.*.*/ .
-# forward 127.*.*.*/ .
+# forward 192.168.*.*/ .
+# forward 10.*.*.*/ .
+# forward 127.*.*.*/ .
#
# Unencrypted connections to systems in these address ranges will
-# be as (un)secure as the local network is, but the alternative
-# is that you can't reach the network at all.
+# be as (un)secure as the local network is, but the alternative is
+# that you can't reach the network at all.
#
# If you also want to be able to reach servers in your local
-# network by using their names, you will need additional exceptions
-# that look like this:
+# network by using their names, you will need additional
+# exceptions that look like this:
+#
+# forward localhost/ .
+#
+
+#
+# 5.3. forwarded-connect-retries
+# ==============================
+#
+# Specifies:
+#
+# How often Privoxy retries if a forwarded connection request
+# fails.
+#
+# Type of value:
+#
+# Number of retries.
+#
+# Default value:
+#
+# 0
+#
+# Effect if unset:
+#
+# Forwarded connections are treated like direct connections and
+# no retry attempts are made.
+#
+# Notes:
+#
+# forwarded-connect-retries is mainly interesting for socks4a
+# connections, where Privoxy can't detect why the connections
+# failed. The connection might have failed because of a DNS timeout
+# in which case a retry makes sense, but it might also have failed
+# because the server doesn't exist or isn't reachable. In this
+# case the retry will just delay the appearance of Privoxy's
+# error message.
+#
+# Only use this option, if you are getting many forwarding related
+# error messages, that go away when you try again manually. Start
+# with a small value and check Privoxy's logfile from time to time,
+# to see how many retries are usually needed.
+#
+# Examples:
#
-# forward localhost/ .
+# forwarded-connect-retries 1
#
+forwarded-connect-retries 0
#
# 6. WINDOWS GUI OPTIONS
diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml
index 8223117d..270e2baa 100644
--- a/doc/source/p-config.sgml
+++ b/doc/source/p-config.sgml
@@ -3,7 +3,7 @@
Purpose : Used with other docs and files only.
- $Id: p-config.sgml,v 2.8 2006/09/06 02:17:53 hal9 Exp $
+ $Id: p-config.sgml,v 2.9 2006/09/06 11:38:33 fabiankeil Exp $
Copyright (C) 2001-2006 Privoxy Developers <developers@privoxy.org>
See LICENSE.
@@ -95,7 +95,7 @@
Sample Configuration File for Privoxy v&p-version;
</title>
<para>
- $Id: p-config.sgml,v 2.8 2006/09/06 02:17:53 hal9 Exp $
+ $Id: p-config.sgml,v 2.9 2006/09/06 11:38:33 fabiankeil Exp $
</para>
<para>
Copyright (C) 2001-2006 Privoxy Developers http://privoxy.org
@@ -110,8 +110,8 @@ Copyright (C) 2001-2006 Privoxy Developers http://privoxy.org
I. INTRODUCTION #
II. FORMAT OF THE CONFIGURATION FILE #
#
- 1. CONFIGURATION AND LOG FILE LOCATIONS #
- 2. LOCAL SET-UP DOCUMENTATION #
+ 1. LOCAL SET-UP DOCUMENTATION #
+ 2. CONFIGURATION AND LOG FILE LOCATIONS #
3. DEBUGGING #
4. ACCESS CONTROL AND SECURITY #
5. FORWARDING #
@@ -179,226 +179,272 @@ II. FORMAT OF THE CONFIGURATION FILE
<!-- The following is common to both outputs (mostly) -->
<!-- ************************************************ -->
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="conf-log-loc">
-<title>Configuration and Log File Locations</title>
-<para>
- <application>Privoxy</application> can (and normally does) use a number of
- other files for additional configuration, help and logging.
- This section of the configuration file tells <application>Privoxy</application>
- where to find those other files.
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="local-set-up">
+<title>Local Set-up Documentation</title>
-<para>
- The user running <application>Privoxy</application>, 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.
-</para>
+ <para>
+ If you intend to operate <application>Privoxy</application> 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.
+ </para>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="confdir"><title>confdir</title>
-
+<sect3 renderas="sect4" id="user-manual"><title>user-manual</title>
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
- <para>The directory where the other configuration files are located</para>
+ <para>
+ Location of the <application>Privoxy</application> User Manual.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type of value:</term>
<listitem>
- <para>Path name</para>
+ <para>A fully qualified URI</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para>/etc/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
+ <para><emphasis>Unset</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Effect if unset:</term>
<listitem>
- <para><emphasis>Mandatory</emphasis></para>
+ <para>
+ <ulink url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/<replaceable class="parameter">version</replaceable>/user-manual/</ulink>
+ will be used, where <replaceable class="parameter">version</replaceable> is the <application>Privoxy</application> version.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
+ <para>
+ The User Manual URI is the single best source of information on
+ <application>Privoxy</application>, 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. For multi-user setups, you could provide a copy on a local
+ webserver for all your users and use the corresponding URL here.
+ </para>
<para>
- No trailing <quote><literal>/</literal></quote>, please
+ Examples:
+ </para>
+ <!--
+ <para>
+ Unix, in local filesystem (may not work with all browsers):
+ </para>
+ <para>
+ <screen> user-manual file:///usr/share/doc/privoxy-&p-version;/user-manual/</screen>
+ </para>
+ <para>
+ Windows, in local filesystem, <emphasis>must</emphasis> use forward slash notation:
+ </para>
+ <para>
+ <screen> user-manual file:/c:/some-dir/privoxy-&p-version;/user-manual/</screen>
+ </para>
+ <para>
+ Windows, UNC notation (with forward slashes):
+ </para>
+ <para>
+ <screen> user-manual file://///some-server/some-path/privoxy-&p-version;/user-manual/</screen>
+ </para>
+ -->
+ <para>
+ The best all purpose solution is simply to put the full local
+ <literal>PATH</literal> to where the <citetitle>User Manual</citetitle> is
+ located:
+ </para>
+<para>
+ <screen> user-manual /usr/share/doc/privoxy/user-manual</screen>
+ </para>
+ <para>
+ The User Manual is then available to anyone with access to the proxy, by
+ following the built-in URL: <literal>http://config.privoxy.org/user-manual/</literal>
+ (or the shortcut: <literal>http://p.p/user-manual/</literal>).
+ </para>
+ <para>
+ If the documentation is not on the local system, it can be accessed
+ from a remote server, as:
+ </para>
+ <para>
+ <screen> user-manual http://example.com/privoxy/user-manual/</screen>
+ </para>
+ <![%user-man;[
+ <!-- this gets hammered in conversion to config. Text repeated below. -->
+ <warning>
+ <para>
+ If set, this option should be <emphasis>the first option in the config
+ file</emphasis>, because it is used while the config file is being read
+ on start-up.
</para>
+ </warning>
+ ]]>
+
+ <![%config-file;[
+ <!-- alternate -->
<para>
- When development goes modular and multi-user, the blocker, filter, and
- per-user config will be stored in subdirectories of <quote>confdir</quote>.
- For now, the configuration directory structure is flat, except for
- <filename>confdir/templates</filename>, where the HTML templates for CGI
- output reside (e.g. <application>Privoxy's</application> 404 error page).
+ WARNING!!!
</para>
- </listitem>
+ <blockquote>
+ <para>
+ If set, this option should be the first option in the config
+ file, because it is used while the config file is being read.
+ </para>
+ </blockquote>
+ ]]>
+
+ </listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@confdir .</literallayout>]]>
+<![%config-file;[<literallayout>@@#user-manual http://www.privoxy.org/user-manual/</literallayout>]]>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="logdir"><title>logdir</title>
+<sect3 renderas="sect4" id="trust-info-url"><title>trust-info-url</title>
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
<para>
- The directory where all logging takes place (i.e. where <filename>logfile</filename> and
- <filename>jarfile</filename> are located)
+ A URL to be displayed in the error page that users will see if access to an untrusted page is denied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type of value:</term>
<listitem>
- <para>Path name</para>
+ <para>URL</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para>/var/log/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
+ <para>Two example URL are provided</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Effect if unset:</term>
<listitem>
- <para><emphasis>Mandatory</emphasis></para>
+ <para>
+ No links are displayed on the "untrusted" error page.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>
- No trailing <quote><literal>/</literal></quote>, please
+ The value of this option only matters if the experimental trust mechanism has been
+ activated. (See <link linkend="trustfile"><emphasis>trustfile</emphasis></link> above.)
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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!
</para>
</listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@logdir .</literallayout>]]>
+<![%config-file;[<literallayout>@@trust-info-url http://www.example.com/why_we_block.html</literallayout>]]>
+<![%config-file;[<literallayout>@@trust-info-url http://www.example.com/what_we_allow.html</literallayout>]]>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="actionsfile"><title>
-actionsfile
-</title>
-<anchor id="default.action">
-<anchor id="standard.action">
-<anchor id="user.action">
-<!-- Note: slightly modified this section 04/28/02, hal. See NOTE. -->
+<sect3 renderas="sect4" id="admin-address"><title>admin-address</title>
+
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
<para>
- The <link linkend="actions-file">actions file(s)</link> to use
+ An email address to reach the proxy administrator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type of value:</term>
<listitem>
- <para>File name, relative to <literal>confdir</literal>, without the <literal>.action</literal> suffix</para>
+ <para>Email address</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Default values:</term>
+ <term>Default value:</term>
<listitem>
- <simplelist>
- <member>
- <msgtext><literallayout> standard # Internal purposes, no editing recommended</literallayout></msgtext>
- </member>
- <member>
- <msgtext><literallayout> default # Main actions file</literallayout></msgtext>
- </member>
- <member>
- <msgtext><literallayout> user # User customizations</literallayout></msgtext>
- </member>
- </simplelist>
+ <para><emphasis>Unset</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Effect if unset:</term>
<listitem>
<para>
- No actions are taken at all. Simple neutral proxying.
+ No email address is displayed on error pages and the CGI user interface.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
- <para>
- Multiple <literal>actionsfile</literal> lines are permitted, and are in fact recommended!
- </para>
- <para>
- The default values include standard.action, which is used for internal
- purposes and should be loaded, default.action, which is the
- <quote>main</quote> actions file maintained by the developers, and
- <filename>user.action</filename>, where you can make your personal additions.
- </para>
- <para>
- Actions files are where all the per site and per URL configuration is done for
- ad blocking, cookie management, privacy considerations, etc.
- There is no point in using <application>Privoxy</application> without at
- least one actions file.
- </para>
+ <para>
+ If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
+ are unset, the whole "Local Privoxy Support" box on all generated pages will
+ not be shown.
+ </para>
</listitem>
</varlistentry>
</variablelist>
-<!-- NOTE: alternate markup to make a simpler list doesn't work due to -->
-<!-- html -> text conversion, blah -->
-<![%config-file;[<literallayout>@@actionsfile standard # Internal purpose, recommended</literallayout>]]>
-<![%config-file;[<literallayout>@@actionsfile default # Main actions file</literallayout>]]>
-<![%config-file;[<literallayout>@@actionsfile user # User customizations</literallayout>]]>
+<![%config-file;[<literallayout>@@#admin-address privoxy-admin@example.com</literallayout>]]>
</sect3>
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="filterfile"><title>filterfile</title>
-<anchor id="default.filter">
+<sect3 renderas="sect4" id="proxy-info-url"><title>proxy-info-url</title>
+
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
<para>
- The <link linkend="filter-file">filter file(s)</link> to use
+ A URL to documentation about the local <application>Privoxy</application> setup,
+ configuration or policies.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type of value:</term>
<listitem>
- <para>File name, relative to <literal>confdir</literal></para>
+ <para>URL</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para>default.filter (Unix) <emphasis>or</emphasis> default.filter.txt (Windows)</para>
+ <para><emphasis>Unset</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Effect if unset:</term>
<listitem>
<para>
- No textual content filtering takes place, i.e. all
- <literal>+<link linkend="filter">filter</link>{<replaceable class="parameter">name</replaceable>}</literal>
- actions in the actions files are turned neutral.
+ No link to local documentation is displayed on error pages and the CGI user interface.
</para>
</listitem>
</varlistentry>
@@ -406,491 +452,438 @@ actionsfile
<term>Notes:</term>
<listitem>
<para>
- Multiple <literal>filterfile</literal> lines are permitted.
- </para>
- <para>
- The <link linkend="filter-file">filter files</link> contain content modification
- rules that use <link linkend="regex">regular expressions</link>. These rules permit
- powerful changes on the content of Web pages, and optionally the headers
- as well, e.g., you could disable your favorite JavaScript annoyances,
- re-write the actual displayed text, or just have some fun
- playing buzzword bingo with web pages.
- </para>
- <para>
- The
- <literal>+<link linkend="filter">filter</link>{<replaceable class="parameter">name</replaceable>}</literal>
- actions rely on the relevant filter (<replaceable class="parameter">name</replaceable>)
- to be defined in a filter file!
- </para>
- <para>
- A pre-defined filter file called <filename>default.filter</filename> that contains
- a number of useful filters for common problems is included in the distribution.
- See the section on the <literal><link linkend="filter">filter</link></literal>
- action for a list.
- </para>
+ If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
+ are unset, the whole "Local Privoxy Support" box on all generated pages will
+ not be shown.
+ </para>
<para>
- It is recommended to place any locally adapted filters into a separate
- file, such as <filename>user.filter</filename>.
- </para>
+ This URL shouldn't be blocked ;-)
+ </para>
</listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@filterfile default.filter</literallayout>]]>
-<![%config-file;[<literallayout>@@#filterfile user.filter # User customizations</literallayout>]]>
+<![%config-file;[<literallayout>@@#proxy-info-url http://www.example.com/proxy-service.html</literallayout>]]>
</sect3>
+</sect2>
+<!-- ~ End section ~ -->
+
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="logfile"><title>logfile</title>
+
+<sect2 id="conf-log-loc">
+<title>Configuration and Log File Locations</title>
+
+<para>
+ <application>Privoxy</application> can (and normally does) use a number of
+ other files for additional configuration, help and logging.
+ This section of the configuration file tells <application>Privoxy</application>
+ where to find those other files.
+</para>
+
+<para>
+ The user running <application>Privoxy</application>, 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.
+</para>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="confdir"><title>confdir</title>
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
- <para>
- The log file to use
- </para>
+ <para>The directory where the other configuration files are located</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type of value:</term>
<listitem>
- <para>File name, relative to <literal>logdir</literal></para>
+ <para>Path name</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para>logfile (Unix) <emphasis>or</emphasis> privoxy.log (Windows)</para>
+ <para>/etc/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Effect if unset:</term>
<listitem>
- <para>
- No log file is used, all log messages go to the console (<literal>STDERR</literal>).
- </para>
+ <para><emphasis>Mandatory</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
- <!--
- removed per bug report 688728 02/20/03 HB
-
- <para>
- The windows version will additionally log to the console.
- </para>
- -->
- <para>
- The logfile is where all logging and error messages are written. The level
- of detail and number of messages are set with the <literal>debug</literal>
- option (see below). The logfile can be useful for tracking down a problem with
- <application>Privoxy</application> (e.g., it's not blocking an ad you
- think it should block) but in most cases you probably will never look at it.
- </para>
- <para>
- 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 <quote>man cron</quote>). For Red Hat, a <command>logrotate</command>
- script has been included.
- </para>
<para>
- On SuSE Linux systems, you can place a line like <quote>/var/log/privoxy.*
- +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
- the effect that cron.daily will automatically archive, gzip, and empty the
- log, when it exceeds 1M size.
+ No trailing <quote><literal>/</literal></quote>, please
</para>
<para>
- Any log files must be writable by whatever user <application>Privoxy</application>
- is being run as (default on UNIX, user id is <quote>privoxy</quote>).
+ When development goes modular and multi-user, the blocker, filter, and
+ per-user config will be stored in subdirectories of <quote>confdir</quote>.
+ For now, the configuration directory structure is flat, except for
+ <filename>confdir/templates</filename>, where the HTML templates for CGI
+ output reside (e.g. <application>Privoxy's</application> 404 error page).
</para>
</listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@logfile logfile</literallayout>]]>
+<![%config-file;[<literallayout>@@confdir .</literallayout>]]>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="jarfile"><title>jarfile</title>
+<sect3 renderas="sect4" id="logdir"><title>logdir</title>
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
<para>
- The file to store intercepted cookies in
+ The directory where all logging takes place (i.e. where <filename>logfile</filename> and
+ <filename>jarfile</filename> are located)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type of value:</term>
<listitem>
- <para>File name, relative to <literal>logdir</literal></para>
+ <para>Path name</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para>Unset (commented out). When activated: jarfile (Unix) <emphasis>or</emphasis> privoxy.jar (Windows)</para>
+ <para>/var/log/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Effect if unset:</term>
<listitem>
- <para>
- Intercepted cookies are not stored in a dedicated log file.
- </para>
+ <para><emphasis>Mandatory</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>
- The jarfile may grow to ridiculous sizes over time.
- </para>
- <para>
- If debug 8 (show header parsing) is enabled, cookies are
- written to the logfile with the rest of the headers.
+ No trailing <quote><literal>/</literal></quote>, please
</para>
</listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@#jarfile jarfile</literallayout>]]>
+<![%config-file;[<literallayout>@@logdir .</literallayout>]]>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="trustfile"><title>trustfile</title>
+<sect3 renderas="sect4" id="actionsfile"><title>
+actionsfile
+</title>
+<anchor id="default.action">
+<anchor id="standard.action">
+<anchor id="user.action">
+<!-- Note: slightly modified this section 04/28/02, hal. See NOTE. -->
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
<para>
- The trust file to use
+ The <link linkend="actions-file">actions file(s)</link> to use
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type of value:</term>
<listitem>
- <para>File name, relative to <literal>confdir</literal></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para><emphasis>Unset (commented out)</emphasis>. When activated: trust (Unix) <emphasis>or</emphasis> trust.txt (Windows)</para>
+ <para>File name, relative to <literal>confdir</literal>, without the <literal>.action</literal> suffix</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Default values:</term>
<listitem>
- <para>
- The entire trust mechanism is turned off.
- </para>
+ <simplelist>
+ <member>
+ <msgtext><literallayout> standard # Internal purposes, no editing recommended</literallayout></msgtext>
+ </member>
+ <member>
+ <msgtext><literallayout> default # Main actions file</literallayout></msgtext>
+ </member>
+ <member>
+ <msgtext><literallayout> user # User customizations</literallayout></msgtext>
+ </member>
+ </simplelist>
</listitem>
</varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- The trust mechanism is an experimental feature for building white-lists and should
- be used with care. It is <emphasis>NOT</emphasis> recommended for the casual user.
- </para>
- <para>
- If you specify a trust file, <application>Privoxy</application> will only allow
- access to sites that are specified in the trustfile. Sites can be listed
- in one of two ways:
- </para>
- <para>
- Prepending a <literal>~</literal> character limits access to this site
- only (and any sub-paths within this site), e.g.
- <literal>~www.example.com</literal>.
- </para>
- <para>
- Or, you can designate sites as <emphasis>trusted referrers</emphasis>, by
- prepending the name with a <literal>+</literal> character. The effect is that
- access to untrusted sites will be granted -- but only if a link from this
- trusted referrer was used. The link target will then be added to the
- <quote>trustfile</quote> 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 <literal>~</literal> designation).
- </para>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
<para>
- If you use the <literal>+</literal> operator in the trust file, it may grow
- considerably over time.
+ No actions are taken at all. Simple neutral proxying.
</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
<para>
- It is recommended that <application>Privoxy</application> be compiled with
- the <literal>--disable-force</literal>, <literal>--disable-toggle</literal> and
- <literal> --disable-editor</literal> options, if this feature is to be
- used.
+ Multiple <literal>actionsfile</literal> lines are permitted, and are in fact recommended!
</para>
- <para>
- Possible applications include limiting Internet access for children.
+ <para>
+ The default values include standard.action, which is used for internal
+ purposes and should be loaded, default.action, which is the
+ <quote>main</quote> actions file maintained by the developers, and
+ <filename>user.action</filename>, where you can make your personal additions.
+ </para>
+ <para>
+ Actions files are where all the per site and per URL configuration is done for
+ ad blocking, cookie management, privacy considerations, etc.
+ There is no point in using <application>Privoxy</application> without at
+ least one actions file.
</para>
-
</listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@#trustfile trust</literallayout>]]>
+<!-- NOTE: alternate markup to make a simpler list doesn't work due to -->
+<!-- html -> text conversion, blah -->
+<![%config-file;[<literallayout>@@actionsfile standard # Internal purpose, recommended</literallayout>]]>
+<![%config-file;[<literallayout>@@actionsfile default # Main actions file</literallayout>]]>
+<![%config-file;[<literallayout>@@actionsfile user # User customizations</literallayout>]]>
</sect3>
-</sect2>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="local-set-up">
-<title>Local Set-up Documentation</title>
-
- <para>
- If you intend to operate <application>Privoxy</application> 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.
- </para>
-
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="user-manual"><title>user-manual</title>
+<sect3 renderas="sect4" id="filterfile"><title>filterfile</title>
+<anchor id="default.filter">
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
<para>
- Location of the <application>Privoxy</application> User Manual.
+ The <link linkend="filter-file">filter file(s)</link> to use
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type of value:</term>
<listitem>
- <para>A fully qualified URI</para>
+ <para>File name, relative to <literal>confdir</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para><emphasis>Unset</emphasis></para>
+ <para>default.filter (Unix) <emphasis>or</emphasis> default.filter.txt (Windows)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Effect if unset:</term>
<listitem>
<para>
- <ulink url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/<replaceable class="parameter">version</replaceable>/user-manual/</ulink>
- will be used, where <replaceable class="parameter">version</replaceable> is the <application>Privoxy</application> version.
+ No textual content filtering takes place, i.e. all
+ <literal>+<link linkend="filter">filter</link>{<replaceable class="parameter">name</replaceable>}</literal>
+ actions in the actions files are turned neutral.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
- <para>
- The User Manual URI 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. For multi-user setups, you could provide a copy on
- a local webserver for all your users and use the corresponding URL here.
+ <para>
+ Multiple <literal>filterfile</literal> lines are permitted.
</para>
<para>
- Examples:
+ The <link linkend="filter-file">filter files</link> contain content modification
+ rules that use <link linkend="regex">regular expressions</link>. These rules permit
+ powerful changes on the content of Web pages, and optionally the headers
+ as well, e.g., you could disable your favorite JavaScript annoyances,
+ re-write the actual displayed text, or just have some fun
+ playing buzzword bingo with web pages.
</para>
- <para>
- Unix, in local filesystem:
- </para>
- <para>
- <screen> user-manual file:///usr/share/doc/privoxy-&p-version;/user-manual/</screen>
- </para>
- <para>
- Windows, in local filesystem, <emphasis>must</emphasis> use forward slash notation:
- </para>
- <para>
- <screen> user-manual file:/c:/some-dir/privoxy-&p-version;/user-manual/</screen>
- </para>
- <para>
- Windows, UNC notation (with forward slashes):
- </para>
- <para>
- <screen> user-manual file://///some-server/some-path/privoxy-&p-version;/user-manual/</screen>
- </para>
- <para>
- Any platform, on local webserver (called <quote>local-webserver</quote>):
- </para>
- <para>
- <screen> user-manual http://local-webserver/privoxy-user-manual/</screen>
- </para>
- <![%user-man;[
- <!-- this gets hammered in conversion to config. Text repeated below. -->
- <warning>
<para>
- If set, this option should be <emphasis>the first option in the config
- file</emphasis>, because it is used while the config file is being read.
+ The
+ <literal>+<link linkend="filter">filter</link>{<replaceable class="parameter">name</replaceable>}</literal>
+ actions rely on the relevant filter (<replaceable class="parameter">name</replaceable>)
+ to be defined in a filter file!
</para>
- </warning>
- ]]>
-
- <![%config-file;[
- <!-- alternate -->
<para>
- WARNING!!!
+ A pre-defined filter file called <filename>default.filter</filename> that contains
+ a number of useful filters for common problems is included in the distribution.
+ See the section on the <literal><link linkend="filter">filter</link></literal>
+ action for a list.
</para>
- <blockquote>
- <para>
- If set, this option should be the first option in the config
- file, because it is used while the config file is being read.
- </para>
- </blockquote>
- ]]>
-
- </listitem>
+ <para>
+ It is recommended to place any locally adapted filters into a separate
+ file, such as <filename>user.filter</filename>.
+ </para>
+ </listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@#user-manual http://www.privoxy.org/user-manual/</literallayout>]]>
+<![%config-file;[<literallayout>@@filterfile default.filter</literallayout>]]>
+<![%config-file;[<literallayout>@@#filterfile user.filter # User customizations</literallayout>]]>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="trust-info-url"><title>trust-info-url</title>
+<sect3 renderas="sect4" id="logfile"><title>logfile</title>
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
<para>
- A URL to be displayed in the error page that users will see if access to an untrusted page is denied.
+ The log file to use
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type of value:</term>
<listitem>
- <para>URL</para>
+ <para>File name, relative to <literal>logdir</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para>Two example URL are provided</para>
+ <para>logfile (Unix) <emphasis>or</emphasis> privoxy.log (Windows)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Effect if unset:</term>
<listitem>
<para>
- No links are displayed on the "untrusted" error page.
+ No log file is used, all log messages go to the console (<literal>STDERR</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
+ <!--
+ removed per bug report 688728 02/20/03 HB
+
<para>
- The value of this option only matters if the experimental trust mechanism has been
- activated. (See <link linkend="trustfile"><emphasis>trustfile</emphasis></link> above.)
+ The windows version will additionally log to the console.
</para>
+ -->
<para>
- 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 logfile is where all logging and error messages are written. The level
+ of detail and number of messages are set with the <literal>debug</literal>
+ option (see below). The logfile can be useful for tracking down a problem with
+ <application>Privoxy</application> (e.g., it's not blocking an ad you
+ think it should block) but in most cases you probably will never look at it.
</para>
<para>
- 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!
+ 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 <quote>man cron</quote>). For Red Hat, a <command>logrotate</command>
+ script has been included.
+ </para>
+ <para>
+ On SuSE Linux systems, you can place a line like <quote>/var/log/privoxy.*
+ +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
+ the effect that cron.daily will automatically archive, gzip, and empty the
+ log, when it exceeds 1M size.
+ </para>
+ <para>
+ Any log files must be writable by whatever user <application>Privoxy</application>
+ is being run as (default on UNIX, user id is <quote>privoxy</quote>).
</para>
</listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@trust-info-url http://www.example.com/why_we_block.html</literallayout>]]>
-<![%config-file;[<literallayout>@@trust-info-url http://www.example.com/what_we_allow.html</literallayout>]]>
+<![%config-file;[<literallayout>@@logfile logfile</literallayout>]]>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="admin-address"><title>admin-address</title>
+<sect3 renderas="sect4" id="jarfile"><title>jarfile</title>
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
<para>
- An email address to reach the proxy administrator.
+ The file to store intercepted cookies in
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type of value:</term>
<listitem>
- <para>Email address</para>
+ <para>File name, relative to <literal>logdir</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para><emphasis>Unset</emphasis></para>
+ <para>Unset (commented out). When activated: jarfile (Unix) <emphasis>or</emphasis> privoxy.jar (Windows)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Effect if unset:</term>
<listitem>
<para>
- No email address is displayed on error pages and the CGI user interface.
+ Intercepted cookies are not stored in a dedicated log file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
- <para>
- If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
- are unset, the whole "Local Privoxy Support" box on all generated pages will
- not be shown.
- </para>
+ <para>
+ The jarfile may grow to ridiculous sizes over time.
+ </para>
+ <para>
+ If debug 8 (show header parsing) is enabled, cookies are
+ written to the logfile with the rest of the headers.
+ </para>
</listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@#admin-address privoxy-admin@example.com</literallayout>]]>
+<![%config-file;[<literallayout>@@#jarfile jarfile</literallayout>]]>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="proxy-info-url"><title>proxy-info-url</title>
-
+<sect3 renderas="sect4" id="trustfile"><title>trustfile</title>
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
<para>
- A URL to documentation about the local <application>Privoxy</application> setup,
- configuration or policies.
+ The trust file to use
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type of value:</term>
<listitem>
- <para>URL</para>
+ <para>File name, relative to <literal>confdir</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para><emphasis>Unset</emphasis></para>
+ <para><emphasis>Unset (commented out)</emphasis>. When activated: trust (Unix) <emphasis>or</emphasis> trust.txt (Windows)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Effect if unset:</term>
<listitem>
<para>
- No link to local documentation is displayed on error pages and the CGI user interface.
+ The entire trust mechanism is turned off.
</para>
</listitem>
</varlistentry>
@@ -898,21 +891,50 @@ actionsfile
<term>Notes:</term>
<listitem>
<para>
- If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
- are unset, the whole "Local Privoxy Support" box on all generated pages will
- not be shown.
- </para>
+ The trust mechanism is an experimental feature for building white-lists and should
+ be used with care. It is <emphasis>NOT</emphasis> recommended for the casual user.
+ </para>
<para>
- This URL shouldn't be blocked ;-)
- </para>
+ If you specify a trust file, <application>Privoxy</application> will only allow
+ access to sites that are specified in the trustfile. Sites can be listed
+ in one of two ways:
+ </para>
+ <para>
+ Prepending a <literal>~</literal> character limits access to this site
+ only (and any sub-paths within this site), e.g.
+ <literal>~www.example.com</literal>.
+ </para>
+ <para>
+ Or, you can designate sites as <emphasis>trusted referrers</emphasis>, by
+ prepending the name with a <literal>+</literal> character. The effect is that
+ access to untrusted sites will be granted -- but only if a link from this
+ trusted referrer was used. The link target will then be added to the
+ <quote>trustfile</quote> 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 <literal>~</literal> designation).
+ </para>
+ <para>
+ If you use the <literal>+</literal> operator in the trust file, it may grow
+ considerably over time.
+ </para>
+ <para>
+ It is recommended that <application>Privoxy</application> be compiled with
+ the <literal>--disable-force</literal>, <literal>--disable-toggle</literal> and
+ <literal> --disable-editor</literal> options, if this feature is to be
+ used.
+ </para>
+ <para>
+ Possible applications include limiting Internet access for children.
+ </para>
+
</listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@#proxy-info-url http://www.example.com/proxy-service.html</literallayout>]]>
+<![%config-file;[<literallayout>@@#trustfile trust</literallayout>]]>
</sect3>
-
</sect2>
+
<!-- ~ End section ~ -->
<!-- ~~~~~ New section ~~~~~ -->