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