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