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