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