X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fp-config.sgml;h=bb831aae7a1c7023df2a7d5cc899beb256a7b350;hb=4ce0ab023d56dc9bc4f1ff161150f9c29002f34a;hp=b2c49b86dd3d16a60faccf820fb55ff911d54177;hpb=46efa6f8fea119c9671cd61aa2e29b2a3f2ad75c;p=privoxy.git

diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml
index b2c49b86..bb831aae 100644
--- a/doc/source/p-config.sgml
+++ b/doc/source/p-config.sgml
@@ -3,9 +3,9 @@
 
  Purpose     :  Used with other docs and files only.
 
- $Id: p-config.sgml,v 2.35 2009/01/13 16:44:32 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.65 2010/10/30 16:09:31 fabiankeil Exp $
 
- Copyright (C) 2001-2009 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2010 Privoxy Developers http://www.privoxy.org/
  See LICENSE.
 
  ========================================================================
@@ -81,7 +81,9 @@
 <para>
  The main config file controls all aspects of <application>Privoxy</application>'s
  operation that are not location dependent (i.e. they apply universally, no matter
- where you may be surfing).
+ where you may be surfing). Like the filter and action files, the config file is
+ a plain text file and can be modified with a text editor like emacs, vim or
+ notepad.exe.
 </para>
 
 ]]>
@@ -95,10 +97,10 @@
  Sample Configuration File for Privoxy v&p-version;
 </title>
 <para>
- $Id: p-config.sgml,v 2.35 2009/01/13 16:44:32 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.65 2010/10/30 16:09:31 fabiankeil Exp $
 </para>
 <para>
-Copyright (C) 2001-2009 Privoxy Developers http://www.privoxy.org/
+Copyright (C) 2001-2010 Privoxy Developers http://www.privoxy.org/
 </para>
 
 <para>
@@ -338,7 +340,7 @@ II. FORMAT OF THE CONFIGURATION FILE
  <varlistentry>
   <term>Default value:</term>
   <listitem>
-   <para>Two example URLs are provided</para>
+   <para><emphasis>Unset</emphasis></para>
   </listitem>
  </varlistentry>
  <varlistentry>
@@ -369,8 +371,8 @@ II. FORMAT OF THE CONFIGURATION FILE
  </varlistentry>
 </variablelist>
 
