From 573c8a27abc6c8df5bfd7ea90b5e4dcbac33151f Mon Sep 17 00:00:00 2001
From: Fabian Keil <fk@fabiankeil.de>
Date: Wed, 7 Nov 2007 18:50:39 +0000
Subject: [PATCH] - Use the name of "the proxy" more often. - Mark some
obsolete features as such. - Split some paragraphs. - Add some more
commentary for the recently disabled features. - Change the Tor instructions
a bit, most importantly fixing the forward line.
---
doc/source/p-config.sgml | 128 +++++++++++++++++++++++++++------------
1 file changed, 89 insertions(+), 39 deletions(-)
diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml
index 53d0629f..b25860fe 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.19 2007/11/04 21:17:31 hal9 Exp $
+ $Id: p-config.sgml,v 2.20 2007/11/07 11:36:53 hal9 Exp $
Copyright (C) 2001-2007 Privoxy Developers http://www.privoxy.org/
See LICENSE.
@@ -95,7 +95,7 @@
Sample Configuration File for Privoxy v&p-version;
</title>
<para>
- $Id: p-config.sgml,v 2.19 2007/11/04 21:17:31 hal9 Exp $
+ $Id: p-config.sgml,v 2.20 2007/11/07 11:36:53 hal9 Exp $
</para>
<para>
Copyright (C) 2001-2007 Privoxy Developers http://www.privoxy.org/
@@ -269,12 +269,13 @@ II. FORMAT OF THE CONFIGURATION FILE
<literal>PATH</literal> to where the <citetitle>User Manual</citetitle> is
located:
</para>
-<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>
+ The User Manual is then available to anyone with access to
+ <application>Privoxy</application>, 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>
@@ -381,7 +382,7 @@ II. FORMAT OF THE CONFIGURATION FILE
<term>Specifies:</term>
<listitem>
<para>
- An email address to reach the proxy administrator.
+ An email address to reach the <application>Privoxy</application> administrator.
</para>
</listitem>
</varlistentry>
@@ -408,7 +409,7 @@ II. FORMAT OF THE CONFIGURATION FILE
<varlistentry>
<term>Notes:</term>
<listitem>
- <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.
@@ -581,8 +582,10 @@ II. FORMAT OF THE CONFIGURATION FILE
<para>
Privoxy's original templates are usually overwritten
with each update. Use this option to relocate customized templates
- that should be kept. Note that you might be missing new features
- if you use outdated templates.
+ that should be kept. Note that template variables might change
+ between updates and templates are not guaranteed to work with
+ <application>Privoxy</application> releases other than the one
+ they were part of.
</para>
</listitem>
</varlistentry>
@@ -715,6 +718,11 @@ actionsfile
<!-- html -> text conversion, blah -->
<![%config-file;[<literallayout>@@actionsfile standard.action # Internal purpose, recommended</literallayout>]]>
<![%config-file;[<literallayout>@@actionsfile default.action # Main actions file</literallayout>]]>
+<!--
+ XXX: Like user.filter, user.action should probably be commented out
+ by default as not all packages install it into the default directory.
+ fk 2007-11-07
+-->
<![%config-file;[<literallayout>@@actionsfile user.action # User customizations</literallayout>]]>
</sect3>
@@ -762,7 +770,7 @@ actionsfile
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,
+ 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.
</para>
@@ -819,7 +827,7 @@ actionsfile
<term>Effect if unset:</term>
<listitem>
<para>
- No log file is used, all log messages go to the console (<literal>STDERR</literal>).
+ Logging is disabled unless <literal>--no-daemon</literal> mode is used.
</para>
</listitem>
</varlistentry>
@@ -838,9 +846,19 @@ actionsfile
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. For this reason, it is disabled by default. For troubleshooting
- purposes, you will have to explicitly enable it.
+ think it should block) and it can help you to monitor what your browser
+ is doing.
+ </para>
+ <para>
+ Many users will never look at it, however, and it's a privacy risk
+ if third parties can get access to it. It is therefore disabled by
+ default in <application>Privoxy</application> 3.0.7 and later.
+ </para>
+ <para>
+ For troubleshooting purposes, you will have to explicitly enable it.
+ Please don't file any support requests without trying to reproduce
+ the problem with logging enabled first. Once you read the log messages,
+ you may even be able to solve the problem on your own.
</para>
<para>
Your logfile will grow indefinitely, and you will probably want to
@@ -848,15 +866,22 @@ actionsfile
(see <quote>man cron</quote>). For Red Hat based Linux distributions, a
<command>logrotate</command> script has been included.
</para>
+<!--
+No one cares enough about SuSE to build privoxy packages,
+so most Privoxy users seem to use different platforms and
+are thus unlikely to care about these instructions.
+It's also questionable if they still work.
+fk 2007-11-07
<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>).
+ is being run as (on Unix, default user id is <quote>privoxy</quote>).
</para>
</listitem>
</varlistentry>
@@ -906,7 +931,10 @@ actionsfile
</para>
<para>
If debug 8 (show header parsing) is enabled, cookies are
- written to the logfile with the rest of the headers.
+ 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.
</para>
</listitem>
</varlistentry>
@@ -1139,7 +1167,7 @@ actionsfile
<term>Notes:</term>
<listitem>
<para>
- This option is only there for debug purposes and you should never
+ This option is only there for debugging purposes and you should never
need to use it. <emphasis>It will drastically reduce performance.</emphasis>
</para>
</listitem>
@@ -1223,7 +1251,6 @@ actionsfile
also want to make sure that the following actions are disabled: <literal><link
linkend="enable-edit-actions">enable-edit-actions</link></literal> and
<literal><link linkend="enable-remote-toggle">enable-remote-toggle</link></literal>
- options!
</para>
</listitem>
</varlistentry>
@@ -1287,11 +1314,16 @@ actionsfile
<para>
If set to 0, <application>Privoxy</application> will start in
<quote>toggled off</quote> mode, i.e. mostly behave like a normal,
- content-neutral proxy where all ad blocking, filtering, etc are disabled. See
- <literal>enable-remote-toggle</literal> below. This is not really useful
+ content-neutral proxy with both ad blocking and content filtering
+ disabled. See <literal>enable-remote-toggle</literal> below.
+<!--
+ This is not really useful
anymore, since toggling is much easier via <ulink
url="http://config.privoxy.org/toggle">the web interface</ulink> than via
editing the <filename>conf</filename> file.
+
+ Remote toggling is now disabled by default. fk 2007-11-07)
+-->
</para>
<para>
The windows version will only display the toggle icon in the system tray
@@ -1342,8 +1374,7 @@ actionsfile
<listitem>
<para>
When toggled off, <application>Privoxy</application> mostly acts like a normal,
- content-neutral proxy, i.e. it acts as if none of the actions applied to
- any URL.
+ content-neutral proxy, i.e. doesn't block ads or filter content.
</para>
<para>
Access to the toggle feature can <emphasis>not</emphasis> be
@@ -1351,11 +1382,15 @@ actionsfile
so that everybody who can access <application>Privoxy</application> (see
<quote>ACLs</quote> and <literal>listen-address</literal> above) can
toggle it for all users. So this option is <emphasis>not recommended</emphasis>
- for multi-user environments with untrusted users. Because of
- the obvious security implications, this feature is off by default.
- Note that malicious client side code (e.g Java) is also potentially
- capable of changing <application>Privoxy's</application> intended
- behavior.
+ for multi-user environments with untrusted users.
+ </para>
+ <para>
+ Note that malicious client side code (e.g Java) is also
+ capable of using this option.
+ </para>
+ <para>
+ As a lot of <application>Privoxy</application> users don't read
+ documentation, this feature has been disabled by default.
</para>
<para>
Note that you must have compiled <application>Privoxy</application> with
@@ -1413,8 +1448,11 @@ actionsfile
This feature is disabled by default. If you are using
<application>Privoxy</application> 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 potentially capable of changing
- <application>Privoxy's</application> intended behavior.
+ side code (e.g Java) is also capable of using this feature.
+ </para>
+ <para>
+ This option may be removed in future releases as it has been obsoleted
+ by the more general header taggers.
</para>
</listitem>
</varlistentry>
@@ -1464,11 +1502,21 @@ actionsfile
controlled separately by <quote>ACLs</quote> or HTTP authentication,
so that everybody who can access <application>Privoxy</application> (see
<quote>ACLs</quote> and <literal>listen-address</literal> above) can
- modify its configuration for all users. This option is <emphasis>not
- recommended</emphasis> for multi-user environments with untrusted users
- and is therefore disabled by default. Note that malicious client side code
- (e.g Java) is also potentially capable of changing
- <application>Privoxy's</application> intended behavior.
+ modify its configuration for all users.
+ </para>
+ <para>
+ This option is <emphasis>not recommended</emphasis> for environments
+ with untrusted users and is therefore disabled by default.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ As a lot of <application>Privoxy</application> users don't read
+ documentation, this feature has been disabled by default.
</para>
<para>
Note that you must have compiled <application>Privoxy</application> with
@@ -1957,13 +2005,14 @@ forward-socks4 and forward-socks4a</title>
</para>
<para>
<screen>
- forward-socks4 / 127.0.0.1:9050 .
+ forward-socks4a / 127.0.0.1:9050 .
</screen>
</para>
<para>
- The public <application>Tor</application> network can't be used to reach your local network,
- therefore it's a good idea to make some exceptions:
+ The public <application>Tor</application> network can't be used to
+ reach your local network, if you need to access local servers you
+ therefore might want to make some exceptions:
</para>
<para>
<screen>
@@ -1975,7 +2024,8 @@ forward-socks4 and forward-socks4a</title>
<para>
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.
+ can't reach the local network through <application>Privoxy</application>
+ at all.
</para>
<para>
If you also want to be able to reach servers in your local network by
@@ -2130,7 +2180,7 @@ forward-socks4 and forward-socks4a</title>
that Privoxy forwards through other proxies. This option is not limited to the HTTP CONNECT method.
</para>
<para>
- Only use this option, if you are getting many forwarding related error messages,
+ Only use this option, if you are getting lots of 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.
</para>
--
2.49.0