doc/webserver/user-manual/config.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2 "http://www.w3.org/TR/html4/loose.dtd">
   3
   4 <html>
   5 <head>
   6   <title>The Main Configuration File</title>
   7   <meta name="GENERATOR" content=
   8   "Modular DocBook HTML Stylesheet Version 1.79">
   9   <link rel="HOME" title="Privoxy 3.0.22 User Manual" href="index.html">
  10   <link rel="PREVIOUS" title="Privoxy Configuration" href=
  11   "configuration.html">
  12   <link rel="NEXT" title="Actions Files" href="actions-file.html">
  13   <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
  14   <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  15   <link rel="STYLESHEET" type="text/css" href="p_doc.css">
  16 </head>
  17
  18 <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
  19 "#840084" alink="#0000FF">
  20   <div class="NAVHEADER">
  21     <table summary="Header navigation table" width="100%" border="0"
  22     cellpadding="0" cellspacing="0">
  23       <tr>
  24         <th colspan="3" align="center">Privoxy 3.0.22 User Manual</th>
  25       </tr>
  26
  27       <tr>
  28         <td width="10%" align="left" valign="bottom"><a href=
  29         "configuration.html" accesskey="P">Prev</a></td>
  30
  31         <td width="80%" align="center" valign="bottom"></td>
  32
  33         <td width="10%" align="right" valign="bottom"><a href=
  34         "actions-file.html" accesskey="N">Next</a></td>
  35       </tr>
  36     </table>
  37     <hr align="left" width="100%">
  38   </div>
  39
  40   <div class="SECT1">
  41     <h1 class="SECT1"><a name="CONFIG" id="CONFIG">7. The Main Configuration
  42     File</a></h1>
  43
  44     <p>By default, the main configuration file is named <tt class=
  45     "FILENAME">config</tt>, with the exception of Windows, where it is named
  46     <tt class="FILENAME">config.txt</tt>. Configuration lines consist of an
  47     initial keyword followed by a list of values, all separated by whitespace
  48     (any number of spaces or tabs). For example:</p>
  49
  50     <p class="LITERALLAYOUT"><tt class="LITERAL">&nbsp;&nbsp;<span class=
  51     "emphasis"><i class="EMPHASIS">confdir /etc/privoxy</i></span></tt></p>
  52
  53     <p>Assigns the value <tt class="LITERAL">/etc/privoxy</tt> to the option
  54     <tt class="LITERAL">confdir</tt> and thus indicates that the
  55     configuration directory is named <span class=
  56     "QUOTE">"/etc/privoxy/"</span>.</p>
  57
  58     <p>All options in the config file except for <tt class=
  59     "LITERAL">confdir</tt> and <tt class="LITERAL">logdir</tt> are optional.
  60     Watch out in the below description for what happens if you leave them
  61     unset.</p>
  62
  63     <p>The main config file controls all aspects of <span class=
  64     "APPLICATION">Privoxy</span>'s operation that are not location dependent
  65     (i.e. they apply universally, no matter where you may be surfing). Like
  66     the filter and action files, the config file is a plain text file and can
  67     be modified with a text editor like emacs, vim or notepad.exe.</p>
  68
  69     <div class="SECT2">
  70       <h2 class="SECT2"><a name="LOCAL-SET-UP" id="LOCAL-SET-UP">7.1. Local
  71       Set-up Documentation</a></h2>
  72
  73       <p>If you intend to operate <span class="APPLICATION">Privoxy</span>
  74       for more users than just yourself, it might be a good idea to let them
  75       know how to reach you, what you block and why you do that, your
  76       policies, etc.</p>
  77
  78       <div class="SECT3">
  79         <h4 class="SECT3"><a name="USER-MANUAL" id="USER-MANUAL">7.1.1.
  80         user-manual</a></h4>
  81
  82         <div class="VARIABLELIST">
  83           <dl>
  84             <dt>Specifies:</dt>
  85
  86             <dd>
  87               <p>Location of the <span class="APPLICATION">Privoxy</span>
  88               User Manual.</p>
  89             </dd>
  90
  91             <dt>Type of value:</dt>
  92
  93             <dd>
  94               <p>A fully qualified URI</p>
  95             </dd>
  96
  97             <dt>Default value:</dt>
  98
  99             <dd>
 100               <p><span class="emphasis"><i class=
 101               "EMPHASIS">Unset</i></span></p>
 102             </dd>
 103
 104             <dt>Effect if unset:</dt>
 105
 106             <dd>
 107               <p><a href="http://www.privoxy.org/user-manual/" target=
 108               "_top">http://www.privoxy.org/<tt class=
 109               "REPLACEABLE"><i>version</i></tt>/user-manual/</a> will be
 110               used, where <tt class="REPLACEABLE"><i>version</i></tt> is the
 111               <span class="APPLICATION">Privoxy</span> version.</p>
 112             </dd>
 113
 114             <dt>Notes:</dt>
 115
 116             <dd>
 117               <p>The User Manual URI is the single best source of information
 118               on <span class="APPLICATION">Privoxy</span>, and is used for
 119               help links from some of the internal CGI pages. The manual
 120               itself is normally packaged with the binary distributions, so
 121               you probably want to set this to a locally installed copy.</p>
 122
 123               <p>Examples:</p>
 124
 125               <p>The best all purpose solution is simply to put the full
 126               local <tt class="LITERAL">PATH</tt> to where the <i class=
 127               "CITETITLE">User Manual</i> is located:</p>
 128
 129               <table border="0" bgcolor="#E0E0E0" width="90%">
 130                 <tr>
 131                   <td>
 132                     <pre class="SCREEN">
 133   user-manual  /usr/share/doc/privoxy/user-manual
 134 </pre>
 135                   </td>
 136                 </tr>
 137               </table>
 138
 139               <p>The User Manual is then available to anyone with access to
 140               <span class="APPLICATION">Privoxy</span>, by following the
 141               built-in URL: <tt class=
 142               "LITERAL">http://config.privoxy.org/user-manual/</tt> (or the
 143               shortcut: <tt class=
 144               "LITERAL">http://p.p/user-manual/</tt>).</p>
 145
 146               <p>If the documentation is not on the local system, it can be
 147               accessed from a remote server, as:</p>
 148
 149               <table border="0" bgcolor="#E0E0E0" width="90%">
 150                 <tr>
 151                   <td>
 152                     <pre class="SCREEN">
 153   user-manual  http://example.com/privoxy/user-manual/
 154 </pre>
 155                   </td>
 156                 </tr>
 157               </table>
 158
 159               <div class="WARNING">
 160                 <table class="WARNING" border="1" width="90%">
 161                   <tr>
 162                     <td align="center"><b>Warning</b></td>
 163                   </tr>
 164
 165                   <tr>
 166                     <td align="left">
 167                       <p>If set, this option should be <span class=
 168                       "emphasis"><i class="EMPHASIS">the first option in the
 169                       config file</i></span>, because it is used while the
 170                       config file is being read on start-up.</p>
 171                     </td>
 172                   </tr>
 173                 </table>
 174               </div>
 175             </dd>
 176           </dl>
 177         </div>
 178       </div>
 179
 180       <div class="SECT3">
 181         <h4 class="SECT3"><a name="TRUST-INFO-URL" id="TRUST-INFO-URL">7.1.2.
 182         trust-info-url</a></h4>
 183
 184         <div class="VARIABLELIST">
 185           <dl>
 186             <dt>Specifies:</dt>
 187
 188             <dd>
 189               <p>A URL to be displayed in the error page that users will see
 190               if access to an untrusted page is denied.</p>
 191             </dd>
 192
 193             <dt>Type of value:</dt>
 194
 195             <dd>
 196               <p>URL</p>
 197             </dd>
 198
 199             <dt>Default value:</dt>
 200
 201             <dd>
 202               <p><span class="emphasis"><i class=
 203               "EMPHASIS">Unset</i></span></p>
 204             </dd>
 205
 206             <dt>Effect if unset:</dt>
 207
 208             <dd>
 209               <p>No links are displayed on the "untrusted" error page.</p>
 210             </dd>
 211
 212             <dt>Notes:</dt>
 213
 214             <dd>
 215               <p>The value of this option only matters if the experimental
 216               trust mechanism has been activated. (See <a href=
 217               "config.html#TRUSTFILE"><span class="emphasis"><i class=
 218               "EMPHASIS">trustfile</i></span></a> below.)</p>
 219
 220               <p>If you use the trust mechanism, it is a good idea to write
 221               up some on-line documentation about your trust policy and to
 222               specify the URL(s) here. Use multiple times for multiple
 223               URLs.</p>
 224
 225               <p>The URL(s) should be added to the trustfile as well, so
 226               users don't end up locked out from the information on why they
 227               were locked out in the first place!</p>
 228             </dd>
 229           </dl>
 230         </div>
 231       </div>
 232
 233       <div class="SECT3">
 234         <h4 class="SECT3"><a name="ADMIN-ADDRESS" id="ADMIN-ADDRESS">7.1.3.
 235         admin-address</a></h4>
 236
 237         <div class="VARIABLELIST">
 238           <dl>
 239             <dt>Specifies:</dt>
 240
 241             <dd>
 242               <p>An email address to reach the <span class=
 243               "APPLICATION">Privoxy</span> administrator.</p>
 244             </dd>
 245
 246             <dt>Type of value:</dt>
 247
 248             <dd>
 249               <p>Email address</p>
 250             </dd>
 251
 252             <dt>Default value:</dt>
 253
 254             <dd>
 255               <p><span class="emphasis"><i class=
 256               "EMPHASIS">Unset</i></span></p>
 257             </dd>
 258
 259             <dt>Effect if unset:</dt>
 260
 261             <dd>
 262               <p>No email address is displayed on error pages and the CGI
 263               user interface.</p>
 264             </dd>
 265
 266             <dt>Notes:</dt>
 267
 268             <dd>
 269               <p>If both <tt class="LITERAL">admin-address</tt> and
 270               <tt class="LITERAL">proxy-info-url</tt> are unset, the whole
 271               "Local Privoxy Support" box on all generated pages will not be
 272               shown.</p>
 273             </dd>
 274           </dl>
 275         </div>
 276       </div>
 277
 278       <div class="SECT3">
 279         <h4 class="SECT3"><a name="PROXY-INFO-URL" id="PROXY-INFO-URL">7.1.4.
 280         proxy-info-url</a></h4>
 281
 282         <div class="VARIABLELIST">
 283           <dl>
 284             <dt>Specifies:</dt>
 285
 286             <dd>
 287               <p>A URL to documentation about the local <span class=
 288               "APPLICATION">Privoxy</span> setup, configuration or
 289               policies.</p>
 290             </dd>
 291
 292             <dt>Type of value:</dt>
 293
 294             <dd>
 295               <p>URL</p>
 296             </dd>
 297
 298             <dt>Default value:</dt>
 299
 300             <dd>
 301               <p><span class="emphasis"><i class=
 302               "EMPHASIS">Unset</i></span></p>
 303             </dd>
 304
 305             <dt>Effect if unset:</dt>
 306
 307             <dd>
 308               <p>No link to local documentation is displayed on error pages
 309               and the CGI user interface.</p>
 310             </dd>
 311
 312             <dt>Notes:</dt>
 313
 314             <dd>
 315               <p>If both <tt class="LITERAL">admin-address</tt> and
 316               <tt class="LITERAL">proxy-info-url</tt> are unset, the whole
 317               "Local Privoxy Support" box on all generated pages will not be
 318               shown.</p>
 319
 320               <p>This URL shouldn't be blocked ;-)</p>
 321             </dd>
 322           </dl>
 323         </div>
 324       </div>
 325     </div>
 326
 327     <div class="SECT2">
 328       <h2 class="SECT2"><a name="CONF-LOG-LOC" id="CONF-LOG-LOC">7.2.
 329       Configuration and Log File Locations</a></h2>
 330
 331       <p><span class="APPLICATION">Privoxy</span> can (and normally does) use
 332       a number of other files for additional configuration, help and logging.
 333       This section of the configuration file tells <span class=
 334       "APPLICATION">Privoxy</span> where to find those other files.</p>
 335
 336       <p>The user running <span class="APPLICATION">Privoxy</span>, must have
 337       read permission for all configuration files, and write permission to
 338       any files that would be modified, such as log files and actions
 339       files.</p>
 340
 341       <div class="SECT3">
 342         <h4 class="SECT3"><a name="CONFDIR" id="CONFDIR">7.2.1.
 343         confdir</a></h4>
 344
 345         <div class="VARIABLELIST">
 346           <dl>
 347             <dt>Specifies:</dt>
 348
 349             <dd>
 350               <p>The directory where the other configuration files are
 351               located.</p>
 352             </dd>
 353
 354             <dt>Type of value:</dt>
 355
 356             <dd>
 357               <p>Path name</p>
 358             </dd>
 359
 360             <dt>Default value:</dt>
 361
 362             <dd>
 363               <p>/etc/privoxy (Unix) <span class="emphasis"><i class=
 364               "EMPHASIS">or</i></span> <span class=
 365               "APPLICATION">Privoxy</span> installation dir (Windows)</p>
 366             </dd>
 367
 368             <dt>Effect if unset:</dt>
 369
 370             <dd>
 371               <p><span class="emphasis"><i class=
 372               "EMPHASIS">Mandatory</i></span></p>
 373             </dd>
 374
 375             <dt>Notes:</dt>
 376
 377             <dd>
 378               <p>No trailing <span class="QUOTE">"<tt class=
 379               "LITERAL">/</tt>"</span>, please.</p>
 380             </dd>
 381           </dl>
 382         </div>
 383       </div>
 384
 385       <div class="SECT3">
 386         <h4 class="SECT3"><a name="TEMPLDIR" id="TEMPLDIR">7.2.2.
 387         templdir</a></h4>
 388
 389         <div class="VARIABLELIST">
 390           <dl>
 391             <dt>Specifies:</dt>
 392
 393             <dd>
 394               <p>An alternative directory where the templates are loaded
 395               from.</p>
 396             </dd>
 397
 398             <dt>Type of value:</dt>
 399
 400             <dd>
 401               <p>Path name</p>
 402             </dd>
 403
 404             <dt>Default value:</dt>
 405
 406             <dd>
 407               <p>unset</p>
 408             </dd>
 409
 410             <dt>Effect if unset:</dt>
 411
 412             <dd>
 413               <p>The templates are assumed to be located in
 414               confdir/template.</p>
 415             </dd>
 416
 417             <dt>Notes:</dt>
 418
 419             <dd>
 420               <p><span class="APPLICATION">Privoxy's</span> original
 421               templates are usually overwritten with each update. Use this
 422               option to relocate customized templates that should be kept. As
 423               template variables might change between updates, you shouldn't
 424               expect templates to work with <span class=
 425               "APPLICATION">Privoxy</span> releases other than the one they
 426               were part of, though.</p>
 427             </dd>
 428           </dl>
 429         </div>
 430       </div>
 431
 432       <div class="SECT3">
 433         <h4 class="SECT3"><a name="TEMPORARY-DIRECTORY" id=
 434         "TEMPORARY-DIRECTORY">7.2.3. temporary-directory</a></h4>
 435
 436         <div class="VARIABLELIST">
 437           <dl>
 438             <dt>Specifies:</dt>
 439
 440             <dd>
 441               <p>A directory where Privoxy can create temporary files.</p>
 442             </dd>
 443
 444             <dt>Type of value:</dt>
 445
 446             <dd>
 447               <p>Path name</p>
 448             </dd>
 449
 450             <dt>Default value:</dt>
 451
 452             <dd>
 453               <p>unset</p>
 454             </dd>
 455
 456             <dt>Effect if unset:</dt>
 457
 458             <dd>
 459               <p>No temporary files are created, external filters don't
 460               work.</p>
 461             </dd>
 462
 463             <dt>Notes:</dt>
 464
 465             <dd>
 466               <p>To execute <tt class="LITERAL"><a href=
 467               "actions-file.html#EXTERNAL-FILTER" target="_top">external
 468               filters</a></tt>, <span class="APPLICATION">Privoxy</span> has
 469               to create temporary files. This directive specifies the
 470               directory the temporary files should be written to.</p>
 471
 472               <p>It should be a directory only <span class=
 473               "APPLICATION">Privoxy</span> (and trusted users) can
 474               access.</p>
 475             </dd>
 476           </dl>
 477         </div>
 478       </div>
 479
 480       <div class="SECT3">
 481         <h4 class="SECT3"><a name="LOGDIR" id="LOGDIR">7.2.4. logdir</a></h4>
 482
 483         <div class="VARIABLELIST">
 484           <dl>
 485             <dt>Specifies:</dt>
 486
 487             <dd>
 488               <p>The directory where all logging takes place (i.e. where the
 489               <tt class="FILENAME">logfile</tt> is located).</p>
 490             </dd>
 491
 492             <dt>Type of value:</dt>
 493
 494             <dd>
 495               <p>Path name</p>
 496             </dd>
 497
 498             <dt>Default value:</dt>
 499
 500             <dd>
 501               <p>/var/log/privoxy (Unix) <span class="emphasis"><i class=
 502               "EMPHASIS">or</i></span> <span class=
 503               "APPLICATION">Privoxy</span> installation dir (Windows)</p>
 504             </dd>
 505
 506             <dt>Effect if unset:</dt>
 507
 508             <dd>
 509               <p><span class="emphasis"><i class=
 510               "EMPHASIS">Mandatory</i></span></p>
 511             </dd>
 512
 513             <dt>Notes:</dt>
 514
 515             <dd>
 516               <p>No trailing <span class="QUOTE">"<tt class=
 517               "LITERAL">/</tt>"</span>, please.</p>
 518             </dd>
 519           </dl>
 520         </div>
 521       </div>
 522
 523       <div class="SECT3">
 524         <h4 class="SECT3"><a name="ACTIONSFILE" id="ACTIONSFILE">7.2.5.
 525         actionsfile</a></h4><a name="DEFAULT.ACTION" id=
 526         "DEFAULT.ACTION"></a><a name="STANDARD.ACTION" id=
 527         "STANDARD.ACTION"></a><a name="USER.ACTION" id="USER.ACTION"></a>
 528
 529         <div class="VARIABLELIST">
 530           <dl>
 531             <dt>Specifies:</dt>
 532
 533             <dd>
 534               <p>The <a href="actions-file.html">actions file(s)</a> to
 535               use</p>
 536             </dd>
 537
 538             <dt>Type of value:</dt>
 539
 540             <dd>
 541               <p>Complete file name, relative to <tt class=
 542               "LITERAL">confdir</tt></p>
 543             </dd>
 544
 545             <dt>Default values:</dt>
 546
 547             <dd>
 548               <table border="0">
 549                 <tbody>
 550                   <tr>
 551                     <td>
 552                       <p class="LITERALLAYOUT">
 553                       &nbsp;&nbsp;match-all.action&nbsp;#&nbsp;Actions&nbsp;that&nbsp;are&nbsp;applied&nbsp;to&nbsp;all&nbsp;sites&nbsp;and&nbsp;maybe&nbsp;overruled&nbsp;later&nbsp;on.</p>
 554                     </td>
 555                   </tr>
 556
 557                   <tr>
 558                     <td>
 559                       <p class="LITERALLAYOUT">
 560                       &nbsp;&nbsp;default.action&nbsp;&nbsp;&nbsp;#&nbsp;Main&nbsp;actions&nbsp;file</p>
 561                     </td>
 562                   </tr>
 563
 564                   <tr>
 565                     <td>
 566                       <p class="LITERALLAYOUT">
 567                       &nbsp;&nbsp;user.action&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;#&nbsp;User&nbsp;customizations</p>
 568                     </td>
 569                   </tr>
 570                 </tbody>
 571               </table>
 572             </dd>
 573
 574             <dt>Effect if unset:</dt>
 575
 576             <dd>
 577               <p>No actions are taken at all. More or less neutral
 578               proxying.</p>
 579             </dd>
 580
 581             <dt>Notes:</dt>
 582
 583             <dd>
 584               <p>Multiple <tt class="LITERAL">actionsfile</tt> lines are
 585               permitted, and are in fact recommended!</p>
 586
 587               <p>The default values are <tt class=
 588               "FILENAME">default.action</tt>, which is the <span class=
 589               "QUOTE">"main"</span> actions file maintained by the
 590               developers, and <tt class="FILENAME">user.action</tt>, where
 591               you can make your personal additions.</p>
 592
 593               <p>Actions files contain all the per site and per URL
 594               configuration for ad blocking, cookie management, privacy
 595               considerations, etc. There is no point in using <span class=
 596               "APPLICATION">Privoxy</span> without at least one actions
 597               file.</p>
 598
 599               <p>Note that since Privoxy 3.0.7, the complete filename,
 600               including the <span class="QUOTE">".action"</span> extension
 601               has to be specified. The syntax change was necessary to be
 602               consistent with the other file options and to allow previously
 603               forbidden characters.</p>
 604             </dd>
 605           </dl>
 606         </div>
 607       </div>
 608
 609       <div class="SECT3">
 610         <h4 class="SECT3"><a name="FILTERFILE" id="FILTERFILE">7.2.6.
 611         filterfile</a></h4><a name="DEFAULT.FILTER" id="DEFAULT.FILTER"></a>
 612
 613         <div class="VARIABLELIST">
 614           <dl>
 615             <dt>Specifies:</dt>
 616
 617             <dd>
 618               <p>The <a href="filter-file.html">filter file(s)</a> to use</p>
 619             </dd>
 620
 621             <dt>Type of value:</dt>
 622
 623             <dd>
 624               <p>File name, relative to <tt class="LITERAL">confdir</tt></p>
 625             </dd>
 626
 627             <dt>Default value:</dt>
 628
 629             <dd>
 630               <p>default.filter (Unix) <span class="emphasis"><i class=
 631               "EMPHASIS">or</i></span> default.filter.txt (Windows)</p>
 632             </dd>
 633
 634             <dt>Effect if unset:</dt>
 635
 636             <dd>
 637               <p>No textual content filtering takes place, i.e. all
 638               <tt class="LITERAL">+<a href=
 639               "actions-file.html#FILTER">filter</a>{<tt class=
 640               "REPLACEABLE"><i>name</i></tt>}</tt> actions in the actions
 641               files are turned neutral.</p>
 642             </dd>
 643
 644             <dt>Notes:</dt>
 645
 646             <dd>
 647               <p>Multiple <tt class="LITERAL">filterfile</tt> lines are
 648               permitted.</p>
 649
 650               <p>The <a href="filter-file.html">filter files</a> contain
 651               content modification rules that use <a href=
 652               "appendix.html#REGEX">regular expressions</a>. These rules
 653               permit powerful changes on the content of Web pages, and
 654               optionally the headers as well, e.g., you could try to disable
 655               your favorite JavaScript annoyances, re-write the actual
 656               displayed text, or just have some fun playing buzzword bingo
 657               with web pages.</p>
 658
 659               <p>The <tt class="LITERAL">+<a href=
 660               "actions-file.html#FILTER">filter</a>{<tt class=
 661               "REPLACEABLE"><i>name</i></tt>}</tt> actions rely on the
 662               relevant filter (<tt class="REPLACEABLE"><i>name</i></tt>) to
 663               be defined in a filter file!</p>
 664
 665               <p>A pre-defined filter file called <tt class=
 666               "FILENAME">default.filter</tt> that contains a number of useful
 667               filters for common problems is included in the distribution.
 668               See the section on the <tt class="LITERAL"><a href=
 669               "actions-file.html#FILTER">filter</a></tt> action for a
 670               list.</p>
 671
 672               <p>It is recommended to place any locally adapted filters into
 673               a separate file, such as <tt class=
 674               "FILENAME">user.filter</tt>.</p>
 675             </dd>
 676           </dl>
 677         </div>
 678       </div>
 679
 680       <div class="SECT3">
 681         <h4 class="SECT3"><a name="LOGFILE" id="LOGFILE">7.2.7.
 682         logfile</a></h4>
 683
 684         <div class="VARIABLELIST">
 685           <dl>
 686             <dt>Specifies:</dt>
 687
 688             <dd>
 689               <p>The log file to use</p>
 690             </dd>
 691
 692             <dt>Type of value:</dt>
 693
 694             <dd>
 695               <p>File name, relative to <tt class="LITERAL">logdir</tt></p>
 696             </dd>
 697
 698             <dt>Default value:</dt>
 699
 700             <dd>
 701               <p><span class="emphasis"><i class="EMPHASIS">Unset (commented
 702               out)</i></span>. When activated: logfile (Unix) <span class=
 703               "emphasis"><i class="EMPHASIS">or</i></span> privoxy.log
 704               (Windows).</p>
 705             </dd>
 706
 707             <dt>Effect if unset:</dt>
 708
 709             <dd>
 710               <p>No logfile is written.</p>
 711             </dd>
 712
 713             <dt>Notes:</dt>
 714
 715             <dd>
 716               <p>The logfile is where all logging and error messages are
 717               written. The level of detail and number of messages are set
 718               with the <tt class="LITERAL">debug</tt> option (see below). The
 719               logfile can be useful for tracking down a problem with
 720               <span class="APPLICATION">Privoxy</span> (e.g., it's not
 721               blocking an ad you think it should block) and it can help you
 722               to monitor what your browser is doing.</p>
 723
 724               <p>Depending on the debug options below, the logfile may be a
 725               privacy risk if third parties can get access to it. As most
 726               users will never look at it, <span class=
 727               "APPLICATION">Privoxy</span> 3.0.7 and later only log fatal
 728               errors by default.</p>
 729
 730               <p>For most troubleshooting purposes, you will have to change
 731               that, please refer to the debugging section for details.</p>
 732
 733               <p>Your logfile will grow indefinitely, and you will probably
 734               want to periodically remove it. On Unix systems, you can do
 735               this with a cron job (see <span class="QUOTE">"man
 736               cron"</span>).</p>
 737
 738               <p>Any log files must be writable by whatever user <span class=
 739               "APPLICATION">Privoxy</span> is being run as (on Unix, default
 740               user id is <span class="QUOTE">"privoxy"</span>).</p>
 741             </dd>
 742           </dl>
 743         </div>
 744       </div>
 745
 746       <div class="SECT3">
 747         <h4 class="SECT3"><a name="TRUSTFILE" id="TRUSTFILE">7.2.8.
 748         trustfile</a></h4>
 749
 750         <div class="VARIABLELIST">
 751           <dl>
 752             <dt>Specifies:</dt>
 753
 754             <dd>
 755               <p>The name of the trust file to use</p>
 756             </dd>
 757
 758             <dt>Type of value:</dt>
 759
 760             <dd>
 761               <p>File name, relative to <tt class="LITERAL">confdir</tt></p>
 762             </dd>
 763
 764             <dt>Default value:</dt>
 765
 766             <dd>
 767               <p><span class="emphasis"><i class="EMPHASIS">Unset (commented
 768               out)</i></span>. When activated: trust (Unix) <span class=
 769               "emphasis"><i class="EMPHASIS">or</i></span> trust.txt
 770               (Windows)</p>
 771             </dd>
 772
 773             <dt>Effect if unset:</dt>
 774
 775             <dd>
 776               <p>The entire trust mechanism is disabled.</p>
 777             </dd>
 778
 779             <dt>Notes:</dt>
 780
 781             <dd>
 782               <p>The trust mechanism is an experimental feature for building
 783               white-lists and should be used with care. It is <span class=
 784               "emphasis"><i class="EMPHASIS">NOT</i></span> recommended for
 785               the casual user.</p>
 786
 787               <p>If you specify a trust file, <span class=
 788               "APPLICATION">Privoxy</span> will only allow access to sites
 789               that are specified in the trustfile. Sites can be listed in one
 790               of two ways:</p>
 791
 792               <p>Prepending a <tt class="LITERAL">~</tt> character limits
 793               access to this site only (and any sub-paths within this site),
 794               e.g. <tt class="LITERAL">~www.example.com</tt> allows access to
 795               <tt class="LITERAL">~www.example.com/features/news.html</tt>,
 796               etc.</p>
 797
 798               <p>Or, you can designate sites as <span class=
 799               "emphasis"><i class="EMPHASIS">trusted referrers</i></span>, by
 800               prepending the name with a <tt class="LITERAL">+</tt>
 801               character. The effect is that access to untrusted sites will be
 802               granted -- but only if a link from this trusted referrer was
 803               used to get there. The link target will then be added to the
 804               <span class="QUOTE">"trustfile"</span> so that future, direct
 805               accesses will be granted. Sites added via this mechanism do not
 806               become trusted referrers themselves (i.e. they are added with a
 807               <tt class="LITERAL">~</tt> designation). There is a limit of
 808               512 such entries, after which new entries will not be made.</p>
 809
 810               <p>If you use the <tt class="LITERAL">+</tt> operator in the
 811               trust file, it may grow considerably over time.</p>
 812
 813               <p>It is recommended that <span class=
 814               "APPLICATION">Privoxy</span> be compiled with the <tt class=
 815               "LITERAL">--disable-force</tt>, <tt class=
 816               "LITERAL">--disable-toggle</tt> and <tt class=
 817               "LITERAL">--disable-editor</tt> options, if this feature is to
 818               be used.</p>
 819
 820               <p>Possible applications include limiting Internet access for
 821               children.</p>
 822             </dd>
 823           </dl>
 824         </div>
 825       </div>
 826     </div>
 827
 828     <div class="SECT2">
 829       <h2 class="SECT2"><a name="DEBUGGING" id="DEBUGGING">7.3.
 830       Debugging</a></h2>
 831
 832       <p>These options are mainly useful when tracing a problem. Note that
 833       you might also want to invoke <span class="APPLICATION">Privoxy</span>
 834       with the <tt class="LITERAL">--no-daemon</tt> command line option when
 835       debugging.</p>
 836
 837       <div class="SECT3">
 838         <h4 class="SECT3"><a name="DEBUG" id="DEBUG">7.3.1. debug</a></h4>
 839
 840         <div class="VARIABLELIST">
 841           <dl>
 842             <dt>Specifies:</dt>
 843
 844             <dd>
 845               <p>Key values that determine what information gets logged.</p>
 846             </dd>
 847
 848             <dt>Type of value:</dt>
 849
 850             <dd>
 851               <p>Integer values</p>
 852             </dd>
 853
 854             <dt>Default value:</dt>
 855
 856             <dd>
 857               <p>0 (i.e.: only fatal errors (that cause Privoxy to exit) are
 858               logged)</p>
 859             </dd>
 860
 861             <dt>Effect if unset:</dt>
 862
 863             <dd>
 864               <p>Default value is used (see above).</p>
 865             </dd>
 866
 867             <dt>Notes:</dt>
 868
 869             <dd>
 870               <p>The available debug levels are:</p>
 871
 872               <table border="0" bgcolor="#E0E0E0" width="90%">
 873                 <tr>
 874                   <td>
 875                     <pre class="PROGRAMLISTING">
 876   debug     1 # Log the destination for each request <span class=
 877 "APPLICATION">Privoxy</span> let through. See also debug 1024.
 878   debug     2 # show each connection status
 879   debug     4 # show I/O status
 880   debug     8 # show header parsing
 881   debug    16 # log all data written to the network
 882   debug    32 # debug force feature
 883   debug    64 # debug regular expression filters
 884   debug   128 # debug redirects
 885   debug   256 # debug GIF de-animation
 886   debug   512 # Common Log Format
 887   debug  1024 # Log the destination for requests <span class=
 888 "APPLICATION">Privoxy</span> didn't let through, and the reason why.
 889   debug  2048 # CGI user interface
 890   debug  4096 # Startup banner and warnings.
 891   debug  8192 # Non-fatal errors
 892   debug 32768 # log all data read from the network
 893   debug 65536 # Log the applying actions
 894 </pre>
 895                   </td>
 896                 </tr>
 897               </table>
 898
 899               <p>To select multiple debug levels, you can either add them or
 900               use multiple <tt class="LITERAL">debug</tt> lines.</p>
 901
 902               <p>A debug level of 1 is informative because it will show you
 903               each request as it happens. <span class="emphasis"><i class=
 904               "EMPHASIS">1, 1024, 4096 and 8192 are recommended</i></span> so
 905               that you will notice when things go wrong. The other levels are
 906               probably only of interest if you are hunting down a specific
 907               problem. They can produce a hell of an output (especially
 908               16).</p>
 909
 910               <p><span class="APPLICATION">Privoxy</span> used to ship with
 911               the debug levels recommended above enabled by default, but due
 912               to privacy concerns 3.0.7 and later are configured to only log
 913               fatal errors.</p>
 914
 915               <p>If you are used to the more verbose settings, simply enable
 916               the debug lines below again.</p>
 917
 918               <p>If you want to use pure CLF (Common Log Format), you should
 919               set <span class="QUOTE">"debug 512"</span> <span class=
 920               "emphasis"><i class="EMPHASIS">ONLY</i></span> and not enable
 921               anything else.</p>
 922
 923               <p><span class="APPLICATION">Privoxy</span> has a hard-coded
 924               limit for the length of log messages. If it's reached, messages
 925               are logged truncated and marked with <span class="QUOTE">"...
 926               [too long, truncated]"</span>.</p>
 927
 928               <p>Please don't file any support requests without trying to
 929               reproduce the problem with increased debug level first. Once
 930               you read the log messages, you may even be able to solve the
 931               problem on your own.</p>
 932             </dd>
 933           </dl>
 934         </div>
 935       </div>
 936
 937       <div class="SECT3">
 938         <h4 class="SECT3"><a name="SINGLE-THREADED" id=
 939         "SINGLE-THREADED">7.3.2. single-threaded</a></h4>
 940
 941         <div class="VARIABLELIST">
 942           <dl>
 943             <dt>Specifies:</dt>
 944
 945             <dd>
 946               <p>Whether to run only one server thread.</p>
 947             </dd>
 948
 949             <dt>Type of value:</dt>
 950
 951             <dd>
 952               <p><span class="emphasis"><i class="EMPHASIS">1 or
 953               0</i></span></p>
 954             </dd>
 955
 956             <dt>Default value:</dt>
 957
 958             <dd>
 959               <p><span class="emphasis"><i class="EMPHASIS">0</i></span></p>
 960             </dd>
 961
 962             <dt>Effect if unset:</dt>
 963
 964             <dd>
 965               <p>Multi-threaded (or, where unavailable: forked) operation,
 966               i.e. the ability to serve multiple requests simultaneously.</p>
 967             </dd>
 968
 969             <dt>Notes:</dt>
 970
 971             <dd>
 972               <p>This option is only there for debugging purposes.
 973               <span class="emphasis"><i class="EMPHASIS">It will drastically
 974               reduce performance.</i></span></p>
 975             </dd>
 976           </dl>
 977         </div>
 978       </div>
 979
 980       <div class="SECT3">
 981         <h4 class="SECT3"><a name="HOSTNAME" id="HOSTNAME">7.3.3.
 982         hostname</a></h4>
 983
 984         <div class="VARIABLELIST">
 985           <dl>
 986             <dt>Specifies:</dt>
 987
 988             <dd>
 989               <p>The hostname shown on the CGI pages.</p>
 990             </dd>
 991
 992             <dt>Type of value:</dt>
 993
 994             <dd>
 995               <p>Text</p>
 996             </dd>
 997
 998             <dt>Default value:</dt>
 999
1000             <dd>
1001               <p><span class="emphasis"><i class=
1002               "EMPHASIS">Unset</i></span></p>
1003             </dd>
1004
1005             <dt>Effect if unset:</dt>
1006
1007             <dd>
1008               <p>The hostname provided by the operating system is used.</p>
1009             </dd>
1010
1011             <dt>Notes:</dt>
1012
1013             <dd>
1014               <p>On some misconfigured systems resolving the hostname fails
1015               or takes too much time and slows Privoxy down. Setting a fixed
1016               hostname works around the problem.</p>
1017
1018               <p>In other circumstances it might be desirable to show a
1019               hostname other than the one returned by the operating system.
1020               For example if the system has several different hostnames and
1021               you don't want to use the first one.</p>
1022
1023               <p>Note that Privoxy does not validate the specified hostname
1024               value.</p>
1025             </dd>
1026           </dl>
1027         </div>
1028       </div>
1029     </div>
1030
1031     <div class="SECT2">
1032       <h2 class="SECT2"><a name="ACCESS-CONTROL" id="ACCESS-CONTROL">7.4.
1033       Access Control and Security</a></h2>
1034
1035       <p>This section of the config file controls the security-relevant
1036       aspects of <span class="APPLICATION">Privoxy</span>'s
1037       configuration.</p>
1038
1039       <div class="SECT3">
1040         <h4 class="SECT3"><a name="LISTEN-ADDRESS" id="LISTEN-ADDRESS">7.4.1.
1041         listen-address</a></h4>
1042
1043         <div class="VARIABLELIST">
1044           <dl>
1045             <dt>Specifies:</dt>
1046
1047             <dd>
1048               <p>The address and TCP port on which <span class=
1049               "APPLICATION">Privoxy</span> will listen for client
1050               requests.</p>
1051             </dd>
1052
1053             <dt>Type of value:</dt>
1054
1055             <dd>
1056               <p>[<tt class="REPLACEABLE"><i>IP-Address</i></tt>]:<tt class=
1057               "REPLACEABLE"><i>Port</i></tt></p>
1058
1059               <p>[<tt class="REPLACEABLE"><i>Hostname</i></tt>]:<tt class=
1060               "REPLACEABLE"><i>Port</i></tt></p>
1061             </dd>
1062
1063             <dt>Default value:</dt>
1064
1065             <dd>
1066               <p>127.0.0.1:8118</p>
1067             </dd>
1068
1069             <dt>Effect if unset:</dt>
1070
1071             <dd>
1072               <p>Bind to 127.0.0.1 (IPv4 localhost), port 8118. This is
1073               suitable and recommended for home users who run <span class=
1074               "APPLICATION">Privoxy</span> on the same machine as their
1075               browser.</p>
1076             </dd>
1077
1078             <dt>Notes:</dt>
1079
1080             <dd>
1081               <p>You will need to configure your browser(s) to this proxy
1082               address and port.</p>
1083
1084               <p>If you already have another service running on port 8118, or
1085               if you want to serve requests from other machines (e.g. on your
1086               local network) as well, you will need to override the
1087               default.</p>
1088
1089               <p>You can use this statement multiple times to make
1090               <span class="APPLICATION">Privoxy</span> listen on more ports
1091               or more <abbr class="ABBREV">IP</abbr> addresses. Suitable if
1092               your operating system does not support sharing <abbr class=
1093               "ABBREV">IPv6</abbr> and <abbr class="ABBREV">IPv4</abbr>
1094               protocols on the same socket.</p>
1095
1096               <p>If a hostname is used instead of an IP address, <span class=
1097               "APPLICATION">Privoxy</span> will try to resolve it to an IP
1098               address and if there are multiple, use the first one
1099               returned.</p>
1100
1101               <p>If the address for the hostname isn't already known on the
1102               system (for example because it's in /etc/hostname), this may
1103               result in DNS traffic.</p>
1104
1105               <p>If the specified address isn't available on the system, or
1106               if the hostname can't be resolved, <span class=
1107               "APPLICATION">Privoxy</span> will fail to start.</p>
1108
1109               <p>IPv6 addresses containing colons have to be quoted by
1110               brackets. They can only be used if <span class=
1111               "APPLICATION">Privoxy</span> has been compiled with IPv6
1112               support. If you aren't sure if your version supports it, have a
1113               look at <tt class=
1114               "LITERAL">http://config.privoxy.org/show-status</tt>.</p>
1115
1116               <p>Some operating systems will prefer IPv6 to IPv4 addresses
1117               even if the system has no IPv6 connectivity which is usually
1118               not expected by the user. Some even rely on DNS to resolve
1119               localhost which mean the "localhost" address used may not
1120               actually be local.</p>
1121
1122               <p>It is therefore recommended to explicitly configure the
1123               intended IP address instead of relying on the operating system,
1124               unless there's a strong reason not to.</p>
1125
1126               <p>If you leave out the address, <span class=
1127               "APPLICATION">Privoxy</span> will bind to all IPv4 interfaces
1128               (addresses) on your machine and may become reachable from the
1129               Internet and/or the local network. Be aware that some GNU/Linux
1130               distributions modify that behaviour without updating the
1131               documentation. Check for non-standard patches if your
1132               <span class="APPLICATION">Privoxy</span> version behaves
1133               differently.</p>
1134
1135               <p>If you configure <span class="APPLICATION">Privoxy</span> to
1136               be reachable from the network, consider using <a href=
1137               "config.html#ACLS">access control lists</a> (ACL's, see below),
1138               and/or a firewall.</p>
1139
1140               <p>If you open <span class="APPLICATION">Privoxy</span> to
1141               untrusted users, you will also want to make sure that the
1142               following actions are disabled: <tt class="LITERAL"><a href=
1143               "config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions</a></tt>
1144               and <tt class="LITERAL"><a href=
1145               "config.html#ENABLE-REMOTE-TOGGLE">enable-remote-toggle</a></tt></p>
1146             </dd>
1147
1148             <dt>Example:</dt>
1149
1150             <dd>
1151               <p>Suppose you are running <span class=
1152               "APPLICATION">Privoxy</span> on a machine which has the address
1153               192.168.0.1 on your local private network (192.168.0.0) and has
1154               another outside connection with a different address. You want
1155               it to serve requests from inside only:</p>
1156
1157               <table border="0" bgcolor="#E0E0E0" width="90%">
1158                 <tr>
1159                   <td>
1160                     <pre class="PROGRAMLISTING">
1161   listen-address  192.168.0.1:8118
1162 </pre>
1163                   </td>
1164                 </tr>
1165               </table>
1166
1167               <p>Suppose you are running <span class=
1168               "APPLICATION">Privoxy</span> on an IPv6-capable machine and you
1169               want it to listen on the IPv6 address of the loopback
1170               device:</p>
1171
1172               <table border="0" bgcolor="#E0E0E0" width="90%">
1173                 <tr>
1174                   <td>
1175                     <pre class="PROGRAMLISTING">
1176   listen-address [::1]:8118
1177 </pre>
1178                   </td>
1179                 </tr>
1180               </table>
1181             </dd>
1182           </dl>
1183         </div>
1184       </div>
1185
1186       <div class="SECT3">
1187         <h4 class="SECT3"><a name="TOGGLE" id="TOGGLE">7.4.2. toggle</a></h4>
1188
1189         <div class="VARIABLELIST">
1190           <dl>
1191             <dt>Specifies:</dt>
1192
1193             <dd>
1194               <p>Initial state of "toggle" status</p>
1195             </dd>
1196
1197             <dt>Type of value:</dt>
1198
1199             <dd>
1200               <p>1 or 0</p>
1201             </dd>
1202
1203             <dt>Default value:</dt>
1204
1205             <dd>
1206               <p>1</p>
1207             </dd>
1208
1209             <dt>Effect if unset:</dt>
1210
1211             <dd>
1212               <p>Act as if toggled on</p>
1213             </dd>
1214
1215             <dt>Notes:</dt>
1216
1217             <dd>
1218               <p>If set to 0, <span class="APPLICATION">Privoxy</span> will
1219               start in <span class="QUOTE">"toggled off"</span> mode, i.e.
1220               mostly behave like a normal, content-neutral proxy with both ad
1221               blocking and content filtering disabled. See <tt class=
1222               "LITERAL">enable-remote-toggle</tt> below.</p>
1223             </dd>
1224           </dl>
1225         </div>
1226       </div>
1227
1228       <div class="SECT3">
1229         <h4 class="SECT3"><a name="ENABLE-REMOTE-TOGGLE" id=
1230         "ENABLE-REMOTE-TOGGLE">7.4.3. enable-remote-toggle</a></h4>
1231
1232         <div class="VARIABLELIST">
1233           <dl>
1234             <dt>Specifies:</dt>
1235
1236             <dd>
1237               <p>Whether or not the <a href=
1238               "http://config.privoxy.org/toggle" target="_top">web-based
1239               toggle feature</a> may be used</p>
1240             </dd>
1241
1242             <dt>Type of value:</dt>
1243
1244             <dd>
1245               <p>0 or 1</p>
1246             </dd>
1247
1248             <dt>Default value:</dt>
1249
1250             <dd>
1251               <p>0</p>
1252             </dd>
1253
1254             <dt>Effect if unset:</dt>
1255
1256             <dd>
1257               <p>The web-based toggle feature is disabled.</p>
1258             </dd>
1259
1260             <dt>Notes:</dt>
1261
1262             <dd>
1263               <p>When toggled off, <span class="APPLICATION">Privoxy</span>
1264               mostly acts like a normal, content-neutral proxy, i.e. doesn't
1265               block ads or filter content.</p>
1266
1267               <p>Access to the toggle feature can <span class=
1268               "emphasis"><i class="EMPHASIS">not</i></span> be controlled
1269               separately by <span class="QUOTE">"ACLs"</span> or HTTP
1270               authentication, so that everybody who can access <span class=
1271               "APPLICATION">Privoxy</span> (see <span class=
1272               "QUOTE">"ACLs"</span> and <tt class=
1273               "LITERAL">listen-address</tt> above) can toggle it for all
1274               users. So this option is <span class="emphasis"><i class=
1275               "EMPHASIS">not recommended</i></span> for multi-user
1276               environments with untrusted users.</p>
1277
1278               <p>Note that malicious client side code (e.g Java) is also
1279               capable of using this option.</p>
1280
1281               <p>As a lot of <span class="APPLICATION">Privoxy</span> users
1282               don't read documentation, this feature is disabled by
1283               default.</p>
1284
1285               <p>Note that you must have compiled <span class=
1286               "APPLICATION">Privoxy</span> with support for this feature,
1287               otherwise this option has no effect.</p>
1288             </dd>
1289           </dl>
1290         </div>
1291       </div>
1292
1293       <div class="SECT3">
1294         <h4 class="SECT3"><a name="ENABLE-REMOTE-HTTP-TOGGLE" id=
1295         "ENABLE-REMOTE-HTTP-TOGGLE">7.4.4. enable-remote-http-toggle</a></h4>
1296
1297         <div class="VARIABLELIST">
1298           <dl>
1299             <dt>Specifies:</dt>
1300
1301             <dd>
1302               <p>Whether or not Privoxy recognizes special HTTP headers to
1303               change its behaviour.</p>
1304             </dd>
1305
1306             <dt>Type of value:</dt>
1307
1308             <dd>
1309               <p>0 or 1</p>
1310             </dd>
1311
1312             <dt>Default value:</dt>
1313
1314             <dd>
1315               <p>0</p>
1316             </dd>
1317
1318             <dt>Effect if unset:</dt>
1319
1320             <dd>
1321               <p>Privoxy ignores special HTTP headers.</p>
1322             </dd>
1323
1324             <dt>Notes:</dt>
1325
1326             <dd>
1327               <p>When toggled on, the client can change <span class=
1328               "APPLICATION">Privoxy's</span> behaviour by setting special
1329               HTTP headers. Currently the only supported special header is
1330               <span class="QUOTE">"X-Filter: No"</span>, to disable filtering
1331               for the ongoing request, even if it is enabled in one of the
1332               action files.</p>
1333
1334               <p>This feature is disabled by default. If you are using
1335               <span class="APPLICATION">Privoxy</span> in a environment with
1336               trusted clients, you may enable this feature at your
1337               discretion. Note that malicious client side code (e.g Java) is
1338               also capable of using this feature.</p>
1339
1340               <p>This option will be removed in future releases as it has
1341               been obsoleted by the more general header taggers.</p>
1342             </dd>
1343           </dl>
1344         </div>
1345       </div>
1346
1347       <div class="SECT3">
1348         <h4 class="SECT3"><a name="ENABLE-EDIT-ACTIONS" id=
1349         "ENABLE-EDIT-ACTIONS">7.4.5. enable-edit-actions</a></h4>
1350
1351         <div class="VARIABLELIST">
1352           <dl>
1353             <dt>Specifies:</dt>
1354
1355             <dd>
1356               <p>Whether or not the <a href=
1357               "http://config.privoxy.org/show-status" target="_top">web-based
1358               actions file editor</a> may be used</p>
1359             </dd>
1360
1361             <dt>Type of value:</dt>
1362
1363             <dd>
1364               <p>0 or 1</p>
1365             </dd>
1366
1367             <dt>Default value:</dt>
1368
1369             <dd>
1370               <p>0</p>
1371             </dd>
1372
1373             <dt>Effect if unset:</dt>
1374
1375             <dd>
1376               <p>The web-based actions file editor is disabled.</p>
1377             </dd>
1378
1379             <dt>Notes:</dt>
1380
1381             <dd>
1382               <p>Access to the editor can <span class="emphasis"><i class=
1383               "EMPHASIS">not</i></span> be controlled separately by
1384               <span class="QUOTE">"ACLs"</span> or HTTP authentication, so
1385               that everybody who can access <span class=
1386               "APPLICATION">Privoxy</span> (see <span class=
1387               "QUOTE">"ACLs"</span> and <tt class=
1388               "LITERAL">listen-address</tt> above) can modify its
1389               configuration for all users.</p>
1390
1391               <p>This option is <span class="emphasis"><i class=
1392               "EMPHASIS">not recommended</i></span> for environments with
1393               untrusted users and as a lot of <span class=
1394               "APPLICATION">Privoxy</span> users don't read documentation,
1395               this feature is disabled by default.</p>
1396
1397               <p>Note that malicious client side code (e.g Java) is also
1398               capable of using the actions editor and you shouldn't enable
1399               this options unless you understand the consequences and are
1400               sure your browser is configured correctly.</p>
1401
1402               <p>Note that you must have compiled <span class=
1403               "APPLICATION">Privoxy</span> with support for this feature,
1404               otherwise this option has no effect.</p>
1405             </dd>
1406           </dl>
1407         </div>
1408       </div>
1409
1410       <div class="SECT3">
1411         <h4 class="SECT3"><a name="ENFORCE-BLOCKS" id="ENFORCE-BLOCKS">7.4.6.
1412         enforce-blocks</a></h4>
1413
1414         <div class="VARIABLELIST">
1415           <dl>
1416             <dt>Specifies:</dt>
1417
1418             <dd>
1419               <p>Whether the user is allowed to ignore blocks and can
1420               <span class="QUOTE">"go there anyway"</span>.</p>
1421             </dd>
1422
1423             <dt>Type of value:</dt>
1424
1425             <dd>
1426               <p><tt class="REPLACEABLE"><i>0 or 1</i></tt></p>
1427             </dd>
1428
1429             <dt>Default value:</dt>
1430
1431             <dd>
1432               <p><span class="emphasis"><i class="EMPHASIS">0</i></span></p>
1433             </dd>
1434
1435             <dt>Effect if unset:</dt>
1436
1437             <dd>
1438               <p>Blocks are not enforced.</p>
1439             </dd>
1440
1441             <dt>Notes:</dt>
1442
1443             <dd>
1444               <p><span class="APPLICATION">Privoxy</span> is mainly used to
1445               block and filter requests as a service to the user, for example
1446               to block ads and other junk that clogs the pipes. <span class=
1447               "APPLICATION">Privoxy's</span> configuration isn't perfect and
1448               sometimes innocent pages are blocked. In this situation it
1449               makes sense to allow the user to enforce the request and have
1450               <span class="APPLICATION">Privoxy</span> ignore the block.</p>
1451
1452               <p>In the default configuration <span class=
1453               "APPLICATION">Privoxy's</span> <span class=
1454               "QUOTE">"Blocked"</span> page contains a <span class=
1455               "QUOTE">"go there anyway"</span> link to adds a special string
1456               (the force prefix) to the request URL. If that link is used,
1457               <span class="APPLICATION">Privoxy</span> will detect the force
1458               prefix, remove it again and let the request pass.</p>
1459
1460               <p>Of course <span class="APPLICATION">Privoxy</span> can also
1461               be used to enforce a network policy. In that case the user
1462               obviously should not be able to bypass any blocks, and that's
1463               what the <span class="QUOTE">"enforce-blocks"</span> option is
1464               for. If it's enabled, <span class="APPLICATION">Privoxy</span>
1465               hides the <span class="QUOTE">"go there anyway"</span> link. If
1466               the user adds the force prefix by hand, it will not be accepted
1467               and the circumvention attempt is logged.</p>
1468             </dd>
1469
1470             <dt>Examples:</dt>
1471
1472             <dd>
1473               <p>enforce-blocks 1</p>
1474             </dd>
1475           </dl>
1476         </div>
1477       </div>
1478
1479       <div class="SECT3">
1480         <h4 class="SECT3"><a name="ACLS" id="ACLS">7.4.7. ACLs: permit-access
1481         and deny-access</a></h4><a name="PERMIT-ACCESS" id=
1482         "PERMIT-ACCESS"></a><a name="DENY-ACCESS" id="DENY-ACCESS"></a>
1483
1484         <div class="VARIABLELIST">
1485           <dl>
1486             <dt>Specifies:</dt>
1487
1488             <dd>
1489               <p>Who can access what.</p>
1490             </dd>
1491
1492             <dt>Type of value:</dt>
1493
1494             <dd>
1495               <p><tt class="REPLACEABLE"><i>src_addr</i></tt>[:<tt class=
1496               "REPLACEABLE"><i>port</i></tt>][/<tt class=
1497               "REPLACEABLE"><i>src_masklen</i></tt>] [<tt class=
1498               "REPLACEABLE"><i>dst_addr</i></tt>[:<tt class=
1499               "REPLACEABLE"><i>port</i></tt>][/<tt class=
1500               "REPLACEABLE"><i>dst_masklen</i></tt>]]</p>
1501
1502               <p>Where <tt class="REPLACEABLE"><i>src_addr</i></tt> and
1503               <tt class="REPLACEABLE"><i>dst_addr</i></tt> are IPv4 addresses
1504               in dotted decimal notation or valid DNS names, <tt class=
1505               "REPLACEABLE"><i>port</i></tt> is a port number, and <tt class=
1506               "REPLACEABLE"><i>src_masklen</i></tt> and <tt class=
1507               "REPLACEABLE"><i>dst_masklen</i></tt> are subnet masks in CIDR
1508               notation, i.e. integer values from 2 to 30 representing the
1509               length (in bits) of the network address. The masks and the
1510               whole destination part are optional.</p>
1511
1512               <p>If your system implements <a href=
1513               "http://tools.ietf.org/html/rfc3493" target="_top">RFC
1514               3493</a>, then <tt class="REPLACEABLE"><i>src_addr</i></tt> and
1515               <tt class="REPLACEABLE"><i>dst_addr</i></tt> can be IPv6
1516               addresses delimeted by brackets, <tt class=
1517               "REPLACEABLE"><i>port</i></tt> can be a number or a service
1518               name, and <tt class="REPLACEABLE"><i>src_masklen</i></tt> and
1519               <tt class="REPLACEABLE"><i>dst_masklen</i></tt> can be a number
1520               from 0 to 128.</p>
1521             </dd>
1522
1523             <dt>Default value:</dt>
1524
1525             <dd>
1526               <p><span class="emphasis"><i class=
1527               "EMPHASIS">Unset</i></span></p>
1528
1529               <p>If no <tt class="REPLACEABLE"><i>port</i></tt> is specified,
1530               any port will match. If no <tt class=
1531               "REPLACEABLE"><i>src_masklen</i></tt> or <tt class=
1532               "REPLACEABLE"><i>src_masklen</i></tt> is given, the complete IP
1533               address has to match (i.e. 32 bits for IPv4 and 128 bits for
1534               IPv6).</p>
1535             </dd>
1536
1537             <dt>Effect if unset:</dt>
1538
1539             <dd>
1540               <p>Don't restrict access further than implied by <tt class=
1541               "LITERAL">listen-address</tt></p>
1542             </dd>
1543
1544             <dt>Notes:</dt>
1545
1546             <dd>
1547               <p>Access controls are included at the request of ISPs and
1548               systems administrators, and <span class="emphasis"><i class=
1549               "EMPHASIS">are not usually needed by individual
1550               users</i></span>. For a typical home user, it will normally
1551               suffice to ensure that <span class="APPLICATION">Privoxy</span>
1552               only listens on the localhost (127.0.0.1) or internal (home)
1553               network address by means of the <a href=
1554               "config.html#LISTEN-ADDRESS"><span class="emphasis"><i class=
1555               "EMPHASIS">listen-address</i></span></a> option.</p>
1556
1557               <p>Please see the warnings in the FAQ that <span class=
1558               "APPLICATION">Privoxy</span> is not intended to be a substitute
1559               for a firewall or to encourage anyone to defer addressing basic
1560               security weaknesses.</p>
1561
1562               <p>Multiple ACL lines are OK. If any ACLs are specified,
1563               <span class="APPLICATION">Privoxy</span> only talks to IP
1564               addresses that match at least one <tt class=
1565               "LITERAL">permit-access</tt> line and don't match any
1566               subsequent <tt class="LITERAL">deny-access</tt> line. In other
1567               words, the last match wins, with the default being <tt class=
1568               "LITERAL">deny-access</tt>.</p>
1569
1570               <p>If <span class="APPLICATION">Privoxy</span> is using a
1571               forwarder (see <tt class="LITERAL">forward</tt> below) for a
1572               particular destination URL, the <tt class=
1573               "REPLACEABLE"><i>dst_addr</i></tt> that is examined is the
1574               address of the forwarder and <span class="emphasis"><i class=
1575               "EMPHASIS">NOT</i></span> the address of the ultimate target.
1576               This is necessary because it may be impossible for the local
1577               <span class="APPLICATION">Privoxy</span> to determine the IP
1578               address of the ultimate target (that's often what gateways are
1579               used for).</p>
1580
1581               <p>You should prefer using IP addresses over DNS names, because
1582               the address lookups take time. All DNS names must resolve! You
1583               can <span class="emphasis"><i class="EMPHASIS">not</i></span>
1584               use domain patterns like <span class="QUOTE">"*.org"</span> or
1585               partial domain names. If a DNS name resolves to multiple IP
1586               addresses, only the first one is used.</p>
1587
1588               <p>Some systems allow IPv4 clients to connect to IPv6 server
1589               sockets. Then the client's IPv4 address will be translated by
1590               the system into IPv6 address space with special prefix
1591               ::ffff:0:0/96 (so called IPv4 mapped IPv6 address).
1592               <span class="APPLICATION">Privoxy</span> can handle it and maps
1593               such ACL addresses automatically.</p>
1594
1595               <p>Denying access to particular sites by ACL may have undesired
1596               side effects if the site in question is hosted on a machine
1597               which also hosts other sites (most sites are).</p>
1598             </dd>
1599
1600             <dt>Examples:</dt>
1601
1602             <dd>
1603               <p>Explicitly define the default behavior if no ACL and
1604               <tt class="LITERAL">listen-address</tt> are set: <span class=
1605               "QUOTE">"localhost"</span> is OK. The absence of a <tt class=
1606               "REPLACEABLE"><i>dst_addr</i></tt> implies that <span class=
1607               "emphasis"><i class="EMPHASIS">all</i></span> destination
1608               addresses are OK:</p>
1609
1610               <table border="0" bgcolor="#E0E0E0" width="90%">
1611                 <tr>
1612                   <td>
1613                     <pre class="SCREEN">
1614   permit-access  localhost
1615 </pre>
1616                   </td>
1617                 </tr>
1618               </table>
1619
1620               <p>Allow any host on the same class C subnet as www.privoxy.org
1621               access to nothing but www.example.com (or other domains hosted
1622               on the same system):</p>
1623
1624               <table border="0" bgcolor="#E0E0E0" width="90%">
1625                 <tr>
1626                   <td>
1627                     <pre class="SCREEN">
1628   permit-access  www.privoxy.org/24 www.example.com/32
1629 </pre>
1630                   </td>
1631                 </tr>
1632               </table>
1633
1634               <p>Allow access from any host on the 26-bit subnet
1635               192.168.45.64 to anywhere, with the exception that
1636               192.168.45.73 may not access the IP address behind
1637               www.dirty-stuff.example.com:</p>
1638
1639               <table border="0" bgcolor="#E0E0E0" width="90%">
1640                 <tr>
1641                   <td>
1642                     <pre class="SCREEN">
1643   permit-access  192.168.45.64/26
1644   deny-access    192.168.45.73    www.dirty-stuff.example.com
1645 </pre>
1646                   </td>
1647                 </tr>
1648               </table>
1649
1650               <p>Allow access from the IPv4 network 192.0.2.0/24 even if
1651               listening on an IPv6 wild card address (not supported on all
1652               platforms):</p>
1653
1654               <table border="0" bgcolor="#E0E0E0" width="90%">
1655                 <tr>
1656                   <td>
1657                     <pre class="PROGRAMLISTING">
1658   permit-access  192.0.2.0/24
1659 </pre>
1660                   </td>
1661                 </tr>
1662               </table>
1663
1664               <p>This is equivalent to the following line even if listening
1665               on an IPv4 address (not supported on all platforms):</p>
1666
1667               <table border="0" bgcolor="#E0E0E0" width="90%">
1668                 <tr>
1669                   <td>
1670                     <pre class="PROGRAMLISTING">
1671   permit-access  [::ffff:192.0.2.0]/120
1672 </pre>
1673                   </td>
1674                 </tr>
1675               </table>
1676             </dd>
1677           </dl>
1678         </div>
1679       </div>
1680
1681       <div class="SECT3">
1682         <h4 class="SECT3"><a name="BUFFER-LIMIT" id="BUFFER-LIMIT">7.4.8.
1683         buffer-limit</a></h4>
1684
1685         <div class="VARIABLELIST">
1686           <dl>
1687             <dt>Specifies:</dt>
1688
1689             <dd>
1690               <p>Maximum size of the buffer for content filtering.</p>
1691             </dd>
1692
1693             <dt>Type of value:</dt>
1694
1695             <dd>
1696               <p>Size in Kbytes</p>
1697             </dd>
1698
1699             <dt>Default value:</dt>
1700
1701             <dd>
1702               <p>4096</p>
1703             </dd>
1704
1705             <dt>Effect if unset:</dt>
1706
1707             <dd>
1708               <p>Use a 4MB (4096 KB) limit.</p>
1709             </dd>
1710
1711             <dt>Notes:</dt>
1712
1713             <dd>
1714               <p>For content filtering, i.e. the <tt class=
1715               "LITERAL">+filter</tt> and <tt class=
1716               "LITERAL">+deanimate-gif</tt> actions, it is necessary that
1717               <span class="APPLICATION">Privoxy</span> buffers the entire
1718               document body. This can be potentially dangerous, since a
1719               server could just keep sending data indefinitely and wait for
1720               your RAM to exhaust -- with nasty consequences. Hence this
1721               option.</p>
1722
1723               <p>When a document buffer size reaches the <tt class=
1724               "LITERAL">buffer-limit</tt>, it is flushed to the client
1725               unfiltered and no further attempt to filter the rest of the
1726               document is made. Remember that there may be multiple threads
1727               running, which might require up to <tt class=
1728               "LITERAL">buffer-limit</tt> Kbytes <span class=
1729               "emphasis"><i class="EMPHASIS">each</i></span>, unless you have
1730               enabled <span class="QUOTE">"single-threaded"</span> above.</p>
1731             </dd>
1732           </dl>
1733         </div>
1734       </div>
1735
1736       <div class="SECT3">
1737         <h4 class="SECT3"><a name="ENABLE-PROXY-AUTHENTICATION-FORWARDING"
1738         id="ENABLE-PROXY-AUTHENTICATION-FORWARDING">7.4.9.
1739         enable-proxy-authentication-forwarding</a></h4>
1740
1741         <div class="VARIABLELIST">
1742           <dl>
1743             <dt>Specifies:</dt>
1744
1745             <dd>
1746               <p>Whether or not proxy authentication through <span class=
1747               "APPLICATION">Privoxy</span> should work.</p>
1748             </dd>
1749
1750             <dt>Type of value:</dt>
1751
1752             <dd>
1753               <p>0 or 1</p>
1754             </dd>
1755
1756             <dt>Default value:</dt>
1757
1758             <dd>
1759               <p>0</p>
1760             </dd>
1761
1762             <dt>Effect if unset:</dt>
1763
1764             <dd>
1765               <p>Proxy authentication headers are removed.</p>
1766             </dd>
1767
1768             <dt>Notes:</dt>
1769
1770             <dd>
1771               <p>Privoxy itself does not support proxy authentication, but
1772               can allow clients to authenticate against Privoxy's parent
1773               proxy.</p>
1774
1775               <p>By default Privoxy (3.0.21 and later) don't do that and
1776               remove Proxy-Authorization headers in requests and
1777               Proxy-Authenticate headers in responses to make it harder for
1778               malicious sites to trick inexperienced users into providing
1779               login information.</p>
1780
1781               <p>If this option is enabled the headers are forwarded.</p>
1782
1783               <p>Enabling this option is <span class="emphasis"><i class=
1784               "EMPHASIS">not recommended</i></span> if there is no parent
1785               proxy that requires authentication or if the local network
1786               between Privoxy and the parent proxy isn't trustworthy. If
1787               proxy authentication is only required for some requests, it is
1788               recommended to use a client header filter to remove the
1789               authentication headers for requests where they aren't
1790               needed.</p>
1791             </dd>
1792           </dl>
1793         </div>
1794       </div>
1795     </div>
1796
1797     <div class="SECT2">
1798       <h2 class="SECT2"><a name="FORWARDING" id="FORWARDING">7.5.
1799       Forwarding</a></h2>
1800
1801       <p>This feature allows routing of HTTP requests through a chain of
1802       multiple proxies.</p>
1803
1804       <p>Forwarding can be used to chain Privoxy with a caching proxy to
1805       speed up browsing. Using a parent proxy may also be necessary if the
1806       machine that <span class="APPLICATION">Privoxy</span> runs on has no
1807       direct Internet access.</p>
1808
1809       <p>Note that parent proxies can severely decrease your privacy level.
1810       For example a parent proxy could add your IP address to the request
1811       headers and if it's a caching proxy it may add the <span class=
1812       "QUOTE">"Etag"</span> header to revalidation requests again, even
1813       though you configured Privoxy to remove it. It may also ignore
1814       Privoxy's header time randomization and use the original values which
1815       could be used by the server as cookie replacement to track your steps
1816       between visits.</p>
1817
1818       <p>Also specified here are SOCKS proxies. <span class=
1819       "APPLICATION">Privoxy</span> supports the SOCKS 4 and SOCKS 4A
1820       protocols.</p>
1821
1822       <div class="SECT3">
1823         <h4 class="SECT3"><a name="FORWARD" id="FORWARD">7.5.1.
1824         forward</a></h4>
1825
1826         <div class="VARIABLELIST">
1827           <dl>
1828             <dt>Specifies:</dt>
1829
1830             <dd>
1831               <p>To which parent HTTP proxy specific requests should be
1832               routed.</p>
1833             </dd>
1834
1835             <dt>Type of value:</dt>
1836
1837             <dd>
1838               <p><tt class="REPLACEABLE"><i>target_pattern</i></tt>
1839               <tt class="REPLACEABLE"><i>http_parent</i></tt>[:<tt class=
1840               "REPLACEABLE"><i>port</i></tt>]</p>
1841
1842               <p>where <tt class="REPLACEABLE"><i>target_pattern</i></tt> is
1843               a <a href="actions-file.html#AF-PATTERNS">URL pattern</a> that
1844               specifies to which requests (i.e. URLs) this forward rule shall
1845               apply. Use <tt class="LITERAL">/</tt> to denote <span class=
1846               "QUOTE">"all URLs"</span>. <tt class=
1847               "REPLACEABLE"><i>http_parent</i></tt>[:<tt class=
1848               "REPLACEABLE"><i>port</i></tt>] is the DNS name or IP address
1849               of the parent HTTP proxy through which the requests should be
1850               forwarded, optionally followed by its listening port (default:
1851               8000). Use a single dot (<tt class="LITERAL">.</tt>) to denote
1852               <span class="QUOTE">"no forwarding"</span>.</p>
1853             </dd>
1854
1855             <dt>Default value:</dt>
1856
1857             <dd>
1858               <p><span class="emphasis"><i class=
1859               "EMPHASIS">Unset</i></span></p>
1860             </dd>
1861
1862             <dt>Effect if unset:</dt>
1863
1864             <dd>
1865               <p>Don't use parent HTTP proxies.</p>
1866             </dd>
1867
1868             <dt>Notes:</dt>
1869
1870             <dd>
1871               <p>If <tt class="REPLACEABLE"><i>http_parent</i></tt> is
1872               <span class="QUOTE">"."</span>, then requests are not forwarded
1873               to another HTTP proxy but are made directly to the web
1874               servers.</p>
1875
1876               <p><tt class="REPLACEABLE"><i>http_parent</i></tt> can be a
1877               numerical IPv6 address (if <a href=
1878               "http://tools.ietf.org/html/rfc3493" target="_top">RFC 3493</a>
1879               is implemented). To prevent clashes with the port delimiter,
1880               the whole IP address has to be put into brackets. On the other
1881               hand a <tt class="REPLACEABLE"><i>target_pattern</i></tt>
1882               containing an IPv6 address has to be put into angle brackets
1883               (normal brackets are reserved for regular expressions
1884               already).</p>
1885
1886               <p>Multiple lines are OK, they are checked in sequence, and the
1887               last match wins.</p>
1888             </dd>
1889
1890             <dt>Examples:</dt>
1891
1892             <dd>
1893               <p>Everything goes to an example parent proxy, except SSL on
1894               port 443 (which it doesn't handle):</p>
1895
1896               <table border="0" bgcolor="#E0E0E0" width="90%">
1897                 <tr>
1898                   <td>
1899                     <pre class="SCREEN">
1900   forward   /      parent-proxy.example.org:8080
1901   forward   :443   .
1902 </pre>
1903                   </td>
1904                 </tr>
1905               </table>
1906
1907               <p>Everything goes to our example ISP's caching proxy, except
1908               for requests to that ISP's sites:</p>
1909
1910               <table border="0" bgcolor="#E0E0E0" width="90%">
1911                 <tr>
1912                   <td>
1913                     <pre class="SCREEN">
1914   forward   /                  caching-proxy.isp.example.net:8000
1915   forward   .isp.example.net   .
1916 </pre>
1917                   </td>
1918                 </tr>
1919               </table>
1920
1921               <p>Parent proxy specified by an IPv6 address:</p>
1922
1923               <table border="0" bgcolor="#E0E0E0" width="90%">
1924                 <tr>
1925                   <td>
1926                     <pre class="PROGRAMLISTING">
1927   forward   /                   [2001:DB8::1]:8000
1928 </pre>
1929                   </td>
1930                 </tr>
1931               </table>
1932
1933               <p>Suppose your parent proxy doesn't support IPv6:</p>
1934
1935               <table border="0" bgcolor="#E0E0E0" width="90%">
1936                 <tr>
1937                   <td>
1938                     <pre class="PROGRAMLISTING">
1939   forward  /                        parent-proxy.example.org:8000
1940   forward  ipv6-server.example.org  .
1941   forward  &lt;[2-3][0-9a-f][0-9a-f][0-9a-f]:*&gt;   .
1942 </pre>
1943                   </td>
1944                 </tr>
1945               </table>
1946             </dd>
1947           </dl>
1948         </div>
1949       </div>
1950
1951       <div class="SECT3">
1952         <h4 class="SECT3"><a name="SOCKS" id="SOCKS">7.5.2. forward-socks4,
1953         forward-socks4a, forward-socks5 and forward-socks5t</a></h4><a name=
1954         "FORWARD-SOCKS4" id="FORWARD-SOCKS4"></a><a name="FORWARD-SOCKS4A"
1955         id="FORWARD-SOCKS4A"></a>
1956
1957         <div class="VARIABLELIST">
1958           <dl>
1959             <dt>Specifies:</dt>
1960
1961             <dd>
1962               <p>Through which SOCKS proxy (and optionally to which parent
1963               HTTP proxy) specific requests should be routed.</p>
1964             </dd>
1965
1966             <dt>Type of value:</dt>
1967
1968             <dd>
1969               <p><tt class="REPLACEABLE"><i>target_pattern</i></tt>
1970               <tt class="REPLACEABLE"><i>socks_proxy</i></tt>[:<tt class=
1971               "REPLACEABLE"><i>port</i></tt>] <tt class=
1972               "REPLACEABLE"><i>http_parent</i></tt>[:<tt class=
1973               "REPLACEABLE"><i>port</i></tt>]</p>
1974
1975               <p>where <tt class="REPLACEABLE"><i>target_pattern</i></tt> is
1976               a <a href="actions-file.html#AF-PATTERNS">URL pattern</a> that
1977               specifies to which requests (i.e. URLs) this forward rule shall
1978               apply. Use <tt class="LITERAL">/</tt> to denote <span class=
1979               "QUOTE">"all URLs"</span>. <tt class=
1980               "REPLACEABLE"><i>http_parent</i></tt> and <tt class=
1981               "REPLACEABLE"><i>socks_proxy</i></tt> are IP addresses in
1982               dotted decimal notation or valid DNS names (<tt class=
1983               "REPLACEABLE"><i>http_parent</i></tt> may be <span class=
1984               "QUOTE">"."</span> to denote <span class="QUOTE">"no HTTP
1985               forwarding"</span>), and the optional <tt class=
1986               "REPLACEABLE"><i>port</i></tt> parameters are TCP ports, i.e.
1987               integer values from 1 to 65535</p>
1988             </dd>
1989
1990             <dt>Default value:</dt>
1991
1992             <dd>
1993               <p><span class="emphasis"><i class=
1994               "EMPHASIS">Unset</i></span></p>
1995             </dd>
1996
1997             <dt>Effect if unset:</dt>
1998
1999             <dd>
2000               <p>Don't use SOCKS proxies.</p>
2001             </dd>
2002
2003             <dt>Notes:</dt>
2004
2005             <dd>
2006               <p>Multiple lines are OK, they are checked in sequence, and the
2007               last match wins.</p>
2008
2009               <p>The difference between <tt class=
2010               "LITERAL">forward-socks4</tt> and <tt class=
2011               "LITERAL">forward-socks4a</tt> is that in the SOCKS 4A
2012               protocol, the DNS resolution of the target hostname happens on
2013               the SOCKS server, while in SOCKS 4 it happens locally.</p>
2014
2015               <p>With <tt class="LITERAL">forward-socks5</tt> the DNS
2016               resolution will happen on the remote server as well.</p>
2017
2018               <p><tt class="LITERAL">forward-socks5t</tt> works like vanilla
2019               <tt class="LITERAL">forward-socks5</tt> but lets <span class=
2020               "APPLICATION">Privoxy</span> additionally use Tor-specific
2021               SOCKS extensions. Currently the only supported SOCKS extension
2022               is optimistic data which can reduce the latency for the first
2023               request made on a newly created connection.</p>
2024
2025               <p><tt class="REPLACEABLE"><i>socks_proxy</i></tt> and
2026               <tt class="REPLACEABLE"><i>http_parent</i></tt> can be a
2027               numerical IPv6 address (if <a href=
2028               "http://tools.ietf.org/html/rfc3493" target="_top">RFC 3493</a>
2029               is implemented). To prevent clashes with the port delimiter,
2030               the whole IP address has to be put into brackets. On the other
2031               hand a <tt class="REPLACEABLE"><i>target_pattern</i></tt>
2032               containing an IPv6 address has to be put into angle brackets
2033               (normal brackets are reserved for regular expressions
2034               already).</p>
2035
2036               <p>If <tt class="REPLACEABLE"><i>http_parent</i></tt> is
2037               <span class="QUOTE">"."</span>, then requests are not forwarded
2038               to another HTTP proxy but are made (HTTP-wise) directly to the
2039               web servers, albeit through a SOCKS proxy.</p>
2040             </dd>
2041
2042             <dt>Examples:</dt>
2043
2044             <dd>
2045               <p>From the company example.com, direct connections are made to
2046               all <span class="QUOTE">"internal"</span> domains, but
2047               everything outbound goes through their ISP's proxy by way of
2048               example.com's corporate SOCKS 4A gateway to the Internet.</p>
2049
2050               <table border="0" bgcolor="#E0E0E0" width="90%">
2051                 <tr>
2052                   <td>
2053                     <pre class="SCREEN">
2054   forward-socks4a   /              socks-gw.example.com:1080  www-cache.isp.example.net:8080
2055   forward           .example.com   .
2056 </pre>
2057                   </td>
2058                 </tr>
2059               </table>
2060
2061               <p>A rule that uses a SOCKS 4 gateway for all destinations but
2062               no HTTP parent looks like this:</p>
2063
2064               <table border="0" bgcolor="#E0E0E0" width="90%">
2065                 <tr>
2066                   <td>
2067                     <pre class="SCREEN">
2068   forward-socks4   /               socks-gw.example.com:1080  .
2069 </pre>
2070                   </td>
2071                 </tr>
2072               </table>
2073
2074               <p>To chain Privoxy and Tor, both running on the same system,
2075               you would use something like:</p>
2076
2077               <table border="0" bgcolor="#E0E0E0" width="90%">
2078                 <tr>
2079                   <td>
2080                     <pre class="SCREEN">
2081   forward-socks5t   /               127.0.0.1:9050 .
2082 </pre>
2083                   </td>
2084                 </tr>
2085               </table>
2086
2087               <p>The public <span class="APPLICATION">Tor</span> network
2088               can't be used to reach your local network, if you need to
2089               access local servers you therefore might want to make some
2090               exceptions:</p>
2091
2092               <table border="0" bgcolor="#E0E0E0" width="90%">
2093                 <tr>
2094                   <td>
2095                     <pre class="SCREEN">
2096   forward         192.168.*.*/     .
2097   forward            10.*.*.*/     .
2098   forward           127.*.*.*/     .
2099 </pre>
2100                   </td>
2101                 </tr>
2102               </table>
2103
2104               <p>Unencrypted connections to systems in these address ranges
2105               will be as (un)secure as the local network is, but the
2106               alternative is that you can't reach the local network through
2107               <span class="APPLICATION">Privoxy</span> at all. Of course this
2108               may actually be desired and there is no reason to make these
2109               exceptions if you aren't sure you need them.</p>
2110
2111               <p>If you also want to be able to reach servers in your local
2112               network by using their names, you will need additional
2113               exceptions that look like this:</p>
2114
2115               <table border="0" bgcolor="#E0E0E0" width="90%">
2116                 <tr>
2117                   <td>
2118                     <pre class="SCREEN">
2119  forward           localhost/     .
2120 </pre>
2121                   </td>
2122                 </tr>
2123               </table>
2124             </dd>
2125           </dl>
2126         </div>
2127       </div>
2128
2129       <div class="SECT3">
2130         <h4 class="SECT3"><a name="ADVANCED-FORWARDING-EXAMPLES" id=
2131         "ADVANCED-FORWARDING-EXAMPLES">7.5.3. Advanced Forwarding
2132         Examples</a></h4>
2133
2134         <p>If you have links to multiple ISPs that provide various special
2135         content only to their subscribers, you can configure multiple
2136         <span class="APPLICATION">Privoxies</span> which have connections to
2137         the respective ISPs to act as forwarders to each other, so that
2138         <span class="emphasis"><i class="EMPHASIS">your</i></span> users can
2139         see the internal content of all ISPs.</p>
2140
2141         <p>Assume that host-a has a PPP connection to isp-a.example.net. And
2142         host-b has a PPP connection to isp-b.example.org. Both run
2143         <span class="APPLICATION">Privoxy</span>. Their forwarding
2144         configuration can look like this:</p>
2145
2146         <p>host-a:</p>
2147
2148         <table border="0" bgcolor="#E0E0E0" width="100%">
2149           <tr>
2150             <td>
2151               <pre class="SCREEN">
2152   forward    /           .
2153   forward    .isp-b.example.net  host-b:8118
2154 </pre>
2155             </td>
2156           </tr>
2157         </table>
2158
2159         <p>host-b:</p>
2160
2161         <table border="0" bgcolor="#E0E0E0" width="100%">
2162           <tr>
2163             <td>
2164               <pre class="SCREEN">
2165   forward    /           .
2166   forward    .isp-a.example.org  host-a:8118
2167 </pre>
2168             </td>
2169           </tr>
2170         </table>
2171
2172         <p>Now, your users can set their browser's proxy to use either host-a
2173         or host-b and be able to browse the internal content of both isp-a
2174         and isp-b.</p>
2175
2176         <p>If you intend to chain <span class="APPLICATION">Privoxy</span>
2177         and <span class="APPLICATION">squid</span> locally, then chaining as
2178         <tt class="LITERAL">browser -&gt; squid -&gt; privoxy</tt> is the
2179         recommended way.</p>
2180
2181         <p>Assuming that <span class="APPLICATION">Privoxy</span> and
2182         <span class="APPLICATION">squid</span> run on the same box, your
2183         <span class="APPLICATION">squid</span> configuration could then look
2184         like this:</p>
2185
2186         <table border="0" bgcolor="#E0E0E0" width="100%">
2187           <tr>
2188             <td>
2189               <pre class="SCREEN">
2190   # Define Privoxy as parent proxy (without ICP)
2191   cache_peer 127.0.0.1 parent 8118 7 no-query
2192
2193   # Define ACL for protocol FTP
2194   acl ftp proto FTP
2195
2196   # Do not forward FTP requests to Privoxy
2197   always_direct allow ftp
2198
2199   # Forward all the rest to Privoxy
2200   never_direct allow all
2201 </pre>
2202             </td>
2203           </tr>
2204         </table>
2205
2206         <p>You would then need to change your browser's proxy settings to
2207         <span class="APPLICATION">squid</span>'s address and port. Squid
2208         normally uses port 3128. If unsure consult <tt class=
2209         "LITERAL">http_port</tt> in <tt class="FILENAME">squid.conf</tt>.</p>
2210
2211         <p>You could just as well decide to only forward requests you suspect
2212         of leading to Windows executables through a virus-scanning parent
2213         proxy, say, on <tt class="LITERAL">antivir.example.com</tt>, port
2214         8010:</p>
2215
2216         <table border="0" bgcolor="#E0E0E0" width="100%">
2217           <tr>
2218             <td>
2219               <pre class="SCREEN">
2220   forward   /                          .
2221   forward   /.*\.(exe|com|dll|zip)$    antivir.example.com:8010
2222 </pre>
2223             </td>
2224           </tr>
2225         </table>
2226       </div>
2227
2228       <div class="SECT3">
2229         <h4 class="SECT3"><a name="FORWARDED-CONNECT-RETRIES" id=
2230         "FORWARDED-CONNECT-RETRIES">7.5.4. forwarded-connect-retries</a></h4>
2231
2232         <div class="VARIABLELIST">
2233           <dl>
2234             <dt>Specifies:</dt>
2235
2236             <dd>
2237               <p>How often Privoxy retries if a forwarded connection request
2238               fails.</p>
2239             </dd>
2240
2241             <dt>Type of value:</dt>
2242
2243             <dd>
2244               <p><tt class="REPLACEABLE"><i>Number of retries.</i></tt></p>
2245             </dd>
2246
2247             <dt>Default value:</dt>
2248
2249             <dd>
2250               <p><span class="emphasis"><i class="EMPHASIS">0</i></span></p>
2251             </dd>
2252
2253             <dt>Effect if unset:</dt>
2254
2255             <dd>
2256               <p>Connections forwarded through other proxies are treated like
2257               direct connections and no retry attempts are made.</p>
2258             </dd>
2259
2260             <dt>Notes:</dt>
2261
2262             <dd>
2263               <p><tt class=
2264               "REPLACEABLE"><i>forwarded-connect-retries</i></tt> is mainly
2265               interesting for socks4a connections, where <span class=
2266               "APPLICATION">Privoxy</span> can't detect why the connections
2267               failed. The connection might have failed because of a DNS
2268               timeout in which case a retry makes sense, but it might also
2269               have failed because the server doesn't exist or isn't
2270               reachable. In this case the retry will just delay the
2271               appearance of Privoxy's error message.</p>
2272
2273               <p>Note that in the context of this option, <span class=
2274               "QUOTE">"forwarded connections"</span> includes all connections
2275               that Privoxy forwards through other proxies. This option is not
2276               limited to the HTTP CONNECT method.</p>
2277
2278               <p>Only use this option, if you are getting lots of
2279               forwarding-related error messages that go away when you try
2280               again manually. Start with a small value and check Privoxy's
2281               logfile from time to time, to see how many retries are usually
2282               needed.</p>
2283             </dd>
2284
2285             <dt>Examples:</dt>
2286
2287             <dd>
2288               <p>forwarded-connect-retries 1</p>
2289             </dd>
2290           </dl>
2291         </div>
2292       </div>
2293     </div>
2294
2295     <div class="SECT2">
2296       <h2 class="SECT2"><a name="MISC" id="MISC">7.6. Miscellaneous</a></h2>
2297
2298       <div class="SECT3">
2299         <h4 class="SECT3"><a name="ACCEPT-INTERCEPTED-REQUESTS" id=
2300         "ACCEPT-INTERCEPTED-REQUESTS">7.6.1.
2301         accept-intercepted-requests</a></h4>
2302
2303         <div class="VARIABLELIST">
2304           <dl>
2305             <dt>Specifies:</dt>
2306
2307             <dd>
2308               <p>Whether intercepted requests should be treated as valid.</p>
2309             </dd>
2310
2311             <dt>Type of value:</dt>
2312
2313             <dd>
2314               <p><tt class="REPLACEABLE"><i>0 or 1</i></tt></p>
2315             </dd>
2316
2317             <dt>Default value:</dt>
2318
2319             <dd>
2320               <p><span class="emphasis"><i class="EMPHASIS">0</i></span></p>
2321             </dd>
2322
2323             <dt>Effect if unset:</dt>
2324
2325             <dd>
2326               <p>Only proxy requests are accepted, intercepted requests are
2327               treated as invalid.</p>
2328             </dd>
2329
2330             <dt>Notes:</dt>
2331
2332             <dd>
2333               <p>If you don't trust your clients and want to force them to
2334               use <span class="APPLICATION">Privoxy</span>, enable this
2335               option and configure your packet filter to redirect outgoing
2336               HTTP connections into <span class=
2337               "APPLICATION">Privoxy</span>.</p>
2338
2339               <p>Note that intercepting encrypted connections (HTTPS) isn't
2340               supported.</p>
2341
2342               <p>Make sure that <span class="APPLICATION">Privoxy's</span>
2343               own requests aren't redirected as well. Additionally take care
2344               that <span class="APPLICATION">Privoxy</span> can't
2345               intentionally connect to itself, otherwise you could run into
2346               redirection loops if <span class="APPLICATION">Privoxy's</span>
2347               listening port is reachable by the outside or an attacker has
2348               access to the pages you visit.</p>
2349             </dd>
2350
2351             <dt>Examples:</dt>
2352
2353             <dd>
2354               <p>accept-intercepted-requests 1</p>
2355             </dd>
2356           </dl>
2357         </div>
2358       </div>
2359
2360       <div class="SECT3">
2361         <h4 class="SECT3"><a name="ALLOW-CGI-REQUEST-CRUNCHING" id=
2362         "ALLOW-CGI-REQUEST-CRUNCHING">7.6.2.
2363         allow-cgi-request-crunching</a></h4>
2364
2365         <div class="VARIABLELIST">
2366           <dl>
2367             <dt>Specifies:</dt>
2368
2369             <dd>
2370               <p>Whether requests to <span class=
2371               "APPLICATION">Privoxy's</span> CGI pages can be blocked or
2372               redirected.</p>
2373             </dd>
2374
2375             <dt>Type of value:</dt>
2376
2377             <dd>
2378               <p><tt class="REPLACEABLE"><i>0 or 1</i></tt></p>
2379             </dd>
2380
2381             <dt>Default value:</dt>
2382
2383             <dd>
2384               <p><span class="emphasis"><i class="EMPHASIS">0</i></span></p>
2385             </dd>
2386
2387             <dt>Effect if unset:</dt>
2388
2389             <dd>
2390               <p><span class="APPLICATION">Privoxy</span> ignores block and
2391               redirect actions for its CGI pages.</p>
2392             </dd>
2393
2394             <dt>Notes:</dt>
2395
2396             <dd>
2397               <p>By default <span class="APPLICATION">Privoxy</span> ignores
2398               block or redirect actions for its CGI pages. Intercepting these
2399               requests can be useful in multi-user setups to implement
2400               fine-grained access control, but it can also render the
2401               complete web interface useless and make debugging problems
2402               painful if done without care.</p>
2403
2404               <p>Don't enable this option unless you're sure that you really
2405               need it.</p>
2406             </dd>
2407
2408             <dt>Examples:</dt>
2409
2410             <dd>
2411               <p>allow-cgi-request-crunching 1</p>
2412             </dd>
2413           </dl>
2414         </div>
2415       </div>
2416
2417       <div class="SECT3">
2418         <h4 class="SECT3"><a name="SPLIT-LARGE-FORMS" id=
2419         "SPLIT-LARGE-FORMS">7.6.3. split-large-forms</a></h4>
2420
2421         <div class="VARIABLELIST">
2422           <dl>
2423             <dt>Specifies:</dt>
2424
2425             <dd>
2426               <p>Whether the CGI interface should stay compatible with broken
2427               HTTP clients.</p>
2428             </dd>
2429
2430             <dt>Type of value:</dt>
2431
2432             <dd>
2433               <p><tt class="REPLACEABLE"><i>0 or 1</i></tt></p>
2434             </dd>
2435
2436             <dt>Default value:</dt>
2437
2438             <dd>
2439               <p><span class="emphasis"><i class="EMPHASIS">0</i></span></p>
2440             </dd>
2441
2442             <dt>Effect if unset:</dt>
2443
2444             <dd>
2445               <p>The CGI form generate long GET URLs.</p>
2446             </dd>
2447
2448             <dt>Notes:</dt>
2449
2450             <dd>
2451               <p><span class="APPLICATION">Privoxy's</span> CGI forms can
2452               lead to rather long URLs. This isn't a problem as far as the
2453               HTTP standard is concerned, but it can confuse clients with
2454               arbitrary URL length limitations.</p>
2455
2456               <p>Enabling split-large-forms causes <span class=
2457               "APPLICATION">Privoxy</span> to divide big forms into smaller
2458               ones to keep the URL length down. It makes editing a lot less
2459               convenient and you can no longer submit all changes at once,
2460               but at least it works around this browser bug.</p>
2461
2462               <p>If you don't notice any editing problems, there is no reason
2463               to enable this option, but if one of the submit buttons appears
2464               to be broken, you should give it a try.</p>
2465             </dd>
2466
2467             <dt>Examples:</dt>
2468
2469             <dd>
2470               <p>split-large-forms 1</p>
2471             </dd>
2472           </dl>
2473         </div>
2474       </div>
2475
2476       <div class="SECT3">
2477         <h4 class="SECT3"><a name="KEEP-ALIVE-TIMEOUT" id=
2478         "KEEP-ALIVE-TIMEOUT">7.6.4. keep-alive-timeout</a></h4>
2479
2480         <div class="VARIABLELIST">
2481           <dl>
2482             <dt>Specifies:</dt>
2483
2484             <dd>
2485               <p>Number of seconds after which an open connection will no
2486               longer be reused.</p>
2487             </dd>
2488
2489             <dt>Type of value:</dt>
2490
2491             <dd>
2492               <p><tt class="REPLACEABLE"><i>Time in seconds.</i></tt></p>
2493             </dd>
2494
2495             <dt>Default value:</dt>
2496
2497             <dd>
2498               <p>None</p>
2499             </dd>
2500
2501             <dt>Effect if unset:</dt>
2502
2503             <dd>
2504               <p>Connections are not kept alive.</p>
2505             </dd>
2506
2507             <dt>Notes:</dt>
2508
2509             <dd>
2510               <p>This option allows clients to keep the connection to
2511               <span class="APPLICATION">Privoxy</span> alive. If the server
2512               supports it, <span class="APPLICATION">Privoxy</span> will keep
2513               the connection to the server alive as well. Under certain
2514               circumstances this may result in speed-ups.</p>
2515
2516               <p>By default, <span class="APPLICATION">Privoxy</span> will
2517               close the connection to the server if the client connection
2518               gets closed, or if the specified timeout has been reached
2519               without a new request coming in. This behaviour can be changed
2520               with the <a href="#CONNECTION-SHARING" target=
2521               "_top">connection-sharing</a> option.</p>
2522
2523               <p>This option has no effect if <span class=
2524               "APPLICATION">Privoxy</span> has been compiled without
2525               keep-alive support.</p>
2526
2527               <p>Note that a timeout of five seconds as used in the default
2528               configuration file significantly decreases the number of
2529               connections that will be reused. The value is used because some
2530               browsers limit the number of connections they open to a single
2531               host and apply the same limit to proxies. This can result in a
2532               single website <span class="QUOTE">"grabbing"</span> all the
2533               connections the browser allows, which means connections to
2534               other websites can't be opened until the connections currently
2535               in use time out.</p>
2536
2537               <p>Several users have reported this as a Privoxy bug, so the
2538               default value has been reduced. Consider increasing it to 300
2539               seconds or even more if you think your browser can handle it.
2540               If your browser appears to be hanging, it probably can't.</p>
2541             </dd>
2542
2543             <dt>Examples:</dt>
2544
2545             <dd>
2546               <p>keep-alive-timeout 300</p>
2547             </dd>
2548           </dl>
2549         </div>
2550       </div>
2551
2552       <div class="SECT3">
2553         <h4 class="SECT3"><a name="TOLERATE-PIPELINING" id=
2554         "TOLERATE-PIPELINING">7.6.5. tolerate-pipelining</a></h4>
2555
2556         <div class="VARIABLELIST">
2557           <dl>
2558             <dt>Specifies:</dt>
2559
2560             <dd>
2561               <p>Whether or not pipelined requests should be served.</p>
2562             </dd>
2563
2564             <dt>Type of value:</dt>
2565
2566             <dd>
2567               <p><tt class="REPLACEABLE"><i>0 or 1.</i></tt></p>
2568             </dd>
2569
2570             <dt>Default value:</dt>
2571
2572             <dd>
2573               <p>None</p>
2574             </dd>
2575
2576             <dt>Effect if unset:</dt>
2577
2578             <dd>
2579               <p>If Privoxy receives more than one request at once, it
2580               terminates the client connection after serving the first
2581               one.</p>
2582             </dd>
2583
2584             <dt>Notes:</dt>
2585
2586             <dd>
2587               <p><span class="APPLICATION">Privoxy</span> currently doesn't
2588               pipeline outgoing requests, thus allowing pipelining on the
2589               client connection is not guaranteed to improve the
2590               performance.</p>
2591
2592               <p>By default <span class="APPLICATION">Privoxy</span> tries to
2593               discourage clients from pipelining by discarding aggressively
2594               pipelined requests, which forces the client to resend them
2595               through a new connection.</p>
2596
2597               <p>This option lets <span class="APPLICATION">Privoxy</span>
2598               tolerate pipelining. Whether or not that improves performance
2599               mainly depends on the client configuration.</p>
2600
2601               <p>If you are seeing problems with pages not properly loading,
2602               disabling this option could work around the problem.</p>
2603             </dd>
2604
2605             <dt>Examples:</dt>
2606
2607             <dd>
2608               <p>tolerate-pipelining 1</p>
2609             </dd>
2610           </dl>
2611         </div>
2612       </div>
2613
2614       <div class="SECT3">
2615         <h4 class="SECT3"><a name="DEFAULT-SERVER-TIMEOUT" id=
2616         "DEFAULT-SERVER-TIMEOUT">7.6.6. default-server-timeout</a></h4>
2617
2618         <div class="VARIABLELIST">
2619           <dl>
2620             <dt>Specifies:</dt>
2621
2622             <dd>
2623               <p>Assumed server-side keep-alive timeout if not specified by
2624               the server.</p>
2625             </dd>
2626
2627             <dt>Type of value:</dt>
2628
2629             <dd>
2630               <p><tt class="REPLACEABLE"><i>Time in seconds.</i></tt></p>
2631             </dd>
2632
2633             <dt>Default value:</dt>
2634
2635             <dd>
2636               <p>None</p>
2637             </dd>
2638
2639             <dt>Effect if unset:</dt>
2640
2641             <dd>
2642               <p>Connections for which the server didn't specify the
2643               keep-alive timeout are not reused.</p>
2644             </dd>
2645
2646             <dt>Notes:</dt>
2647
2648             <dd>
2649               <p>Enabling this option significantly increases the number of
2650               connections that are reused, provided the <a href=
2651               "#KEEP-ALIVE-TIMEOUT" target="_top">keep-alive-timeout</a>
2652               option is also enabled.</p>
2653
2654               <p>While it also increases the number of connections problems
2655               when <span class="APPLICATION">Privoxy</span> tries to reuse a
2656               connection that already has been closed on the server side, or
2657               is closed while <span class="APPLICATION">Privoxy</span> is
2658               trying to reuse it, this should only be a problem if it happens
2659               for the first request sent by the client. If it happens for
2660               requests on reused client connections, <span class=
2661               "APPLICATION">Privoxy</span> will simply close the connection
2662               and the client is supposed to retry the request without
2663               bothering the user.</p>
2664
2665               <p>Enabling this option is therefore only recommended if the
2666               <a href="#CONNECTION-SHARING" target=
2667               "_top">connection-sharing</a> option is disabled.</p>
2668
2669               <p>It is an error to specify a value larger than the <a href=
2670               "#KEEP-ALIVE-TIMEOUT" target="_top">keep-alive-timeout</a>
2671               value.</p>
2672
2673               <p>This option has no effect if <span class=
2674               "APPLICATION">Privoxy</span> has been compiled without
2675               keep-alive support.</p>
2676             </dd>
2677
2678             <dt>Examples:</dt>
2679
2680             <dd>
2681               <p>default-server-timeout 60</p>
2682             </dd>
2683           </dl>
2684         </div>
2685       </div>
2686
2687       <div class="SECT3">
2688         <h4 class="SECT3"><a name="CONNECTION-SHARING" id=
2689         "CONNECTION-SHARING">7.6.7. connection-sharing</a></h4>
2690
2691         <div class="VARIABLELIST">
2692           <dl>
2693             <dt>Specifies:</dt>
2694
2695             <dd>
2696               <p>Whether or not outgoing connections that have been kept
2697               alive should be shared between different incoming
2698               connections.</p>
2699             </dd>
2700
2701             <dt>Type of value:</dt>
2702
2703             <dd>
2704               <p><tt class="REPLACEABLE"><i>0 or 1</i></tt></p>
2705             </dd>
2706
2707             <dt>Default value:</dt>
2708
2709             <dd>
2710               <p>None</p>
2711             </dd>
2712
2713             <dt>Effect if unset:</dt>
2714
2715             <dd>
2716               <p>Connections are not shared.</p>
2717             </dd>
2718
2719             <dt>Notes:</dt>
2720
2721             <dd>
2722               <p>This option has no effect if <span class=
2723               "APPLICATION">Privoxy</span> has been compiled without
2724               keep-alive support, or if it's disabled.</p>
2725             </dd>
2726
2727             <dt>Notes:</dt>
2728
2729             <dd>
2730               <p>Note that reusing connections doesn't necessary cause
2731               speedups. There are also a few privacy implications you should
2732               be aware of.</p>
2733
2734               <p>If this option is effective, outgoing connections are shared
2735               between clients (if there are more than one) and closing the
2736               browser that initiated the outgoing connection does no longer
2737               affect the connection between <span class=
2738               "APPLICATION">Privoxy</span> and the server unless the client's
2739               request hasn't been completed yet.</p>
2740
2741               <p>If the outgoing connection is idle, it will not be closed
2742               until either <span class="APPLICATION">Privoxy's</span> or the
2743               server's timeout is reached. While it's open, the server knows
2744               that the system running <span class=
2745               "APPLICATION">Privoxy</span> is still there.</p>
2746
2747               <p>If there are more than one client (maybe even belonging to
2748               multiple users), they will be able to reuse each others
2749               connections. This is potentially dangerous in case of
2750               authentication schemes like NTLM where only the connection is
2751               authenticated, instead of requiring authentication for each
2752               request.</p>
2753
2754               <p>If there is only a single client, and if said client can
2755               keep connections alive on its own, enabling this option has
2756               next to no effect. If the client doesn't support connection
2757               keep-alive, enabling this option may make sense as it allows
2758               <span class="APPLICATION">Privoxy</span> to keep outgoing
2759               connections alive even if the client itself doesn't support
2760               it.</p>
2761
2762               <p>You should also be aware that enabling this option increases
2763               the likelihood of getting the "No server or forwarder data"
2764               error message, especially if you are using a slow connection to
2765               the Internet.</p>
2766
2767               <p>This option should only be used by experienced users who
2768               understand the risks and can weight them against the
2769               benefits.</p>
2770             </dd>
2771
2772             <dt>Examples:</dt>
2773
2774             <dd>
2775               <p>connection-sharing 1</p>
2776             </dd>
2777           </dl>
2778         </div>
2779       </div>
2780
2781       <div class="SECT3">
2782         <h4 class="SECT3"><a name="SOCKET-TIMEOUT" id="SOCKET-TIMEOUT">7.6.8.
2783         socket-timeout</a></h4>
2784
2785         <div class="VARIABLELIST">
2786           <dl>
2787             <dt>Specifies:</dt>
2788
2789             <dd>
2790               <p>Number of seconds after which a socket times out if no data
2791               is received.</p>
2792             </dd>
2793
2794             <dt>Type of value:</dt>
2795
2796             <dd>
2797               <p><tt class="REPLACEABLE"><i>Time in seconds.</i></tt></p>
2798             </dd>
2799
2800             <dt>Default value:</dt>
2801
2802             <dd>
2803               <p>None</p>
2804             </dd>
2805
2806             <dt>Effect if unset:</dt>
2807
2808             <dd>
2809               <p>A default value of 300 seconds is used.</p>
2810             </dd>
2811
2812             <dt>Notes:</dt>
2813
2814             <dd>
2815               <p>The default is quite high and you probably want to reduce
2816               it. If you aren't using an occasionally slow proxy like Tor,
2817               reducing it to a few seconds should be fine.</p>
2818             </dd>
2819
2820             <dt>Examples:</dt>
2821
2822             <dd>
2823               <p>socket-timeout 300</p>
2824             </dd>
2825           </dl>
2826         </div>
2827       </div>
2828
2829       <div class="SECT3">
2830         <h4 class="SECT3"><a name="MAX-CLIENT-CONNECTIONS" id=
2831         "MAX-CLIENT-CONNECTIONS">7.6.9. max-client-connections</a></h4>
2832
2833         <div class="VARIABLELIST">
2834           <dl>
2835             <dt>Specifies:</dt>
2836
2837             <dd>
2838               <p>Maximum number of client connections that will be
2839               served.</p>
2840             </dd>
2841
2842             <dt>Type of value:</dt>
2843
2844             <dd>
2845               <p><tt class="REPLACEABLE"><i>Positive number.</i></tt></p>
2846             </dd>
2847
2848             <dt>Default value:</dt>
2849
2850             <dd>
2851               <p>128</p>
2852             </dd>
2853
2854             <dt>Effect if unset:</dt>
2855
2856             <dd>
2857               <p>Connections are served until a resource limit is
2858               reached.</p>
2859             </dd>
2860
2861             <dt>Notes:</dt>
2862
2863             <dd>
2864               <p><span class="APPLICATION">Privoxy</span> creates one thread
2865               (or process) for every incoming client connection that isn't
2866               rejected based on the access control settings.</p>
2867
2868               <p>If the system is powerful enough, <span class=
2869               "APPLICATION">Privoxy</span> can theoretically deal with
2870               several hundred (or thousand) connections at the same time, but
2871               some operating systems enforce resource limits by shutting down
2872               offending processes and their default limits may be below the
2873               ones <span class="APPLICATION">Privoxy</span> would require
2874               under heavy load.</p>
2875
2876               <p>Configuring <span class="APPLICATION">Privoxy</span> to
2877               enforce a connection limit below the thread or process limit
2878               used by the operating system makes sure this doesn't happen.
2879               Simply increasing the operating system's limit would work too,
2880               but if <span class="APPLICATION">Privoxy</span> isn't the only
2881               application running on the system, you may actually want to
2882               limit the resources used by <span class=
2883               "APPLICATION">Privoxy</span>.</p>
2884
2885               <p>If <span class="APPLICATION">Privoxy</span> is only used by
2886               a single trusted user, limiting the number of client
2887               connections is probably unnecessary. If there are multiple
2888               possibly untrusted users you probably still want to
2889               additionally use a packet filter to limit the maximal number of
2890               incoming connections per client. Otherwise a malicious user
2891               could intentionally create a high number of connections to
2892               prevent other users from using <span class=
2893               "APPLICATION">Privoxy</span>.</p>
2894
2895               <p>Obviously using this option only makes sense if you choose a
2896               limit below the one enforced by the operating system.</p>
2897
2898               <p>One most POSIX-compliant systems <span class=
2899               "APPLICATION">Privoxy</span> can't properly deal with more than
2900               FD_SETSIZE file descriptors at the same time and has to reject
2901               connections if the limit is reached. This will likely change in
2902               a future version, but currently this limit can't be increased
2903               without recompiling <span class="APPLICATION">Privoxy</span>
2904               with a different FD_SETSIZE limit.</p>
2905             </dd>
2906
2907             <dt>Examples:</dt>
2908
2909             <dd>
2910               <p>max-client-connections 256</p>
2911             </dd>
2912           </dl>
2913         </div>
2914       </div>
2915
2916       <div class="SECT3">
2917         <h4 class="SECT3"><a name="HANDLE-AS-EMPTY-DOC-RETURNS-OK" id=
2918         "HANDLE-AS-EMPTY-DOC-RETURNS-OK">7.6.10.
2919         handle-as-empty-doc-returns-ok</a></h4>
2920
2921         <div class="VARIABLELIST">
2922           <dl>
2923             <dt>Specifies:</dt>
2924
2925             <dd>
2926               <p>The status code Privoxy returns for pages blocked with
2927               <tt class="LITERAL"><a href=
2928               "actions-file.html#HANDLE-AS-EMPTY-DOCUMENT" target=
2929               "_top">+handle-as-empty-document</a></tt>.</p>
2930             </dd>
2931
2932             <dt>Type of value:</dt>
2933
2934             <dd>
2935               <p><tt class="REPLACEABLE"><i>0 or 1</i></tt></p>
2936             </dd>
2937
2938             <dt>Default value:</dt>
2939
2940             <dd>
2941               <p>0</p>
2942             </dd>
2943
2944             <dt>Effect if unset:</dt>
2945
2946             <dd>
2947               <p>Privoxy returns a status 403(forbidden) for all blocked
2948               pages.</p>
2949             </dd>
2950
2951             <dt>Effect if set:</dt>
2952
2953             <dd>
2954               <p>Privoxy returns a status 200(OK) for pages blocked with
2955               +handle-as-empty-document and a status 403(Forbidden) for all
2956               other blocked pages.</p>
2957             </dd>
2958
2959             <dt>Notes:</dt>
2960
2961             <dd>
2962               <p>This directive was added as a work-around for Firefox bug
2963               492459: <span class="QUOTE">" Websites are no longer rendered
2964               if SSL requests for JavaScripts are blocked by a proxy.
2965               "</span> (<a href=
2966               "https://bugzilla.mozilla.org/show_bug.cgi?id=492459" target=
2967               "_top">https://bugzilla.mozilla.org/show_bug.cgi?id=492459</a>),
2968               the bug has been fixed for quite some time, but this directive
2969               is also useful to make it harder for websites to detect whether
2970               or not resources are being blocked.</p>
2971             </dd>
2972           </dl>
2973         </div>
2974       </div>
2975
2976       <div class="SECT3">
2977         <h4 class="SECT3"><a name="ENABLE-COMPRESSION" id=
2978         "ENABLE-COMPRESSION">7.6.11. enable-compression</a></h4>
2979
2980         <div class="VARIABLELIST">
2981           <dl>
2982             <dt>Specifies:</dt>
2983
2984             <dd>
2985               <p>Whether or not buffered content is compressed before
2986               delivery.</p>
2987             </dd>
2988
2989             <dt>Type of value:</dt>
2990
2991             <dd>
2992               <p><tt class="REPLACEABLE"><i>0 or 1</i></tt></p>
2993             </dd>
2994
2995             <dt>Default value:</dt>
2996
2997             <dd>
2998               <p>0</p>
2999             </dd>
3000
3001             <dt>Effect if unset:</dt>
3002
3003             <dd>
3004               <p>Privoxy does not compress buffered content.</p>
3005             </dd>
3006
3007             <dt>Effect if set:</dt>
3008
3009             <dd>
3010               <p>Privoxy compresses buffered content before delivering it to
3011               the client, provided the client supports it.</p>
3012             </dd>
3013
3014             <dt>Notes:</dt>
3015
3016             <dd>
3017               <p>This directive is only supported if Privoxy has been
3018               compiled with FEATURE_COMPRESSION, which should not to be
3019               confused with FEATURE_ZLIB.</p>
3020
3021               <p>Compressing buffered content is mainly useful if Privoxy and
3022               the client are running on different systems. If they are
3023               running on the same system, enabling compression is likely to
3024               slow things down. If you didn't measure otherwise, you should
3025               assume that it does and keep this option disabled.</p>
3026
3027               <p>Privoxy will not compress buffered content below a certain
3028               length.</p>
3029             </dd>
3030           </dl>
3031         </div>
3032       </div>
3033
3034       <div class="SECT3">
3035         <h4 class="SECT3"><a name="COMPRESSION-LEVEL" id=
3036         "COMPRESSION-LEVEL">7.6.12. compression-level</a></h4>
3037
3038         <div class="VARIABLELIST">
3039           <dl>
3040             <dt>Specifies:</dt>
3041
3042             <dd>
3043               <p>The compression level that is passed to the zlib library
3044               when compressing buffered content.</p>
3045             </dd>
3046
3047             <dt>Type of value:</dt>
3048
3049             <dd>
3050               <p><tt class="REPLACEABLE"><i>Positive number ranging from 0 to
3051               9.</i></tt></p>
3052             </dd>
3053
3054             <dt>Default value:</dt>
3055
3056             <dd>
3057               <p>1</p>
3058             </dd>
3059
3060             <dt>Notes:</dt>
3061
3062             <dd>
3063               <p>Compressing the data more takes usually longer than
3064               compressing it less or not compressing it at all. Which level
3065               is best depends on the connection between Privoxy and the
3066               client. If you can't be bothered to benchmark it for yourself,
3067               you should stick with the default and keep compression
3068               disabled.</p>
3069
3070               <p>If compression is disabled, the compression level is
3071               irrelevant.</p>
3072             </dd>
3073
3074             <dt>Examples:</dt>
3075
3076             <dd>
3077               <table border="0" bgcolor="#E0E0E0" width="90%">
3078                 <tr>
3079                   <td>
3080                     <pre class="SCREEN">
3081     # Best speed (compared to the other levels)
3082     compression-level 1
3083     # Best compression
3084     compression-level 9
3085     # No compression. Only useful for testing as the added header
3086     # slightly increases the amount of data that has to be sent.
3087     # If your benchmark shows that using this compression level
3088     # is superior to using no compression at all, the benchmark
3089     # is likely to be flawed.
3090     compression-level 0
3091
3092 </pre>
3093                   </td>
3094                 </tr>
3095               </table>
3096             </dd>
3097           </dl>
3098         </div>
3099       </div>
3100
3101       <div class="SECT3">
3102         <h4 class="SECT3"><a name="CLIENT-HEADER-ORDER" id=
3103         "CLIENT-HEADER-ORDER">7.6.13. client-header-order</a></h4>
3104
3105         <div class="VARIABLELIST">
3106           <dl>
3107             <dt>Specifies:</dt>
3108
3109             <dd>
3110               <p>The order in which client headers are sorted before
3111               forwarding them.</p>
3112             </dd>
3113
3114             <dt>Type of value:</dt>
3115
3116             <dd>
3117               <p><tt class="REPLACEABLE"><i>Client header names delimited by
3118               spaces or tabs</i></tt></p>
3119             </dd>
3120
3121             <dt>Default value:</dt>
3122
3123             <dd>
3124               <p>None</p>
3125             </dd>
3126
3127             <dt>Notes:</dt>
3128
3129             <dd>
3130               <p>By default <span class="APPLICATION">Privoxy</span> leaves
3131               the client headers in the order they were sent by the client.
3132               Headers are modified in-place, new headers are added at the end
3133               of the already existing headers.</p>
3134
3135               <p>The header order can be used to fingerprint client requests
3136               independently of other headers like the User-Agent.</p>
3137
3138               <p>This directive allows to sort the headers differently to
3139               better mimic a different User-Agent. Client headers will be
3140               emitted in the order given, headers whose name isn't explicitly
3141               specified are added at the end.</p>
3142
3143               <p>Note that sorting headers in an uncommon way will make
3144               fingerprinting actually easier. Encrypted headers are not
3145               affected by this directive.</p>
3146             </dd>
3147           </dl>
3148         </div>
3149       </div>
3150     </div>
3151
3152     <div class="SECT2">
3153       <h2 class="SECT2"><a name="WINDOWS-GUI" id="WINDOWS-GUI">7.7. Windows
3154       GUI Options</a></h2>
3155
3156       <p><span class="APPLICATION">Privoxy</span> has a number of options
3157       specific to the Windows GUI interface:</p><a name="ACTIVITY-ANIMATION"
3158       id="ACTIVITY-ANIMATION"></a>
3159
3160       <p>If <span class="QUOTE">"activity-animation"</span> is set to 1, the
3161       <span class="APPLICATION">Privoxy</span> icon will animate when
3162       <span class="QUOTE">"Privoxy"</span> is active. To turn off, set to
3163       0.</p>
3164
3165       <p class="LITERALLAYOUT"><tt class="LITERAL">&nbsp;&nbsp;<span class=
3166       "emphasis"><i class="EMPHASIS">activity-animation 1</i></span><br>
3167       &nbsp;&nbsp;&nbsp;</tt></p><a name="LOG-MESSAGES" id=
3168       "LOG-MESSAGES"></a>
3169
3170       <p>If <span class="QUOTE">"log-messages"</span> is set to 1,
3171       <span class="APPLICATION">Privoxy</span> copies log messages to the
3172       console window. The log detail depends on the <a href=
3173       "config.html#DEBUG">debug</a> directive.</p>
3174
3175       <p class="LITERALLAYOUT"><tt class="LITERAL">&nbsp;&nbsp;<span class=
3176       "emphasis"><i class="EMPHASIS">log-messages 1</i></span><br>
3177       &nbsp;&nbsp;&nbsp;</tt></p><a name="LOG-BUFFER-SIZE" id=
3178       "LOG-BUFFER-SIZE"></a>
3179
3180       <p>If <span class="QUOTE">"log-buffer-size"</span> is set to 1, the
3181       size of the log buffer, i.e. the amount of memory used for the log
3182       messages displayed in the console window, will be limited to
3183       <span class="QUOTE">"log-max-lines"</span> (see below).</p>
3184
3185       <p>Warning: Setting this to 0 will result in the buffer to grow
3186       infinitely and eat up all your memory!</p>
3187
3188       <p class="LITERALLAYOUT"><tt class="LITERAL">&nbsp;&nbsp;<span class=
3189       "emphasis"><i class="EMPHASIS">log-buffer-size 1</i></span><br>
3190       &nbsp;&nbsp;&nbsp;</tt></p><a name="LOG-MAX-LINES" id=
3191       "LOG-MAX-LINES"></a>
3192
3193       <p><span class="APPLICATION">log-max-lines</span> is the maximum number
3194       of lines held in the log buffer. See above.</p>
3195
3196       <p class="LITERALLAYOUT"><tt class="LITERAL">&nbsp;&nbsp;<span class=
3197       "emphasis"><i class="EMPHASIS">log-max-lines 200</i></span><br>
3198       &nbsp;&nbsp;&nbsp;</tt></p><a name="LOG-HIGHLIGHT-MESSAGES" id=
3199       "LOG-HIGHLIGHT-MESSAGES"></a>
3200
3201       <p>If <span class="QUOTE">"log-highlight-messages"</span> is set to 1,
3202       <span class="APPLICATION">Privoxy</span> will highlight portions of the
3203       log messages with a bold-faced font:</p>
3204
3205       <p class="LITERALLAYOUT"><tt class="LITERAL">&nbsp;&nbsp;<span class=
3206       "emphasis"><i class="EMPHASIS">log-highlight-messages 1</i></span><br>
3207       &nbsp;&nbsp;&nbsp;</tt></p><a name="LOG-FONT-NAME" id=
3208       "LOG-FONT-NAME"></a>
3209
3210       <p>The font used in the console window:</p>
3211
3212       <p class="LITERALLAYOUT"><tt class="LITERAL">&nbsp;&nbsp;<span class=
3213       "emphasis"><i class="EMPHASIS">log-font-name Comic Sans
3214       MS</i></span><br>
3215       &nbsp;&nbsp;&nbsp;</tt></p><a name="LOG-FONT-SIZE" id=
3216       "LOG-FONT-SIZE"></a>
3217
3218       <p>Font size used in the console window:</p>
3219
3220       <p class="LITERALLAYOUT"><tt class="LITERAL">&nbsp;&nbsp;<span class=
3221       "emphasis"><i class="EMPHASIS">log-font-size 8</i></span><br>
3222       &nbsp;&nbsp;&nbsp;</tt></p><a name="SHOW-ON-TASK-BAR" id=
3223       "SHOW-ON-TASK-BAR"></a>
3224
3225       <p><span class="QUOTE">"show-on-task-bar"</span> controls whether or
3226       not <span class="APPLICATION">Privoxy</span> will appear as a button on
3227       the Task bar when minimized:</p>
3228
3229       <p class="LITERALLAYOUT"><tt class="LITERAL">&nbsp;&nbsp;<span class=
3230       "emphasis"><i class="EMPHASIS">show-on-task-bar 0</i></span><br>
3231       &nbsp;&nbsp;&nbsp;</tt></p><a name="CLOSE-BUTTON-MINIMIZES" id=
3232       "CLOSE-BUTTON-MINIMIZES"></a>
3233
3234       <p>If <span class="QUOTE">"close-button-minimizes"</span> is set to 1,
3235       the Windows close button will minimize <span class=
3236       "APPLICATION">Privoxy</span> instead of closing the program (close with
3237       the exit option on the File menu).</p>
3238
3239       <p class="LITERALLAYOUT"><tt class="LITERAL">&nbsp;&nbsp;<span class=
3240       "emphasis"><i class="EMPHASIS">close-button-minimizes 1</i></span><br>
3241       &nbsp;&nbsp;&nbsp;</tt></p><a name="HIDE-CONSOLE" id=
3242       "HIDE-CONSOLE"></a>
3243
3244       <p>The <span class="QUOTE">"hide-console"</span> option is specific to
3245       the MS-Win console version of <span class="APPLICATION">Privoxy</span>.
3246       If this option is used, <span class="APPLICATION">Privoxy</span> will
3247       disconnect from and hide the command console.</p>
3248
3249       <p class="LITERALLAYOUT"><tt class="LITERAL">&nbsp;&nbsp;#<span class=
3250       "emphasis"><i class="EMPHASIS">hide-console</i></span><br>
3251       &nbsp;&nbsp;&nbsp;</tt></p>
3252     </div>
3253   </div>
3254
3255   <div class="NAVFOOTER">
3256     <hr align="left" width="100%">
3257
3258     <table summary="Footer navigation table" width="100%" border="0"
3259     cellpadding="0" cellspacing="0">
3260       <tr>
3261         <td width="33%" align="left" valign="top"><a href=
3262         "configuration.html" accesskey="P">Prev</a></td>
3263
3264         <td width="34%" align="center" valign="top"><a href="index.html"
3265         accesskey="H">Home</a></td>
3266
3267         <td width="33%" align="right" valign="top"><a href=
3268         "actions-file.html" accesskey="N">Next</a></td>
3269       </tr>
3270
3271       <tr>
3272         <td width="33%" align="left" valign="top">Privoxy Configuration</td>
3273
3274         <td width="34%" align="center" valign="top">&nbsp;</td>
3275
3276         <td width="33%" align="right" valign="top">Actions Files</td>
3277       </tr>
3278     </table>
3279   </div>
3280 </body>
3281 </html>