+ <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 local network through <application>Privoxy</application>
+ at all. Of course this may actually be desired and there is no reason
+ to make these exceptions if you aren't sure you need them.
+ </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>
+
+<![%user-man;[ <!-- not included in config due to length -->
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="advanced-forwarding-examples"><title>Advanced Forwarding Examples</title>
+
+<para>
+ If you have links to multiple ISPs that provide various special content
+ only to their subscribers, you can configure multiple <application>Privoxies</application>
+ which have connections to the respective ISPs to act as forwarders to each other, so that
+ <emphasis>your</emphasis> users can see the internal content of all ISPs.
+</para>
+
+<para>
+ Assume that host-a has a PPP connection to isp-a.example.net. And host-b has a PPP connection to
+ isp-b.example.org. Both run <application>Privoxy</application>. Their forwarding
+ configuration can look like this:
+</para>
+
+<para>
+ host-a:
+</para>
+
+<para>
+ <screen>
+ forward / .
+ forward .isp-b.example.net host-b:8118
+</screen>
+</para>
+
+<para>
+ host-b:
+</para>
+
+<para>
+ <screen>
+ forward / .
+ forward .isp-a.example.org host-a:8118
+</screen>
+</para>
+
+<para>
+ Now, your users can set their browser's proxy to use either
+ host-a or host-b and be able to browse the internal content
+ of both isp-a and isp-b.
+</para>
+
+<para>
+ If you intend to chain <application>Privoxy</application> and
+ <application>squid</application> locally, then chaining as
+ <literal>browser -> squid -> privoxy</literal> is the recommended way.
+</para>
+
+<para>
+ Assuming that <application>Privoxy</application> and <application>squid</application>
+ run on the same box, your <application>squid</application> configuration could then look like this:
+</para>
+
+<para>
+ <screen>
+ # Define Privoxy as parent proxy (without ICP)
+ cache_peer 127.0.0.1 parent 8118 7 no-query
+
+ # Define ACL for protocol FTP
+ acl ftp proto FTP
+
+ # Do not forward FTP requests to Privoxy
+ always_direct allow ftp
+
+ # Forward all the rest to Privoxy
+ never_direct allow all</screen>
+</para>
+
+<para>
+ You would then need to change your browser's proxy settings to <application>squid</application>'s address and port.
+ 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 you suspect
+ of leading to 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>
+ Connections forwarded through other proxies 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 <application>Privoxy</application> 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>
+ Note that in the context of this option, <quote>forwarded connections</quote> includes all connections
+ 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 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>
+ </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>
+
+<sect2 id="misc">
+<title>Miscellaneous</title>
+
+<sect3 renderas="sect4" id="accept-intercepted-requests"><title>accept-intercepted-requests</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Whether intercepted requests should be treated as valid.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable>0 or 1</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>
+ Only proxy requests are accepted, intercepted requests are treated as invalid.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ If you don't trust your clients and want to force them
+ to use <application>Privoxy</application>, enable this
+ option and configure your packet filter to redirect outgoing
+ HTTP connections into <application>Privoxy</application>.
+ </para>
+ <para>
+ Note that intercepting encrypted connections (HTTPS) isn't supported.
+ </para>
+ <para>
+ Make sure that <application>Privoxy's</application> own requests
+ aren't redirected as well. Additionally take care that
+ <application>Privoxy</application> can't intentionally connect
+ to itself, otherwise you could run into redirection loops if
+ <application>Privoxy's</application> listening port is reachable
+ by the outside or an attacker has access to the pages you visit.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ accept-intercepted-requests 1
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@accept-intercepted-requests 0</literallayout>]]>
+</sect3>
+
+<sect3 renderas="sect4" id="allow-cgi-request-crunching"><title>allow-cgi-request-crunching</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Whether requests to <application>Privoxy's</application> CGI pages can be blocked or redirected.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable>0 or 1</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>
+ <application>Privoxy</application> ignores block and redirect actions for its CGI pages.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ By default <application>Privoxy</application> ignores block or redirect actions
+ for its CGI pages. Intercepting these requests can be useful in multi-user
+ setups to implement fine-grained access control, but it can also render the complete
+ web interface useless and make debugging problems painful if done without care.
+ </para>
+ <para>
+ Don't enable this option unless you're sure that you really need it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ allow-cgi-request-crunching 1
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@allow-cgi-request-crunching 0</literallayout>]]>
+</sect3>
+
+<sect3 renderas="sect4" id="split-large-forms"><title>split-large-forms</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Whether the CGI interface should stay compatible with broken HTTP clients.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable>0 or 1</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>
+ The CGI form generate long GET URLs.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ <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 length limitations.
+ </para>
+ <para>
+ Enabling split-large-forms causes <application>Privoxy</application>
+ 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.
+ </para>
+ <para>
+ If you don't notice any editing problems, there is no reason
+ to enable this option, but if one of the submit buttons appears
+ to be broken, you should give it a try.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ split-large-forms 1
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@split-large-forms 0</literallayout>]]>
+</sect3>
+
+<sect3 renderas="sect4" id="keep-alive-timeout"><title>keep-alive-timeout</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Number of seconds after which an open connection will no longer be reused.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable>Time in seconds.</replaceable>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>None</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Connections are not kept alive.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This option allows clients to keep the connection to &my-app;
+ alive. If the server supports it, &my-app; will keep
+ the connection to the server alive as well. Under certain
+ circumstances this may result in speed-ups.
+ </para>
+ <para>
+ By default, &my-app; will close the connection to the server if
+ the client connection gets closed, or if the specified timeout
+ has been reached without a new request coming in. This behaviour
+ can be changed with the <ulink
+ url="#CONNECTION-SHARING">connection-sharing</ulink> option.
+ </para>
+ <para>
+ This option has no effect if <application>Privoxy</application>
+ has been compiled without keep-alive support.
+ </para>
+ <para>
+ Note that a timeout of five seconds as used in the default
+ configuration file significantly decreases the number of
+ connections that will be reused. The value is used because
+ some browsers limit the number of connections they open to
+ a single host and apply the same limit to proxies. This can
+ result in a single website <quote>grabbing</quote> all the
+ connections the browser allows, which means connections to
+ other websites can't be opened until the connections currently
+ in use time out.
+ </para>
+ <para>
+ Several users have reported this as a Privoxy bug, so the
+ default value has been reduced. Consider increasing it to
+ 300 seconds or even more if you think your browser can handle
+ it. If your browser appears to be hanging, it probably can't.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ keep-alive-timeout 300
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@keep-alive-timeout 5</literallayout>]]>
+</sect3>
+
+
+<sect3 renderas="sect4" id="tolerate-pipelining"><title>tolerate-pipelining</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Whether or not pipelined requests should be served.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable>0 or 1.</replaceable>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>None</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ If Privoxy receives more than one request at once, it terminates the
+ client connection after serving the first one.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ &my-app; currently doesn't pipeline outgoing requests,
+ thus allowing pipelining on the client connection is not
+ guaranteed to improve the performance.
+ </para>
+ <para>
+ By default &my-app; tries to discourage clients from pipelining
+ by discarding aggressively pipelined requests, which forces the
+ client to resend them through a new connection.
+ </para>
+ <para>
+ This option lets &my-app; tolerate pipelining. Whether or not
+ that improves performance mainly depends on the client configuration.
+ </para>
+ <para>
+ If you are seeing problems with pages not properly loading,
+ disabling this option could work around the problem.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ tolerate-pipelining 1
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@tolerate-pipelining 1</literallayout>]]>
+</sect3>
+
+
+<sect3 renderas="sect4" id="default-server-timeout"><title>default-server-timeout</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Assumed server-side keep-alive timeout if not specified by the server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable>Time in seconds.</replaceable>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>None</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Connections for which the server didn't specify the keep-alive
+ timeout are not reused.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Enabling this option significantly increases the number of connections
+ that are reused, provided the <ulink
+ url="#KEEP-ALIVE-TIMEOUT">keep-alive-timeout</ulink> option
+ is also enabled.
+ </para>
+ <para>
+ While it also increases the number of connections problems
+ when &my-app; tries to reuse a connection that already has
+ been closed on the server side, or is closed while &my-app;
+ is trying to reuse it, this should only be a problem if it
+ happens for the first request sent by the client. If it happens
+ for requests on reused client connections, &my-app; will simply
+ close the connection and the client is supposed to retry the
+ request without bothering the user.
+ </para>
+ <para>
+ Enabling this option is therefore only recommended if the
+ <ulink
+ url="#CONNECTION-SHARING">connection-sharing</ulink> option
+ is disabled.
+ </para>
+ <para>
+ It is an error to specify a value larger than the <ulink
+ url="#KEEP-ALIVE-TIMEOUT">keep-alive-timeout</ulink> value.
+ </para>
+ <para>
+ This option has no effect if <application>Privoxy</application>
+ has been compiled without keep-alive support.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ default-server-timeout 60
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#default-server-timeout 60</literallayout>]]>
+</sect3>
+
+
+<sect3 renderas="sect4" id="connection-sharing"><title>connection-sharing</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Whether or not outgoing connections that have been kept alive
+ should be shared between different incoming connections.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable>0 or 1</replaceable>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>None</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Connections are not shared.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This option has no effect if <application>Privoxy</application>
+ has been compiled without keep-alive support, or if it's disabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Note that reusing connections doesn't necessary cause speedups.
+ There are also a few privacy implications you should be aware of.
+ </para>
+ <para>
+ If this option is effective, outgoing connections are shared between
+ clients (if there are more than one) and closing the browser that initiated
+ the outgoing connection does no longer affect the connection between &my-app;
+ and the server unless the client's request hasn't been completed yet.
+ </para>
+ <para>
+ If the outgoing connection is idle, it will not be closed until either
+ <application>Privoxy's</application> or the server's timeout is reached.
+ While it's open, the server knows that the system running &my-app; is still
+ there.
+ </para>
+ <para>
+ If there are more than one client (maybe even belonging to multiple users),
+ they will be able to reuse each others connections. This is potentially
+ dangerous in case of authentication schemes like NTLM where only the
+ connection is authenticated, instead of requiring authentication for
+ each request.
+ </para>
+ <para>
+ If there is only a single client, and if said client can keep connections
+ alive on its own, enabling this option has next to no effect. If the client
+ doesn't support connection keep-alive, enabling this option may make sense
+ as it allows &my-app; to keep outgoing connections alive even if the client
+ itself doesn't support it.
+ </para>
+ <para>
+ You should also be aware that enabling this option increases the likelihood
+ of getting the "No server or forwarder data" error message, especially if you
+ are using a slow connection to the Internet.
+ </para>
+ <para>
+ This option should only be used by experienced users who
+ understand the risks and can weight them against the benefits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ connection-sharing 1
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#connection-sharing 1</literallayout>]]>
+</sect3>
+
+
+<sect3 renderas="sect4" id="socket-timeout"><title>socket-timeout</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Number of seconds after which a socket times out if
+ no data is received.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable>Time in seconds.</replaceable>