doc/source/p-config.sgml

   1 <!--
   2  File        :  $Source: /cvsroot/ijbswa/current/doc/source/p-config.sgml,v $
   3
   4  Purpose     :  Used with other docs and files only.
   5
   6  $Id: p-config.sgml,v 2.16 2007/06/01 14:14:29 fabiankeil Exp $
   7
   8  Copyright (C) 2001-2007 Privoxy Developers http://www.privoxy.org/
   9  See LICENSE.
  10
  11  ========================================================================
  12  NOTE: Please read developer-manual/documentation.html before touching
  13  anything in this, or other Privoxy documentation.
  14  ========================================================================
  15
  16
  17  This file contains all the config file comments and options. It used to
  18  build both the user-manual config sections, and all of config (yes, the main
  19  config file) itself.
  20
  21  Rationale: This is broken up into two files since a file with a prolog
  22  (DTD, etc) cannot be sourced as a secondary file. config.sgml is basically
  23  a wrapper for this file.
  24
  25  IMPORTANT:
  26
  27  OPTIONS: The actual options are included in this file and prefixed with
  28  '@@', and processed by the Makefile to strip the '@@'. Default options
  29  that should appear commented out should be listed as: '@@#OPTION'.
  30  Otherwise, as '@@OPTION'. Example:
  31
  32   @@listen-address  127.0.0.1:8118
  33
  34  The Makefile does significant other processing too. The final results
  35  should be checked to make sure that the perl processing does not
  36  fubar something!!! Makefile processing requires w3m, fmt (shell line
  37  formatter), and perl.
  38
  39
  40  This file is included into:
  41
  42    user-manual.sgml
  43    config   (the actual Privoxy config file)
  44
  45 -->
  46
  47 <![%user-man;[
  48 <!-- This part only goes into user-manual -->
  49 <sect1 id="config">
  50 <title>The Main Configuration File</title>
  51
  52 <para>
  53  Again, the main configuration file is named <filename>config</filename> on
  54  Linux/Unix/BSD and OS/2, and <filename>config.txt</filename> on Windows.
  55  Configuration lines consist of an initial keyword followed by a list of
  56  values, all separated by whitespace (any number of spaces or tabs). For
  57  example:
  58 </para>
  59
  60 <para>
  61  <literal>
  62   <msgtext>
  63    <literallayout>
  64   <emphasis>confdir /etc/privoxy</emphasis></literallayout>
  65   </msgtext>
  66  </literal>
  67 </para>
  68
  69 <para>
  70  Assigns the value <literal>/etc/privoxy</literal> to the option
  71  <literal>confdir</literal> and thus indicates that the configuration
  72  directory is named <quote>/etc/privoxy/</quote>.
  73 </para>
  74
  75 <para>
  76  All options in the config file except for <literal>confdir</literal> and
  77  <literal>logdir</literal> are optional. Watch out in the below description
  78  for what happens if you leave them unset.
  79 </para>
  80
  81 <para>
  82  The main config file controls all aspects of <application>Privoxy</application>'s
  83  operation that are not location dependent (i.e. they apply universally, no matter
  84  where you may be surfing).
  85 </para>
  86
  87 ]]>
  88
  89
  90 <![%config-file;[
  91 <!-- This part only goes into the config file -->
  92 <sect1 id="config">
  93 <title>
  94  @@TITLE<!-- between the @@ is stripped by Makefile -->@@
  95  Sample Configuration File for Privoxy v&p-version;
  96 </title>
  97 <para>
  98  $Id: p-config.sgml,v 2.16 2007/06/01 14:14:29 fabiankeil Exp $
  99 </para>
 100 <para>
 101 Copyright (C) 2001-2007 Privoxy Developers http://www.privoxy.org/
 102 </para>
 103
 104 <para>
 105  <literallayout>
 106 #################################################################
 107                                                                 #
 108                     Table of Contents                           #
 109                                                                 #
 110       I. INTRODUCTION                                           #
 111      II. FORMAT OF THE CONFIGURATION FILE                       #
 112                                                                 #
 113       1. LOCAL SET-UP DOCUMENTATION                             #
 114       2. CONFIGURATION AND LOG FILE LOCATIONS                   #
 115       3. DEBUGGING                                              #
 116       4. ACCESS CONTROL AND SECURITY                            #
 117       5. FORWARDING                                             #
 118       6. WINDOWS GUI OPTIONS                                    #
 119                                                                 #
 120 #################################################################
 121  </literallayout>
 122 </para>
 123
 124 <literallayout>I. INTRODUCTION
 125  ===============  <!-- fuck this madness --></literallayout>
 126
 127 <para>
 128  This file holds Privoxy's main configuration.  Privoxy detects
 129  configuration changes automatically, so you don't have to restart it
 130  unless you want to load a different configuration file.
 131 </para>
 132 <para>
 133  The configuration will be reloaded with the first request after the
 134  change was done, this request itself will still use the old configuration,
 135  though. In other words: it takes two requests before you see the result of
 136  your changes. Requests that are dropped due to ACL don't trigger reloads.
 137 </para>
 138 <para>
 139  When starting Privoxy on Unix systems, give the location of this
 140  file as last argument.  On Windows systems, Privoxy will look for
 141  this file with the name 'config.txt' in the current working directory
 142  of the Privoxy process.
 143 </para>
 144
 145 <para>
 146  <literallayout><!-- funky spacing -->
 147
 148 II. FORMAT OF THE CONFIGURATION FILE
 149 ====================================</literallayout>
 150 </para>
 151 <para>
 152  Configuration lines consist of an initial keyword followed by a list
 153  of values, all separated by whitespace (any number of spaces or
 154  tabs).  For example,
 155 </para>
 156 <para>
 157  actionsfile default.action
 158 </para>
 159 <para>
 160  Indicates that the actionsfile is named 'default.action'.
 161 </para>
 162 <para>
 163  The '#' indicates a comment.  Any part of a line following a '#' is
 164  ignored, except if the '#' is preceded by a '\'.
 165 </para>
 166 <para>
 167  Thus, by placing a # at the start of an existing configuration line,
 168  you can make it a comment and it will be treated as if it weren't there.
 169  This is called "commenting out" an option and can be useful. Removing
 170  the # again is called "uncommenting".
 171 </para>
 172 <para>
 173  Note that commenting out an option and leaving it at its default
 174  are two completely different things! Most options behave very
 175  differently when unset. See the the "Effect if unset" explanation
 176  in each option's description for details.
 177 </para>
 178 <para>
 179  Long lines can be continued on the next line by using a `\' as
 180  the last character.
 181 </para>
 182
 183 ]]>
 184
 185 <!-- ************************************************ -->
 186 <!-- The following is common to both outputs (mostly) -->
 187 <!-- ************************************************ -->
 188
 189
 190
 191 <!--   ~~~~~       New section      ~~~~~     -->
 192 <sect2 id="local-set-up">
 193 <title>Local Set-up Documentation</title>
 194
 195   <para>
 196     If you intend to operate <application>Privoxy</application> for more users
 197     than just yourself, it might be a good idea to let them know how to reach
 198     you, what you block and why you do that, your policies, etc.
 199    </para>
 200
 201
 202 <!--   ~~~~~       New section      ~~~~~     -->
 203 <sect3 renderas="sect4" id="user-manual"><title>user-manual</title>
 204 <variablelist>
 205  <varlistentry>
 206   <term>Specifies:</term>
 207   <listitem>
 208    <para>
 209     Location of the <application>Privoxy</application> User Manual.
 210    </para>
 211   </listitem>
 212  </varlistentry>
 213  <varlistentry>
 214   <term>Type of value:</term>
 215   <listitem>
 216    <para>A fully qualified URI</para>
 217   </listitem>
 218  </varlistentry>
 219  <varlistentry>
 220   <term>Default value:</term>
 221   <listitem>
 222    <para><emphasis>Unset</emphasis></para>
 223   </listitem>
 224  </varlistentry>
 225  <varlistentry>
 226   <term>Effect if unset:</term>
 227   <listitem>
 228    <para>
 229     <ulink url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/<replaceable class="parameter">version</replaceable>/user-manual/</ulink>
 230     will be used, where <replaceable class="parameter">version</replaceable> is the <application>Privoxy</application> version.
 231    </para>
 232   </listitem>
 233  </varlistentry>
 234  <varlistentry>
 235   <term>Notes:</term>
 236   <listitem>
 237     <para>
 238     The User Manual URI is the single best source of information on
 239     <application>Privoxy</application>, and is used for help links from some
 240     of the internal CGI pages. The manual itself is normally packaged with the
 241     binary distributions, so you probably want to set this to a locally
 242     installed copy.
 243    </para>
 244    <para>
 245     Examples:
 246    </para>
 247   <!--
 248   <para>
 249    Unix, in local filesystem (may not work with all browsers):
 250   </para>
 251   <para>
 252    <screen>&nbsp;&nbsp;user-manual&nbsp;&nbsp;file:///usr/share/doc/privoxy-&p-version;/user-manual/</screen>
 253   </para>
 254   <para>
 255    Windows, in local filesystem, <emphasis>must</emphasis> use forward slash notation:
 256   </para>
 257   <para>
 258    <screen>&nbsp;&nbsp;user-manual&nbsp;&nbsp;file:/c:/some-dir/privoxy-&p-version;/user-manual/</screen>
 259   </para>
 260   <para>
 261    Windows, UNC notation (with forward slashes):
 262   </para>
 263   <para>
 264    <screen>&nbsp;&nbsp;user-manual&nbsp;&nbsp;file://///some-server/some-path/privoxy-&p-version;/user-manual/</screen>
 265   </para>
 266  -->
 267   <para>
 268    The best all purpose solution is simply to put the full local
 269    <literal>PATH</literal> to where the <citetitle>User Manual</citetitle> is
 270    located:
 271   </para>
 272 <para>
 273    <screen>&nbsp;&nbsp;user-manual&nbsp;&nbsp;/usr/share/doc/privoxy/user-manual</screen>
 274   </para>
 275   <para>
 276    The User Manual is then available to anyone with access to the proxy, by
 277    following the built-in URL: <literal>http://config.privoxy.org/user-manual/</literal>
 278    (or the shortcut: <literal>http://p.p/user-manual/</literal>).
 279   </para>
 280   <para>
 281    If the documentation is not on the local system, it can be accessed
 282    from a remote server, as:
 283   </para>
 284   <para>
 285    <screen>&nbsp;&nbsp;user-manual&nbsp;&nbsp;http://example.com/privoxy/user-manual/</screen>
 286   </para>
 287   <![%user-man;[
 288    <!-- this gets hammered in conversion to config. Text repeated below. -->
 289   <warning>
 290    <para>
 291      If set, this option should be <emphasis>the first option in the config
 292      file</emphasis>, because it is used while the config file is being read
 293      on start-up.
 294    </para>
 295   </warning>
 296   ]]>
 297
 298   <![%config-file;[
 299    <!-- alternate -->
 300    <para>
 301     WARNING!!!
 302    </para>
 303    <blockquote>
 304     <para>
 305      If set, this option should be the first option in the config
 306      file, because it is used while the config file is being read.
 307     </para>
 308    </blockquote>
 309   ]]>
 310
 311  </listitem>
 312  </varlistentry>
 313 </variablelist>
 314
 315 <![%config-file;[<literallayout>@@#user-manual http://www.privoxy.org/user-manual/</literallayout>]]>
 316 </sect3>
 317
 318
 319 <!--   ~~~~~       New section      ~~~~~     -->
 320 <sect3 renderas="sect4" id="trust-info-url"><title>trust-info-url</title>
 321
 322 <variablelist>
 323  <varlistentry>
 324   <term>Specifies:</term>
 325   <listitem>
 326    <para>
 327     A URL to be displayed in the error page that users will see if access to an untrusted page is denied.
 328    </para>
 329   </listitem>
 330  </varlistentry>
 331  <varlistentry>
 332   <term>Type of value:</term>
 333   <listitem>
 334    <para>URL</para>
 335   </listitem>
 336  </varlistentry>
 337  <varlistentry>
 338   <term>Default value:</term>
 339   <listitem>
 340    <para>Two example URL are provided</para>
 341   </listitem>
 342  </varlistentry>
 343  <varlistentry>
 344   <term>Effect if unset:</term>
 345   <listitem>
 346    <para>
 347     No links are displayed on the "untrusted" error page.
 348    </para>
 349   </listitem>
 350  </varlistentry>
 351  <varlistentry>
 352   <term>Notes:</term>
 353   <listitem>
 354    <para>
 355     The value of this option only matters if the experimental trust mechanism has been
 356     activated. (See <link linkend="trustfile"><emphasis>trustfile</emphasis></link> above.)
 357    </para>
 358    <para>
 359     If you use the trust mechanism, it is a good idea to write up some on-line
 360     documentation about your trust policy and to specify the URL(s) here.
 361     Use multiple times for multiple URLs.
 362    </para>
 363    <para>
 364     The URL(s) should be added to the trustfile as well, so users don't end up
 365     locked out from the information on why they were locked out in the first place!
 366    </para>
 367   </listitem>
 368  </varlistentry>
 369 </variablelist>
 370
 371 <![%config-file;[<literallayout>@@trust-info-url  http://www.example.com/why_we_block.html</literallayout>]]>
 372 <![%config-file;[<literallayout>@@trust-info-url  http://www.example.com/what_we_allow.html</literallayout>]]>
 373 </sect3>
 374
 375
 376 <!--   ~~~~~       New section      ~~~~~     -->
 377 <sect3 renderas="sect4" id="admin-address"><title>admin-address</title>
 378
 379 <variablelist>
 380  <varlistentry>
 381   <term>Specifies:</term>
 382   <listitem>
 383    <para>
 384     An email address to reach the proxy administrator.
 385    </para>
 386   </listitem>
 387  </varlistentry>
 388  <varlistentry>
 389   <term>Type of value:</term>
 390   <listitem>
 391    <para>Email address</para>
 392   </listitem>
 393  </varlistentry>
 394  <varlistentry>
 395   <term>Default value:</term>
 396   <listitem>
 397    <para><emphasis>Unset</emphasis></para>
 398   </listitem>
 399  </varlistentry>
 400  <varlistentry>
 401   <term>Effect if unset:</term>
 402   <listitem>
 403    <para>
 404     No email address is displayed on error pages and the CGI user interface.
 405    </para>
 406   </listitem>
 407  </varlistentry>
 408  <varlistentry>
 409   <term>Notes:</term>
 410   <listitem>
 411     <para>
 412     If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
 413     are unset, the whole "Local Privoxy Support" box on all generated pages will
 414     not be shown.
 415    </para>
 416   </listitem>
 417  </varlistentry>
 418 </variablelist>
 419
 420 <![%config-file;[<literallayout>@@#admin-address privoxy-admin@example.com</literallayout>]]>
 421 </sect3>
 422
 423
 424 <!--   ~~~~~       New section      ~~~~~     -->
 425 <sect3 renderas="sect4" id="proxy-info-url"><title>proxy-info-url</title>
 426
 427 <variablelist>
 428  <varlistentry>
 429   <term>Specifies:</term>
 430   <listitem>
 431    <para>
 432     A URL to documentation about the local <application>Privoxy</application> setup,
 433     configuration or policies.
 434    </para>
 435   </listitem>
 436  </varlistentry>
 437  <varlistentry>
 438   <term>Type of value:</term>
 439   <listitem>
 440    <para>URL</para>
 441   </listitem>
 442  </varlistentry>
 443  <varlistentry>
 444   <term>Default value:</term>
 445   <listitem>
 446    <para><emphasis>Unset</emphasis></para>
 447   </listitem>
 448  </varlistentry>
 449  <varlistentry>
 450   <term>Effect if unset:</term>
 451   <listitem>
 452    <para>
 453     No link to local documentation is displayed on error pages and the CGI user interface.
 454    </para>
 455   </listitem>
 456  </varlistentry>
 457  <varlistentry>
 458   <term>Notes:</term>
 459   <listitem>
 460    <para>
 461     If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
 462     are unset, the whole "Local Privoxy Support" box on all generated pages will
 463     not be shown.
 464    </para>
 465    <para>
 466     This URL shouldn't be blocked ;-)
 467    </para>
 468   </listitem>
 469  </varlistentry>
 470 </variablelist>
 471
 472 <![%config-file;[<literallayout>@@#proxy-info-url http://www.example.com/proxy-service.html</literallayout>]]>
 473 </sect3>
 474
 475 </sect2>
 476 <!--  ~  End section  ~  -->
 477
 478
 479
 480 <!--   ~~~~~       New section      ~~~~~     -->
 481
 482 <sect2 id="conf-log-loc">
 483 <title>Configuration and Log File Locations</title>
 484
 485 <para>
 486  <application>Privoxy</application> can (and normally does) use a number of
 487  other files for additional configuration, help and logging.
 488  This section of the configuration file tells <application>Privoxy</application>
 489  where to find those other files.
 490 </para>
 491
 492 <para>
 493  The user running <application>Privoxy</application>, must have read
 494  permission for all configuration files, and write permission to any files
 495  that would be modified, such as log files and actions files.
 496 </para>
 497
 498
 499 <!--   ~~~~~       New section      ~~~~~     -->
 500 <sect3 renderas="sect4" id="confdir"><title>confdir</title>
 501
 502 <variablelist>
 503  <varlistentry>
 504   <term>Specifies:</term>
 505   <listitem>
 506    <para>The directory where the other configuration files are located</para>
 507   </listitem>
 508  </varlistentry>
 509  <varlistentry>
 510   <term>Type of value:</term>
 511   <listitem>
 512    <para>Path name</para>
 513   </listitem>
 514  </varlistentry>
 515  <varlistentry>
 516   <term>Default value:</term>
 517   <listitem>
 518    <para>/etc/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
 519   </listitem>
 520  </varlistentry>
 521  <varlistentry>
 522   <term>Effect if unset:</term>
 523   <listitem>
 524    <para><emphasis>Mandatory</emphasis></para>
 525   </listitem>
 526  </varlistentry>
 527  <varlistentry>
 528   <term>Notes:</term>
 529   <listitem>
 530    <para>
 531     No trailing <quote><literal>/</literal></quote>, please
 532    </para>
 533   <!--
 534    This is really outdated and not likely to happen. HB 09/20/06
 535    <para>
 536     When development goes modular and multi-user, the blocker, filter, and
 537     per-user config will be stored in subdirectories of <quote>confdir</quote>.
 538     For now, the configuration directory structure is flat, except for
 539     <filename>confdir/templates</filename>, where the HTML templates for CGI
 540     output reside (e.g. <application>Privoxy's</application> 404 error page).
 541    </para>
 542   -->
 543   </listitem>
 544  </varlistentry>
 545 </variablelist>
 546
 547 <![%config-file;[<literallayout>@@confdir .</literallayout>]]>
 548 </sect3>
 549
 550 <!--   ~~~~~       New section      ~~~~~     -->
 551 <sect3 renderas="sect4" id="templdir"><title>templdir</title>
 552
 553 <variablelist>
 554  <varlistentry>
 555   <term>Specifies:</term>
 556   <listitem>
 557    <para>An alternative directory where the templates are loaded from</para>
 558   </listitem>
 559  </varlistentry>
 560  <varlistentry>
 561   <term>Type of value:</term>
 562   <listitem>
 563    <para>Path name</para>
 564   </listitem>
 565  </varlistentry>
 566  <varlistentry>
 567   <term>Default value:</term>
 568   <listitem>
 569    <para>unset</para>
 570   </listitem>
 571  </varlistentry>
 572  <varlistentry>
 573   <term>Effect if unset:</term>
 574   <listitem>
 575    <para>The templates are assumed to be located in confdir/template.</para>
 576   </listitem>
 577  </varlistentry>
 578  <varlistentry>
 579   <term>Notes:</term>
 580   <listitem>
 581    <para>
 582     Privoxy's original templates are usually overwritten
 583     with each update. Use this option to relocate customized templates
 584     that should be kept. Note that you might be missing new features
 585     if you use outdated templates.
 586    </para>
 587   </listitem>
 588  </varlistentry>
 589 </variablelist>
 590
 591 <![%config-file;[<literallayout>@@#templdir .</literallayout>]]>
 592 </sect3>
 593
 594
 595 <!--   ~~~~~       New section      ~~~~~     -->
 596 <sect3 renderas="sect4" id="logdir"><title>logdir</title>
 597
 598 <variablelist>
 599  <varlistentry>
 600   <term>Specifies:</term>
 601   <listitem>
 602    <para>
 603     The directory where all logging takes place (i.e. where <filename>logfile</filename> and
 604     <filename>jarfile</filename> are located)
 605    </para>
 606   </listitem>
 607  </varlistentry>
 608  <varlistentry>
 609   <term>Type of value:</term>
 610   <listitem>
 611    <para>Path name</para>
 612   </listitem>
 613  </varlistentry>
 614  <varlistentry>
 615   <term>Default value:</term>
 616   <listitem>
 617    <para>/var/log/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
 618   </listitem>
 619  </varlistentry>
 620  <varlistentry>
 621   <term>Effect if unset:</term>
 622   <listitem>
 623    <para><emphasis>Mandatory</emphasis></para>
 624   </listitem>
 625  </varlistentry>
 626  <varlistentry>
 627   <term>Notes:</term>
 628   <listitem>
 629    <para>
 630     No trailing <quote><literal>/</literal></quote>, please
 631    </para>
 632   </listitem>
 633  </varlistentry>
 634 </variablelist>
 635
 636 <![%config-file;[<literallayout>@@logdir .</literallayout>]]>
 637 </sect3>
 638
 639
 640 <!--   ~~~~~       New section      ~~~~~     -->
 641 <sect3 renderas="sect4" id="actionsfile"><title>
 642 actionsfile
 643 </title>
 644 <anchor id="default.action">
 645 <anchor id="standard.action">
 646 <anchor id="user.action">
 647 <!-- Note: slightly modified this section 04/28/02, hal. See NOTE. -->
 648 <variablelist>
 649  <varlistentry>
 650   <term>Specifies:</term>
 651   <listitem>
 652    <para>
 653     The <link linkend="actions-file">actions file(s)</link> to use
 654    </para>
 655   </listitem>
 656  </varlistentry>
 657  <varlistentry>
 658   <term>Type of value:</term>
 659   <listitem>
 660    <para>Complete file name, relative to <literal>confdir</literal></para>
 661   </listitem>
 662  </varlistentry>
 663  <varlistentry>
 664   <term>Default values:</term>
 665   <listitem>
 666    <simplelist>
 667     <member>
 668      <msgtext><literallayout>  standard.action     # Internal purposes, no editing recommended</literallayout></msgtext>
 669     </member>
 670     <member>
 671      <msgtext><literallayout>  default.action      # Main actions file</literallayout></msgtext>
 672     </member>
 673     <member>
 674      <msgtext><literallayout>  user.action         # User customizations</literallayout></msgtext>
 675     </member>
 676    </simplelist>
 677   </listitem>
 678  </varlistentry>
 679  <varlistentry>
 680   <term>Effect if unset:</term>
 681   <listitem>
 682    <para>
 683     No actions are taken at all. More or less neutral proxying.
 684    </para>
 685   </listitem>
 686  </varlistentry>
 687  <varlistentry>
 688   <term>Notes:</term>
 689   <listitem>
 690    <para>
 691     Multiple <literal>actionsfile</literal> lines are permitted, and are in fact recommended!
 692    </para>
 693    <para>
 694     The default values include standard.action, which is used for internal
 695     purposes and should be loaded, default.action, which is the
 696     <quote>main</quote> actions file maintained by the developers, and
 697     <filename>user.action</filename>, where you can make your personal additions.
 698    </para>
 699    <para>
 700     Actions files are where all the per site and per URL configuration is done for
 701     ad blocking, cookie management, privacy considerations, etc.
 702     There is no point in using <application>Privoxy</application> without at
 703     least one actions file.
 704    </para>
 705    <para>
 706     Note that since Privoxy 3.0.7, the complete filename, including the <quote>.action</quote>
 707     extension has to be specified.  The syntax change was necessary to be consistent
 708     with the other file options and to allow previously forbidden characters.
 709    </para>
 710   </listitem>
 711  </varlistentry>
 712 </variablelist>
 713
 714 <!-- NOTE: alternate markup to make a simpler list doesn't work due to -->
 715 <!-- html -> text conversion, blah -->
 716 <![%config-file;[<literallayout>@@actionsfile standard.action  # Internal purpose, recommended</literallayout>]]>
 717 <![%config-file;[<literallayout>@@actionsfile default.action   # Main actions file</literallayout>]]>
 718 <![%config-file;[<literallayout>@@actionsfile user.action      # User customizations</literallayout>]]>
 719 </sect3>
 720
 721 <!--   ~~~~~       New section      ~~~~~     -->
 722 <sect3 renderas="sect4" id="filterfile"><title>filterfile</title>
 723 <anchor id="default.filter">
 724 <variablelist>
 725  <varlistentry>
 726   <term>Specifies:</term>
 727   <listitem>
 728    <para>
 729     The <link linkend="filter-file">filter file(s)</link> to use
 730    </para>
 731   </listitem>
 732  </varlistentry>
 733  <varlistentry>
 734   <term>Type of value:</term>
 735   <listitem>
 736    <para>File name, relative to <literal>confdir</literal></para>
 737   </listitem>
 738  </varlistentry>
 739  <varlistentry>
 740   <term>Default value:</term>
 741   <listitem>
 742    <para>default.filter (Unix) <emphasis>or</emphasis> default.filter.txt (Windows)</para>
 743   </listitem>
 744  </varlistentry>
 745  <varlistentry>
 746   <term>Effect if unset:</term>
 747   <listitem>
 748    <para>
 749     No textual content filtering takes place, i.e. all
 750     <literal>+<link linkend="filter">filter</link>{<replaceable class="parameter">name</replaceable>}</literal>
 751     actions in the actions files are turned neutral.
 752    </para>
 753   </listitem>
 754  </varlistentry>
 755  <varlistentry>
 756   <term>Notes:</term>
 757   <listitem>
 758    <para>
 759     Multiple <literal>filterfile</literal> lines are permitted.
 760    </para>
 761    <para>
 762     The <link linkend="filter-file">filter files</link> contain content modification
 763     rules that use <link linkend="regex">regular expressions</link>. These rules permit
 764     powerful changes on the content of Web pages, and optionally the headers
 765     as well, e.g., you could disable your favorite JavaScript annoyances,
 766     re-write the actual displayed text, or just have some fun
 767     playing buzzword bingo with web pages.
 768    </para>
 769    <para>
 770     The
 771     <literal>+<link linkend="filter">filter</link>{<replaceable class="parameter">name</replaceable>}</literal>
 772     actions rely on the relevant filter (<replaceable class="parameter">name</replaceable>)
 773     to be defined in a filter file!
 774    </para>
 775    <para>
 776     A pre-defined filter file called <filename>default.filter</filename> that contains
 777     a number of useful filters for common problems is included in the distribution.
 778     See the section on the <literal><link linkend="filter">filter</link></literal>
 779     action for a list.
 780    </para>
 781    <para>
 782     It is recommended to place any locally adapted filters into a separate
 783     file, such as <filename>user.filter</filename>.
 784    </para>
 785   </listitem>
 786  </varlistentry>
 787 </variablelist>
 788
 789 <![%config-file;[<literallayout>@@filterfile default.filter</literallayout>]]>
 790 <![%config-file;[<literallayout>@@#filterfile user.filter      # User customizations</literallayout>]]>
 791 </sect3>
 792
 793
 794 <!--   ~~~~~       New section      ~~~~~     -->
 795 <sect3 renderas="sect4" id="logfile"><title>logfile</title>
 796
 797 <variablelist>
 798  <varlistentry>
 799   <term>Specifies:</term>
 800   <listitem>
 801    <para>
 802     The log file to use
 803    </para>
 804   </listitem>
 805  </varlistentry>
 806  <varlistentry>
 807   <term>Type of value:</term>
 808   <listitem>
 809    <para>File name, relative to <literal>logdir</literal></para>
 810   </listitem>
 811  </varlistentry>
 812  <varlistentry>
 813   <term>Default value:</term>
 814   <listitem>
 815    <para>logfile (Unix) <emphasis>or</emphasis> privoxy.log (Windows)</para>
 816   </listitem>
 817  </varlistentry>
 818  <varlistentry>
 819   <term>Effect if unset:</term>
 820   <listitem>
 821    <para>
 822     No log file is used, all log messages go to the console (<literal>STDERR</literal>).
 823    </para>
 824   </listitem>
 825  </varlistentry>
 826  <varlistentry>
 827   <term>Notes:</term>
 828   <listitem>
 829  <!--
 830   removed per bug report 688728 02/20/03 HB
 831
 832    <para>
 833     The windows version will additionally log to the console.
 834    </para>
 835   -->
 836    <para>
 837     The logfile is where all logging and error messages are written. The level
 838     of detail and number of messages are set with the <literal>debug</literal>
 839     option (see below). The logfile can be useful for tracking down a problem with
 840     <application>Privoxy</application> (e.g., it's not blocking an ad you
 841     think it should block) but in most cases you probably will never look at it.
 842    </para>
 843    <para>
 844     Your logfile will grow indefinitely, and you will probably want to
 845     periodically remove it.  On Unix systems, you can do this with a cron job
 846     (see <quote>man cron</quote>). For Red Hat, a <command>logrotate</command>
 847     script has been included.
 848    </para>
 849    <para>
 850     On SuSE Linux systems, you can place a line like <quote>/var/log/privoxy.*
 851     +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
 852     the effect that cron.daily will automatically archive, gzip, and empty the
 853     log, when it exceeds 1M size.
 854    </para>
 855    <para>
 856     Any log files must be writable by whatever user <application>Privoxy</application>
 857     is being run as (default on UNIX, user id is <quote>privoxy</quote>).
 858    </para>
 859   </listitem>
 860  </varlistentry>
 861 </variablelist>
 862
 863 <![%config-file;[<literallayout>@@logfile logfile</literallayout>]]>
 864 </sect3>
 865
 866
 867 <!--   ~~~~~       New section      ~~~~~     -->
 868 <sect3 renderas="sect4" id="jarfile"><title>jarfile</title>
 869
 870 <variablelist>
 871  <varlistentry>
 872   <term>Specifies:</term>
 873   <listitem>
 874    <para>
 875     The file to store intercepted cookies in
 876    </para>
 877   </listitem>
 878  </varlistentry>
 879  <varlistentry>
 880   <term>Type of value:</term>
 881   <listitem>
 882    <para>File name, relative to <literal>logdir</literal></para>
 883   </listitem>
 884  </varlistentry>
 885  <varlistentry>
 886   <term>Default value:</term>
 887   <listitem>
 888    <para>Unset (commented out). When activated: jarfile (Unix) <emphasis>or</emphasis> privoxy.jar (Windows)</para>
 889   </listitem>
 890  </varlistentry>
 891  <varlistentry>
 892   <term>Effect if unset:</term>
 893   <listitem>
 894    <para>
 895     Intercepted cookies are not stored in a dedicated log file.
 896    </para>
 897   </listitem>
 898  </varlistentry>
 899  <varlistentry>
 900   <term>Notes:</term>
 901   <listitem>
 902    <para>
 903     The jarfile may grow to ridiculous sizes over time.
 904    </para>
 905    <para>
 906     If debug 8 (show header parsing) is enabled, cookies are
 907     written to the logfile with the rest of the headers.
 908    </para>
 909   </listitem>
 910  </varlistentry>
 911 </variablelist>
 912
 913 <![%config-file;[<literallayout>@@#jarfile jarfile</literallayout>]]>
 914 </sect3>
 915
 916
 917 <!--   ~~~~~       New section      ~~~~~     -->
 918 <sect3 renderas="sect4" id="trustfile"><title>trustfile</title>
 919 <variablelist>
 920  <varlistentry>
 921   <term>Specifies:</term>
 922   <listitem>
 923    <para>
 924     The name of the trust file to use
 925    </para>
 926   </listitem>
 927  </varlistentry>
 928  <varlistentry>
 929   <term>Type of value:</term>
 930   <listitem>
 931    <para>File name, relative to <literal>confdir</literal></para>
 932   </listitem>
 933  </varlistentry>
 934  <varlistentry>
 935   <term>Default value:</term>
 936   <listitem>
 937    <para><emphasis>Unset (commented out)</emphasis>. When activated: trust (Unix) <emphasis>or</emphasis> trust.txt (Windows)</para>
 938   </listitem>
 939  </varlistentry>
 940  <varlistentry>
 941   <term>Effect if unset:</term>
 942   <listitem>
 943    <para>
 944     The entire trust mechanism is disabled.
 945    </para>
 946   </listitem>
 947  </varlistentry>
 948  <varlistentry>
 949   <term>Notes:</term>
 950   <listitem>
 951    <para>
 952     The trust mechanism is an experimental feature for building white-lists and should
 953     be used with care. It is <emphasis>NOT</emphasis> recommended for the casual user.
 954    </para>
 955    <para>
 956     If you specify a trust file, <application>Privoxy</application> will only allow
 957     access to sites that are specified in the trustfile. Sites can be listed
 958     in one of two ways:
 959    </para>
 960    <para>
 961     Prepending a <literal>~</literal> character limits access to this site
 962     only (and any sub-paths within this site), e.g.
 963     <literal>~www.example.com</literal> allows access to
 964     <literal>~www.example.com/features/news.html</literal>, etc.
 965    </para>
 966    <para>
 967     Or, you can designate sites as <emphasis>trusted referrers</emphasis>, by
 968     prepending the name with a <literal>+</literal> character. The effect is that
 969     access to untrusted sites will be granted -- but only if a link from this
 970     trusted referrer was used to get there. The link target will then be added
 971     to the <quote>trustfile</quote> so that future, direct accesses will be
 972     granted. Sites added via this mechanism do not become trusted referrers
 973     themselves (i.e. they are added with a <literal>~</literal> designation).
 974     There is a limit of 512 such entries, after which new entries will not be
 975     made.
 976    </para>
 977    <para>
 978     If you use the <literal>+</literal> operator in the trust file, it may grow
 979     considerably over time.
 980    </para>
 981    <para>
 982     It is recommended that <application>Privoxy</application> be compiled with
 983     the <literal>--disable-force</literal>, <literal>--disable-toggle</literal> and
 984     <literal> --disable-editor</literal> options, if this feature is to be
 985     used.
 986    </para>
 987    <para>
 988     Possible applications include limiting Internet access for children.
 989    </para>
 990
 991   </listitem>
 992  </varlistentry>
 993 </variablelist>
 994
 995 <![%config-file;[<literallayout>@@#trustfile trust</literallayout>]]>
 996 </sect3>
 997 </sect2>
 998
 999 <!--  ~  End section  ~  -->
1000
1001 <!--   ~~~~~       New section      ~~~~~     -->
1002 <sect2 id="debugging">
1003 <title>Debugging</title>
1004
1005  <para>
1006   These options are mainly useful when tracing a problem.
1007   Note that you might also want to invoke
1008   <application>Privoxy</application> with the <literal>--no-daemon</literal>
1009   command line option when debugging.
1010  </para>
1011
1012 <sect3 renderas="sect4" id="debug"><title>debug</title>
1013
1014 <variablelist>
1015  <varlistentry>
1016   <term>Specifies:</term>
1017   <listitem>
1018    <para>
1019     Key values that determine what information gets logged to the
1020     <link linkend="logfile"><emphasis>logfile</emphasis></link>.
1021    </para>
1022   </listitem>
1023  </varlistentry>
1024  <varlistentry>
1025   <term>Type of value:</term>
1026   <listitem>
1027    <para>Integer values</para>
1028   </listitem>
1029  </varlistentry>
1030  <varlistentry>
1031   <term>Default value:</term>
1032   <listitem>
1033    <para>12289 (i.e.: URLs plus informational and warning messages)</para>
1034   </listitem>
1035  </varlistentry>
1036  <varlistentry>
1037   <term>Effect if unset:</term>
1038   <listitem>
1039    <para>
1040     Nothing gets logged.
1041    </para>
1042   </listitem>
1043  </varlistentry>
1044  <varlistentry>
1045   <term>Notes:</term>
1046   <listitem>
1047    <para>
1048     The available debug levels are:
1049    </para>
1050    <para>
1051     <programlisting>
1052   debug         1 # show each GET/POST/CONNECT request
1053   debug         2 # show each connection status
1054   debug         4 # show I/O status
1055   debug         8 # show header parsing
1056   debug        16 # log all data written to the network into the logfile
1057   debug        32 # debug force feature
1058   debug        64 # debug regular expression filters
1059   debug       128 # debug redirects
1060   debug       256 # debug GIF de-animation
1061   debug       512 # Common Log Format
1062   debug      1024 # debug kill pop-ups
1063   debug      2048 # CGI user interface
1064   debug      4096 # Startup banner and warnings.
1065   debug      8192 # Non-fatal errors
1066 </programlisting>
1067    </para>
1068    <para>
1069     To select multiple debug levels, you can either add them or use
1070     multiple <literal>debug</literal> lines.
1071    </para>
1072    <para>
1073     A debug level of 1 is informative because it will show you each request
1074     as it happens. <emphasis>1, 4096 and 8192 are highly recommended</emphasis>
1075     so that you will notice when things go wrong. The other levels are probably
1076     only of interest if you are hunting down a specific problem. They can produce
1077     a hell of an output (especially 16).
1078     <!-- LOL -->
1079    </para>
1080    <para>
1081     The reporting of <emphasis>fatal</emphasis> errors (i.e. ones which causes
1082     <application>Privoxy</application> to exit) is always on and cannot be disabled.
1083    </para>
1084    <para>
1085     If you want to use CLF (Common Log Format), you should set <quote>debug
1086     512</quote> <emphasis>ONLY</emphasis> and not enable anything else.
1087    </para>
1088    <para>
1089     <application>Privoxy</application> has a hard-coded limit for the
1090     length of log messages. If it's reached, messages are logged truncated
1091     and marked with <quote>... [too long, truncated]</quote>.
1092    </para>
1093   </listitem>
1094  </varlistentry>
1095 </variablelist>
1096
1097 <![%config-file;[<literallayout>@@debug   1    # show each GET/POST/CONNECT request</literallayout>]]>
1098 <![%config-file;[<literallayout>@@debug   4096 # Startup banner and warnings</literallayout>]]>
1099 <![%config-file;[<literallayout>@@debug   8192 # Errors - *we highly recommended enabling this*</literallayout>]]>
1100 </sect3>
1101
1102
1103 <!--   ~~~~~       New section      ~~~~~     -->
1104 <sect3 renderas="sect4" id="single-threaded"><title>single-threaded</title>
1105
1106 <variablelist>
1107  <varlistentry>
1108   <term>Specifies:</term>
1109   <listitem>
1110    <para>
1111     Whether to run only one server thread
1112    </para>
1113   </listitem>
1114  </varlistentry>
1115  <varlistentry>
1116   <term>Type of value:</term>
1117   <listitem>
1118    <para><emphasis>None</emphasis></para>
1119   </listitem>
1120  </varlistentry>
1121  <varlistentry>
1122   <term>Default value:</term>
1123   <listitem>
1124    <para><emphasis>Unset</emphasis></para>
1125   </listitem>
1126  </varlistentry>
1127  <varlistentry>
1128   <term>Effect if unset:</term>
1129   <listitem>
1130    <para>
1131     Multi-threaded (or, where unavailable: forked) operation, i.e. the ability to
1132     serve multiple requests simultaneously.
1133    </para>
1134   </listitem>
1135  </varlistentry>
1136  <varlistentry>
1137   <term>Notes:</term>
1138   <listitem>
1139    <para>
1140     This option is only there for debug purposes and you should never
1141     need to use it. <emphasis>It will drastically reduce performance.</emphasis>
1142    </para>
1143   </listitem>
1144  </varlistentry>
1145 </variablelist>
1146
1147 <![%config-file;[<literallayout>@@#single-threaded</literallayout>]]>
1148 </sect3>
1149
1150 </sect2>
1151
1152 <!--  ~  End section  ~  -->
1153
1154
1155 <!--   ~~~~~       New section      ~~~~~     -->
1156 <sect2 id="access-control">
1157 <title>Access Control and Security</title>
1158
1159  <para>
1160   This section of the config file controls the security-relevant aspects
1161   of <application>Privoxy</application>'s configuration.
1162  </para>
1163
1164
1165 <!--   ~~~~~       New section      ~~~~~     -->
1166 <sect3 renderas="sect4" id="listen-address"><title>listen-address</title>
1167
1168 <variablelist>
1169  <varlistentry>
1170   <term>Specifies:</term>
1171   <listitem>
1172    <para>
1173     The IP address and TCP port on which <application>Privoxy</application> will
1174     listen for client requests.
1175    </para>
1176   </listitem>
1177  </varlistentry>
1178  <varlistentry>
1179   <term>Type of value:</term>
1180   <listitem>
1181    <para>[<replaceable class="parameter">IP-Address</replaceable>]:<replaceable class="parameter">Port</replaceable></para>
1182   </listitem>
1183  </varlistentry>
1184
1185  <varlistentry>
1186   <term>Default value:</term>
1187   <listitem>
1188    <para>127.0.0.1:8118</para>
1189   </listitem>
1190  </varlistentry>
1191  <varlistentry>
1192   <term>Effect if unset:</term>
1193   <listitem>
1194    <para>
1195     Bind to 127.0.0.1 (localhost), port 8118. This is suitable and recommended for
1196     home users who run <application>Privoxy</application> on the same machine as
1197     their browser.
1198    </para>
1199   </listitem>
1200  </varlistentry>
1201  <varlistentry>
1202   <term>Notes:</term>
1203   <listitem>
1204    <para>
1205     You will need to configure your browser(s) to this proxy address and port.
1206    </para>
1207    <para>
1208     If you already have another service running on port 8118, or if you want to
1209     serve requests from other machines (e.g. on your local network) as well, you
1210     will need to override the default.
1211    </para>
1212    <para>
1213     If you leave out the IP address, <application>Privoxy</application> will
1214     bind to all interfaces (addresses) on your machine and may become reachable
1215     from the Internet. In that case, consider using <link
1216     linkend="acls">access control lists</link> (ACL's, see below), and/or
1217     a firewall.
1218    </para>
1219    <para>
1220     If you open <application>Privoxy</application> to untrusted users, you will
1221     also want to turn off the <literal><link
1222     linkend="enable-edit-actions">enable-edit-actions</link></literal> and
1223     <literal><link linkend="enable-remote-toggle">enable-remote-toggle</link></literal>
1224     options!
1225    </para>
1226   </listitem>
1227  </varlistentry>
1228  <varlistentry>
1229   <term>Example:</term>
1230   <listitem>
1231    <para>
1232      Suppose you are running <application>Privoxy</application> on
1233      a machine which has the address 192.168.0.1 on your local private network
1234      (192.168.0.0) and has another outside connection with a different address.
1235      You want it to serve requests from inside only:
1236    </para>
1237    <para>
1238     <programlisting>
1239   listen-address  192.168.0.1:8118
1240 </programlisting>
1241    </para>
1242   </listitem>
1243  </varlistentry>
1244 </variablelist>
1245
1246 <![%config-file;[<literallayout>@@listen-address  127.0.0.1:8118</literallayout>]]>
1247 </sect3>
1248
1249
1250 <!--   ~~~~~       New section      ~~~~~     -->
1251 <sect3 renderas="sect4" id="toggle"><title>toggle</title>
1252
1253 <variablelist>
1254  <varlistentry>
1255   <term>Specifies:</term>
1256   <listitem>
1257    <para>
1258     Initial state of "toggle" status
1259    </para>
1260   </listitem>
1261  </varlistentry>
1262  <varlistentry>
1263   <term>Type of value:</term>
1264   <listitem>
1265    <para>1 or 0</para>
1266   </listitem>
1267  </varlistentry>
1268  <varlistentry>
1269   <term>Default value:</term>
1270   <listitem>
1271    <para>1</para>
1272   </listitem>
1273  </varlistentry>
1274  <varlistentry>
1275   <term>Effect if unset:</term>
1276   <listitem>
1277    <para>
1278     Act as if toggled on
1279    </para>
1280   </listitem>
1281  </varlistentry>
1282  <varlistentry>
1283   <term>Notes:</term>
1284   <listitem>
1285    <para>
1286     If set to 0, <application>Privoxy</application> will start in
1287     <quote>toggled off</quote> mode, i.e. mostly behave like a normal,
1288     content-neutral proxy where all ad blocking, filtering, etc are disabled. See
1289     <literal>enable-remote-toggle</literal> below. This is not really useful
1290     anymore, since toggling is much easier via <ulink
1291     url="http://config.privoxy.org/toggle">the web interface</ulink> than via
1292     editing the <filename>conf</filename> file.
1293    </para>
1294    <para>
1295     The windows version will only display the toggle icon in the system tray
1296     if this option is present.
1297    </para>
1298   </listitem>
1299  </varlistentry>
1300 </variablelist>
1301
1302 <![%config-file;[<literallayout>@@toggle  1</literallayout>]]>
1303 </sect3>
1304
1305
1306 <!--   ~~~~~       New section      ~~~~~     -->
1307 <sect3 renderas="sect4" id="enable-remote-toggle"><title>enable-remote-toggle</title>
1308 <variablelist>
1309  <varlistentry>
1310   <term>Specifies:</term>
1311   <listitem>
1312    <para>
1313     Whether or not the <ulink url="http://config.privoxy.org/toggle">web-based toggle
1314     feature</ulink> may be used
1315    </para>
1316   </listitem>
1317  </varlistentry>
1318  <varlistentry>
1319   <term>Type of value:</term>
1320   <listitem>
1321    <para>0 or 1</para>
1322   </listitem>
1323  </varlistentry>
1324  <varlistentry>
1325   <term>Default value:</term>
1326   <listitem>
1327    <para>1</para>
1328   </listitem>
1329  </varlistentry>
1330  <varlistentry>
1331   <term>Effect if unset:</term>
1332   <listitem>
1333    <para>
1334     The web-based toggle feature is disabled.
1335    </para>
1336   </listitem>
1337  </varlistentry>
1338  <varlistentry>
1339   <term>Notes:</term>
1340   <listitem>
1341    <para>
1342     When toggled off, <application>Privoxy</application> mostly acts like a normal,
1343     content-neutral proxy, i.e. it acts as if none of the actions applied to
1344     any URL.
1345    </para>
1346    <para>
1347     For the time being, access to the toggle feature can <emphasis>not</emphasis> be
1348     controlled separately by <quote>ACLs</quote> or HTTP authentication,
1349     so that everybody who can access <application>Privoxy</application> (see
1350     <quote>ACLs</quote> and <literal>listen-address</literal> above) can
1351     toggle it for all users. So this option is <emphasis>not recommended</emphasis>
1352     for multi-user environments with untrusted users.
1353    </para>
1354    <para>
1355     Note that you must have compiled <application>Privoxy</application> with
1356     support for this feature, otherwise this option has no effect.
1357    </para>
1358   </listitem>
1359  </varlistentry>
1360 </variablelist>
1361
1362 <![%config-file;[<literallayout>@@enable-remote-toggle  1</literallayout>]]>
1363 </sect3>
1364
1365
1366 <!--   ~~~~~       New section      ~~~~~     -->
1367 <sect3 renderas="sect4" id="enable-remote-http-toggle"><title>enable-remote-http-toggle</title>
1368 <variablelist>
1369  <varlistentry>
1370   <term>Specifies:</term>
1371   <listitem>
1372    <para>
1373     Whether or not Privoxy recognizes special HTTP headers to change its behaviour.
1374    </para>
1375   </listitem>
1376  </varlistentry>
1377  <varlistentry>
1378   <term>Type of value:</term>
1379   <listitem>
1380    <para>0 or 1</para>
1381   </listitem>
1382  </varlistentry>
1383  <varlistentry>
1384   <term>Default value:</term>
1385   <listitem>
1386    <para>1</para>
1387   </listitem>
1388  </varlistentry>
1389  <varlistentry>
1390   <term>Effect if unset:</term>
1391   <listitem>
1392    <para>
1393     Privoxy ignores special HTTP headers.
1394    </para>
1395   </listitem>
1396  </varlistentry>
1397  <varlistentry>
1398   <term>Notes:</term>
1399   <listitem>
1400    <para>
1401     When toggled on, the client can change <application>Privoxy's</application>
1402     behaviour by setting special HTTP headers. Currently the only supported
1403     special header is <quote>X-Filter: No</quote>, to disable filtering for
1404     the ongoing request, even if it is enabled in one of the action files.
1405    </para>
1406    <para>
1407     If you are using <application>Privoxy</application> in a
1408     multi-user environment or with untrustworthy clients and want to
1409     enforce filtering, you will have to disable this option,
1410     otherwise you can ignore it.
1411    </para>
1412   </listitem>
1413  </varlistentry>
1414 </variablelist>
1415
1416 <![%config-file;[<literallayout>@@enable-remote-http-toggle  1</literallayout>]]>
1417 </sect3>
1418
1419
1420 <!--   ~~~~~       New section      ~~~~~     -->
1421 <sect3 renderas="sect4" id="enable-edit-actions"><title>enable-edit-actions</title>
1422 <variablelist>
1423  <varlistentry>
1424   <term>Specifies:</term>
1425   <listitem>
1426    <para>
1427     Whether or not the <ulink url="http://config.privoxy.org/show-status">web-based actions
1428     file editor</ulink> may be used
1429    </para>
1430   </listitem>
1431  </varlistentry>
1432  <varlistentry>
1433   <term>Type of value:</term>
1434   <listitem>
1435    <para>0 or 1</para>
1436   </listitem>
1437  </varlistentry>
1438  <varlistentry>
1439   <term>Default value:</term>
1440   <listitem>
1441    <para>1</para>
1442   </listitem>
1443  </varlistentry>
1444  <varlistentry>
1445   <term>Effect if unset:</term>
1446   <listitem>
1447    <para>
1448     The web-based actions file editor is disabled.
1449    </para>
1450   </listitem>
1451  </varlistentry>
1452  <varlistentry>
1453   <term>Notes:</term>
1454   <listitem>
1455    <para>
1456     For the time being, access to the editor can <emphasis>not</emphasis> be
1457     controlled separately by <quote>ACLs</quote> or HTTP authentication,
1458     so that everybody who can access <application>Privoxy</application> (see
1459     <quote>ACLs</quote> and <literal>listen-address</literal> above) can
1460     modify its configuration for all users. So this option is <emphasis>not
1461     recommended</emphasis> for multi-user environments with untrusted users.
1462    </para>
1463    <para>
1464     Note that you must have compiled <application>Privoxy</application> with
1465     support for this feature, otherwise this option has no effect.
1466    </para>
1467   </listitem>
1468  </varlistentry>
1469 </variablelist>
1470
1471 <![%config-file;[<literallayout>@@enable-edit-actions 1</literallayout>]]>
1472 </sect3>
1473
1474
1475 <sect3 renderas="sect4" id="enforce-blocks"><title>enforce-blocks</title>
1476 <variablelist>
1477  <varlistentry>
1478   <term>Specifies:</term>
1479   <listitem>
1480    <para>
1481     Whether the user is allowed to ignore blocks and can <quote>go there anyway</quote>.
1482    </para>
1483   </listitem>
1484  </varlistentry>
1485  <varlistentry>
1486   <term>Type of value:</term>
1487   <listitem>
1488    <para>
1489     <replaceable>0 or 1</replaceable>
1490    </para>
1491   </listitem>
1492  </varlistentry>
1493  <varlistentry>
1494   <term>Default value:</term>
1495   <listitem>
1496    <para><emphasis>0</emphasis></para>
1497   </listitem>
1498  </varlistentry>
1499  <varlistentry>
1500   <term>Effect if unset:</term>
1501   <listitem>
1502    <para>
1503     Blocks are not enforced.
1504    </para>
1505   </listitem>
1506  </varlistentry>
1507  <varlistentry>
1508   <term>Notes:</term>
1509   <listitem>
1510    <para>
1511     <application>Privoxy</application> is mainly used to block and filter
1512     requests as a service to the user, for example to block ads and other
1513     junk that clogs the pipes. <application>Privoxy's</application> configuration
1514     isn't perfect and sometimes innocent pages are blocked. In this situation it
1515     makes sense to allow the user to enforce the request and have
1516     <application>Privoxy</application> ignore the block.
1517    </para>
1518    <para>
1519     In the default configuration <application>Privoxy's</application>
1520     <quote>Blocked</quote> page contains a <quote>go there anyway</quote>
1521     link to adds a special string (the force prefix) to the request URL.
1522     If that link is used, <application>Privoxy</application> will
1523     detect the force prefix, remove it again and let the request pass.
1524    </para>
1525    <para>
1526     Of course <application>Privoxy</application> can also be used to enforce
1527     a network policy. In that case the user obviously should not be able to
1528     bypass any blocks, and that's what the <quote>enforce-blocks</quote>
1529     option is for. If it's enabled, <application>Privoxy</application> hides
1530     the <quote>go there anyway</quote> link. If the user adds the force
1531     prefix by hand, it will not be accepted and the circumvention attempt
1532     is logged.
1533    </para>
1534   </listitem>
1535  </varlistentry>
1536  <varlistentry>
1537   <term>Examples:</term>
1538   <listitem>
1539    <para>
1540     enforce-blocks 1
1541    </para>
1542   </listitem>
1543  </varlistentry>
1544 </variablelist>
1545 <![%config-file;[<literallayout>@@enforce-blocks 0</literallayout>]]>
1546 </sect3>
1547
1548
1549 <!--   ~~~~~       New section      ~~~~~     -->
1550 <sect3 renderas="sect4" id="acls"><title>
1551 ACLs: permit-access and deny-access</title>
1552 <anchor id="permit-access">
1553 <anchor id="deny-access">
1554
1555 <variablelist>
1556  <varlistentry>
1557   <term>Specifies:</term>
1558   <listitem>
1559    <para>
1560     Who can access what.
1561    </para>
1562   </listitem>
1563  </varlistentry>
1564  <varlistentry>
1565   <term>Type of value:</term>
1566   <listitem>
1567    <para>
1568     <replaceable class="parameter">src_addr</replaceable>[/<replaceable class="parameter">src_masklen</replaceable>]
1569     [<replaceable class="parameter">dst_addr</replaceable>[/<replaceable class="parameter">dst_masklen</replaceable>]]
1570    </para>
1571    <para>
1572     Where <replaceable class="parameter">src_addr</replaceable> and
1573    <replaceable class="parameter">dst_addr</replaceable> are IP addresses in dotted decimal notation or valid
1574     DNS names, and <replaceable class="parameter">src_masklen</replaceable> and
1575     <replaceable class="parameter">dst_masklen</replaceable> are subnet masks in CIDR notation, i.e. integer
1576     values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole
1577     destination part are optional.
1578    </para>
1579   </listitem>
1580  </varlistentry>
1581  <varlistentry>
1582   <term>Default value:</term>
1583   <listitem>
1584    <para><emphasis>Unset</emphasis></para>
1585   </listitem>
1586  </varlistentry>
1587  <varlistentry>
1588   <term>Effect if unset:</term>
1589   <listitem>
1590    <para>
1591     Don't restrict access further than implied by <literal>listen-address</literal>
1592    </para>
1593   </listitem>
1594  </varlistentry>
1595  <varlistentry>
1596   <term>Notes:</term>
1597   <listitem>
1598    <para>
1599     Access controls are included at the request of ISPs and systems
1600     administrators, and <emphasis>are not usually needed by individual users</emphasis>.
1601     For a typical home user, it will normally suffice to ensure that
1602     <application>Privoxy</application> only listens on the localhost
1603     (127.0.0.1) or internal (home) network address by means of the
1604     <link linkend="listen-address"><emphasis>listen-address</emphasis></link>
1605     option.
1606    </para>
1607    <para>
1608     Please see the warnings in the FAQ that this proxy is not intended to be a substitute
1609     for a firewall or to encourage anyone to defer addressing basic security
1610     weaknesses.
1611    </para>
1612    <para>
1613     Multiple ACL lines are OK.
1614     If any ACLs are specified, <application>Privoxy</application> only talks
1615     to IP addresses that match at least one <literal>permit-access</literal> line
1616     and don't match any subsequent <literal>deny-access</literal> line. In other words, the
1617     last match wins, with the default being <literal>deny-access</literal>.
1618    </para>
1619    <para>
1620     If <application>Privoxy</application> is using a forwarder (see <literal>forward</literal> below)
1621     for a particular destination URL, the <replaceable class="parameter">dst_addr</replaceable>
1622     that is examined is the address of the forwarder and <emphasis>NOT</emphasis> the address
1623     of the ultimate target. This is necessary because it may be impossible for the local
1624     <application>Privoxy</application> to determine the IP address of the
1625     ultimate target (that's often what gateways are used for).
1626    </para>
1627    <para>
1628     You should prefer using IP addresses over DNS names, because the address lookups take
1629     time. All DNS names must resolve! You can <emphasis>not</emphasis> use domain patterns
1630     like <quote>*.org</quote> or partial domain names. If a DNS name resolves to multiple
1631     IP addresses, only the first one is used.
1632    </para>
1633    <para>
1634     Denying access to particular sites by ACL may have undesired side effects
1635     if the site in question is hosted on a machine which also hosts other sites
1636     (most sites are).
1637    </para>
1638   </listitem>
1639  </varlistentry>
1640  <varlistentry>
1641   <term>Examples:</term>
1642   <listitem>
1643    <para>
1644     Explicitly define the default behavior if no ACL and
1645     <literal>listen-address</literal> are set: <quote>localhost</quote>
1646     is OK. The absence of a <replaceable class="parameter">dst_addr</replaceable> implies that
1647     <emphasis>all</emphasis> destination addresses are OK:
1648    </para>
1649    <para>
1650     <screen>
1651   permit-access  localhost
1652 </screen>
1653    </para>
1654    <para>
1655     Allow any host on the same class C subnet as www.privoxy.org access to
1656     nothing but www.example.com (or other domains hosted on the same system):
1657    </para>
1658    <para>
1659     <screen>
1660   permit-access  www.privoxy.org/24 www.example.com/32
1661 </screen>
1662    </para>
1663    <para>
1664     Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
1665     with the exception that 192.168.45.73 may not access the IP address behind
1666     www.dirty-stuff.example.com:
1667    </para>
1668    <para>
1669     <screen>
1670   permit-access  192.168.45.64/26
1671   deny-access    192.168.45.73    www.dirty-stuff.example.com
1672 </screen>
1673    </para>
1674   </listitem>
1675  </varlistentry>
1676 </variablelist>
1677 </sect3>
1678
1679
1680 <!--   ~~~~~       New section      ~~~~~     -->
1681 <sect3 renderas="sect4" id="buffer-limit"><title>buffer-limit</title>
1682
1683 <variablelist>
1684  <varlistentry>
1685   <term>Specifies:</term>
1686   <listitem>
1687    <para>
1688     Maximum size of the buffer for content filtering.
1689    </para>
1690   </listitem>
1691  </varlistentry>
1692  <varlistentry>
1693   <term>Type of value:</term>
1694   <listitem>
1695    <para>Size in Kbytes</para>
1696   </listitem>
1697  </varlistentry>
1698  <varlistentry>
1699   <term>Default value:</term>
1700   <listitem>
1701    <para>4096</para>
1702   </listitem>
1703  </varlistentry>
1704  <varlistentry>
1705   <term>Effect if unset:</term>
1706   <listitem>
1707    <para>
1708     Use a 4MB (4096 KB) limit.
1709    </para>
1710   </listitem>
1711  </varlistentry>
1712  <varlistentry>
1713   <term>Notes:</term>
1714   <listitem>
1715    <para>
1716     For content filtering, i.e. the <literal>+filter</literal> and
1717     <literal>+deanimate-gif</literal> actions, it is necessary that
1718     <application>Privoxy</application> buffers the entire document body.
1719     This can be potentially dangerous, since a server could just keep sending
1720     data indefinitely and wait for your RAM to exhaust -- with nasty consequences.
1721     Hence this option.
1722    </para>
1723    <para>
1724     When a document buffer size reaches the <literal>buffer-limit</literal>, it is
1725     flushed to the client unfiltered and no further attempt to
1726     filter the rest of the document is made. Remember that there may be multiple threads
1727     running, which might require up to <literal>buffer-limit</literal> Kbytes
1728     <emphasis>each</emphasis>, unless you have enabled <quote>single-threaded</quote>
1729     above.
1730    </para>
1731   </listitem>
1732  </varlistentry>
1733 </variablelist>
1734
1735 <![%config-file;[<literallayout>@@buffer-limit 4096</literallayout>]]>
1736 </sect3>
1737
1738 </sect2>
1739
1740 <!--  ~  End section  ~  -->
1741
1742
1743 <!--   ~~~~~       New section      ~~~~~     -->
1744
1745 <sect2 id="forwarding">
1746 <title>Forwarding</title>
1747
1748 <para>
1749  This feature allows routing of HTTP requests through a chain of
1750  multiple proxies.
1751 </para>
1752 <para>
1753  Forwarding can be used to chain Privoxy with a caching proxy to speed
1754  up browsing. Using a parent proxy may also be necessary if the machine
1755  that <application>Privoxy</application> runs on has no direct Internet access.
1756 </para>
1757 <para>
1758  Note that parent proxies can severely decrease your privacy level.
1759  For example a parent proxy could add your IP address to the request
1760  headers and if it's a caching proxy it may add the <quote>Etag</quote>
1761  header to revalidation requests again, even though you configured Privoxy
1762  to remove it. It may also ignore Privoxy's header time randomization and use the
1763  original values which could be used by the server as cookie replacement
1764  to track your steps between visits.
1765 </para>
1766
1767 <para>
1768  Also specified here are SOCKS proxies. <application>Privoxy</application>
1769  supports the SOCKS 4 and SOCKS 4A protocols.
1770 </para>
1771
1772 <sect3 renderas="sect4" id="forward"><title>forward</title>
1773 <variablelist>
1774  <varlistentry>
1775   <term>Specifies:</term>
1776   <listitem>
1777    <para>
1778     To which parent HTTP proxy specific requests should be routed.
1779    </para>
1780   </listitem>
1781  </varlistentry>
1782  <varlistentry>
1783   <term>Type of value:</term>
1784   <listitem>
1785    <para>
1786     <replaceable class="parameter">target_pattern</replaceable>
1787     <replaceable class="parameter">http_parent</replaceable>[:<replaceable class="parameter">port</replaceable>]
1788    </para>
1789    <para>
1790     where <replaceable class="parameter">target_pattern</replaceable> is a <link linkend="af-patterns">URL pattern</link>
1791     that specifies to which requests (i.e. URLs) this forward rule shall apply. Use <literal>/</literal> to
1792     denote <quote>all URLs</quote>.
1793     <replaceable class="parameter">http_parent</replaceable>[:<replaceable class="parameter">port</replaceable>]
1794     is the DNS name or IP address of the parent HTTP proxy through which the requests should be forwarded,
1795     optionally followed by its listening port (default: 8080).
1796     Use a single dot (<literal>.</literal>) to denote <quote>no forwarding</quote>.
1797    </para>
1798   </listitem>
1799  </varlistentry>
1800  <varlistentry>
1801   <term>Default value:</term>
1802   <listitem>
1803    <para><emphasis>Unset</emphasis></para>
1804   </listitem>
1805  </varlistentry>
1806  <varlistentry>
1807   <term>Effect if unset:</term>
1808   <listitem>
1809    <para>
1810     Don't use parent HTTP proxies.
1811    </para>
1812   </listitem>
1813  </varlistentry>
1814  <varlistentry>
1815   <term>Notes:</term>
1816   <listitem>
1817    <para>
1818     If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
1819     forwarded to another HTTP proxy but are made directly to the web servers.
1820    </para>
1821    <para>
1822     Multiple lines are OK, they are checked in sequence, and the last match wins.
1823    </para>
1824   </listitem>
1825  </varlistentry>
1826  <varlistentry>
1827   <term>Examples:</term>
1828   <listitem>
1829    <para>
1830     Everything goes to an example parent proxy, except SSL on port 443 (which it doesn't handle):
1831    </para>
1832    <para>
1833     <screen>
1834   forward   /      parent-proxy.example.org:8080
1835   forward   :443   .
1836 </screen>
1837    </para>
1838    <para>
1839     Everything goes to our example ISP's caching proxy, except for requests
1840     to that ISP's sites:
1841    </para>
1842    <para>
1843     <screen>
1844   forward   /                  caching-proxy.example-isp.net:8000
1845   forward   .example-isp.net   .
1846 </screen>
1847    </para>
1848   </listitem>
1849  </varlistentry>
1850 </variablelist>
1851 </sect3>
1852
1853
1854 <!--   ~~~~~       New section      ~~~~~     -->
1855 <sect3 renderas="sect4" id="socks"><title>
1856 forward-socks4 and forward-socks4a</title>
1857 <anchor id="forward-socks4">
1858 <anchor id="forward-socks4a">
1859
1860 <variablelist>
1861  <varlistentry>
1862   <term>Specifies:</term>
1863   <listitem>
1864    <para>
1865     Through which SOCKS proxy (and optionally to which parent HTTP proxy) specific requests should be routed.
1866    </para>
1867   </listitem>
1868  </varlistentry>
1869  <varlistentry>
1870   <term>Type of value:</term>
1871   <listitem>
1872    <para>
1873     <replaceable class="parameter">target_pattern</replaceable>
1874     <replaceable class="parameter">socks_proxy</replaceable>[:<replaceable class="parameter">port</replaceable>]
1875     <replaceable class="parameter">http_parent</replaceable>[:<replaceable class="parameter">port</replaceable>]
1876    </para>
1877    <para>
1878     where <replaceable class="parameter">target_pattern</replaceable> is a <link linkend="af-patterns">URL pattern</link>
1879     that specifies to which requests (i.e. URLs) this forward rule shall apply. Use <literal>/</literal> to
1880     denote <quote>all URLs</quote>.
1881     <replaceable class="parameter">http_parent</replaceable> and <replaceable class="parameter">socks_proxy</replaceable>
1882     are IP addresses in dotted decimal notation or valid DNS names (<replaceable class="parameter">http_parent</replaceable>
1883     may be <quote>.</quote> to denote <quote>no HTTP forwarding</quote>), and the optional
1884     <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer values from 1 to 64535
1885    </para>
1886   </listitem>
1887  </varlistentry>
1888  <varlistentry>
1889   <term>Default value:</term>
1890   <listitem>
1891    <para><emphasis>Unset</emphasis></para>
1892   </listitem>
1893  </varlistentry>
1894  <varlistentry>
1895   <term>Effect if unset:</term>
1896   <listitem>
1897    <para>
1898     Don't use SOCKS proxies.
1899    </para>
1900   </listitem>
1901  </varlistentry>
1902  <varlistentry>
1903   <term>Notes:</term>
1904   <listitem>
1905    <para>
1906     Multiple lines are OK, they are checked in sequence, and the last match wins.
1907    </para>
1908    <para>
1909     The difference between <literal>forward-socks4</literal> and <literal>forward-socks4a</literal>
1910     is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS
1911     server, while in SOCKS 4 it happens locally.
1912    </para>
1913    <para>
1914     If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
1915     forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
1916     a SOCKS proxy.
1917    </para>
1918   </listitem>
1919  </varlistentry>
1920  <varlistentry>
1921   <term>Examples:</term>
1922   <listitem>
1923    <para>
1924      From the company example.com, direct connections are made to all
1925      <quote>internal</quote> domains, but everything outbound goes through
1926      their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
1927      the Internet.
1928    </para>
1929    <para>
1930     <screen>
1931   forward-socks4a   /              socks-gw.example.com:1080  www-cache.example-isp.net:8080
1932   forward           .example.com   .
1933 </screen>
1934    </para>
1935    <para>
1936     A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
1937    </para>
1938    <para>
1939     <screen>
1940   forward-socks4   /               socks-gw.example.com:1080  .
1941 </screen>
1942    </para>
1943
1944     <para>
1945     To chain Privoxy and Tor, both running on the same system, you should use
1946     the rule:
1947    </para>
1948    <para>
1949     <screen>
1950   forward-socks4   /               127.0.0.1:9050 .
1951 </screen>
1952    </para>
1953
1954     <para>
1955     The public <application>Tor</application> network can't be used to reach your local network,
1956     therefore it's a good idea to make some exceptions:
1957    </para>
1958    <para>
1959     <screen>
1960   forward         192.168.*.*/     .
1961   forward            10.*.*.*/     .
1962   forward           127.*.*.*/     .
1963 </screen>
1964    </para>
1965    <para>
1966     Unencrypted connections to systems in these address ranges will
1967     be as (un)secure as the local network is, but the alternative is that you
1968     can't reach the network at all.
1969    </para>
1970    <para>
1971     If you also want to be able to reach servers in your local network by
1972     using their names, you will need additional exceptions that look like
1973     this:
1974    </para>
1975    <para>
1976     <screen>
1977  forward           localhost/     .
1978 </screen>
1979    </para>
1980
1981   </listitem>
1982  </varlistentry>
1983 </variablelist>
1984 </sect3>
1985
1986 <![%user-man;[     <!-- not included in config due to length -->
1987 <!--   ~~~~~       New section      ~~~~~     -->
1988 <sect3 renderas="sect4" id="advanced-forwarding-examples"><title>Advanced Forwarding Examples</title>
1989
1990 <para>
1991  If you have links to multiple ISPs that provide various special content
1992  only to their subscribers, you can configure multiple <application>Privoxies</application>
1993  which have connections to the respective ISPs to act as forwarders to each other, so that
1994  <emphasis>your</emphasis> users can see the internal content of all ISPs.
1995 </para>
1996
1997 <para>
1998  Assume that host-a has a PPP connection to isp-a.net. And host-b has a PPP connection to
1999  isp-b.net. Both run <application>Privoxy</application>. Their forwarding
2000  configuration can look like this:
2001 </para>
2002
2003 <para>
2004  host-a:
2005 </para>
2006
2007 <para>
2008  <screen>
2009   forward    /           .
2010   forward    .isp-b.net  host-b:8118
2011 </screen>
2012 </para>
2013
2014 <para>
2015  host-b:
2016 </para>
2017
2018 <para>
2019  <screen>
2020   forward    /           .
2021   forward    .isp-a.net  host-a:8118
2022 </screen>
2023 </para>
2024
2025 <para>
2026  Now, your users can set their browser's proxy to use either
2027  host-a or host-b and be able to browse the internal content
2028  of both isp-a and isp-b.
2029 </para>
2030
2031 <para>
2032  If you intend to chain <application>Privoxy</application> and
2033  <application>squid</application> locally, then chain as
2034  <literal>browser -> squid -> privoxy</literal> is the recommended way.
2035 </para>
2036
2037 <para>
2038  Assuming that <application>Privoxy</application> and <application>squid</application>
2039  run on the same box, your <application>squid</application> configuration could then look like this:
2040 </para>
2041
2042 <para>
2043  <screen>
2044   # Define Privoxy as parent proxy (without ICP)
2045   cache_peer 127.0.0.1 parent 8118 7 no-query
2046
2047   # Define ACL for protocol FTP
2048   acl ftp proto FTP
2049
2050   # Do not forward FTP requests to Privoxy
2051   always_direct allow ftp
2052
2053   # Forward all the rest to Privoxy
2054   never_direct allow all</screen>
2055 </para>
2056
2057 <para>
2058  You would then need to change your browser's proxy settings to <application>squid</application>'s address and port.
2059  Squid normally uses port 3128. If unsure consult <literal>http_port</literal> in <filename>squid.conf</filename>.
2060 </para>
2061
2062 <para>
2063  You could just as well decide to only forward requests for Windows executables through
2064  a virus-scanning parent proxy, say, on <literal>antivir.example.com</literal>, port 8010:
2065 </para>
2066
2067 <para>
2068  <screen>
2069   forward   /                          .
2070   forward   /.*\.(exe|com|dll|zip)$    antivir.example.com:8010</screen>
2071 </para>
2072
2073 </sect3>
2074 ]]>
2075
2076 <sect3 renderas="sect4" id="forwarded-connect-retries"><title>forwarded-connect-retries</title>
2077 <variablelist>
2078  <varlistentry>
2079   <term>Specifies:</term>
2080   <listitem>
2081    <para>
2082     How often Privoxy retries if a forwarded connection request fails.
2083    </para>
2084   </listitem>
2085  </varlistentry>
2086  <varlistentry>
2087   <term>Type of value:</term>
2088   <listitem>
2089    <para>
2090     <replaceable class="parameter">Number of retries.</replaceable>
2091    </para>
2092   </listitem>
2093  </varlistentry>
2094  <varlistentry>
2095   <term>Default value:</term>
2096   <listitem>
2097    <para><emphasis>0</emphasis></para>
2098   </listitem>
2099  </varlistentry>
2100  <varlistentry>
2101   <term>Effect if unset:</term>
2102   <listitem>
2103    <para>
2104     Connections forwarded through other proxies are treated like direct connections and no retry attempts are made.
2105    </para>
2106   </listitem>
2107  </varlistentry>
2108  <varlistentry>
2109   <term>Notes:</term>
2110   <listitem>
2111    <para>
2112     <replaceable class="parameter">forwarded-connect-retries</replaceable> is mainly interesting
2113     for socks4a connections, where <application>Privoxy</application> can't detect why the connections failed.
2114     The connection might have failed because of a DNS timeout in which case a retry makes sense,
2115     but it might also have failed because the server doesn't exist or isn't reachable. In this
2116     case the retry will just delay the appearance of Privoxy's error message.
2117    </para>
2118    <para>
2119     Note that in the context of this option, <quote>forwarded connections</quote> includes all connections
2120     that Privoxy forwards through other proxies. This option is not limited to the HTTP CONNECT method.
2121    </para>
2122    <para>
2123     Only use this option, if you are getting many forwarding related error messages,
2124     that go away when you try again manually. Start with a small value and check Privoxy's
2125     logfile from time to time, to see how many retries are usually needed.
2126    </para>
2127   </listitem>
2128  </varlistentry>
2129  <varlistentry>
2130   <term>Examples:</term>
2131   <listitem>
2132    <para>
2133     forwarded-connect-retries 1
2134    </para>
2135   </listitem>
2136  </varlistentry>
2137 </variablelist>
2138 <![%config-file;[<literallayout>@@forwarded-connect-retries  0</literallayout>]]>
2139 </sect3>
2140
2141 <sect3 renderas="sect4" id="accept-intercepted-requests"><title>accept-intercepted-requests</title>
2142 <variablelist>
2143  <varlistentry>
2144   <term>Specifies:</term>
2145   <listitem>
2146    <para>
2147     Whether intercepted requests should be treated as valid.
2148    </para>
2149   </listitem>
2150  </varlistentry>
2151  <varlistentry>
2152   <term>Type of value:</term>
2153   <listitem>
2154    <para>
2155     <replaceable>0 or 1</replaceable>
2156    </para>
2157   </listitem>
2158  </varlistentry>
2159  <varlistentry>
2160   <term>Default value:</term>
2161   <listitem>
2162    <para><emphasis>0</emphasis></para>
2163   </listitem>
2164  </varlistentry>
2165  <varlistentry>
2166   <term>Effect if unset:</term>
2167   <listitem>
2168    <para>
2169     Only proxy requests are accepted, intercepted requests are treated as invalid.
2170    </para>
2171   </listitem>
2172  </varlistentry>
2173  <varlistentry>
2174   <term>Notes:</term>
2175   <listitem>
2176    <para>
2177     If you don't trust your clients and want to force them
2178     to use <application>Privoxy</application>, enable this
2179     option and configure your packet filter to redirect outgoing
2180     HTTP connections into <application>Privoxy</application>.
2181    </para>
2182    <para>
2183     Make sure that <application>Privoxy's</application> own requests
2184     aren't redirected as well. Additionally take care that
2185     <application>Privoxy</application> can't intentionally connect
2186     to itself, otherwise you could run into redirection loops if
2187     <application>Privoxy's</application> listening port is reachable
2188     by the outside or an attacker has access to the pages you visit.
2189    </para>
2190   </listitem>
2191  </varlistentry>
2192  <varlistentry>
2193   <term>Examples:</term>
2194   <listitem>
2195    <para>
2196     accept-intercepted-requests 1
2197    </para>
2198   </listitem>
2199  </varlistentry>
2200 </variablelist>
2201 <![%config-file;[<literallayout>@@accept-intercepted-requests 0</literallayout>]]>
2202 </sect3>
2203
2204 <sect3 renderas="sect4" id="allow-cgi-request-crunching"><title>allow-cgi-request-crunching</title>
2205 <variablelist>
2206  <varlistentry>
2207   <term>Specifies:</term>
2208   <listitem>
2209    <para>
2210     Whether requests to <application>Privoxy's</application> CGI pages can be blocked or redirected.
2211    </para>
2212   </listitem>
2213  </varlistentry>
2214  <varlistentry>
2215   <term>Type of value:</term>
2216   <listitem>
2217    <para>
2218     <replaceable>0 or 1</replaceable>
2219    </para>
2220   </listitem>
2221  </varlistentry>
2222  <varlistentry>
2223   <term>Default value:</term>
2224   <listitem>
2225    <para><emphasis>0</emphasis></para>
2226   </listitem>
2227  </varlistentry>
2228  <varlistentry>
2229   <term>Effect if unset:</term>
2230   <listitem>
2231    <para>
2232     <application>Privoxy</application> ignores block and redirect actions for its CGI pages.
2233    </para>
2234   </listitem>
2235  </varlistentry>
2236  <varlistentry>
2237   <term>Notes:</term>
2238   <listitem>
2239    <para>
2240     By default <application>Privoxy</application> ignores block or redirect actions
2241     for its CGI pages. Intercepting these requests can be useful in multi-user
2242     setups to implement fine-grained access control, but it can also render the complete
2243     web interface useless and make debugging problems painful if done without care.
2244    </para>
2245    <para>
2246     Don't enable this option unless you're sure that you really need it.
2247    </para>
2248   </listitem>
2249  </varlistentry>
2250  <varlistentry>
2251   <term>Examples:</term>
2252   <listitem>
2253    <para>
2254     allow-cgi-request-crunching 1
2255    </para>
2256   </listitem>
2257  </varlistentry>
2258 </variablelist>
2259 <![%config-file;[<literallayout>@@allow-cgi-request-crunching 0</literallayout>]]>
2260 </sect3>
2261
2262 <sect3 renderas="sect4" id="split-large-forms"><title>split-large-forms</title>
2263 <variablelist>
2264  <varlistentry>
2265   <term>Specifies:</term>
2266   <listitem>
2267    <para>
2268     Whether the CGI interface should stay compatible with broken HTTP clients.
2269    </para>
2270   </listitem>
2271  </varlistentry>
2272  <varlistentry>
2273   <term>Type of value:</term>
2274   <listitem>
2275    <para>
2276     <replaceable>0 or 1</replaceable>
2277    </para>
2278   </listitem>
2279  </varlistentry>
2280  <varlistentry>
2281   <term>Default value:</term>
2282   <listitem>
2283    <para><emphasis>0</emphasis></para>
2284   </listitem>
2285  </varlistentry>
2286  <varlistentry>
2287   <term>Effect if unset:</term>
2288   <listitem>
2289    <para>
2290     The CGI form generate long GET URLs.
2291    </para>
2292   </listitem>
2293  </varlistentry>
2294  <varlistentry>
2295   <term>Notes:</term>
2296   <listitem>
2297    <para>
2298     <application>Privoxy's</application> CGI forms can lead to
2299     rather long URLs. This isn't a problem as far as the HTTP
2300     standard is concerned, but it can confuse clients with arbitrary
2301     URL lenght limitations.
2302    </para>
2303    <para>
2304     Enabling split-large-forms causes <application>Privoxy</application>
2305     to devide big forms into smaller ones to keep the URL length down.
2306     It makes editing a lot less convenient and you can no longer
2307     submit all changes at once, but at least it works around this
2308     browser bug.
2309    </para>
2310    <para>
2311     If you don't notice any editing problems, there is no reason
2312     to enable this option, but if one of the submit buttons appears
2313     to be broken, you should give it a try.
2314    </para>
2315   </listitem>
2316  </varlistentry>
2317  <varlistentry>
2318   <term>Examples:</term>
2319   <listitem>
2320    <para>
2321     split-large-forms 1
2322    </para>
2323   </listitem>
2324  </varlistentry>
2325 </variablelist>
2326 <![%config-file;[<literallayout>@@split-large-forms 0</literallayout>]]>
2327 </sect3>
2328
2329 </sect2>
2330
2331 <!--  ~  End section  ~  -->
2332
2333
2334 <!--   ~~~~~       New section      ~~~~~     -->
2335
2336 <sect2 id="windows-gui">
2337 <title>Windows GUI Options</title>
2338 <para>
2339  <application>Privoxy</application> has a number of options specific to the
2340  Windows GUI interface:
2341 </para>
2342
2343 <anchor id="activity-animation">
2344 <![%config-file;[<para>@@</para>]]> <!-- for spacing -->
2345 <para>
2346  If <quote>activity-animation</quote> is set to 1, the
2347  <application>Privoxy</application> icon will animate when
2348  <quote>Privoxy</quote> is active. To turn off, set to 0.
2349 </para>
2350
2351 <![%config-file;[<literallayout>@@#activity-animation   1</literallayout>]]>
2352 <![%user-man;[
2353 <para>
2354  <literal>
2355   <msgtext>
2356    <literallayout>
2357   <emphasis>activity-animation   1</emphasis>
2358    </literallayout>
2359   </msgtext>
2360  </literal>
2361 </para>
2362 ]]>
2363
2364 <anchor id="log-messages">
2365 <![%config-file;[<para>@@</para>]]> <!-- for spacing -->
2366 <para>
2367  If <quote>log-messages</quote> is set to 1,
2368  <application>Privoxy</application> will log messages to the console
2369  window:
2370 </para>
2371
2372 <![%config-file;[<literallayout>@@#log-messages   1</literallayout>]]>
2373 <![%user-man;[
2374 <para>
2375  <literal>
2376   <msgtext>
2377    <literallayout>
2378   <emphasis>log-messages       1</emphasis>
2379    </literallayout>
2380   </msgtext>
2381  </literal>
2382 </para>
2383 ]]>
2384
2385 <anchor id="log-buffer-size">
2386 <![%config-file;[<para>@@</para>]]> <!-- for spacing -->
2387 <para>
2388  If <quote>log-buffer-size</quote> is set to 1, the size of the log buffer,
2389  i.e. the amount of memory used for the log messages displayed in the
2390  console window, will be limited to <quote>log-max-lines</quote> (see below).
2391 </para>
2392
2393 <para>
2394  Warning: Setting this to 0 will result in the buffer to grow infinitely and
2395  eat up all your memory!
2396 </para>
2397
2398 <![%config-file;[<literallayout>@@#log-buffer-size 1</literallayout>]]>
2399 <![%user-man;[
2400 <para>
2401  <literal>
2402   <msgtext>
2403    <literallayout>
2404   <emphasis>log-buffer-size      1</emphasis>
2405    </literallayout>
2406   </msgtext>
2407  </literal>
2408 </para>
2409 ]]>
2410
2411 <anchor id="log-max-lines">
2412 <![%config-file;[<para>@@</para>]]> <!-- for spacing -->
2413 <para>
2414  <application>log-max-lines</application> is the maximum number of lines held
2415  in the log buffer. See above.
2416 </para>
2417
2418 <![%config-file;[<literallayout>@@#log-max-lines 200</literallayout>]]>
2419 <![%user-man;[
2420 <para>
2421  <literal>
2422   <msgtext>
2423    <literallayout>
2424   <emphasis>log-max-lines      200</emphasis>
2425    </literallayout>
2426   </msgtext>
2427  </literal>
2428 </para>
2429 ]]>
2430
2431 <anchor id="log-highlight-messages">
2432 <![%config-file;[<para>@@</para>]]> <!-- for spacing -->
2433 <para>
2434  If <quote>log-highlight-messages</quote> is set to 1,
2435  <application>Privoxy</application> will highlight portions of the log
2436  messages with a bold-faced font:
2437 </para>
2438
2439 <![%config-file;[<literallayout>@@#log-highlight-messages 1</literallayout>]]>
2440 <![%user-man;[
2441 <para>
2442  <literal>
2443   <msgtext>
2444    <literallayout>
2445   <emphasis>log-highlight-messages   1</emphasis>
2446    </literallayout>
2447   </msgtext>
2448  </literal>
2449 </para>
2450 ]]>
2451
2452 <anchor id="log-font-name">
2453 <![%config-file;[<para>@@</para>]]> <!-- for spacing -->
2454 <para>
2455  The font used in the console window:
2456 </para>
2457
2458 <![%config-file;[<literallayout>@@#log-font-name Comic Sans MS</literallayout>]]>
2459 <![%user-man;[
2460 <para>
2461  <literal>
2462   <msgtext>
2463    <literallayout>
2464   <emphasis>log-font-name        Comic Sans MS</emphasis>
2465    </literallayout>
2466   </msgtext>
2467  </literal>
2468 </para>
2469 ]]>
2470
2471 <anchor id="log-font-size">
2472 <![%config-file;[<para>@@</para>]]> <!-- for spacing -->
2473 <para>
2474  Font size used in the console window:
2475 </para>
2476
2477 <![%config-file;[<literallayout>@@#log-font-size 8</literallayout>]]>
2478 <![%user-man;[
2479 <para>
2480  <literal>
2481   <msgtext>
2482    <literallayout>
2483   <emphasis>log-font-size        8</emphasis>
2484    </literallayout>
2485   </msgtext>
2486  </literal>
2487 </para>
2488 ]]>
2489
2490 <anchor id="show-on-task-bar">
2491 <![%config-file;[<para>@@</para>]]> <!-- for spacing -->
2492 <para>
2493  <quote>show-on-task-bar</quote> controls whether or not
2494  <application>Privoxy</application> will appear as a button on the Task bar
2495  when minimized:
2496 </para>
2497
2498 <![%config-file;[<literallayout>@@#show-on-task-bar 0</literallayout>]]>
2499 <![%user-man;[
2500 <para>
2501  <literal>
2502   <msgtext>
2503    <literallayout>
2504   <emphasis>show-on-task-bar     0</emphasis>
2505    </literallayout>
2506   </msgtext>
2507  </literal>
2508 </para>
2509 ]]>
2510
2511 <anchor id="close-button-minimizes">
2512 <![%config-file;[<para>@@</para>]]> <!-- for spacing -->
2513 <para>
2514  If <quote>close-button-minimizes</quote> is set to 1, the Windows close
2515  button will minimize <application>Privoxy</application> instead of closing
2516  the program (close with the exit option on the File menu).
2517 </para>
2518
2519 <![%config-file;[<literallayout>@@#close-button-minimizes 1</literallayout>]]>
2520 <![%user-man;[
2521 <para>
2522  <literal>
2523   <msgtext>
2524    <literallayout>
2525   <emphasis>close-button-minimizes  1</emphasis>
2526    </literallayout>
2527   </msgtext>
2528  </literal>
2529 </para>
2530 ]]>
2531
2532 <anchor id="hide-console">
2533 <![%config-file;[<para>@@</para>]]> <!-- for spacing -->
2534 <para>
2535  The <quote>hide-console</quote> option is specific to the MS-Win console
2536  version of <application>Privoxy</application>. If this option is used,
2537  <application>Privoxy</application> will disconnect from and hide  the
2538  command console.
2539 </para>
2540
2541 <![%config-file;[<literallayout>@@#hide-console</literallayout>]]>
2542 <![%user-man;[
2543 <para>
2544  <literal>
2545   <msgtext>
2546    <literallayout>
2547   #<emphasis>hide-console</emphasis>
2548    </literallayout>
2549   </msgtext>
2550  </literal>
2551 </para>
2552 ]]>
2553
2554 </sect2>
2555 </sect1>
2556
2557 <!-- end config content common to both outputs -->
2558
2559 <![%config-file;[
2560 <!-- These are dummy anchors to keep the processor quiet            -->
2561 <!-- when building config-file only (ie. they are used in u-m only) -->
2562 <sect1 label="">
2563 <title></title>
2564 <anchor id="filter">
2565 <anchor id="filter-file">
2566 <anchor id="regex">
2567 <anchor id="actions-file">
2568 <anchor id="af-patterns">
2569 </sect1>
2570 ]]>
2571
2572 <!-- eof p-config.sgml -->