-<![%config-file;[<literallayout>@@trust-info-url  http://www.example.com/why_we_block.html</literallayout>]]>
-<![%config-file;[<literallayout>@@trust-info-url  http://www.example.com/what_we_allow.html</literallayout>]]>
+<![%config-file;[<literallayout>@@#trust-info-url  http://www.example.com/why_we_block.html</literallayout>]]>
+<![%config-file;[<literallayout>@@#trust-info-url  http://www.example.com/what_we_allow.html</literallayout>]]>
 </sect3>
 
 
@@ -668,10 +670,13 @@ actionsfile
   <listitem>
    <simplelist>
     <member>
-     <msgtext><literallayout>  default.action      # Main actions file</literallayout></msgtext>
+     <msgtext><literallayout>  match-all.action # Actions that are applied to all sites and maybe overruled later on.</literallayout></msgtext>
+    </member>
+    <member>
+     <msgtext><literallayout>  default.action   # Main actions file</literallayout></msgtext>
     </member>
     <member>
-     <msgtext><literallayout>  user.action         # User customizations</literallayout></msgtext>
+     <msgtext><literallayout>  user.action      # User customizations</literallayout></msgtext>
     </member>
    </simplelist>
   </listitem>
@@ -712,6 +717,7 @@ actionsfile
 
 <!-- NOTE: alternate markup to make a simpler list doesn't work due to -->
 <!-- html -> text conversion, blah -->
+<![%config-file;[<literallayout>@@actionsfile match-all.action # Actions that are applied to all sites and maybe overruled later on.</literallayout>]]>
 <![%config-file;[<literallayout>@@actionsfile default.action   # Main actions file</literallayout>]]>
 <!--
  XXX: Like user.filter, user.action should probably be commented out
@@ -790,7 +796,7 @@ actionsfile
 </variablelist>
 
 <![%config-file;[<literallayout>@@filterfile default.filter</literallayout>]]>
-<![%config-file;[<literallayout>@@#filterfile user.filter      # User customizations</literallayout>]]>
+<![%config-file;[<literallayout>@@filterfile user.filter      # User customizations</literallayout>]]>
 </sect3>
 
 
@@ -1003,7 +1009,7 @@ actionsfile
   debug     2 # show each connection status
   debug     4 # show I/O status
   debug     8 # show header parsing
-  debug    16 # log all data written to the network into the logfile
+  debug    16 # log all data written to the network
   debug    32 # debug force feature
   debug    64 # debug regular expression filters
   debug   128 # debug redirects
@@ -1013,6 +1019,7 @@ actionsfile
   debug  2048 # CGI user interface
   debug  4096 # Startup banner and warnings.
   debug  8192 # Non-fatal errors
+  debug 32768 # log all data read from the network
 </programlisting>
    </para>
    <para>
@@ -1021,7 +1028,7 @@ actionsfile
    </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 recommended</emphasis>
+    as it happens. <emphasis>1, 1024, 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).
@@ -1209,9 +1216,9 @@ actionsfile
   <term>Effect if unset:</term>
   <listitem>
    <para>
-    Bind to 127.0.0.1 (localhost), port 8118. This is suitable and recommended for
-    home users who run <application>Privoxy</application> on the same machine as
-    their browser.
+    Bind to 127.0.0.1 (IPv4 localhost), port 8118. This is suitable and
+    recommended for home users who run <application>Privoxy</application> on
+    the same machine as their browser.
    </para>
   </listitem>
  </varlistentry>
@@ -1226,9 +1233,12 @@ actionsfile
     serve requests from other machines (e.g. on your local network) as well, you
     will need to override the default.
    </para>
+   <para>
+    IPv6 addresses containing colons have to be quoted by brackets.
+   </para>
    <para>
     If you leave out the IP address, <application>Privoxy</application> will
-    bind to all interfaces (addresses) on your machine and may become reachable
+    bind to all IPv4 interfaces (addresses) on your machine and may become reachable
     from the Internet. In that case, consider using <link
     linkend="acls">access control lists</link> (ACL's, see below), and/or
     a firewall.
@@ -1253,6 +1263,16 @@ actionsfile
    <para>
     <programlisting>
   listen-address  192.168.0.1:8118
+</programlisting>
+   </para>
+   <para>
+    Suppose you are running <application>Privoxy</application> on an
+    IPv6-capable machine and you want it to listen on the IPv6 address
+    of the loopback device:
+   </para>
+   <para>
+    <programlisting>
+  listen-address [::1]:8118
 </programlisting>
    </para>
   </listitem>
@@ -1607,23 +1627,41 @@ ACLs: permit-access and deny-access</title>
   <term>Type of value:</term>
   <listitem>
    <para>
-    <replaceable class="parameter">src_addr</replaceable>[/<replaceable class="parameter">src_masklen</replaceable>]
-    [<replaceable class="parameter">dst_addr</replaceable>[/<replaceable class="parameter">dst_masklen</replaceable>]]
+    <replaceable class="parameter">src_addr</replaceable>[:<replaceable class="parameter">port</replaceable>][/<replaceable class="parameter">src_masklen</replaceable>]
+    [<replaceable class="parameter">dst_addr</replaceable>[:<replaceable class="parameter">port</replaceable>][/<replaceable class="parameter">dst_masklen</replaceable>]]
    </para>
    <para>
     Where <replaceable class="parameter">src_addr</replaceable> and 
-   <replaceable class="parameter">dst_addr</replaceable> are IP addresses in dotted decimal notation or valid
-    DNS names, and <replaceable class="parameter">src_masklen</replaceable> and
+   <replaceable class="parameter">dst_addr</replaceable> are IPv4 addresses in dotted decimal notation or valid
+    DNS names, <replaceable class="parameter">port</replaceable> is a port
+    number, and <replaceable class="parameter">src_masklen</replaceable> and
     <replaceable class="parameter">dst_masklen</replaceable> are subnet masks in CIDR notation, i.e. integer
     values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole
     destination part are optional.
    </para>
+   <para>
+    If your system implements
+    <ulink url="http://tools.ietf.org/html/rfc3493">RFC 3493</ulink>, then
+    <replaceable class="parameter">src_addr</replaceable> and <replaceable
+    class="parameter">dst_addr</replaceable> can be IPv6 addresses delimeted by
+    brackets, <replaceable class="parameter">port</replaceable> can be a number
+    or a service name, and
+    <replaceable class="parameter">src_masklen</replaceable> and
+    <replaceable class="parameter">dst_masklen</replaceable> can be a number
+    from 0 to 128.
+   </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term>Default value:</term>
   <listitem>
    <para><emphasis>Unset</emphasis></para>
+   <para>
+    If no <replaceable class="parameter">port</replaceable> is specified,
+    any port will match. If no <replaceable class="parameter">src_masklen</replaceable> or
+    <replaceable class="parameter">src_masklen</replaceable> is given, the complete IP
+    address has to match (i.e. 32 bits for IPv4 and 128 bits for IPv6).
+   </para>
   </listitem>
  </varlistentry>
  <varlistentry>
@@ -1672,6 +1710,13 @@ ACLs: permit-access and deny-access</title>
     like <quote>*.org</quote> or partial domain names. If a DNS name resolves to multiple
     IP addresses, only the first one is used.
    </para>
+   <para>
+     Some systems allow IPv4 clients to connect to IPv6 server sockets.
+     Then the client's IPv4 address will be translated by the system into
+     IPv6 address space with special prefix ::ffff:0:0/96 (so called IPv4
+     mapped IPv6 address). <application>Privoxy</application> can handle it
+     and maps such ACL addresses automatically.
+   </para>
    <para>
     Denying access to particular sites by ACL may have undesired side effects
     if the site in question is hosted on a machine which also hosts other sites
@@ -1713,6 +1758,24 @@ ACLs: permit-access and deny-access</title>
   deny-access    192.168.45.73    www.dirty-stuff.example.com
 </screen>
    </para>
+   <para>
+     Allow access from the IPv4 network 192.0.2.0/24 even if listening on
+     an IPv6 wild card address (not supported on all platforms):
+   </para>
+   <para>
+    <programlisting>
+  permit-access  192.0.2.0/24
+</programlisting>
+   </para>
+   <para>
+     This is equivalent to the following line even if listening on an
+     IPv4 address (not supported on all platforms):
+   </para>
+   <para>
+    <programlisting>
+  permit-access  [::ffff:192.0.2.0]/120
+</programlisting>
+   </para>
   </listitem>
  </varlistentry>
 </variablelist>
@@ -1834,7 +1897,7 @@ ACLs: permit-access and deny-access</title>
     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).
+    optionally followed by its listening port (default: 8000).
     Use a single dot (<literal>.</literal>) to denote <quote>no forwarding</quote>.
    </para>
   </listitem>
@@ -1860,6 +1923,16 @@ ACLs: permit-access and deny-access</title>
     If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
     forwarded to another HTTP proxy but are made directly to the web servers.
    </para>
+   <para>
+    <replaceable class="parameter">http_parent</replaceable> can be a
+     numerical IPv6 address (if
+    <ulink url="http://tools.ietf.org/html/rfc3493">RFC 3493</ulink> is
+    implemented). To prevent clashes with the port delimiter, the whole IP
+    address has to be put into brackets. On the other hand a <replaceable
+    class="parameter">target_pattern</replaceable> containing an IPv6 address
+    has to be put into angle brackets (normal brackets are reserved for
+    regular expressions already).
+   </para>
    <para>
     Multiple lines are OK, they are checked in sequence, and the last match wins.
    </para>
@@ -1887,6 +1960,24 @@ ACLs: permit-access and deny-access</title>
   forward   .isp.example.net   .
 </screen>
    </para>
+   <para>
+    Parent proxy specified by an IPv6 address:
+   </para>
+   <para>
+    <programlisting>
+  foward   /                   [2001:DB8::1]:8000
+</programlisting>
+   </para>
+   <para>
+    Suppose your parent proxy doesn't support IPv6:
+   </para>
+   <para>
+    <programlisting>
+  forward  /                        parent-proxy.example.org:8000
+  forward  ipv6-server.example.org  .
+  forward  &lt;[2-3][0-9a-f][0-9a-f][0-9a-f]:*&gt;   .
+</programlisting>
+   </para>
   </listitem>
  </varlistentry>
 </variablelist>
@@ -1958,6 +2049,17 @@ forward-socks4, forward-socks4a and forward-socks5</title>
    <para>
     With <literal>forward-socks5</literal> the DNS resolution will happen on the remote server as well.
    </para>
+   <para>
+    <replaceable class="parameter">socks_proxy</replaceable> and
+    <replaceable class="parameter">http_parent</replaceable> can be a
+     numerical IPv6 address (if
+    <ulink url="http://tools.ietf.org/html/rfc3493">RFC 3493</ulink> is
+    implemented). To prevent clashes with the port delimiter, the whole IP
+    address has to be put into brackets. On the other hand a <replaceable
+    class="parameter">target_pattern</replaceable> containing an IPv6 address
+    has to be put into angle brackets (normal brackets are reserved for
+    regular expressions already).
+   </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
@@ -1995,7 +2097,7 @@ forward-socks4, forward-socks4a and forward-socks5</title>
    </para>
    <para>
     <screen>
-  forward-socks4a   /               127.0.0.1:9050 .
+  forward-socks5   /               127.0.0.1:9050 .
 </screen>
    </para>
 
@@ -2176,6 +2278,10 @@ forward-socks4, forward-socks4a and forward-socks5</title>
     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>
+   <para>
+    Due to a bug, this option currently also causes Privoxy to
+    retry in case of certain problems with direct connections.
+   </para>
   </listitem>
  </varlistentry>
  <varlistentry>
@@ -2190,6 +2296,11 @@ forward-socks4, forward-socks4a and forward-socks5</title>
 <![%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>
@@ -2406,17 +2517,47 @@ forward-socks4, forward-socks4a and forward-socks5</title>
   <term>Effect if unset:</term>
   <listitem>
    <para>
-    Connections are not reused.
+    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 can't.
+   </para>
   </listitem>
  </varlistentry>
  <varlistentry>
@@ -2428,7 +2569,187 @@ forward-socks4, forward-socks4a and forward-socks5</title>
   </listitem>
  </varlistentry>
 </variablelist>
-<![%config-file;[<literallayout>@@keep-alive-timeout 300</literallayout>]]>
+<![%config-file;[<literallayout>@@keep-alive-timeout 5</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>
 
 
@@ -2461,7 +2782,98 @@ forward-socks4, forward-socks4a and forward-socks5</title>
   <term>Effect if unset:</term>
   <listitem>
    <para>
-    A default value of 180 seconds is used.
+    A default value of 300 seconds is used.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    For SOCKS requests the timeout currently doesn't start until
+    the SOCKS server accepted the request. This will be fixed in
+    the next release.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Examples:</term>
+  <listitem>
+   <para>
+    socket-timeout 300
+   </para>
+  </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@socket-timeout 300</literallayout>]]>
+</sect3>
+
+
+<sect3 renderas="sect4" id="max-client-connections"><title>max-client-connections</title>
+<variablelist>
+ <varlistentry>
+  <term>Specifies:</term>
+  <listitem>
+   <para>
+    Maximum number of client connections that will be served.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Type of value:</term>
+  <listitem>
+   <para>
+    <replaceable>Positive number.</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 served until a resource limit is reached.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    &my-app; creates one thread (or process) for every incoming client
+    connection that isn't rejected based on the access control settings.
+   </para>
+   <para>
+    If the system is powerful enough, &my-app; can theoretically deal with
+    several hundred (or thousand) connections at the same time, but some
+    operating systems enforce resource limits by shutting down offending
+    processes and their default limits may be below the ones &my-app; would
+    require under heavy load.
+   </para>
+   <para>
+    Configuring &my-app; to enforce a connection limit below the thread
+    or process limit used by the operating system makes sure this doesn't
+    happen. Simply increasing the operating system's limit would work too,
+    but if &my-app; isn't the only application running on the system,
+    you may actually want to limit the resources used by &my-app;.
+   </para>
+   <para>
+    If &my-app; is only used by a single trusted user, limiting the
+    number of client connections is probably unnecessary. If there
+    are multiple possibly untrusted users you probably still want to
+    additionally use a packet filter to limit the maximal number of
+    incoming connections per client. Otherwise a malicious user could
+    intentionally create a high number of connections to prevent other
+    users from using &my-app;.
+   </para>
+   <para>
+    Obviously using this option only makes sense if you choose a limit
+    below the one enforced by the operating system.
    </para>
   </listitem>
  </varlistentry>
@@ -2469,12 +2881,73 @@ forward-socks4, forward-socks4a and forward-socks5</title>
   <term>Examples:</term>
   <listitem>
    <para>
-    socket-timeout 180
+    max-client-connections 256
+   </para>
+  </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#max-client-connections 256</literallayout>]]>
+</sect3>
+
+
+<sect3 renderas="sect4" id="handle-as-empty-doc-returns-ok"><title>handle-as-empty-doc-returns-ok</title>
+<variablelist>
+ <varlistentry>
+  <term>Note:</term>
+  <listitem>
+   <para>
+    This is a work-around for Firefox bug 492459:
+    <quote>
+    Websites are no longer rendered if SSL requests for JavaScripts are blocked by a proxy.
+    </quote>
+    (<ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=492459"
+	>https://bugzilla.mozilla.org/show_bug.cgi?id=492459</ulink>)
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Specifies:</term>
+  <listitem>
+   <para>
+    The status code Privoxy returns for pages blocked with
+    <!--  URL will only end up in the user manual so the relative link should work. -->
+    <literal><ulink url="actions-file.html#HANDLE-AS-EMPTY-DOCUMENT">+handle-as-empty-document</ulink></literal>.
+   </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>0</para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Effect if unset:</term>
+  <listitem>
+   <para>
+    Privoxy returns a status 403(forbidden) for all blocked pages.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Effect if set:</term>
+  <listitem>
+   <para>
+    Privoxy returns a status 200(OK) for pages blocked with +handle-as-empty-document
+    and a status 403(Forbidden) for all other blocked pages.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
-<![%config-file;[<literallayout>@@socket-timeout 180</literallayout>]]>
+<![%config-file;[<literallayout>@@handle-as-empty-doc-returns-ok 1</literallayout>]]>
 </sect3>