Purpose : Used with other docs and files only.
- $Id: p-config.sgml,v 2.2 2002/09/05 05:45:30 hal9 Exp $
+ $Id: p-config.sgml,v 2.8 2006/09/06 02:17:53 hal9 Exp $
- Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
+ Copyright (C) 2001-2006 Privoxy Developers <developers@privoxy.org>
See LICENSE.
========================================================================
Sample Configuration File for Privoxy v&p-version;
</title>
<para>
- $Id: p-config.sgml,v 2.2 2002/09/05 05:45:30 hal9 Exp $
+ $Id: p-config.sgml,v 2.8 2006/09/06 02:17:53 hal9 Exp $
</para>
<para>
-Copyright (C) 2001, 2002 Privoxy Developers http://privoxy.org
+Copyright (C) 2001-2006 Privoxy Developers http://privoxy.org
</para>
<para>
<para>
This file holds the Privoxy configuration. If you modify this
- file, you will need to send a couple of requests to the proxy
+ file, you will need to send a couple of requests (of any kind) to the proxy
before any changes take effect.
</para>
<para>
<term>Specifies:</term>
<listitem>
<para>
- The <link linkend="filter-file">filter file</link> to use
+ The <link linkend="filter-file">filter file(s)</link> to use
</para>
</listitem>
</varlistentry>
<term>Notes:</term>
<listitem>
<para>
- The <link linkend="filter-file">filter file</link> contains content modification
+ 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, e.g., you could disable your favorite
- JavaScript annoyances, re-write the actual displayed text, or just have some
- fun replacing <quote>Microsoft</quote> with <quote>MicroSuck</quote> wherever
- it appears on a Web page.
+ 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 the filter file!
+ to be defined in a filter file!
</para>
<para>
A pre-defined filter file called <filename>default.filter</filename> that contains
- a bunch of handy filters for common problems is included in the distribution.
+ 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>
+ <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>@@filterfile default.filter</literallayout>]]>
+<![%config-file;[<literallayout>@@#filterfile user.filter # User customizations</literallayout>]]>
</sect3>
<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>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para>jarfile (Unix) <emphasis>or</emphasis> privoxy.jar (Windows)</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>
- Intercepted cookies are not stored at all.
+ Intercepted cookies are not stored in a dedicated log file.
</para>
</listitem>
</varlistentry>
<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>@@jarfile jarfile</literallayout>]]>
+<![%config-file;[<literallayout>@@#jarfile jarfile</literallayout>]]>
</sect3>
<term>Effect if unset:</term>
<listitem>
<para>
- The whole trust mechanism is turned off.
+ The entire trust mechanism is turned off.
</para>
</listitem>
</varlistentry>
<para>
Possible applications include limiting Internet access for children.
</para>
+
</listitem>
</varlistentry>
</variablelist>
<para>
Examples:
</para>
- <!-- The below needs checking after a rebuild due to long file names -->
<para>
Unix, in local filesystem:
</para>
<para>
- <screen> user-manual file:///usr/share/doc/privoxy-&p-version;/user-manual/index.html</screen>
+ <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, and <literal>%20</literal> to denote
- spaces in path names:
+ Windows, in local filesystem, <emphasis>must</emphasis> use forward slash notation:
</para>
<para>
- <screen> user-manual file:///c:/some%20dir/privoxy/user-manual/index.html</screen>
+ <screen> user-manual file:/c:/some-dir/privoxy-&p-version;/user-manual/</screen>
</para>
<para>
- Windows, UNC notation (forward slashes required again):
+ Windows, UNC notation (with forward slashes):
</para>
<para>
- <screen> user-manual file://///some-server/some-path/privoxy/user-manual/index.html</screen>
+ <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>
+ <screen> user-manual http://local-webserver/privoxy-user-manual/</screen>
</para>
<![%user-man;[
<!-- this gets hammered in conversion to config. Text repeated below. -->
</sect3>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="enable-remote-http-toggle"><title>enable-remote-http-toggle</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Whether or not Privoxy recognizes special HTTP headers to change its behaviour.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>0 or 1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Privoxy ignores special HTTP headers.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ When toggled on, the client can change <application>Privoxy's</application>
+ behaviour by setting special HTTP headers. Currently the only supported
+ special header is <quote>X-Filter: No</quote>, to disable filtering for
+ the ongoing request, even if it is enabled in one of the action files.
+ </para>
+ <para>
+ If you are using <application>Privoxy</application> 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.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<![%config-file;[<literallayout>@@enable-remote-http-toggle 1</literallayout>]]>
+</sect3>
+
+
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="enable-edit-actions"><title>enable-edit-actions</title>
<variablelist>
forward-socks4 / socks-gw.example.com:1080 .
</screen>
</para>
+
+ <para>
+ To chain Privoxy and Tor, both running on the same system, you should use
+ the rule:
+ </para>
+ <para>
+ <screen>
+ forward-socks4 / 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:
+ </para>
+ <para>
+ <screen>
+ forward 192.168.*.*/ .
+ forward 10.*.*.*/ .
+ forward 127.*.*.*/ .
+</screen>
+ </para>
+ <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.
+ </para>
+ <para>
+ 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:
+ </para>
+ <para>
+ <screen>
+ forward localhost/ .
+</screen>
+ </para>
+
</listitem>
</varlistentry>
</variablelist>
</sect3>
]]>
+<sect3 renderas="sect4" id="forwarded-connect-retries"><title>forwarded-connect-retries</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ How often Privoxy retries if a forwarded connection request fails.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable class="parameter">Number of retries.</replaceable>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>0</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Forwarded connections are treated like direct connections and no retry attempts are made.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ <replaceable class="parameter">forwarded-connect-retries</replaceable> 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ forwarded-connect-retries 1
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@forwarded-connect-retries 0</literallayout>]]>
+</sect3>
+
</sect2>
<!-- ~ End section ~ -->
projects / privoxy.git / blobdiff