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