<!--
- File : $Source: /cvsroot/ijbswa/current/doc/source/Attic/p-config.sgml,v $
+ File : $Source: /cvsroot/ijbswa/current/doc/source/p-config.sgml,v $
Purpose : Used with other docs and files only.
- $Id: p-config.sgml,v 1.1 2002/05/31 02:56:25 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>
-Copyright (C) 2001, 2002 Privoxy Developers http://privoxy.org
+ $Id: p-config.sgml,v 2.8 2006/09/06 02:17:53 hal9 Exp $
</para>
<para>
-$Id: p-config.sgml,v 1.1.2.3 2002/05/31 02:56:25 hal9 Exp $
+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>
<para>
If you specify a trust file, <application>Privoxy</application> will only allow
- access to sites that are named in the trustfile.
- You can also mark sites as trusted referrers (with <literal>+</literal>), with
- the effect that access to untrusted sites will be granted, if a link from a
- trusted referrer was used.
- The link target will then be added to the <quote>trustfile</quote>.
- Possible applications include limiting Internet access for children.
+ 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>
- If you use <literal>+</literal> operator in the trust file, it may grow considerably over time.
+ 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>
Unix, in local filesystem:
</para>
<para>
- <screen>user-manual file:///usr/share/doc/privoxy-&p-version;/user-manual/</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:
+ </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>
+ <screen> user-manual http://local-webserver/privoxy-user-manual/</screen>
</para>
<![%user-man;[
<!-- this gets hammered in conversion to config. Text repeated below. -->
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
</programlisting>
<![%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 8192 # Errors - *we highly recommended enabling this*</literallayout>]]>
</sect3>
</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>
<term>Type of value:</term>
<listitem>
<para>
- <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
- <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
+ <replaceable class="parameter">target_pattern</replaceable>
+ <replaceable class="parameter">http_parent</replaceable>[:<replaceable class="parameter">port</replaceable>]
</para>
<para>
- Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
- chapter on domain matching in the <filename>default.action</filename> file),
- <replaceable class="parameter">http_parent</replaceable> is the address of the parent HTTP proxy
- as an IP addresses in dotted decimal notation or as a valid DNS name (or <quote>.</quote> to denote
- <quote>no forwarding</quote>, and the optional
- <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer
- values from 1 to 64535
+ 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>[:<replaceable class="parameter">port</replaceable>]
+ is the DNS name or IP address of the parent HTTP proxy through which the requests should be forwarded,
+ optionally followed by its listening port (default: 8080).
+ Use a single dot (<literal>.</literal>) to denote <quote>no forwarding</quote>.
</para>
</listitem>
</varlistentry>
</para>
<para>
<screen>
- forward .* anon-proxy.example.org:8080
+ forward / anon-proxy.example.org:8080
forward :443 .
</screen>
</para>
</para>
<para>
<screen>
- forward .*. caching-proxy.example-isp.net:8000
+ forward / caching-proxy.example-isp.net:8000
forward .example-isp.net .
</screen>
</para>
<term>Type of value:</term>
<listitem>
<para>
- <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
- <replaceable class="parameter">socks_proxy</replaceable>[/<replaceable class="parameter">port</replaceable>]
- <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
+ <replaceable class="parameter">target_pattern</replaceable>
+ <replaceable class="parameter">socks_proxy</replaceable>[:<replaceable class="parameter">port</replaceable>]
+ <replaceable class="parameter">http_parent</replaceable>[:<replaceable class="parameter">port</replaceable>]
</para>
<para>
- Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
- chapter on domain matching in the <filename>default.action</filename> file),
+ 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
</para>
<para>
<screen>
- forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080
+ forward-socks4a / socks-gw.example.com:1080 www-cache.example-isp.net:8080
forward .example.com .
</screen>
</para>
</para>
<para>
<screen>
- forward-socks4 .*. socks-gw.example.com:1080 .
+ 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>
<para>
<screen>
- forward .*. .
+ forward / .
forward .isp-b.net host-b:8118
</screen>
</para>
<para>
<screen>
- forward .*. .
+ forward / .
forward .isp-a.net host-a:8118
</screen>
</para>
Squid normally uses port 3128. If unsure consult <literal>http_port</literal> in <filename>squid.conf</filename>.
</para>
+<para>
+ You could just as well decide to only forward requests for Windows executables through
+ a virus-scanning parent proxy, say, on <literal>antivir.example.com</literal>, port 8010:
+</para>
+
+<para>
+ <screen>
+ forward / .
+ forward /.*\.(exe|com|dll|zip)$ antivir.example.com:8010</screen>
+</para>
+
</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 ~ -->
<!-- end config content common to both outputs -->
<![%config-file;[
-<!-- These are dummy anchors to keep the processor quiet -->
-<!-- Needed for config-file only -->
+<!-- These are dummy anchors to keep the processor quiet -->
+<!-- when building config-file only (ie. they are used in u-m only) -->
<sect1 label="">
<title></title>
<anchor id="filter">
<anchor id="filter-file">
<anchor id="regex">
<anchor id="actions-file">
+<anchor id="af-patterns">
</sect1>
]]>
projects / privoxy.git / blobdiff