Rebuild for 3.0.17 stable
[privoxy.git] / doc / webserver / user-manual / config.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
2 <HTML
3 ><HEAD
4 ><TITLE
5 >The Main Configuration File</TITLE
6 ><META
7 NAME="GENERATOR"
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
9 REL="HOME"
10 TITLE="Privoxy 3.0.17 User Manual"
11 HREF="index.html"><LINK
12 REL="PREVIOUS"
13 TITLE="Privoxy Configuration"
14 HREF="configuration.html"><LINK
15 REL="NEXT"
16 TITLE="Actions Files"
17 HREF="actions-file.html"><LINK
18 REL="STYLESHEET"
19 TYPE="text/css"
20 HREF="../p_doc.css"><META
21 HTTP-EQUIV="Content-Type"
22 CONTENT="text/html;
23 charset=ISO-8859-1">
24 <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css">
25 </head
26 ><BODY
27 CLASS="SECT1"
28 BGCOLOR="#EEEEEE"
29 TEXT="#000000"
30 LINK="#0000FF"
31 VLINK="#840084"
32 ALINK="#0000FF"
33 ><DIV
34 CLASS="NAVHEADER"
35 ><TABLE
36 SUMMARY="Header navigation table"
37 WIDTH="100%"
38 BORDER="0"
39 CELLPADDING="0"
40 CELLSPACING="0"
41 ><TR
42 ><TH
43 COLSPAN="3"
44 ALIGN="center"
45 >Privoxy 3.0.17 User Manual</TH
46 ></TR
47 ><TR
48 ><TD
49 WIDTH="10%"
50 ALIGN="left"
51 VALIGN="bottom"
52 ><A
53 HREF="configuration.html"
54 ACCESSKEY="P"
55 >Prev</A
56 ></TD
57 ><TD
58 WIDTH="80%"
59 ALIGN="center"
60 VALIGN="bottom"
61 ></TD
62 ><TD
63 WIDTH="10%"
64 ALIGN="right"
65 VALIGN="bottom"
66 ><A
67 HREF="actions-file.html"
68 ACCESSKEY="N"
69 >Next</A
70 ></TD
71 ></TR
72 ></TABLE
73 ><HR
74 ALIGN="LEFT"
75 WIDTH="100%"></DIV
76 ><DIV
77 CLASS="SECT1"
78 ><H1
79 CLASS="SECT1"
80 ><A
81 NAME="CONFIG"
82 >7. The Main Configuration File</A
83 ></H1
84 ><P
85 > Again, the main configuration file is named <TT
86 CLASS="FILENAME"
87 >config</TT
88 > on
89  Linux/Unix/BSD and OS/2, and <TT
90 CLASS="FILENAME"
91 >config.txt</TT
92 > on Windows.
93  Configuration lines consist of an initial keyword followed by a list of
94  values, all separated by whitespace (any number of spaces or tabs). For
95  example:</P
96 ><P
97 > <TT
98 CLASS="LITERAL"
99 >  <P
100 CLASS="LITERALLAYOUT"
101 >&nbsp;&nbsp;<SPAN
102 CLASS="emphasis"
103 ><I
104 CLASS="EMPHASIS"
105 >confdir /etc/privoxy</I
106 ></SPAN
107 ></P
108 >
109  </TT
110 > </P
111 ><P
112 > Assigns the value <TT
113 CLASS="LITERAL"
114 >/etc/privoxy</TT
115 > to the option
116  <TT
117 CLASS="LITERAL"
118 >confdir</TT
119 > and thus indicates that the configuration
120  directory is named <SPAN
121 CLASS="QUOTE"
122 >"/etc/privoxy/"</SPAN
123 >.</P
124 ><P
125 > All options in the config file except for <TT
126 CLASS="LITERAL"
127 >confdir</TT
128 > and
129  <TT
130 CLASS="LITERAL"
131 >logdir</TT
132 > are optional. Watch out in the below description
133  for what happens if you leave them unset.</P
134 ><P
135 > The main config file controls all aspects of <SPAN
136 CLASS="APPLICATION"
137 >Privoxy</SPAN
138 >'s
139  operation that are not location dependent (i.e. they apply universally, no matter
140  where you may be surfing). Like the filter and action files, the config file is
141  a plain text file and can be modified with a text editor like emacs, vim or
142  notepad.exe.</P
143 ><DIV
144 CLASS="SECT2"
145 ><H2
146 CLASS="SECT2"
147 ><A
148 NAME="LOCAL-SET-UP"
149 >7.1. Local Set-up Documentation</A
150 ></H2
151 ><P
152 >    If you intend to operate <SPAN
153 CLASS="APPLICATION"
154 >Privoxy</SPAN
155 > for more users
156     than just yourself, it might be a good idea to let them know how to reach
157     you, what you block and why you do that, your policies, etc.
158    </P
159 ><DIV
160 CLASS="SECT3"
161 ><H4
162 CLASS="SECT3"
163 ><A
164 NAME="USER-MANUAL"
165 >7.1.1. user-manual</A
166 ></H4
167 ><P
168 ></P
169 ><DIV
170 CLASS="VARIABLELIST"
171 ><DL
172 ><DT
173 >Specifies:</DT
174 ><DD
175 ><P
176 >    Location of the <SPAN
177 CLASS="APPLICATION"
178 >Privoxy</SPAN
179 > User Manual.
180    </P
181 ></DD
182 ><DT
183 >Type of value:</DT
184 ><DD
185 ><P
186 >A fully qualified URI</P
187 ></DD
188 ><DT
189 >Default value:</DT
190 ><DD
191 ><P
192 ><SPAN
193 CLASS="emphasis"
194 ><I
195 CLASS="EMPHASIS"
196 >Unset</I
197 ></SPAN
198 ></P
199 ></DD
200 ><DT
201 >Effect if unset:</DT
202 ><DD
203 ><P
204 >    <A
205 HREF="http://www.privoxy.org/user-manual/"
206 TARGET="_top"
207 >http://www.privoxy.org/<TT
208 CLASS="REPLACEABLE"
209 ><I
210 >version</I
211 ></TT
212 >/user-manual/</A
213 >
214     will be used, where <TT
215 CLASS="REPLACEABLE"
216 ><I
217 >version</I
218 ></TT
219 > is the <SPAN
220 CLASS="APPLICATION"
221 >Privoxy</SPAN
222 > version.
223    </P
224 ></DD
225 ><DT
226 >Notes:</DT
227 ><DD
228 ><P
229 >    The User Manual URI is the single best source of information on 
230     <SPAN
231 CLASS="APPLICATION"
232 >Privoxy</SPAN
233 >, and is used for help links from some
234     of the internal CGI pages. The manual itself is normally packaged with the
235     binary distributions, so you probably want to set this to a locally
236     installed copy. 
237    </P
238 ><P
239 >    Examples:
240    </P
241 ><P
242 >   The best all purpose solution is simply to put the full local
243    <TT
244 CLASS="LITERAL"
245 >PATH</TT
246 > to where the <I
247 CLASS="CITETITLE"
248 >User Manual</I
249 > is
250    located:
251   </P
252 ><P
253 >   <TABLE
254 BORDER="0"
255 BGCOLOR="#E0E0E0"
256 WIDTH="90%"
257 ><TR
258 ><TD
259 ><PRE
260 CLASS="SCREEN"
261 >  user-manual  /usr/share/doc/privoxy/user-manual</PRE
262 ></TD
263 ></TR
264 ></TABLE
265 >
266   </P
267 ><P
268 >   The User Manual is then available to anyone with access to
269    <SPAN
270 CLASS="APPLICATION"
271 >Privoxy</SPAN
272 >, by following the built-in URL:
273    <TT
274 CLASS="LITERAL"
275 >http://config.privoxy.org/user-manual/</TT
276 >
277    (or the shortcut: <TT
278 CLASS="LITERAL"
279 >http://p.p/user-manual/</TT
280 >).
281   </P
282 ><P
283 >   If the documentation is not on the local system, it can be accessed 
284    from a remote server, as:
285   </P
286 ><P
287 >   <TABLE
288 BORDER="0"
289 BGCOLOR="#E0E0E0"
290 WIDTH="90%"
291 ><TR
292 ><TD
293 ><PRE
294 CLASS="SCREEN"
295 >  user-manual  http://example.com/privoxy/user-manual/</PRE
296 ></TD
297 ></TR
298 ></TABLE
299 >
300   </P
301 ><DIV
302 CLASS="WARNING"
303 ><P
304 ></P
305 ><TABLE
306 CLASS="WARNING"
307 BORDER="1"
308 WIDTH="90%"
309 ><TR
310 ><TD
311 ALIGN="CENTER"
312 ><B
313 >Warning</B
314 ></TD
315 ></TR
316 ><TR
317 ><TD
318 ALIGN="LEFT"
319 ><P
320 >     If set, this option should be <SPAN
321 CLASS="emphasis"
322 ><I
323 CLASS="EMPHASIS"
324 >the first option in the config
325      file</I
326 ></SPAN
327 >, because it is used while the config file is being read
328      on start-up.
329    </P
330 ></TD
331 ></TR
332 ></TABLE
333 ></DIV
334 ></DD
335 ></DL
336 ></DIV
337 ></DIV
338 ><DIV
339 CLASS="SECT3"
340 ><H4
341 CLASS="SECT3"
342 ><A
343 NAME="TRUST-INFO-URL"
344 >7.1.2. trust-info-url</A
345 ></H4
346 ><P
347 ></P
348 ><DIV
349 CLASS="VARIABLELIST"
350 ><DL
351 ><DT
352 >Specifies:</DT
353 ><DD
354 ><P
355 >    A URL to be displayed in the error page that users will see if access to an untrusted page is denied.    
356    </P
357 ></DD
358 ><DT
359 >Type of value:</DT
360 ><DD
361 ><P
362 >URL</P
363 ></DD
364 ><DT
365 >Default value:</DT
366 ><DD
367 ><P
368 ><SPAN
369 CLASS="emphasis"
370 ><I
371 CLASS="EMPHASIS"
372 >Unset</I
373 ></SPAN
374 ></P
375 ></DD
376 ><DT
377 >Effect if unset:</DT
378 ><DD
379 ><P
380 >    No links are displayed on the "untrusted" error page.
381    </P
382 ></DD
383 ><DT
384 >Notes:</DT
385 ><DD
386 ><P
387 >    The value of this option only matters if the experimental trust mechanism has been
388     activated. (See <A
389 HREF="config.html#TRUSTFILE"
390 ><SPAN
391 CLASS="emphasis"
392 ><I
393 CLASS="EMPHASIS"
394 >trustfile</I
395 ></SPAN
396 ></A
397 > below.)
398    </P
399 ><P
400 >    If you use the trust mechanism, it is a good idea to write up some on-line
401     documentation about your trust policy and to specify the URL(s) here.
402     Use multiple times for multiple URLs.
403    </P
404 ><P
405 >    The URL(s) should be added to the trustfile as well, so users don't end up
406     locked out from the information on why they were locked out in the first place!
407    </P
408 ></DD
409 ></DL
410 ></DIV
411 ></DIV
412 ><DIV
413 CLASS="SECT3"
414 ><H4
415 CLASS="SECT3"
416 ><A
417 NAME="ADMIN-ADDRESS"
418 >7.1.3. admin-address</A
419 ></H4
420 ><P
421 ></P
422 ><DIV
423 CLASS="VARIABLELIST"
424 ><DL
425 ><DT
426 >Specifies:</DT
427 ><DD
428 ><P
429 >    An email address to reach the <SPAN
430 CLASS="APPLICATION"
431 >Privoxy</SPAN
432 > administrator.
433    </P
434 ></DD
435 ><DT
436 >Type of value:</DT
437 ><DD
438 ><P
439 >Email address</P
440 ></DD
441 ><DT
442 >Default value:</DT
443 ><DD
444 ><P
445 ><SPAN
446 CLASS="emphasis"
447 ><I
448 CLASS="EMPHASIS"
449 >Unset</I
450 ></SPAN
451 ></P
452 ></DD
453 ><DT
454 >Effect if unset:</DT
455 ><DD
456 ><P
457 >    No email address is displayed on error pages and the CGI user interface.
458    </P
459 ></DD
460 ><DT
461 >Notes:</DT
462 ><DD
463 ><P
464 >    If both <TT
465 CLASS="LITERAL"
466 >admin-address</TT
467 > and <TT
468 CLASS="LITERAL"
469 >proxy-info-url</TT
470 >
471     are unset, the whole "Local Privoxy Support" box on all generated pages will
472     not be shown.
473    </P
474 ></DD
475 ></DL
476 ></DIV
477 ></DIV
478 ><DIV
479 CLASS="SECT3"
480 ><H4
481 CLASS="SECT3"
482 ><A
483 NAME="PROXY-INFO-URL"
484 >7.1.4. proxy-info-url</A
485 ></H4
486 ><P
487 ></P
488 ><DIV
489 CLASS="VARIABLELIST"
490 ><DL
491 ><DT
492 >Specifies:</DT
493 ><DD
494 ><P
495 >    A URL to documentation about the local <SPAN
496 CLASS="APPLICATION"
497 >Privoxy</SPAN
498 > setup,
499     configuration or policies.
500    </P
501 ></DD
502 ><DT
503 >Type of value:</DT
504 ><DD
505 ><P
506 >URL</P
507 ></DD
508 ><DT
509 >Default value:</DT
510 ><DD
511 ><P
512 ><SPAN
513 CLASS="emphasis"
514 ><I
515 CLASS="EMPHASIS"
516 >Unset</I
517 ></SPAN
518 ></P
519 ></DD
520 ><DT
521 >Effect if unset:</DT
522 ><DD
523 ><P
524 >    No link to local documentation is displayed on error pages and the CGI user interface.
525    </P
526 ></DD
527 ><DT
528 >Notes:</DT
529 ><DD
530 ><P
531 >    If both <TT
532 CLASS="LITERAL"
533 >admin-address</TT
534 > and <TT
535 CLASS="LITERAL"
536 >proxy-info-url</TT
537 >
538     are unset, the whole "Local Privoxy Support" box on all generated pages will
539     not be shown.
540    </P
541 ><P
542 >    This URL shouldn't be blocked ;-)
543    </P
544 ></DD
545 ></DL
546 ></DIV
547 ></DIV
548 ></DIV
549 ><DIV
550 CLASS="SECT2"
551 ><H2
552 CLASS="SECT2"
553 ><A
554 NAME="CONF-LOG-LOC"
555 >7.2. Configuration and Log File Locations</A
556 ></H2
557 ><P
558 > <SPAN
559 CLASS="APPLICATION"
560 >Privoxy</SPAN
561 > can (and normally does) use a number of
562  other files for additional configuration, help and logging.
563  This section of the configuration file tells <SPAN
564 CLASS="APPLICATION"
565 >Privoxy</SPAN
566 >
567  where to find those other files. </P
568 ><P
569 > The user running <SPAN
570 CLASS="APPLICATION"
571 >Privoxy</SPAN
572 >, must have read
573  permission for all configuration files, and write permission to any files
574  that would be modified, such as log files and actions files.</P
575 ><DIV
576 CLASS="SECT3"
577 ><H4
578 CLASS="SECT3"
579 ><A
580 NAME="CONFDIR"
581 >7.2.1. confdir</A
582 ></H4
583 ><P
584 ></P
585 ><DIV
586 CLASS="VARIABLELIST"
587 ><DL
588 ><DT
589 >Specifies:</DT
590 ><DD
591 ><P
592 >The directory where the other configuration files are located.</P
593 ></DD
594 ><DT
595 >Type of value:</DT
596 ><DD
597 ><P
598 >Path name</P
599 ></DD
600 ><DT
601 >Default value:</DT
602 ><DD
603 ><P
604 >/etc/privoxy (Unix) <SPAN
605 CLASS="emphasis"
606 ><I
607 CLASS="EMPHASIS"
608 >or</I
609 ></SPAN
610 > <SPAN
611 CLASS="APPLICATION"
612 >Privoxy</SPAN
613 > installation dir (Windows) </P
614 ></DD
615 ><DT
616 >Effect if unset:</DT
617 ><DD
618 ><P
619 ><SPAN
620 CLASS="emphasis"
621 ><I
622 CLASS="EMPHASIS"
623 >Mandatory</I
624 ></SPAN
625 ></P
626 ></DD
627 ><DT
628 >Notes:</DT
629 ><DD
630 ><P
631 >    No trailing <SPAN
632 CLASS="QUOTE"
633 >"<TT
634 CLASS="LITERAL"
635 >/</TT
636 >"</SPAN
637 >, please.
638    </P
639 ></DD
640 ></DL
641 ></DIV
642 ></DIV
643 ><DIV
644 CLASS="SECT3"
645 ><H4
646 CLASS="SECT3"
647 ><A
648 NAME="TEMPLDIR"
649 >7.2.2. templdir</A
650 ></H4
651 ><P
652 ></P
653 ><DIV
654 CLASS="VARIABLELIST"
655 ><DL
656 ><DT
657 >Specifies:</DT
658 ><DD
659 ><P
660 >An alternative directory where the templates are loaded from.</P
661 ></DD
662 ><DT
663 >Type of value:</DT
664 ><DD
665 ><P
666 >Path name</P
667 ></DD
668 ><DT
669 >Default value:</DT
670 ><DD
671 ><P
672 >unset</P
673 ></DD
674 ><DT
675 >Effect if unset:</DT
676 ><DD
677 ><P
678 >The templates are assumed to be located in confdir/template.</P
679 ></DD
680 ><DT
681 >Notes:</DT
682 ><DD
683 ><P
684 >    <SPAN
685 CLASS="APPLICATION"
686 >Privoxy's</SPAN
687 > original templates are usually
688     overwritten with each update. Use this option to relocate customized
689     templates that should be kept. As template variables might change
690     between updates, you shouldn't expect templates to work with
691     <SPAN
692 CLASS="APPLICATION"
693 >Privoxy</SPAN
694 > releases other than the one
695     they were part of, though.
696    </P
697 ></DD
698 ></DL
699 ></DIV
700 ></DIV
701 ><DIV
702 CLASS="SECT3"
703 ><H4
704 CLASS="SECT3"
705 ><A
706 NAME="LOGDIR"
707 >7.2.3. logdir</A
708 ></H4
709 ><P
710 ></P
711 ><DIV
712 CLASS="VARIABLELIST"
713 ><DL
714 ><DT
715 >Specifies:</DT
716 ><DD
717 ><P
718 >    The directory where all logging takes place
719     (i.e. where the <TT
720 CLASS="FILENAME"
721 >logfile</TT
722 > is located).
723    </P
724 ></DD
725 ><DT
726 >Type of value:</DT
727 ><DD
728 ><P
729 >Path name</P
730 ></DD
731 ><DT
732 >Default value:</DT
733 ><DD
734 ><P
735 >/var/log/privoxy (Unix) <SPAN
736 CLASS="emphasis"
737 ><I
738 CLASS="EMPHASIS"
739 >or</I
740 ></SPAN
741 > <SPAN
742 CLASS="APPLICATION"
743 >Privoxy</SPAN
744 > installation dir (Windows) </P
745 ></DD
746 ><DT
747 >Effect if unset:</DT
748 ><DD
749 ><P
750 ><SPAN
751 CLASS="emphasis"
752 ><I
753 CLASS="EMPHASIS"
754 >Mandatory</I
755 ></SPAN
756 ></P
757 ></DD
758 ><DT
759 >Notes:</DT
760 ><DD
761 ><P
762 >    No trailing <SPAN
763 CLASS="QUOTE"
764 >"<TT
765 CLASS="LITERAL"
766 >/</TT
767 >"</SPAN
768 >, please.
769    </P
770 ></DD
771 ></DL
772 ></DIV
773 ></DIV
774 ><DIV
775 CLASS="SECT3"
776 ><H4
777 CLASS="SECT3"
778 ><A
779 NAME="ACTIONSFILE"
780 >7.2.4. actionsfile</A
781 ></H4
782 ><A
783 NAME="DEFAULT.ACTION"
784 ></A
785 ><A
786 NAME="STANDARD.ACTION"
787 ></A
788 ><A
789 NAME="USER.ACTION"
790 ></A
791 ><P
792 ></P
793 ><DIV
794 CLASS="VARIABLELIST"
795 ><DL
796 ><DT
797 >Specifies:</DT
798 ><DD
799 ><P
800 >    The <A
801 HREF="actions-file.html"
802 >actions file(s)</A
803 > to use
804    </P
805 ></DD
806 ><DT
807 >Type of value:</DT
808 ><DD
809 ><P
810 >Complete file name, relative to <TT
811 CLASS="LITERAL"
812 >confdir</TT
813 ></P
814 ></DD
815 ><DT
816 >Default values:</DT
817 ><DD
818 ><P
819 ></P
820 ><TABLE
821 BORDER="0"
822 ><TBODY
823 ><TR
824 ><TD
825 >     <P
826 CLASS="LITERALLAYOUT"
827 >&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
828 >
829     </TD
830 ></TR
831 ><TR
832 ><TD
833 >     <P
834 CLASS="LITERALLAYOUT"
835 >&nbsp;&nbsp;default.action&nbsp;&nbsp;&nbsp;#&nbsp;Main&nbsp;actions&nbsp;file</P
836 >
837     </TD
838 ></TR
839 ><TR
840 ><TD
841 >     <P
842 CLASS="LITERALLAYOUT"
843 >&nbsp;&nbsp;user.action&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;#&nbsp;User&nbsp;customizations</P
844 >
845     </TD
846 ></TR
847 ></TBODY
848 ></TABLE
849 ><P
850 ></P
851 ></DD
852 ><DT
853 >Effect if unset:</DT
854 ><DD
855 ><P
856 >    No actions are taken at all. More or less neutral proxying. 
857    </P
858 ></DD
859 ><DT
860 >Notes:</DT
861 ><DD
862 ><P
863 >    Multiple <TT
864 CLASS="LITERAL"
865 >actionsfile</TT
866 > lines are permitted, and are in fact recommended!
867    </P
868 ><P
869
870     The default values are <TT
871 CLASS="FILENAME"
872 >default.action</TT
873 >, which is the
874     <SPAN
875 CLASS="QUOTE"
876 >"main"</SPAN
877 > actions file maintained by the developers, and
878     <TT
879 CLASS="FILENAME"
880 >user.action</TT
881 >, where you can make your personal additions.
882    </P
883 ><P
884
885     Actions files contain all the per site and per URL configuration for 
886     ad blocking, cookie management, privacy considerations, etc.
887     There is no point in using <SPAN
888 CLASS="APPLICATION"
889 >Privoxy</SPAN
890 > without at 
891     least one actions file.
892    </P
893 ><P
894 >    Note that since Privoxy 3.0.7, the complete filename, including the <SPAN
895 CLASS="QUOTE"
896 >".action"</SPAN
897 >
898     extension has to be specified.  The syntax change was necessary to be consistent
899     with the other file options and to allow previously forbidden characters.
900    </P
901 ></DD
902 ></DL
903 ></DIV
904 ></DIV
905 ><DIV
906 CLASS="SECT3"
907 ><H4
908 CLASS="SECT3"
909 ><A
910 NAME="FILTERFILE"
911 >7.2.5. filterfile</A
912 ></H4
913 ><A
914 NAME="DEFAULT.FILTER"
915 ></A
916 ><P
917 ></P
918 ><DIV
919 CLASS="VARIABLELIST"
920 ><DL
921 ><DT
922 >Specifies:</DT
923 ><DD
924 ><P
925 >    The <A
926 HREF="filter-file.html"
927 >filter file(s)</A
928 > to use
929    </P
930 ></DD
931 ><DT
932 >Type of value:</DT
933 ><DD
934 ><P
935 >File name, relative to <TT
936 CLASS="LITERAL"
937 >confdir</TT
938 ></P
939 ></DD
940 ><DT
941 >Default value:</DT
942 ><DD
943 ><P
944 >default.filter (Unix) <SPAN
945 CLASS="emphasis"
946 ><I
947 CLASS="EMPHASIS"
948 >or</I
949 ></SPAN
950 > default.filter.txt (Windows)</P
951 ></DD
952 ><DT
953 >Effect if unset:</DT
954 ><DD
955 ><P
956 >    No textual content filtering takes place, i.e. all
957     <TT
958 CLASS="LITERAL"
959 >+<A
960 HREF="actions-file.html#FILTER"
961 >filter</A
962 >{<TT
963 CLASS="REPLACEABLE"
964 ><I
965 >name</I
966 ></TT
967 >}</TT
968 >
969     actions in the actions files are turned neutral.
970    </P
971 ></DD
972 ><DT
973 >Notes:</DT
974 ><DD
975 ><P
976 >    Multiple <TT
977 CLASS="LITERAL"
978 >filterfile</TT
979 > lines are permitted.
980    </P
981 ><P
982 >    The <A
983 HREF="filter-file.html"
984 >filter files</A
985 > contain content modification
986     rules that use <A
987 HREF="appendix.html#REGEX"
988 >regular expressions</A
989 >. These rules permit
990     powerful changes on the content of Web pages, and optionally the headers
991     as well, e.g., you could try to disable your favorite JavaScript annoyances,
992     re-write the actual displayed text, or just have some fun 
993     playing buzzword bingo with web pages.
994    </P
995 ><P
996 >    The
997     <TT
998 CLASS="LITERAL"
999 >+<A
1000 HREF="actions-file.html#FILTER"
1001 >filter</A
1002 >{<TT
1003 CLASS="REPLACEABLE"
1004 ><I
1005 >name</I
1006 ></TT
1007 >}</TT
1008 >
1009     actions rely on the relevant filter (<TT
1010 CLASS="REPLACEABLE"
1011 ><I
1012 >name</I
1013 ></TT
1014 >)
1015     to be defined in a filter file!
1016    </P
1017 ><P
1018 >    A pre-defined filter file called <TT
1019 CLASS="FILENAME"
1020 >default.filter</TT
1021 > that contains
1022     a number of useful filters for common problems is included in the distribution.
1023     See the section on the <TT
1024 CLASS="LITERAL"
1025 ><A
1026 HREF="actions-file.html#FILTER"
1027 >filter</A
1028 ></TT
1029 >
1030     action for a list.
1031    </P
1032 ><P
1033 >    It is recommended to place any locally adapted filters into a separate
1034     file, such as <TT
1035 CLASS="FILENAME"
1036 >user.filter</TT
1037 >.
1038    </P
1039 ></DD
1040 ></DL
1041 ></DIV
1042 ></DIV
1043 ><DIV
1044 CLASS="SECT3"
1045 ><H4
1046 CLASS="SECT3"
1047 ><A
1048 NAME="LOGFILE"
1049 >7.2.6. logfile</A
1050 ></H4
1051 ><P
1052 ></P
1053 ><DIV
1054 CLASS="VARIABLELIST"
1055 ><DL
1056 ><DT
1057 >Specifies:</DT
1058 ><DD
1059 ><P
1060 >    The log file to use
1061    </P
1062 ></DD
1063 ><DT
1064 >Type of value:</DT
1065 ><DD
1066 ><P
1067 >File name, relative to <TT
1068 CLASS="LITERAL"
1069 >logdir</TT
1070 ></P
1071 ></DD
1072 ><DT
1073 >Default value:</DT
1074 ><DD
1075 ><P
1076 ><SPAN
1077 CLASS="emphasis"
1078 ><I
1079 CLASS="EMPHASIS"
1080 >Unset (commented out)</I
1081 ></SPAN
1082 >. When activated: logfile (Unix) <SPAN
1083 CLASS="emphasis"
1084 ><I
1085 CLASS="EMPHASIS"
1086 >or</I
1087 ></SPAN
1088 > privoxy.log (Windows).</P
1089 ></DD
1090 ><DT
1091 >Effect if unset:</DT
1092 ><DD
1093 ><P
1094 >    No logfile is written.
1095    </P
1096 ></DD
1097 ><DT
1098 >Notes:</DT
1099 ><DD
1100 ><P
1101 >    The logfile is where all logging and error messages are written. The level
1102     of detail and number of messages are set with the <TT
1103 CLASS="LITERAL"
1104 >debug</TT
1105 >
1106     option (see below). The logfile can be useful for tracking down a problem with
1107     <SPAN
1108 CLASS="APPLICATION"
1109 >Privoxy</SPAN
1110 > (e.g., it's not blocking an ad you
1111     think it should block) and it can help you to monitor what your browser
1112     is doing.
1113    </P
1114 ><P
1115 >    Depending on the debug options below, the logfile may be a privacy risk
1116     if third parties can get access to it. As most users will never look
1117     at it, <SPAN
1118 CLASS="APPLICATION"
1119 >Privoxy</SPAN
1120 > 3.0.7 and later only log fatal
1121     errors by default.
1122    </P
1123 ><P
1124 >    For most troubleshooting purposes, you will have to change that,
1125     please refer to the debugging section for details.
1126    </P
1127 ><P
1128 >    Your logfile will grow indefinitely, and you will probably want to
1129     periodically remove it.  On Unix systems, you can do this with a cron job
1130     (see <SPAN
1131 CLASS="QUOTE"
1132 >"man cron"</SPAN
1133 >). For Red Hat based Linux distributions, a
1134     <B
1135 CLASS="COMMAND"
1136 >logrotate</B
1137 > script has been included.
1138    </P
1139 ><P
1140 >    Any log files must be writable by whatever user <SPAN
1141 CLASS="APPLICATION"
1142 >Privoxy</SPAN
1143 >
1144     is being run as (on Unix, default user id is <SPAN
1145 CLASS="QUOTE"
1146 >"privoxy"</SPAN
1147 >).
1148    </P
1149 ></DD
1150 ></DL
1151 ></DIV
1152 ></DIV
1153 ><DIV
1154 CLASS="SECT3"
1155 ><H4
1156 CLASS="SECT3"
1157 ><A
1158 NAME="TRUSTFILE"
1159 >7.2.7. trustfile</A
1160 ></H4
1161 ><P
1162 ></P
1163 ><DIV
1164 CLASS="VARIABLELIST"
1165 ><DL
1166 ><DT
1167 >Specifies:</DT
1168 ><DD
1169 ><P
1170 >    The name of the trust file to use
1171    </P
1172 ></DD
1173 ><DT
1174 >Type of value:</DT
1175 ><DD
1176 ><P
1177 >File name, relative to <TT
1178 CLASS="LITERAL"
1179 >confdir</TT
1180 ></P
1181 ></DD
1182 ><DT
1183 >Default value:</DT
1184 ><DD
1185 ><P
1186 ><SPAN
1187 CLASS="emphasis"
1188 ><I
1189 CLASS="EMPHASIS"
1190 >Unset (commented out)</I
1191 ></SPAN
1192 >. When activated: trust (Unix) <SPAN
1193 CLASS="emphasis"
1194 ><I
1195 CLASS="EMPHASIS"
1196 >or</I
1197 ></SPAN
1198 > trust.txt (Windows)</P
1199 ></DD
1200 ><DT
1201 >Effect if unset:</DT
1202 ><DD
1203 ><P
1204 >    The entire trust mechanism is disabled.
1205    </P
1206 ></DD
1207 ><DT
1208 >Notes:</DT
1209 ><DD
1210 ><P
1211 >    The trust mechanism is an experimental feature for building white-lists and should
1212     be used with care. It is <SPAN
1213 CLASS="emphasis"
1214 ><I
1215 CLASS="EMPHASIS"
1216 >NOT</I
1217 ></SPAN
1218 > recommended for the casual user.
1219    </P
1220 ><P
1221 >    If you specify a trust file, <SPAN
1222 CLASS="APPLICATION"
1223 >Privoxy</SPAN
1224 > will only allow
1225     access to sites that are specified in the trustfile. Sites can be listed 
1226     in one of two ways:
1227    </P
1228 ><P
1229 >    Prepending a <TT
1230 CLASS="LITERAL"
1231 >~</TT
1232 > character limits access to this site 
1233     only (and any sub-paths within this site), e.g. 
1234     <TT
1235 CLASS="LITERAL"
1236 >~www.example.com</TT
1237 > allows access to
1238     <TT
1239 CLASS="LITERAL"
1240 >~www.example.com/features/news.html</TT
1241 >, etc. 
1242    </P
1243 ><P
1244 >    Or, you can designate sites as <SPAN
1245 CLASS="emphasis"
1246 ><I
1247 CLASS="EMPHASIS"
1248 >trusted referrers</I
1249 ></SPAN
1250 >, by
1251     prepending the name with a <TT
1252 CLASS="LITERAL"
1253 >+</TT
1254 > character. The effect is that
1255     access to untrusted sites will be granted -- but only if a link from this
1256     trusted referrer was used to get there. The link target will then be added
1257     to the <SPAN
1258 CLASS="QUOTE"
1259 >"trustfile"</SPAN
1260 > so that future, direct accesses will be
1261     granted. Sites added via this mechanism do not become trusted referrers
1262     themselves (i.e. they are added with a <TT
1263 CLASS="LITERAL"
1264 >~</TT
1265 > designation).
1266     There is a limit of 512 such entries, after which new entries will not be
1267     made.
1268    </P
1269 ><P
1270 >    If you use the <TT
1271 CLASS="LITERAL"
1272 >+</TT
1273 > operator in the trust file, it may grow 
1274     considerably over time.
1275    </P
1276 ><P
1277 >    It is recommended that <SPAN
1278 CLASS="APPLICATION"
1279 >Privoxy</SPAN
1280 > be compiled with
1281     the <TT
1282 CLASS="LITERAL"
1283 >--disable-force</TT
1284 >, <TT
1285 CLASS="LITERAL"
1286 >--disable-toggle</TT
1287 > and
1288     <TT
1289 CLASS="LITERAL"
1290 > --disable-editor</TT
1291 > options, if this feature is to be
1292     used.
1293    </P
1294 ><P
1295 >    Possible applications include limiting Internet access for children.
1296    </P
1297 ></DD
1298 ></DL
1299 ></DIV
1300 ></DIV
1301 ></DIV
1302 ><DIV
1303 CLASS="SECT2"
1304 ><H2
1305 CLASS="SECT2"
1306 ><A
1307 NAME="DEBUGGING"
1308 >7.3. Debugging</A
1309 ></H2
1310 ><P
1311 >  These options are mainly useful when tracing a problem.
1312   Note that you might also want to invoke
1313   <SPAN
1314 CLASS="APPLICATION"
1315 >Privoxy</SPAN
1316 > with the <TT
1317 CLASS="LITERAL"
1318 >--no-daemon</TT
1319 >
1320   command line option when debugging.
1321  </P
1322 ><DIV
1323 CLASS="SECT3"
1324 ><H4
1325 CLASS="SECT3"
1326 ><A
1327 NAME="DEBUG"
1328 >7.3.1. debug</A
1329 ></H4
1330 ><P
1331 ></P
1332 ><DIV
1333 CLASS="VARIABLELIST"
1334 ><DL
1335 ><DT
1336 >Specifies:</DT
1337 ><DD
1338 ><P
1339 >    Key values that determine what information gets logged.
1340    </P
1341 ></DD
1342 ><DT
1343 >Type of value:</DT
1344 ><DD
1345 ><P
1346 >Integer values</P
1347 ></DD
1348 ><DT
1349 >Default value:</DT
1350 ><DD
1351 ><P
1352 >0 (i.e.: only fatal errors (that cause Privoxy to exit) are logged)</P
1353 ></DD
1354 ><DT
1355 >Effect if unset:</DT
1356 ><DD
1357 ><P
1358 >    Default value is used (see above).
1359    </P
1360 ></DD
1361 ><DT
1362 >Notes:</DT
1363 ><DD
1364 ><P
1365 >    The available debug levels are:
1366    </P
1367 ><P
1368 >    <TABLE
1369 BORDER="0"
1370 BGCOLOR="#E0E0E0"
1371 WIDTH="90%"
1372 ><TR
1373 ><TD
1374 ><PRE
1375 CLASS="PROGRAMLISTING"
1376 >  debug     1 # Log the destination for each request <SPAN
1377 CLASS="APPLICATION"
1378 >Privoxy</SPAN
1379 > let through. See also debug 1024.
1380   debug     2 # show each connection status
1381   debug     4 # show I/O status
1382   debug     8 # show header parsing
1383   debug    16 # log all data written to the network
1384   debug    32 # debug force feature
1385   debug    64 # debug regular expression filters
1386   debug   128 # debug redirects
1387   debug   256 # debug GIF de-animation
1388   debug   512 # Common Log Format
1389   debug  1024 # Log the destination for requests <SPAN
1390 CLASS="APPLICATION"
1391 >Privoxy</SPAN
1392 > didn't let through, and the reason why.
1393   debug  2048 # CGI user interface
1394   debug  4096 # Startup banner and warnings.
1395   debug  8192 # Non-fatal errors
1396   debug 32768 # log all data read from the network</PRE
1397 ></TD
1398 ></TR
1399 ></TABLE
1400 >
1401    </P
1402 ><P
1403 >    To select multiple debug levels, you can either add them or use
1404     multiple <TT
1405 CLASS="LITERAL"
1406 >debug</TT
1407 > lines.
1408    </P
1409 ><P
1410 >    A debug level of 1 is informative because it will show you each request
1411     as it happens. <SPAN
1412 CLASS="emphasis"
1413 ><I
1414 CLASS="EMPHASIS"
1415 >1, 1024, 4096 and 8192 are recommended</I
1416 ></SPAN
1417 >
1418     so that you will notice when things go wrong. The other levels are
1419     probably only of interest if you are hunting down a specific problem.
1420     They can produce a hell of an output (especially 16).
1421     
1422    </P
1423 ><P
1424 >    <SPAN
1425 CLASS="APPLICATION"
1426 >Privoxy</SPAN
1427 > used to ship with the debug levels recommended above enabled by
1428     default, but due to privacy concerns 3.0.7 and later are configured to
1429     only log fatal errors.
1430    </P
1431 ><P
1432 >    If you are used to the more verbose settings, simply enable the debug lines
1433     below again.
1434    </P
1435 ><P
1436 >    If you want to use pure CLF (Common Log Format), you should set <SPAN
1437 CLASS="QUOTE"
1438 >"debug
1439     512"</SPAN
1440 > <SPAN
1441 CLASS="emphasis"
1442 ><I
1443 CLASS="EMPHASIS"
1444 >ONLY</I
1445 ></SPAN
1446 > and not enable anything else.
1447    </P
1448 ><P
1449 >    <SPAN
1450 CLASS="APPLICATION"
1451 >Privoxy</SPAN
1452 > has a hard-coded limit for the
1453     length of log messages. If it's reached, messages are logged truncated
1454     and marked with <SPAN
1455 CLASS="QUOTE"
1456 >"... [too long, truncated]"</SPAN
1457 >.
1458    </P
1459 ><P
1460 >    Please don't file any support requests without trying to reproduce
1461     the problem with increased debug level first. Once you read the log
1462     messages, you may even be able to solve the problem on your own.
1463    </P
1464 ></DD
1465 ></DL
1466 ></DIV
1467 ></DIV
1468 ><DIV
1469 CLASS="SECT3"
1470 ><H4
1471 CLASS="SECT3"
1472 ><A
1473 NAME="SINGLE-THREADED"
1474 >7.3.2. single-threaded</A
1475 ></H4
1476 ><P
1477 ></P
1478 ><DIV
1479 CLASS="VARIABLELIST"
1480 ><DL
1481 ><DT
1482 >Specifies:</DT
1483 ><DD
1484 ><P
1485 >    Whether to run only one server thread.
1486    </P
1487 ></DD
1488 ><DT
1489 >Type of value:</DT
1490 ><DD
1491 ><P
1492 ><SPAN
1493 CLASS="emphasis"
1494 ><I
1495 CLASS="EMPHASIS"
1496 >None</I
1497 ></SPAN
1498 ></P
1499 ></DD
1500 ><DT
1501 >Default value:</DT
1502 ><DD
1503 ><P
1504 ><SPAN
1505 CLASS="emphasis"
1506 ><I
1507 CLASS="EMPHASIS"
1508 >Unset</I
1509 ></SPAN
1510 ></P
1511 ></DD
1512 ><DT
1513 >Effect if unset:</DT
1514 ><DD
1515 ><P
1516 >    Multi-threaded (or, where unavailable: forked) operation, i.e. the ability to
1517     serve multiple requests simultaneously.
1518    </P
1519 ></DD
1520 ><DT
1521 >Notes:</DT
1522 ><DD
1523 ><P
1524 >    This option is only there for debugging purposes.
1525     <SPAN
1526 CLASS="emphasis"
1527 ><I
1528 CLASS="EMPHASIS"
1529 >It will drastically reduce performance.</I
1530 ></SPAN
1531 >
1532    </P
1533 ></DD
1534 ></DL
1535 ></DIV
1536 ></DIV
1537 ><DIV
1538 CLASS="SECT3"
1539 ><H4
1540 CLASS="SECT3"
1541 ><A
1542 NAME="HOSTNAME"
1543 >7.3.3. hostname</A
1544 ></H4
1545 ><P
1546 ></P
1547 ><DIV
1548 CLASS="VARIABLELIST"
1549 ><DL
1550 ><DT
1551 >Specifies:</DT
1552 ><DD
1553 ><P
1554 >    The hostname shown on the CGI pages.
1555    </P
1556 ></DD
1557 ><DT
1558 >Type of value:</DT
1559 ><DD
1560 ><P
1561 >Text</P
1562 ></DD
1563 ><DT
1564 >Default value:</DT
1565 ><DD
1566 ><P
1567 ><SPAN
1568 CLASS="emphasis"
1569 ><I
1570 CLASS="EMPHASIS"
1571 >Unset</I
1572 ></SPAN
1573 ></P
1574 ></DD
1575 ><DT
1576 >Effect if unset:</DT
1577 ><DD
1578 ><P
1579 >    The hostname provided by the operating system is used.
1580    </P
1581 ></DD
1582 ><DT
1583 >Notes:</DT
1584 ><DD
1585 ><P
1586 >    On some misconfigured systems resolving the hostname fails or
1587     takes too much time and slows Privoxy down. Setting a fixed hostname
1588     works around the problem.
1589    </P
1590 ><P
1591 >    In other circumstances it might be desirable to show a hostname
1592     other than the one returned by the operating system. For example
1593     if the system has several different hostnames and you don't want
1594     to use the first one.
1595    </P
1596 ><P
1597 >    Note that Privoxy does not validate the specified hostname value.
1598    </P
1599 ></DD
1600 ></DL
1601 ></DIV
1602 ></DIV
1603 ></DIV
1604 ><DIV
1605 CLASS="SECT2"
1606 ><H2
1607 CLASS="SECT2"
1608 ><A
1609 NAME="ACCESS-CONTROL"
1610 >7.4. Access Control and Security</A
1611 ></H2
1612 ><P
1613 >  This section of the config file controls the security-relevant aspects
1614   of <SPAN
1615 CLASS="APPLICATION"
1616 >Privoxy</SPAN
1617 >'s configuration.
1618  </P
1619 ><DIV
1620 CLASS="SECT3"
1621 ><H4
1622 CLASS="SECT3"
1623 ><A
1624 NAME="LISTEN-ADDRESS"
1625 >7.4.1. listen-address</A
1626 ></H4
1627 ><P
1628 ></P
1629 ><DIV
1630 CLASS="VARIABLELIST"
1631 ><DL
1632 ><DT
1633 >Specifies:</DT
1634 ><DD
1635 ><P
1636 >    The IP address and TCP port on which <SPAN
1637 CLASS="APPLICATION"
1638 >Privoxy</SPAN
1639 > will
1640     listen for client requests.
1641    </P
1642 ></DD
1643 ><DT
1644 >Type of value:</DT
1645 ><DD
1646 ><P
1647 >[<TT
1648 CLASS="REPLACEABLE"
1649 ><I
1650 >IP-Address</I
1651 ></TT
1652 >]:<TT
1653 CLASS="REPLACEABLE"
1654 ><I
1655 >Port</I
1656 ></TT
1657 ></P
1658 ></DD
1659 ><DT
1660 >Default value:</DT
1661 ><DD
1662 ><P
1663 >127.0.0.1:8118</P
1664 ></DD
1665 ><DT
1666 >Effect if unset:</DT
1667 ><DD
1668 ><P
1669 >    Bind to 127.0.0.1 (IPv4 localhost), port 8118. This is suitable and
1670     recommended for home users who run <SPAN
1671 CLASS="APPLICATION"
1672 >Privoxy</SPAN
1673 > on
1674     the same machine as their browser.
1675    </P
1676 ></DD
1677 ><DT
1678 >Notes:</DT
1679 ><DD
1680 ><P
1681 >    You will need to configure your browser(s) to this proxy address and port.
1682    </P
1683 ><P
1684 >    If you already have another service running on port 8118, or if you want to
1685     serve requests from other machines (e.g. on your local network) as well, you
1686     will need to override the default.
1687    </P
1688 ><P
1689 >    IPv6 addresses containing colons have to be quoted by brackets.
1690    </P
1691 ><P
1692 >    If you leave out the IP address, <SPAN
1693 CLASS="APPLICATION"
1694 >Privoxy</SPAN
1695 > will
1696     bind to all IPv4 interfaces (addresses) on your machine and may become reachable
1697     from the Internet. In that case, consider using <A
1698 HREF="config.html#ACLS"
1699 >access control lists</A
1700 > (ACL's, see below), and/or
1701     a firewall.
1702    </P
1703 ><P
1704 >    If you open <SPAN
1705 CLASS="APPLICATION"
1706 >Privoxy</SPAN
1707 > to untrusted users, you will
1708     also want to make sure that the following actions are disabled:  <TT
1709 CLASS="LITERAL"
1710 ><A
1711 HREF="config.html#ENABLE-EDIT-ACTIONS"
1712 >enable-edit-actions</A
1713 ></TT
1714 > and
1715     <TT
1716 CLASS="LITERAL"
1717 ><A
1718 HREF="config.html#ENABLE-REMOTE-TOGGLE"
1719 >enable-remote-toggle</A
1720 ></TT
1721 >
1722    </P
1723 ></DD
1724 ><DT
1725 >Example:</DT
1726 ><DD
1727 ><P
1728 >     Suppose you are running <SPAN
1729 CLASS="APPLICATION"
1730 >Privoxy</SPAN
1731 > on
1732      a machine which has the address 192.168.0.1 on your local private network
1733      (192.168.0.0) and has another outside connection with a different address.
1734      You want it to serve requests from inside only:
1735    </P
1736 ><P
1737 >    <TABLE
1738 BORDER="0"
1739 BGCOLOR="#E0E0E0"
1740 WIDTH="90%"
1741 ><TR
1742 ><TD
1743 ><PRE
1744 CLASS="PROGRAMLISTING"
1745 >  listen-address  192.168.0.1:8118</PRE
1746 ></TD
1747 ></TR
1748 ></TABLE
1749 >
1750    </P
1751 ><P
1752 >    Suppose you are running <SPAN
1753 CLASS="APPLICATION"
1754 >Privoxy</SPAN
1755 > on an
1756     IPv6-capable machine and you want it to listen on the IPv6 address
1757     of the loopback device:
1758    </P
1759 ><P
1760 >    <TABLE
1761 BORDER="0"
1762 BGCOLOR="#E0E0E0"
1763 WIDTH="90%"
1764 ><TR
1765 ><TD
1766 ><PRE
1767 CLASS="PROGRAMLISTING"
1768 >  listen-address [::1]:8118</PRE
1769 ></TD
1770 ></TR
1771 ></TABLE
1772 >
1773    </P
1774 ></DD
1775 ></DL
1776 ></DIV
1777 ></DIV
1778 ><DIV
1779 CLASS="SECT3"
1780 ><H4
1781 CLASS="SECT3"
1782 ><A
1783 NAME="TOGGLE"
1784 >7.4.2. toggle</A
1785 ></H4
1786 ><P
1787 ></P
1788 ><DIV
1789 CLASS="VARIABLELIST"
1790 ><DL
1791 ><DT
1792 >Specifies:</DT
1793 ><DD
1794 ><P
1795 >    Initial state of "toggle" status
1796    </P
1797 ></DD
1798 ><DT
1799 >Type of value:</DT
1800 ><DD
1801 ><P
1802 >1 or 0</P
1803 ></DD
1804 ><DT
1805 >Default value:</DT
1806 ><DD
1807 ><P
1808 >1</P
1809 ></DD
1810 ><DT
1811 >Effect if unset:</DT
1812 ><DD
1813 ><P
1814 >    Act as if toggled on
1815    </P
1816 ></DD
1817 ><DT
1818 >Notes:</DT
1819 ><DD
1820 ><P
1821 >    If set to 0, <SPAN
1822 CLASS="APPLICATION"
1823 >Privoxy</SPAN
1824 > will start in
1825     <SPAN
1826 CLASS="QUOTE"
1827 >"toggled off"</SPAN
1828 > mode, i.e. mostly behave like a normal,
1829     content-neutral proxy with both ad blocking and content filtering
1830     disabled. See <TT
1831 CLASS="LITERAL"
1832 >enable-remote-toggle</TT
1833 > below.
1834    </P
1835 ><P
1836 >    The windows version will only display the toggle icon in the system tray
1837     if this option is present.
1838    </P
1839 ></DD
1840 ></DL
1841 ></DIV
1842 ></DIV
1843 ><DIV
1844 CLASS="SECT3"
1845 ><H4
1846 CLASS="SECT3"
1847 ><A
1848 NAME="ENABLE-REMOTE-TOGGLE"
1849 >7.4.3. enable-remote-toggle</A
1850 ></H4
1851 ><P
1852 ></P
1853 ><DIV
1854 CLASS="VARIABLELIST"
1855 ><DL
1856 ><DT
1857 >Specifies:</DT
1858 ><DD
1859 ><P
1860 >    Whether or not the <A
1861 HREF="http://config.privoxy.org/toggle"
1862 TARGET="_top"
1863 >web-based toggle
1864     feature</A
1865 > may be used
1866    </P
1867 ></DD
1868 ><DT
1869 >Type of value:</DT
1870 ><DD
1871 ><P
1872 >0 or 1</P
1873 ></DD
1874 ><DT
1875 >Default value:</DT
1876 ><DD
1877 ><P
1878 >0</P
1879 ></DD
1880 ><DT
1881 >Effect if unset:</DT
1882 ><DD
1883 ><P
1884 >    The web-based toggle feature is disabled.
1885    </P
1886 ></DD
1887 ><DT
1888 >Notes:</DT
1889 ><DD
1890 ><P
1891 >    When toggled off, <SPAN
1892 CLASS="APPLICATION"
1893 >Privoxy</SPAN
1894 > mostly acts like a normal,
1895     content-neutral proxy, i.e. doesn't block ads or filter content.
1896    </P
1897 ><P
1898 >    Access to the toggle feature can <SPAN
1899 CLASS="emphasis"
1900 ><I
1901 CLASS="EMPHASIS"
1902 >not</I
1903 ></SPAN
1904 > be
1905     controlled separately by <SPAN
1906 CLASS="QUOTE"
1907 >"ACLs"</SPAN
1908 > or HTTP authentication,
1909     so that everybody who can access <SPAN
1910 CLASS="APPLICATION"
1911 >Privoxy</SPAN
1912 > (see
1913     <SPAN
1914 CLASS="QUOTE"
1915 >"ACLs"</SPAN
1916 > and <TT
1917 CLASS="LITERAL"
1918 >listen-address</TT
1919 > above) can
1920     toggle it for all users. So this option is <SPAN
1921 CLASS="emphasis"
1922 ><I
1923 CLASS="EMPHASIS"
1924 >not recommended</I
1925 ></SPAN
1926 >
1927     for multi-user environments with untrusted users.
1928    </P
1929 ><P
1930 >    Note that malicious client side code (e.g Java) is also
1931     capable of using this option.
1932    </P
1933 ><P
1934 >    As a lot of <SPAN
1935 CLASS="APPLICATION"
1936 >Privoxy</SPAN
1937 > users don't read
1938     documentation, this feature is disabled by default.
1939    </P
1940 ><P
1941 >    Note that you must have compiled <SPAN
1942 CLASS="APPLICATION"
1943 >Privoxy</SPAN
1944 > with
1945     support for this feature, otherwise this option has no effect. 
1946    </P
1947 ></DD
1948 ></DL
1949 ></DIV
1950 ></DIV
1951 ><DIV
1952 CLASS="SECT3"
1953 ><H4
1954 CLASS="SECT3"
1955 ><A
1956 NAME="ENABLE-REMOTE-HTTP-TOGGLE"
1957 >7.4.4. enable-remote-http-toggle</A
1958 ></H4
1959 ><P
1960 ></P
1961 ><DIV
1962 CLASS="VARIABLELIST"
1963 ><DL
1964 ><DT
1965 >Specifies:</DT
1966 ><DD
1967 ><P
1968 >    Whether or not Privoxy recognizes special HTTP headers to change its behaviour.
1969    </P
1970 ></DD
1971 ><DT
1972 >Type of value:</DT
1973 ><DD
1974 ><P
1975 >0 or 1</P
1976 ></DD
1977 ><DT
1978 >Default value:</DT
1979 ><DD
1980 ><P
1981 >0</P
1982 ></DD
1983 ><DT
1984 >Effect if unset:</DT
1985 ><DD
1986 ><P
1987 >    Privoxy ignores special HTTP headers.
1988    </P
1989 ></DD
1990 ><DT
1991 >Notes:</DT
1992 ><DD
1993 ><P
1994 >    When toggled on, the client can change <SPAN
1995 CLASS="APPLICATION"
1996 >Privoxy's</SPAN
1997 >
1998     behaviour by setting special HTTP headers. Currently the only supported
1999     special header is <SPAN
2000 CLASS="QUOTE"
2001 >"X-Filter: No"</SPAN
2002 >, to disable filtering for
2003     the ongoing request, even if it is enabled in one of the action files.
2004    </P
2005 ><P
2006 >    This feature is disabled by default. If you are using
2007     <SPAN
2008 CLASS="APPLICATION"
2009 >Privoxy</SPAN
2010 > in a environment with trusted clients,
2011     you may enable this feature at your discretion. Note that malicious client
2012     side code (e.g Java) is also capable of using this feature.
2013    </P
2014 ><P
2015 >    This option will be removed in future releases as it has been obsoleted
2016     by the more general header taggers.
2017    </P
2018 ></DD
2019 ></DL
2020 ></DIV
2021 ></DIV
2022 ><DIV
2023 CLASS="SECT3"
2024 ><H4
2025 CLASS="SECT3"
2026 ><A
2027 NAME="ENABLE-EDIT-ACTIONS"
2028 >7.4.5. enable-edit-actions</A
2029 ></H4
2030 ><P
2031 ></P
2032 ><DIV
2033 CLASS="VARIABLELIST"
2034 ><DL
2035 ><DT
2036 >Specifies:</DT
2037 ><DD
2038 ><P
2039 >    Whether or not the <A
2040 HREF="http://config.privoxy.org/show-status"
2041 TARGET="_top"
2042 >web-based actions
2043     file editor</A
2044 > may be used
2045    </P
2046 ></DD
2047 ><DT
2048 >Type of value:</DT
2049 ><DD
2050 ><P
2051 >0 or 1</P
2052 ></DD
2053 ><DT
2054 >Default value:</DT
2055 ><DD
2056 ><P
2057 >0</P
2058 ></DD
2059 ><DT
2060 >Effect if unset:</DT
2061 ><DD
2062 ><P
2063 >    The web-based actions file editor is disabled.
2064    </P
2065 ></DD
2066 ><DT
2067 >Notes:</DT
2068 ><DD
2069 ><P
2070 >    Access to the editor can <SPAN
2071 CLASS="emphasis"
2072 ><I
2073 CLASS="EMPHASIS"
2074 >not</I
2075 ></SPAN
2076 > be
2077     controlled separately by <SPAN
2078 CLASS="QUOTE"
2079 >"ACLs"</SPAN
2080 > or HTTP authentication,
2081     so that everybody who can access <SPAN
2082 CLASS="APPLICATION"
2083 >Privoxy</SPAN
2084 > (see
2085     <SPAN
2086 CLASS="QUOTE"
2087 >"ACLs"</SPAN
2088 > and <TT
2089 CLASS="LITERAL"
2090 >listen-address</TT
2091 > above) can
2092     modify its configuration for all users.
2093    </P
2094 ><P
2095 >    This option is <SPAN
2096 CLASS="emphasis"
2097 ><I
2098 CLASS="EMPHASIS"
2099 >not recommended</I
2100 ></SPAN
2101 > for environments
2102     with untrusted users and as a lot of <SPAN
2103 CLASS="APPLICATION"
2104 >Privoxy</SPAN
2105 >
2106     users don't read documentation, this feature is disabled by default.
2107    </P
2108 ><P
2109 >    Note that malicious client side code (e.g Java) is also
2110     capable of using the actions editor and you shouldn't enable
2111     this options unless you understand the consequences and are
2112     sure your browser is configured correctly.
2113    </P
2114 ><P
2115 >    Note that you must have compiled <SPAN
2116 CLASS="APPLICATION"
2117 >Privoxy</SPAN
2118 > with
2119     support for this feature, otherwise this option has no effect. 
2120    </P
2121 ></DD
2122 ></DL
2123 ></DIV
2124 ></DIV
2125 ><DIV
2126 CLASS="SECT3"
2127 ><H4
2128 CLASS="SECT3"
2129 ><A
2130 NAME="ENFORCE-BLOCKS"
2131 >7.4.6. enforce-blocks</A
2132 ></H4
2133 ><P
2134 ></P
2135 ><DIV
2136 CLASS="VARIABLELIST"
2137 ><DL
2138 ><DT
2139 >Specifies:</DT
2140 ><DD
2141 ><P
2142 >    Whether the user is allowed to ignore blocks and can <SPAN
2143 CLASS="QUOTE"
2144 >"go there anyway"</SPAN
2145 >.
2146    </P
2147 ></DD
2148 ><DT
2149 >Type of value:</DT
2150 ><DD
2151 ><P
2152 >    <TT
2153 CLASS="REPLACEABLE"
2154 ><I
2155 >0 or 1</I
2156 ></TT
2157 >
2158    </P
2159 ></DD
2160 ><DT
2161 >Default value:</DT
2162 ><DD
2163 ><P
2164 ><SPAN
2165 CLASS="emphasis"
2166 ><I
2167 CLASS="EMPHASIS"
2168 >0</I
2169 ></SPAN
2170 ></P
2171 ></DD
2172 ><DT
2173 >Effect if unset:</DT
2174 ><DD
2175 ><P
2176 >    Blocks are not enforced.
2177    </P
2178 ></DD
2179 ><DT
2180 >Notes:</DT
2181 ><DD
2182 ><P
2183 >    <SPAN
2184 CLASS="APPLICATION"
2185 >Privoxy</SPAN
2186 > is mainly used to block and filter
2187     requests as a service to the user, for example to block ads and other
2188     junk that clogs the pipes. <SPAN
2189 CLASS="APPLICATION"
2190 >Privoxy's</SPAN
2191 > configuration
2192     isn't perfect and sometimes innocent pages are blocked. In this situation it
2193     makes sense to allow the user to enforce the request and have
2194     <SPAN
2195 CLASS="APPLICATION"
2196 >Privoxy</SPAN
2197 > ignore the block.
2198    </P
2199 ><P
2200 >    In the default configuration <SPAN
2201 CLASS="APPLICATION"
2202 >Privoxy's</SPAN
2203 >
2204     <SPAN
2205 CLASS="QUOTE"
2206 >"Blocked"</SPAN
2207 > page contains a <SPAN
2208 CLASS="QUOTE"
2209 >"go there anyway"</SPAN
2210 >
2211     link to adds a special string (the force prefix) to the request URL.
2212     If that link is used, <SPAN
2213 CLASS="APPLICATION"
2214 >Privoxy</SPAN
2215 > will
2216     detect the force prefix, remove it again and let the request pass.
2217    </P
2218 ><P
2219 >    Of course <SPAN
2220 CLASS="APPLICATION"
2221 >Privoxy</SPAN
2222 > can also be used to enforce
2223     a network policy. In that case the user obviously should not be able to
2224     bypass any blocks, and that's what the <SPAN
2225 CLASS="QUOTE"
2226 >"enforce-blocks"</SPAN
2227 >
2228     option is for. If it's enabled, <SPAN
2229 CLASS="APPLICATION"
2230 >Privoxy</SPAN
2231 > hides
2232     the <SPAN
2233 CLASS="QUOTE"
2234 >"go there anyway"</SPAN
2235 > link. If the user adds the force
2236     prefix by hand, it will not be accepted and the circumvention attempt
2237     is logged.
2238    </P
2239 ></DD
2240 ><DT
2241 >Examples:</DT
2242 ><DD
2243 ><P
2244 >    enforce-blocks 1
2245    </P
2246 ></DD
2247 ></DL
2248 ></DIV
2249 ></DIV
2250 ><DIV
2251 CLASS="SECT3"
2252 ><H4
2253 CLASS="SECT3"
2254 ><A
2255 NAME="ACLS"
2256 >7.4.7. ACLs: permit-access and deny-access</A
2257 ></H4
2258 ><A
2259 NAME="PERMIT-ACCESS"
2260 ></A
2261 ><A
2262 NAME="DENY-ACCESS"
2263 ></A
2264 ><P
2265 ></P
2266 ><DIV
2267 CLASS="VARIABLELIST"
2268 ><DL
2269 ><DT
2270 >Specifies:</DT
2271 ><DD
2272 ><P
2273 >    Who can access what.
2274    </P
2275 ></DD
2276 ><DT
2277 >Type of value:</DT
2278 ><DD
2279 ><P
2280 >    <TT
2281 CLASS="REPLACEABLE"
2282 ><I
2283 >src_addr</I
2284 ></TT
2285 >[:<TT
2286 CLASS="REPLACEABLE"
2287 ><I
2288 >port</I
2289 ></TT
2290 >][/<TT
2291 CLASS="REPLACEABLE"
2292 ><I
2293 >src_masklen</I
2294 ></TT
2295 >]
2296     [<TT
2297 CLASS="REPLACEABLE"
2298 ><I
2299 >dst_addr</I
2300 ></TT
2301 >[:<TT
2302 CLASS="REPLACEABLE"
2303 ><I
2304 >port</I
2305 ></TT
2306 >][/<TT
2307 CLASS="REPLACEABLE"
2308 ><I
2309 >dst_masklen</I
2310 ></TT
2311 >]]
2312    </P
2313 ><P
2314 >    Where <TT
2315 CLASS="REPLACEABLE"
2316 ><I
2317 >src_addr</I
2318 ></TT
2319 > and 
2320    <TT
2321 CLASS="REPLACEABLE"
2322 ><I
2323 >dst_addr</I
2324 ></TT
2325 > are IPv4 addresses in dotted decimal notation or valid
2326     DNS names, <TT
2327 CLASS="REPLACEABLE"
2328 ><I
2329 >port</I
2330 ></TT
2331 > is a port
2332     number, and <TT
2333 CLASS="REPLACEABLE"
2334 ><I
2335 >src_masklen</I
2336 ></TT
2337 > and
2338     <TT
2339 CLASS="REPLACEABLE"
2340 ><I
2341 >dst_masklen</I
2342 ></TT
2343 > are subnet masks in CIDR notation, i.e. integer
2344     values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole
2345     destination part are optional.
2346    </P
2347 ><P
2348 >    If your system implements
2349     <A
2350 HREF="http://tools.ietf.org/html/rfc3493"
2351 TARGET="_top"
2352 >RFC 3493</A
2353 >, then
2354     <TT
2355 CLASS="REPLACEABLE"
2356 ><I
2357 >src_addr</I
2358 ></TT
2359 > and <TT
2360 CLASS="REPLACEABLE"
2361 ><I
2362 >dst_addr</I
2363 ></TT
2364 > can be IPv6 addresses delimeted by
2365     brackets, <TT
2366 CLASS="REPLACEABLE"
2367 ><I
2368 >port</I
2369 ></TT
2370 > can be a number
2371     or a service name, and
2372     <TT
2373 CLASS="REPLACEABLE"
2374 ><I
2375 >src_masklen</I
2376 ></TT
2377 > and
2378     <TT
2379 CLASS="REPLACEABLE"
2380 ><I
2381 >dst_masklen</I
2382 ></TT
2383 > can be a number
2384     from 0 to 128.
2385    </P
2386 ></DD
2387 ><DT
2388 >Default value:</DT
2389 ><DD
2390 ><P
2391 ><SPAN
2392 CLASS="emphasis"
2393 ><I
2394 CLASS="EMPHASIS"
2395 >Unset</I
2396 ></SPAN
2397 ></P
2398 ><P
2399 >    If no <TT
2400 CLASS="REPLACEABLE"
2401 ><I
2402 >port</I
2403 ></TT
2404 > is specified,
2405     any port will match. If no <TT
2406 CLASS="REPLACEABLE"
2407 ><I
2408 >src_masklen</I
2409 ></TT
2410 > or
2411     <TT
2412 CLASS="REPLACEABLE"
2413 ><I
2414 >src_masklen</I
2415 ></TT
2416 > is given, the complete IP
2417     address has to match (i.e. 32 bits for IPv4 and 128 bits for IPv6).
2418    </P
2419 ></DD
2420 ><DT
2421 >Effect if unset:</DT
2422 ><DD
2423 ><P
2424 >    Don't restrict access further than implied by <TT
2425 CLASS="LITERAL"
2426 >listen-address</TT
2427 >
2428    </P
2429 ></DD
2430 ><DT
2431 >Notes:</DT
2432 ><DD
2433 ><P
2434 >    Access controls are included at the request of ISPs and systems
2435     administrators, and <SPAN
2436 CLASS="emphasis"
2437 ><I
2438 CLASS="EMPHASIS"
2439 >are not usually needed by individual users</I
2440 ></SPAN
2441 >.
2442     For a typical home user, it will normally suffice to ensure that 
2443     <SPAN
2444 CLASS="APPLICATION"
2445 >Privoxy</SPAN
2446 > only listens on the localhost
2447     (127.0.0.1) or internal (home) network address by means of the
2448     <A
2449 HREF="config.html#LISTEN-ADDRESS"
2450 ><SPAN
2451 CLASS="emphasis"
2452 ><I
2453 CLASS="EMPHASIS"
2454 >listen-address</I
2455 ></SPAN
2456 ></A
2457 >
2458     option. 
2459    </P
2460 ><P
2461 >    Please see the warnings in the FAQ that <SPAN
2462 CLASS="APPLICATION"
2463 >Privoxy</SPAN
2464 >
2465     is not intended to be a substitute for a firewall or to encourage anyone
2466     to defer addressing basic security weaknesses.
2467    </P
2468 ><P
2469 >    Multiple ACL lines are OK.
2470     If any ACLs are specified, <SPAN
2471 CLASS="APPLICATION"
2472 >Privoxy</SPAN
2473 > only talks
2474     to IP addresses that match at least one <TT
2475 CLASS="LITERAL"
2476 >permit-access</TT
2477 > line
2478     and don't match any subsequent <TT
2479 CLASS="LITERAL"
2480 >deny-access</TT
2481 > line. In other words, the
2482     last match wins, with the default being <TT
2483 CLASS="LITERAL"
2484 >deny-access</TT
2485 >.
2486    </P
2487 ><P
2488 >    If <SPAN
2489 CLASS="APPLICATION"
2490 >Privoxy</SPAN
2491 > is using a forwarder (see <TT
2492 CLASS="LITERAL"
2493 >forward</TT
2494 > below)
2495     for a particular destination URL, the <TT
2496 CLASS="REPLACEABLE"
2497 ><I
2498 >dst_addr</I
2499 ></TT
2500 >
2501     that is examined is the address of the forwarder and <SPAN
2502 CLASS="emphasis"
2503 ><I
2504 CLASS="EMPHASIS"
2505 >NOT</I
2506 ></SPAN
2507 > the address
2508     of the ultimate target. This is necessary because it may be impossible for the local
2509     <SPAN
2510 CLASS="APPLICATION"
2511 >Privoxy</SPAN
2512 > to determine the IP address of the
2513     ultimate target (that's often what gateways are used for).
2514    </P
2515 ><P
2516 >    You should prefer using IP addresses over DNS names, because the address lookups take
2517     time. All DNS names must resolve! You can <SPAN
2518 CLASS="emphasis"
2519 ><I
2520 CLASS="EMPHASIS"
2521 >not</I
2522 ></SPAN
2523 > use domain patterns
2524     like <SPAN
2525 CLASS="QUOTE"
2526 >"*.org"</SPAN
2527 > or partial domain names. If a DNS name resolves to multiple
2528     IP addresses, only the first one is used.
2529    </P
2530 ><P
2531 >     Some systems allow IPv4 clients to connect to IPv6 server sockets.
2532      Then the client's IPv4 address will be translated by the system into
2533      IPv6 address space with special prefix ::ffff:0:0/96 (so called IPv4
2534      mapped IPv6 address). <SPAN
2535 CLASS="APPLICATION"
2536 >Privoxy</SPAN
2537 > can handle it
2538      and maps such ACL addresses automatically.
2539    </P
2540 ><P
2541 >    Denying access to particular sites by ACL may have undesired side effects
2542     if the site in question is hosted on a machine which also hosts other sites
2543     (most sites are).
2544    </P
2545 ></DD
2546 ><DT
2547 >Examples:</DT
2548 ><DD
2549 ><P
2550 >    Explicitly define the default behavior if no ACL and
2551     <TT
2552 CLASS="LITERAL"
2553 >listen-address</TT
2554 > are set: <SPAN
2555 CLASS="QUOTE"
2556 >"localhost"</SPAN
2557 >
2558     is OK. The absence of a <TT
2559 CLASS="REPLACEABLE"
2560 ><I
2561 >dst_addr</I
2562 ></TT
2563 > implies that
2564     <SPAN
2565 CLASS="emphasis"
2566 ><I
2567 CLASS="EMPHASIS"
2568 >all</I
2569 ></SPAN
2570 > destination addresses are OK:
2571    </P
2572 ><P
2573 >    <TABLE
2574 BORDER="0"
2575 BGCOLOR="#E0E0E0"
2576 WIDTH="90%"
2577 ><TR
2578 ><TD
2579 ><PRE
2580 CLASS="SCREEN"
2581 >  permit-access  localhost</PRE
2582 ></TD
2583 ></TR
2584 ></TABLE
2585 >
2586    </P
2587 ><P
2588 >    Allow any host on the same class C subnet as www.privoxy.org access to
2589     nothing but www.example.com (or other domains hosted on the same system):
2590    </P
2591 ><P
2592 >    <TABLE
2593 BORDER="0"
2594 BGCOLOR="#E0E0E0"
2595 WIDTH="90%"
2596 ><TR
2597 ><TD
2598 ><PRE
2599 CLASS="SCREEN"
2600 >  permit-access  www.privoxy.org/24 www.example.com/32</PRE
2601 ></TD
2602 ></TR
2603 ></TABLE
2604 >
2605    </P
2606 ><P
2607 >    Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
2608     with the exception that 192.168.45.73 may not access the IP address behind
2609     www.dirty-stuff.example.com:
2610    </P
2611 ><P
2612 >    <TABLE
2613 BORDER="0"
2614 BGCOLOR="#E0E0E0"
2615 WIDTH="90%"
2616 ><TR
2617 ><TD
2618 ><PRE
2619 CLASS="SCREEN"
2620 >  permit-access  192.168.45.64/26
2621   deny-access    192.168.45.73    www.dirty-stuff.example.com</PRE
2622 ></TD
2623 ></TR
2624 ></TABLE
2625 >
2626    </P
2627 ><P
2628 >     Allow access from the IPv4 network 192.0.2.0/24 even if listening on
2629      an IPv6 wild card address (not supported on all platforms):
2630    </P
2631 ><P
2632 >    <TABLE
2633 BORDER="0"
2634 BGCOLOR="#E0E0E0"
2635 WIDTH="90%"
2636 ><TR
2637 ><TD
2638 ><PRE
2639 CLASS="PROGRAMLISTING"
2640 >  permit-access  192.0.2.0/24</PRE
2641 ></TD
2642 ></TR
2643 ></TABLE
2644 >
2645    </P
2646 ><P
2647 >     This is equivalent to the following line even if listening on an
2648      IPv4 address (not supported on all platforms):
2649    </P
2650 ><P
2651 >    <TABLE
2652 BORDER="0"
2653 BGCOLOR="#E0E0E0"
2654 WIDTH="90%"
2655 ><TR
2656 ><TD
2657 ><PRE
2658 CLASS="PROGRAMLISTING"
2659 >  permit-access  [::ffff:192.0.2.0]/120</PRE
2660 ></TD
2661 ></TR
2662 ></TABLE
2663 >
2664    </P
2665 ></DD
2666 ></DL
2667 ></DIV
2668 ></DIV
2669 ><DIV
2670 CLASS="SECT3"
2671 ><H4
2672 CLASS="SECT3"
2673 ><A
2674 NAME="BUFFER-LIMIT"
2675 >7.4.8. buffer-limit</A
2676 ></H4
2677 ><P
2678 ></P
2679 ><DIV
2680 CLASS="VARIABLELIST"
2681 ><DL
2682 ><DT
2683 >Specifies:</DT
2684 ><DD
2685 ><P
2686 >    Maximum size of the buffer for content filtering.
2687    </P
2688 ></DD
2689 ><DT
2690 >Type of value:</DT
2691 ><DD
2692 ><P
2693 >Size in Kbytes</P
2694 ></DD
2695 ><DT
2696 >Default value:</DT
2697 ><DD
2698 ><P
2699 >4096</P
2700 ></DD
2701 ><DT
2702 >Effect if unset:</DT
2703 ><DD
2704 ><P
2705 >    Use a 4MB (4096 KB) limit.
2706    </P
2707 ></DD
2708 ><DT
2709 >Notes:</DT
2710 ><DD
2711 ><P
2712 >    For content filtering, i.e. the <TT
2713 CLASS="LITERAL"
2714 >+filter</TT
2715 > and
2716     <TT
2717 CLASS="LITERAL"
2718 >+deanimate-gif</TT
2719 > actions, it is necessary that 
2720     <SPAN
2721 CLASS="APPLICATION"
2722 >Privoxy</SPAN
2723 > buffers the entire document body.
2724     This can be potentially dangerous, since a server could just keep sending
2725     data indefinitely and wait for your RAM to exhaust -- with nasty consequences.
2726     Hence this option.
2727    </P
2728 ><P
2729 >    When a document buffer size reaches the <TT
2730 CLASS="LITERAL"
2731 >buffer-limit</TT
2732 >, it is
2733     flushed to the client unfiltered and no further attempt to
2734     filter the rest of the document is made. Remember that there may be multiple threads
2735     running, which might require up to <TT
2736 CLASS="LITERAL"
2737 >buffer-limit</TT
2738 > Kbytes
2739     <SPAN
2740 CLASS="emphasis"
2741 ><I
2742 CLASS="EMPHASIS"
2743 >each</I
2744 ></SPAN
2745 >, unless you have enabled <SPAN
2746 CLASS="QUOTE"
2747 >"single-threaded"</SPAN
2748 >
2749     above.
2750    </P
2751 ></DD
2752 ></DL
2753 ></DIV
2754 ></DIV
2755 ></DIV
2756 ><DIV
2757 CLASS="SECT2"
2758 ><H2
2759 CLASS="SECT2"
2760 ><A
2761 NAME="FORWARDING"
2762 >7.5. Forwarding</A
2763 ></H2
2764 ><P
2765 > This feature allows routing of HTTP requests through a chain of
2766  multiple proxies.</P
2767 ><P
2768 > Forwarding can be used to chain Privoxy with a caching proxy to speed
2769  up browsing. Using a parent proxy may also be necessary if the machine
2770  that <SPAN
2771 CLASS="APPLICATION"
2772 >Privoxy</SPAN
2773 > runs on has no direct Internet access.</P
2774 ><P
2775 > Note that parent proxies can severely decrease your privacy level.
2776  For example a parent proxy could add your IP address to the request
2777  headers and if it's a caching proxy it may add the <SPAN
2778 CLASS="QUOTE"
2779 >"Etag"</SPAN
2780 >
2781  header to revalidation requests again, even though you configured Privoxy
2782  to remove it. It may also ignore Privoxy's header time randomization and use the
2783  original values which could be used by the server as cookie replacement
2784  to track your steps between visits.</P
2785 ><P
2786 > Also specified here are SOCKS proxies. <SPAN
2787 CLASS="APPLICATION"
2788 >Privoxy</SPAN
2789 >
2790  supports the SOCKS 4 and SOCKS 4A protocols.</P
2791 ><DIV
2792 CLASS="SECT3"
2793 ><H4
2794 CLASS="SECT3"
2795 ><A
2796 NAME="FORWARD"
2797 >7.5.1. forward</A
2798 ></H4
2799 ><P
2800 ></P
2801 ><DIV
2802 CLASS="VARIABLELIST"
2803 ><DL
2804 ><DT
2805 >Specifies:</DT
2806 ><DD
2807 ><P
2808 >    To which parent HTTP proxy specific requests should be routed.
2809    </P
2810 ></DD
2811 ><DT
2812 >Type of value:</DT
2813 ><DD
2814 ><P
2815 >    <TT
2816 CLASS="REPLACEABLE"
2817 ><I
2818 >target_pattern</I
2819 ></TT
2820 >
2821     <TT
2822 CLASS="REPLACEABLE"
2823 ><I
2824 >http_parent</I
2825 ></TT
2826 >[:<TT
2827 CLASS="REPLACEABLE"
2828 ><I
2829 >port</I
2830 ></TT
2831 >]
2832    </P
2833 ><P
2834 >    where <TT
2835 CLASS="REPLACEABLE"
2836 ><I
2837 >target_pattern</I
2838 ></TT
2839 > is a <A
2840 HREF="actions-file.html#AF-PATTERNS"
2841 >URL pattern</A
2842
2843     that specifies to which requests (i.e. URLs) this forward rule shall apply. Use <TT
2844 CLASS="LITERAL"
2845 >/</TT
2846 > to
2847     denote <SPAN
2848 CLASS="QUOTE"
2849 >"all URLs"</SPAN
2850 >.
2851     <TT
2852 CLASS="REPLACEABLE"
2853 ><I
2854 >http_parent</I
2855 ></TT
2856 >[:<TT
2857 CLASS="REPLACEABLE"
2858 ><I
2859 >port</I
2860 ></TT
2861 >]
2862     is the DNS name or IP address of the parent HTTP proxy through which the requests should be forwarded,
2863     optionally followed by its listening port (default: 8000).
2864     Use a single dot (<TT
2865 CLASS="LITERAL"
2866 >.</TT
2867 >) to denote <SPAN
2868 CLASS="QUOTE"
2869 >"no forwarding"</SPAN
2870 >.
2871    </P
2872 ></DD
2873 ><DT
2874 >Default value:</DT
2875 ><DD
2876 ><P
2877 ><SPAN
2878 CLASS="emphasis"
2879 ><I
2880 CLASS="EMPHASIS"
2881 >Unset</I
2882 ></SPAN
2883 ></P
2884 ></DD
2885 ><DT
2886 >Effect if unset:</DT
2887 ><DD
2888 ><P
2889 >    Don't use parent HTTP proxies.
2890    </P
2891 ></DD
2892 ><DT
2893 >Notes:</DT
2894 ><DD
2895 ><P
2896 >    If <TT
2897 CLASS="REPLACEABLE"
2898 ><I
2899 >http_parent</I
2900 ></TT
2901 > is <SPAN
2902 CLASS="QUOTE"
2903 >"."</SPAN
2904 >, then requests are not
2905     forwarded to another HTTP proxy but are made directly to the web servers.
2906    </P
2907 ><P
2908 >    <TT
2909 CLASS="REPLACEABLE"
2910 ><I
2911 >http_parent</I
2912 ></TT
2913 > can be a
2914      numerical IPv6 address (if
2915     <A
2916 HREF="http://tools.ietf.org/html/rfc3493"
2917 TARGET="_top"
2918 >RFC 3493</A
2919 > is
2920     implemented). To prevent clashes with the port delimiter, the whole IP
2921     address has to be put into brackets. On the other hand a <TT
2922 CLASS="REPLACEABLE"
2923 ><I
2924 >target_pattern</I
2925 ></TT
2926 > containing an IPv6 address
2927     has to be put into angle brackets (normal brackets are reserved for
2928     regular expressions already).
2929    </P
2930 ><P
2931 >    Multiple lines are OK, they are checked in sequence, and the last match wins.
2932    </P
2933 ></DD
2934 ><DT
2935 >Examples:</DT
2936 ><DD
2937 ><P
2938 >    Everything goes to an example parent proxy, except SSL on port 443 (which it doesn't handle):
2939    </P
2940 ><P
2941 >    <TABLE
2942 BORDER="0"
2943 BGCOLOR="#E0E0E0"
2944 WIDTH="90%"
2945 ><TR
2946 ><TD
2947 ><PRE
2948 CLASS="SCREEN"
2949 >  forward   /      parent-proxy.example.org:8080
2950   forward   :443   .</PRE
2951 ></TD
2952 ></TR
2953 ></TABLE
2954 >
2955    </P
2956 ><P
2957 >    Everything goes to our example ISP's caching proxy, except for requests
2958     to that ISP's sites:
2959    </P
2960 ><P
2961 >    <TABLE
2962 BORDER="0"
2963 BGCOLOR="#E0E0E0"
2964 WIDTH="90%"
2965 ><TR
2966 ><TD
2967 ><PRE
2968 CLASS="SCREEN"
2969 >  forward   /                  caching-proxy.isp.example.net:8000
2970   forward   .isp.example.net   .</PRE
2971 ></TD
2972 ></TR
2973 ></TABLE
2974 >
2975    </P
2976 ><P
2977 >    Parent proxy specified by an IPv6 address:
2978    </P
2979 ><P
2980 >    <TABLE
2981 BORDER="0"
2982 BGCOLOR="#E0E0E0"
2983 WIDTH="90%"
2984 ><TR
2985 ><TD
2986 ><PRE
2987 CLASS="PROGRAMLISTING"
2988 >  foward   /                   [2001:DB8::1]:8000</PRE
2989 ></TD
2990 ></TR
2991 ></TABLE
2992 >
2993    </P
2994 ><P
2995 >    Suppose your parent proxy doesn't support IPv6:
2996    </P
2997 ><P
2998 >    <TABLE
2999 BORDER="0"
3000 BGCOLOR="#E0E0E0"
3001 WIDTH="90%"
3002 ><TR
3003 ><TD
3004 ><PRE
3005 CLASS="PROGRAMLISTING"
3006 >  forward  /                        parent-proxy.example.org:8000
3007   forward  ipv6-server.example.org  .
3008   forward  &#60;[2-3][0-9a-f][0-9a-f][0-9a-f]:*&#62;   .</PRE
3009 ></TD
3010 ></TR
3011 ></TABLE
3012 >
3013    </P
3014 ></DD
3015 ></DL
3016 ></DIV
3017 ></DIV
3018 ><DIV
3019 CLASS="SECT3"
3020 ><H4
3021 CLASS="SECT3"
3022 ><A
3023 NAME="SOCKS"
3024 >7.5.2. forward-socks4, forward-socks4a and forward-socks5</A
3025 ></H4
3026 ><A
3027 NAME="FORWARD-SOCKS4"
3028 ></A
3029 ><A
3030 NAME="FORWARD-SOCKS4A"
3031 ></A
3032 ><P
3033 ></P
3034 ><DIV
3035 CLASS="VARIABLELIST"
3036 ><DL
3037 ><DT
3038 >Specifies:</DT
3039 ><DD
3040 ><P
3041 >    Through which SOCKS proxy (and optionally to which parent HTTP proxy) specific requests should be routed.
3042    </P
3043 ></DD
3044 ><DT
3045 >Type of value:</DT
3046 ><DD
3047 ><P
3048 >    <TT
3049 CLASS="REPLACEABLE"
3050 ><I
3051 >target_pattern</I
3052 ></TT
3053 >
3054     <TT
3055 CLASS="REPLACEABLE"
3056 ><I
3057 >socks_proxy</I
3058 ></TT
3059 >[:<TT
3060 CLASS="REPLACEABLE"
3061 ><I
3062 >port</I
3063 ></TT
3064 >]
3065     <TT
3066 CLASS="REPLACEABLE"
3067 ><I
3068 >http_parent</I
3069 ></TT
3070 >[:<TT
3071 CLASS="REPLACEABLE"
3072 ><I
3073 >port</I
3074 ></TT
3075 >]
3076    </P
3077 ><P
3078 >    where <TT
3079 CLASS="REPLACEABLE"
3080 ><I
3081 >target_pattern</I
3082 ></TT
3083 > is a
3084     <A
3085 HREF="actions-file.html#AF-PATTERNS"
3086 >URL pattern</A
3087 > that specifies to which
3088     requests (i.e. URLs) this forward rule shall apply. Use <TT
3089 CLASS="LITERAL"
3090 >/</TT
3091 > to
3092     denote <SPAN
3093 CLASS="QUOTE"
3094 >"all URLs"</SPAN
3095 >. <TT
3096 CLASS="REPLACEABLE"
3097 ><I
3098 >http_parent</I
3099 ></TT
3100 >
3101     and <TT
3102 CLASS="REPLACEABLE"
3103 ><I
3104 >socks_proxy</I
3105 ></TT
3106 >
3107     are IP addresses in dotted decimal notation or valid DNS names
3108     (<TT
3109 CLASS="REPLACEABLE"
3110 ><I
3111 >http_parent</I
3112 ></TT
3113 >
3114     may be <SPAN
3115 CLASS="QUOTE"
3116 >"."</SPAN
3117 > to denote <SPAN
3118 CLASS="QUOTE"
3119 >"no HTTP forwarding"</SPAN
3120 >), and the optional 
3121     <TT
3122 CLASS="REPLACEABLE"
3123 ><I
3124 >port</I
3125 ></TT
3126 > parameters are TCP ports,
3127     i.e. integer values from 1 to 65535
3128    </P
3129 ></DD
3130 ><DT
3131 >Default value:</DT
3132 ><DD
3133 ><P
3134 ><SPAN
3135 CLASS="emphasis"
3136 ><I
3137 CLASS="EMPHASIS"
3138 >Unset</I
3139 ></SPAN
3140 ></P
3141 ></DD
3142 ><DT
3143 >Effect if unset:</DT
3144 ><DD
3145 ><P
3146 >    Don't use SOCKS proxies.
3147    </P
3148 ></DD
3149 ><DT
3150 >Notes:</DT
3151 ><DD
3152 ><P
3153 >    Multiple lines are OK, they are checked in sequence, and the last match wins.
3154    </P
3155 ><P
3156 >    The difference between <TT
3157 CLASS="LITERAL"
3158 >forward-socks4</TT
3159 > and <TT
3160 CLASS="LITERAL"
3161 >forward-socks4a</TT
3162 >
3163     is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS
3164     server, while in SOCKS 4 it happens locally.
3165    </P
3166 ><P
3167 >    With <TT
3168 CLASS="LITERAL"
3169 >forward-socks5</TT
3170 > the DNS resolution will happen on the remote server as well.
3171    </P
3172 ><P
3173 >    <TT
3174 CLASS="REPLACEABLE"
3175 ><I
3176 >socks_proxy</I
3177 ></TT
3178 > and
3179     <TT
3180 CLASS="REPLACEABLE"
3181 ><I
3182 >http_parent</I
3183 ></TT
3184 > can be a
3185      numerical IPv6 address (if
3186     <A
3187 HREF="http://tools.ietf.org/html/rfc3493"
3188 TARGET="_top"
3189 >RFC 3493</A
3190 > is
3191     implemented). To prevent clashes with the port delimiter, the whole IP
3192     address has to be put into brackets. On the other hand a <TT
3193 CLASS="REPLACEABLE"
3194 ><I
3195 >target_pattern</I
3196 ></TT
3197 > containing an IPv6 address
3198     has to be put into angle brackets (normal brackets are reserved for
3199     regular expressions already).
3200    </P
3201 ><P
3202 >    If <TT
3203 CLASS="REPLACEABLE"
3204 ><I
3205 >http_parent</I
3206 ></TT
3207 > is <SPAN
3208 CLASS="QUOTE"
3209 >"."</SPAN
3210 >, then requests are not
3211     forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
3212     a SOCKS proxy.
3213    </P
3214 ></DD
3215 ><DT
3216 >Examples:</DT
3217 ><DD
3218 ><P
3219 >     From the company example.com, direct connections are made to all
3220      <SPAN
3221 CLASS="QUOTE"
3222 >"internal"</SPAN
3223 > domains, but everything outbound goes through
3224      their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
3225      the Internet.
3226    </P
3227 ><P
3228 >    <TABLE
3229 BORDER="0"
3230 BGCOLOR="#E0E0E0"
3231 WIDTH="90%"
3232 ><TR
3233 ><TD
3234 ><PRE
3235 CLASS="SCREEN"
3236 >  forward-socks4a   /              socks-gw.example.com:1080  www-cache.isp.example.net:8080
3237   forward           .example.com   .</PRE
3238 ></TD
3239 ></TR
3240 ></TABLE
3241 >
3242    </P
3243 ><P
3244 >    A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
3245    </P
3246 ><P
3247 >    <TABLE
3248 BORDER="0"
3249 BGCOLOR="#E0E0E0"
3250 WIDTH="90%"
3251 ><TR
3252 ><TD
3253 ><PRE
3254 CLASS="SCREEN"
3255 >  forward-socks4   /               socks-gw.example.com:1080  .</PRE
3256 ></TD
3257 ></TR
3258 ></TABLE
3259 >
3260    </P
3261 ><P
3262 >    To chain Privoxy and Tor, both running on the same system, you would use 
3263     something like:
3264    </P
3265 ><P
3266 >    <TABLE
3267 BORDER="0"
3268 BGCOLOR="#E0E0E0"
3269 WIDTH="90%"
3270 ><TR
3271 ><TD
3272 ><PRE
3273 CLASS="SCREEN"
3274 >  forward-socks5   /               127.0.0.1:9050 .</PRE
3275 ></TD
3276 ></TR
3277 ></TABLE
3278 >
3279    </P
3280 ><P
3281 >    The public <SPAN
3282 CLASS="APPLICATION"
3283 >Tor</SPAN
3284 > network can't be used to
3285     reach your local network, if you need to access local servers you
3286     therefore might want to make some exceptions:
3287    </P
3288 ><P
3289 >    <TABLE
3290 BORDER="0"
3291 BGCOLOR="#E0E0E0"
3292 WIDTH="90%"
3293 ><TR
3294 ><TD
3295 ><PRE
3296 CLASS="SCREEN"
3297 >  forward         192.168.*.*/     .
3298   forward            10.*.*.*/     .
3299   forward           127.*.*.*/     .</PRE
3300 ></TD
3301 ></TR
3302 ></TABLE
3303 >
3304    </P
3305 ><P
3306 >    Unencrypted connections to systems in these address ranges will
3307     be as (un)secure as the local network is, but the alternative is that you
3308     can't reach the local network through <SPAN
3309 CLASS="APPLICATION"
3310 >Privoxy</SPAN
3311 >
3312     at all. Of course this may actually be desired and there is no reason
3313     to make these exceptions if you aren't sure you need them.
3314    </P
3315 ><P
3316 >    If you also want to be able to reach servers in your local network by
3317     using their names, you will need additional exceptions that look like
3318     this:
3319    </P
3320 ><P
3321 >    <TABLE
3322 BORDER="0"
3323 BGCOLOR="#E0E0E0"
3324 WIDTH="90%"
3325 ><TR
3326 ><TD
3327 ><PRE
3328 CLASS="SCREEN"
3329 > forward           localhost/     .</PRE
3330 ></TD
3331 ></TR
3332 ></TABLE
3333 >
3334    </P
3335 ></DD
3336 ></DL
3337 ></DIV
3338 ></DIV
3339 ><DIV
3340 CLASS="SECT3"
3341 ><H4
3342 CLASS="SECT3"
3343 ><A
3344 NAME="ADVANCED-FORWARDING-EXAMPLES"
3345 >7.5.3. Advanced Forwarding Examples</A
3346 ></H4
3347 ><P
3348 > If you have links to multiple ISPs that provide various special content 
3349  only to their subscribers, you can configure multiple <SPAN
3350 CLASS="APPLICATION"
3351 >Privoxies</SPAN
3352 >
3353  which have connections to the respective ISPs to act as forwarders to each other, so that
3354  <SPAN
3355 CLASS="emphasis"
3356 ><I
3357 CLASS="EMPHASIS"
3358 >your</I
3359 ></SPAN
3360 > users can see the internal content of all ISPs.</P
3361 ><P
3362 > Assume that host-a has a PPP connection to isp-a.example.net. And host-b has a PPP connection to
3363  isp-b.example.org. Both run <SPAN
3364 CLASS="APPLICATION"
3365 >Privoxy</SPAN
3366 >. Their forwarding
3367  configuration can look like this:</P
3368 ><P
3369 > host-a:</P
3370 ><P
3371 > <TABLE
3372 BORDER="0"
3373 BGCOLOR="#E0E0E0"
3374 WIDTH="100%"
3375 ><TR
3376 ><TD
3377 ><PRE
3378 CLASS="SCREEN"
3379 >  forward    /           .
3380   forward    .isp-b.example.net  host-b:8118</PRE
3381 ></TD
3382 ></TR
3383 ></TABLE
3384 ></P
3385 ><P
3386 > host-b:</P
3387 ><P
3388 > <TABLE
3389 BORDER="0"
3390 BGCOLOR="#E0E0E0"
3391 WIDTH="100%"
3392 ><TR
3393 ><TD
3394 ><PRE
3395 CLASS="SCREEN"
3396 >  forward    /           .
3397   forward    .isp-a.example.org  host-a:8118</PRE
3398 ></TD
3399 ></TR
3400 ></TABLE
3401 ></P
3402 ><P
3403 > Now, your users can set their browser's proxy to use either
3404  host-a or host-b and be able to browse the internal content
3405  of both isp-a and isp-b.</P
3406 ><P
3407 > If you intend to chain <SPAN
3408 CLASS="APPLICATION"
3409 >Privoxy</SPAN
3410 > and 
3411  <SPAN
3412 CLASS="APPLICATION"
3413 >squid</SPAN
3414 > locally, then chaining as 
3415  <TT
3416 CLASS="LITERAL"
3417 >browser -&#62; squid -&#62; privoxy</TT
3418 > is the recommended way. </P
3419 ><P
3420 > Assuming that <SPAN
3421 CLASS="APPLICATION"
3422 >Privoxy</SPAN
3423 > and <SPAN
3424 CLASS="APPLICATION"
3425 >squid</SPAN
3426 >
3427  run on the same box, your <SPAN
3428 CLASS="APPLICATION"
3429 >squid</SPAN
3430 > configuration could then look like this:</P
3431 ><P
3432 > <TABLE
3433 BORDER="0"
3434 BGCOLOR="#E0E0E0"
3435 WIDTH="100%"
3436 ><TR
3437 ><TD
3438 ><PRE
3439 CLASS="SCREEN"
3440 >  # Define Privoxy as parent proxy (without ICP) 
3441   cache_peer 127.0.0.1 parent 8118 7 no-query 
3442
3443   # Define ACL for protocol FTP 
3444   acl ftp proto FTP 
3445
3446   # Do not forward FTP requests to Privoxy
3447   always_direct allow ftp 
3448
3449   # Forward all the rest to Privoxy
3450   never_direct allow all</PRE
3451 ></TD
3452 ></TR
3453 ></TABLE
3454 ></P
3455 ><P
3456 > You would then need to change your browser's proxy settings to <SPAN
3457 CLASS="APPLICATION"
3458 >squid</SPAN
3459 >'s address and port.
3460  Squid normally uses port 3128. If unsure consult <TT
3461 CLASS="LITERAL"
3462 >http_port</TT
3463 > in <TT
3464 CLASS="FILENAME"
3465 >squid.conf</TT
3466 >.</P
3467 ><P
3468 > You could just as well decide to only forward requests you suspect
3469  of leading to Windows executables through a virus-scanning parent proxy,
3470  say, on <TT
3471 CLASS="LITERAL"
3472 >antivir.example.com</TT
3473 >, port 8010:</P
3474 ><P
3475 > <TABLE
3476 BORDER="0"
3477 BGCOLOR="#E0E0E0"
3478 WIDTH="100%"
3479 ><TR
3480 ><TD
3481 ><PRE
3482 CLASS="SCREEN"
3483 >  forward   /                          .
3484   forward   /.*\.(exe|com|dll|zip)$    antivir.example.com:8010</PRE
3485 ></TD
3486 ></TR
3487 ></TABLE
3488 > </P
3489 ></DIV
3490 ><DIV
3491 CLASS="SECT3"
3492 ><H4
3493 CLASS="SECT3"
3494 ><A
3495 NAME="FORWARDED-CONNECT-RETRIES"
3496 >7.5.4. forwarded-connect-retries</A
3497 ></H4
3498 ><P
3499 ></P
3500 ><DIV
3501 CLASS="VARIABLELIST"
3502 ><DL
3503 ><DT
3504 >Specifies:</DT
3505 ><DD
3506 ><P
3507 >    How often Privoxy retries if a forwarded connection request fails. 
3508    </P
3509 ></DD
3510 ><DT
3511 >Type of value:</DT
3512 ><DD
3513 ><P
3514 >    <TT
3515 CLASS="REPLACEABLE"
3516 ><I
3517 >Number of retries.</I
3518 ></TT
3519 >
3520    </P
3521 ></DD
3522 ><DT
3523 >Default value:</DT
3524 ><DD
3525 ><P
3526 ><SPAN
3527 CLASS="emphasis"
3528 ><I
3529 CLASS="EMPHASIS"
3530 >0</I
3531 ></SPAN
3532 ></P
3533 ></DD
3534 ><DT
3535 >Effect if unset:</DT
3536 ><DD
3537 ><P
3538 >    Connections forwarded through other proxies are treated like direct connections and no retry attempts are made.
3539    </P
3540 ></DD
3541 ><DT
3542 >Notes:</DT
3543 ><DD
3544 ><P
3545 >    <TT
3546 CLASS="REPLACEABLE"
3547 ><I
3548 >forwarded-connect-retries</I
3549 ></TT
3550 > is mainly interesting
3551     for socks4a connections, where <SPAN
3552 CLASS="APPLICATION"
3553 >Privoxy</SPAN
3554 > can't detect why the connections failed.
3555     The connection might have failed because of a DNS timeout in which case a retry makes sense,
3556     but it might also have failed because the server doesn't exist or isn't reachable. In this
3557     case the retry will just delay the appearance of Privoxy's error message.
3558    </P
3559 ><P
3560 >    Note that in the context of this option, <SPAN
3561 CLASS="QUOTE"
3562 >"forwarded connections"</SPAN
3563 > includes all connections
3564     that Privoxy forwards through other proxies. This option is not limited to the HTTP CONNECT method.
3565    </P
3566 ><P
3567 >    Only use this option, if you are getting lots of forwarding-related error messages
3568     that go away when you try again manually. Start with a small value and check Privoxy's
3569     logfile from time to time, to see how many retries are usually needed.
3570    </P
3571 ><P
3572 >    Due to a bug, this option currently also causes Privoxy to
3573     retry in case of certain problems with direct connections.
3574    </P
3575 ></DD
3576 ><DT
3577 >Examples:</DT
3578 ><DD
3579 ><P
3580 >    forwarded-connect-retries 1
3581    </P
3582 ></DD
3583 ></DL
3584 ></DIV
3585 ></DIV
3586 ></DIV
3587 ><DIV
3588 CLASS="SECT2"
3589 ><H2
3590 CLASS="SECT2"
3591 ><A
3592 NAME="MISC"
3593 >7.6. Miscellaneous</A
3594 ></H2
3595 ><DIV
3596 CLASS="SECT3"
3597 ><H4
3598 CLASS="SECT3"
3599 ><A
3600 NAME="ACCEPT-INTERCEPTED-REQUESTS"
3601 >7.6.1. accept-intercepted-requests</A
3602 ></H4
3603 ><P
3604 ></P
3605 ><DIV
3606 CLASS="VARIABLELIST"
3607 ><DL
3608 ><DT
3609 >Specifies:</DT
3610 ><DD
3611 ><P
3612 >    Whether intercepted requests should be treated as valid.
3613    </P
3614 ></DD
3615 ><DT
3616 >Type of value:</DT
3617 ><DD
3618 ><P
3619 >    <TT
3620 CLASS="REPLACEABLE"
3621 ><I
3622 >0 or 1</I
3623 ></TT
3624 >
3625    </P
3626 ></DD
3627 ><DT
3628 >Default value:</DT
3629 ><DD
3630 ><P
3631 ><SPAN
3632 CLASS="emphasis"
3633 ><I
3634 CLASS="EMPHASIS"
3635 >0</I
3636 ></SPAN
3637 ></P
3638 ></DD
3639 ><DT
3640 >Effect if unset:</DT
3641 ><DD
3642 ><P
3643 >    Only proxy requests are accepted, intercepted requests are treated as invalid.
3644    </P
3645 ></DD
3646 ><DT
3647 >Notes:</DT
3648 ><DD
3649 ><P
3650 >    If you don't trust your clients and want to force them
3651     to use <SPAN
3652 CLASS="APPLICATION"
3653 >Privoxy</SPAN
3654 >, enable this
3655     option and configure your packet filter to redirect outgoing
3656     HTTP connections into <SPAN
3657 CLASS="APPLICATION"
3658 >Privoxy</SPAN
3659 >. 
3660    </P
3661 ><P
3662 >    Make sure that <SPAN
3663 CLASS="APPLICATION"
3664 >Privoxy's</SPAN
3665 > own requests
3666     aren't redirected as well. Additionally take care that
3667     <SPAN
3668 CLASS="APPLICATION"
3669 >Privoxy</SPAN
3670 > can't intentionally connect
3671     to itself, otherwise you could run into redirection loops if
3672     <SPAN
3673 CLASS="APPLICATION"
3674 >Privoxy's</SPAN
3675 > listening port is reachable
3676     by the outside or an attacker has access to the pages you visit.
3677    </P
3678 ></DD
3679 ><DT
3680 >Examples:</DT
3681 ><DD
3682 ><P
3683 >    accept-intercepted-requests 1
3684    </P
3685 ></DD
3686 ></DL
3687 ></DIV
3688 ></DIV
3689 ><DIV
3690 CLASS="SECT3"
3691 ><H4
3692 CLASS="SECT3"
3693 ><A
3694 NAME="ALLOW-CGI-REQUEST-CRUNCHING"
3695 >7.6.2. allow-cgi-request-crunching</A
3696 ></H4
3697 ><P
3698 ></P
3699 ><DIV
3700 CLASS="VARIABLELIST"
3701 ><DL
3702 ><DT
3703 >Specifies:</DT
3704 ><DD
3705 ><P
3706 >    Whether requests to <SPAN
3707 CLASS="APPLICATION"
3708 >Privoxy's</SPAN
3709 > CGI pages can be blocked or redirected.
3710    </P
3711 ></DD
3712 ><DT
3713 >Type of value:</DT
3714 ><DD
3715 ><P
3716 >    <TT
3717 CLASS="REPLACEABLE"
3718 ><I
3719 >0 or 1</I
3720 ></TT
3721 >
3722    </P
3723 ></DD
3724 ><DT
3725 >Default value:</DT
3726 ><DD
3727 ><P
3728 ><SPAN
3729 CLASS="emphasis"
3730 ><I
3731 CLASS="EMPHASIS"
3732 >0</I
3733 ></SPAN
3734 ></P
3735 ></DD
3736 ><DT
3737 >Effect if unset:</DT
3738 ><DD
3739 ><P
3740 >    <SPAN
3741 CLASS="APPLICATION"
3742 >Privoxy</SPAN
3743 > ignores block and redirect actions for its CGI pages.
3744    </P
3745 ></DD
3746 ><DT
3747 >Notes:</DT
3748 ><DD
3749 ><P
3750 >    By default <SPAN
3751 CLASS="APPLICATION"
3752 >Privoxy</SPAN
3753 > ignores block or redirect actions
3754     for its CGI pages. Intercepting these requests can be useful in multi-user
3755     setups to implement fine-grained access control, but it can also render the complete
3756     web interface useless and make debugging problems painful if done without care.
3757    </P
3758 ><P
3759 >    Don't enable this option unless you're sure that you really need it.
3760    </P
3761 ></DD
3762 ><DT
3763 >Examples:</DT
3764 ><DD
3765 ><P
3766 >    allow-cgi-request-crunching 1
3767    </P
3768 ></DD
3769 ></DL
3770 ></DIV
3771 ></DIV
3772 ><DIV
3773 CLASS="SECT3"
3774 ><H4
3775 CLASS="SECT3"
3776 ><A
3777 NAME="SPLIT-LARGE-FORMS"
3778 >7.6.3. split-large-forms</A
3779 ></H4
3780 ><P
3781 ></P
3782 ><DIV
3783 CLASS="VARIABLELIST"
3784 ><DL
3785 ><DT
3786 >Specifies:</DT
3787 ><DD
3788 ><P
3789 >    Whether the CGI interface should stay compatible with broken HTTP clients.
3790    </P
3791 ></DD
3792 ><DT
3793 >Type of value:</DT
3794 ><DD
3795 ><P
3796 >    <TT
3797 CLASS="REPLACEABLE"
3798 ><I
3799 >0 or 1</I
3800 ></TT
3801 >
3802    </P
3803 ></DD
3804 ><DT
3805 >Default value:</DT
3806 ><DD
3807 ><P
3808 ><SPAN
3809 CLASS="emphasis"
3810 ><I
3811 CLASS="EMPHASIS"
3812 >0</I
3813 ></SPAN
3814 ></P
3815 ></DD
3816 ><DT
3817 >Effect if unset:</DT
3818 ><DD
3819 ><P
3820 >    The CGI form generate long GET URLs.
3821    </P
3822 ></DD
3823 ><DT
3824 >Notes:</DT
3825 ><DD
3826 ><P
3827 >    <SPAN
3828 CLASS="APPLICATION"
3829 >Privoxy's</SPAN
3830 > CGI forms can lead to
3831     rather long URLs. This isn't a problem as far as the HTTP
3832     standard is concerned, but it can confuse clients with arbitrary
3833     URL length limitations.
3834    </P
3835 ><P
3836 >    Enabling split-large-forms causes <SPAN
3837 CLASS="APPLICATION"
3838 >Privoxy</SPAN
3839 >
3840     to divide big forms into smaller ones to keep the URL length down.
3841     It makes editing a lot less convenient and you can no longer
3842     submit all changes at once, but at least it works around this
3843     browser bug.
3844    </P
3845 ><P
3846 >    If you don't notice any editing problems, there is no reason
3847     to enable this option, but if one of the submit buttons appears
3848     to be broken, you should give it a try.
3849    </P
3850 ></DD
3851 ><DT
3852 >Examples:</DT
3853 ><DD
3854 ><P
3855 >    split-large-forms 1
3856    </P
3857 ></DD
3858 ></DL
3859 ></DIV
3860 ></DIV
3861 ><DIV
3862 CLASS="SECT3"
3863 ><H4
3864 CLASS="SECT3"
3865 ><A
3866 NAME="KEEP-ALIVE-TIMEOUT"
3867 >7.6.4. keep-alive-timeout</A
3868 ></H4
3869 ><P
3870 ></P
3871 ><DIV
3872 CLASS="VARIABLELIST"
3873 ><DL
3874 ><DT
3875 >Specifies:</DT
3876 ><DD
3877 ><P
3878 >    Number of seconds after which an open connection will no longer be reused.
3879    </P
3880 ></DD
3881 ><DT
3882 >Type of value:</DT
3883 ><DD
3884 ><P
3885 >    <TT
3886 CLASS="REPLACEABLE"
3887 ><I
3888 >Time in seconds.</I
3889 ></TT
3890 >
3891    </P
3892 ></DD
3893 ><DT
3894 >Default value:</DT
3895 ><DD
3896 ><P
3897 >None</P
3898 ></DD
3899 ><DT
3900 >Effect if unset:</DT
3901 ><DD
3902 ><P
3903 >    Connections are not kept alive.
3904    </P
3905 ></DD
3906 ><DT
3907 >Notes:</DT
3908 ><DD
3909 ><P
3910 >    This option allows clients to keep the connection to <SPAN
3911 CLASS="APPLICATION"
3912 >Privoxy</SPAN
3913 >
3914     alive. If the server supports it, <SPAN
3915 CLASS="APPLICATION"
3916 >Privoxy</SPAN
3917 > will keep
3918     the connection to the server alive as well. Under certain
3919     circumstances this may result in speed-ups.
3920    </P
3921 ><P
3922 >    By default, <SPAN
3923 CLASS="APPLICATION"
3924 >Privoxy</SPAN
3925 > will close the connection to the server if
3926     the client connection gets closed, or if the specified timeout
3927     has been reached without a new request coming in. This behaviour
3928     can be changed with the <A
3929 HREF="#CONNECTION-SHARING"
3930 TARGET="_top"
3931 >connection-sharing</A
3932 > option.
3933    </P
3934 ><P
3935 >    This option has no effect if <SPAN
3936 CLASS="APPLICATION"
3937 >Privoxy</SPAN
3938 >
3939     has been compiled without keep-alive support.
3940    </P
3941 ><P
3942 >    Note that a timeout of five seconds as used in the default
3943     configuration file significantly decreases the number of
3944     connections that will be reused. The value is used because
3945     some browsers limit the number of connections they open to
3946     a single host and apply the same limit to proxies. This can
3947     result in a single website <SPAN
3948 CLASS="QUOTE"
3949 >"grabbing"</SPAN
3950 > all the
3951     connections the browser allows, which means connections to
3952     other websites can't be opened until the connections currently
3953     in use time out.
3954    </P
3955 ><P
3956 >    Several users have reported this as a Privoxy bug, so the
3957     default value has been reduced. Consider increasing it to
3958     300 seconds or even more if you think your browser can handle
3959     it. If your browser appears to be hanging it can't.
3960    </P
3961 ></DD
3962 ><DT
3963 >Examples:</DT
3964 ><DD