doc/webserver/user-manual/config.html

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