Purpose : Used with other docs and files only.
- $Id: p-config.sgml,v 2.21 2007/11/07 18:50:39 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.29 2008/03/26 18:07:18 fabiankeil Exp $
- Copyright (C) 2001-2007 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2008 Privoxy Developers http://www.privoxy.org/
See LICENSE.
========================================================================
Sample Configuration File for Privoxy v&p-version;
</title>
<para>
- $Id: p-config.sgml,v 2.21 2007/11/07 18:50:39 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.29 2008/03/26 18:07:18 fabiankeil Exp $
</para>
<para>
-Copyright (C) 2001-2007 Privoxy Developers http://www.privoxy.org/
+Copyright (C) 2001-2008 Privoxy Developers http://www.privoxy.org/
</para>
<para>
<term>Effect if unset:</term>
<listitem>
<para>
- Logging is disabled unless <literal>--no-daemon</literal> mode is used.
+ No logfile is written.
</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>
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.
+ 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, <application>Privoxy</application> 3.0.7 and later only log fatal
+ errors by default.
+ </para>
+ <para>
+ For most troubleshooting purposes, you will have to change that,
+ please refer to the debugging section for details.
</para>
<para>
Your logfile will grow indefinitely, and you will probably want to
(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 (on Unix, default user id is <quote>privoxy</quote>).
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@#logfile logfile</literallayout>]]>
+<![%config-file;[<literallayout>@@logfile logfile</literallayout>]]>
</sect3>
<term>Specifies:</term>
<listitem>
<para>
- Key values that determine what information gets logged to the
- <link linkend="logfile"><emphasis>logfile</emphasis></link>.
+ Key values that determine what information gets logged.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para>12289 (i.e.: URLs plus informational and warning messages)</para>
+ <para>0 (i.e.: only fatal errors (that cause Privoxy to exit) are logged)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Effect if unset:</term>
<listitem>
<para>
- Nothing gets logged.
+ Default value is used (see above).
</para>
</listitem>
</varlistentry>
</para>
<para>
<programlisting>
- debug 1 # show each GET/POST/CONNECT request
+ debug 1 # log each request destination (and the crunch reason if &my-app; intercepted the request)
debug 2 # show each connection status
debug 4 # show I/O status
debug 8 # show header parsing
debug 128 # debug redirects
debug 256 # debug GIF de-animation
debug 512 # Common Log Format
- debug 1024 # debug kill pop-ups
+ debug 1024 # Unused
debug 2048 # CGI user interface
debug 4096 # Startup banner and warnings.
debug 8192 # Non-fatal errors
</para>
<para>
A debug level of 1 is informative because it will show you each request
- as it happens. <emphasis>1, 4096 and 8192 are highly recommended</emphasis>
- 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).
+ as it happens. <emphasis>1, 4096 and 8192 are recommended</emphasis>
+ 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).
<!-- LOL -->
</para>
-<!--
<para>
- The reporting of <emphasis>fatal</emphasis> errors (i.e. ones which causes
- <application>Privoxy</application> to exit) is always on and cannot be disabled.
+ &my-app; 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.
+ </para>
+ <para>
+ If you are used to the more verbose settings, simply enable the debug lines
+ below again.
</para>
- It can be disabled by not logging at all (now the default)
- and I doubt that any user would care about not being able
- to disable it anyway.
- fk 2007-11-09
--->
<para>
- If you want to use CLF (Common Log Format), you should set <quote>debug
+ If you want to use pure CLF (Common Log Format), you should set <quote>debug
512</quote> <emphasis>ONLY</emphasis> and not enable anything else.
</para>
<para>
length of log messages. If it's reached, messages are logged truncated
and marked with <quote>... [too long, truncated]</quote>.
</para>
+ <para>
+ 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.
+ </para>
</listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@debug 1 # show each GET/POST/CONNECT request</literallayout>]]>
-<![%config-file;[<literallayout>@@debug 4096 # Startup banner and warnings</literallayout>]]>
-<![%config-file;[<literallayout>@@debug 8192 # Errors - *we highly recommended enabling this*</literallayout>]]>
+<![%config-file;[<literallayout>@@#debug 1 # log each request destination (and the crunch reason if &my-app; intercepted the request)</literallayout>]]>
+<![%config-file;[<literallayout>@@#debug 4096 # Startup banner and warnings</literallayout>]]>
+<![%config-file;[<literallayout>@@#debug 8192 # Non-fatal errors</literallayout>]]>
</sect3>
<![%config-file;[<literallayout>@@#single-threaded</literallayout>]]>
</sect3>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="hostname"><title>hostname</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The hostname shown on the CGI pages.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>Text</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ The hostname provided by the operating system is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ Note that Privoxy does not validate the specified hostname value.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<![%config-file;[<literallayout>@@#hostname hostname.example.org</literallayout>]]>
+</sect3>
+
</sect2>
<!-- ~ End section ~ -->
with untrusted users and as a lot of <application>Privoxy</application>
users don't read documentation, this feature is disabled by default.
</para>
- </para>
<para>
Note that malicious client side code (e.g Java) is also
capable of using the actions editor and you shouldn't enable
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="socks"><title>
-forward-socks4 and forward-socks4a</title>
+forward-socks4, forward-socks4a and forward-socks5</title>
<anchor id="forward-socks4">
<anchor id="forward-socks4a">
<replaceable class="parameter">http_parent</replaceable>[:<replaceable class="parameter">port</replaceable>]
</para>
<para>
- where <replaceable class="parameter">target_pattern</replaceable> is a <link linkend="af-patterns">URL pattern</link>
- that specifies to which requests (i.e. URLs) this forward rule shall apply. Use <literal>/</literal> to
- denote <quote>all URLs</quote>.
- <replaceable class="parameter">http_parent</replaceable> and <replaceable class="parameter">socks_proxy</replaceable>
- are IP addresses in dotted decimal notation or valid DNS names (<replaceable class="parameter">http_parent</replaceable>
+ where <replaceable class="parameter">target_pattern</replaceable> is a
+ <link linkend="af-patterns">URL pattern</link> that specifies to which
+ requests (i.e. URLs) this forward rule shall apply. Use <literal>/</literal> to
+ denote <quote>all URLs</quote>. <replaceable class="parameter">http_parent</replaceable>
+ and <replaceable class="parameter">socks_proxy</replaceable>
+ are IP addresses in dotted decimal notation or valid DNS names
+ (<replaceable class="parameter">http_parent</replaceable>
may be <quote>.</quote> to denote <quote>no HTTP forwarding</quote>), and the optional
- <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer values from 1 to 64535
+ <replaceable class="parameter">port</replaceable> parameters are TCP ports,
+ i.e. integer values from 1 to 65535
</para>
</listitem>
</varlistentry>
is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS
server, while in SOCKS 4 it happens locally.
</para>
+ <para>
+ With <literal>forward-socks5</literal> the DNS resolution will happen on the remote server as well.
+ </para>
<para>
If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
<application>Privoxy's</application> CGI forms can lead to
rather long URLs. This isn't a problem as far as the HTTP
standard is concerned, but it can confuse clients with arbitrary
- URL lenght limitations.
+ URL length limitations.
</para>
<para>
Enabling split-large-forms causes <application>Privoxy</application>
- to devide big forms into smaller ones to keep the URL length down.
+ to divide big forms into smaller ones to keep the URL length down.
It makes editing a lot less convenient and you can no longer
submit all changes at once, but at least it works around this
browser bug.
projects / privoxy.git / blobdiff