doc/webserver/user-manual/configuration.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >Privoxy Configuration</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.4 User Manual"
  11 HREF="index.html"><LINK
  12 REL="PREVIOUS"
  13 TITLE="Starting Privoxy"
  14 HREF="startup.html"><LINK
  15 REL="NEXT"
  16 TITLE="The Main Configuration File"
  17 HREF="config.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.4 User Manual</TH
  43 ></TR
  44 ><TR
  45 ><TD
  46 WIDTH="10%"
  47 ALIGN="left"
  48 VALIGN="bottom"
  49 ><A
  50 HREF="startup.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="config.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="CONFIGURATION"
  79 ></A
  80 >6. <SPAN
  81 CLASS="APPLICATION"
  82 >Privoxy</SPAN
  83 > Configuration</H1
  84 ><P
  85 >  All <SPAN
  86 CLASS="APPLICATION"
  87 >Privoxy</SPAN
  88 > configuration is stored
  89   in text files. These files can be edited with a text editor.
  90   Many important aspects of <SPAN
  91 CLASS="APPLICATION"
  92 >Privoxy</SPAN
  93 > can
  94   also be controlled easily with a web browser.
  95  </P
  96 ><DIV
  97 CLASS="SECT2"
  98 ><H2
  99 CLASS="SECT2"
 100 ><A
 101 NAME="AEN766"
 102 ></A
 103 >6.1. Controlling <SPAN
 104 CLASS="APPLICATION"
 105 >Privoxy</SPAN
 106 > with Your Web Browser</H2
 107 ><P
 108 > <SPAN
 109 CLASS="APPLICATION"
 110 >Privoxy</SPAN
 111 >'s user interface can be reached through the special
 112  URL <A
 113 HREF="http://config.privoxy.org/"
 114 TARGET="_top"
 115 >http://config.privoxy.org/</A
 116 >
 117  (shortcut: <A
 118 HREF="http://p.p/"
 119 TARGET="_top"
 120 >http://p.p/</A
 121 >),
 122  which is a built-in page and works without Internet access.
 123  You will see the following section:&#13;</P
 124 ><TABLE
 125 BORDER="0"
 126 BGCOLOR="#E0E0E0"
 127 WIDTH="100%"
 128 ><TR
 129 ><TD
 130 ><PRE
 131 CLASS="SCREEN"
 132 > <H2
 133 CLASS="BRIDGEHEAD"
 134 ><A
 135 NAME="AEN775"
 136 ></A
 137 >    Privoxy Menu</H2
 138 ><P
 139 ></P
 140 ><TABLE
 141 BORDER="0"
 142 ><TBODY
 143 ><TR
 144 ><TD
 145 >          &#9642;  <A
 146 HREF="http://config.privoxy.org/show-status"
 147 TARGET="_top"
 148 >View &#38; change the current configuration</A
 149 >
 150  </TD
 151 ></TR
 152 ><TR
 153 ><TD
 154 >          &#9642;  <A
 155 HREF="http://config.privoxy.org/show-version"
 156 TARGET="_top"
 157 >View the source code version numbers</A
 158 >
 159  </TD
 160 ></TR
 161 ><TR
 162 ><TD
 163 >          &#9642;  <A
 164 HREF="http://config.privoxy.org/show-request"
 165 TARGET="_top"
 166 >View the request headers.</A
 167 >
 168  </TD
 169 ></TR
 170 ><TR
 171 ><TD
 172 >          &#9642;  <A
 173 HREF="http://config.privoxy.org/show-url-info"
 174 TARGET="_top"
 175 >Look up which actions apply to a URL and why</A
 176 >
 177  </TD
 178 ></TR
 179 ><TR
 180 ><TD
 181 >          &#9642;  <A
 182 HREF="http://config.privoxy.org/toggle"
 183 TARGET="_top"
 184 >Toggle Privoxy on or off</A
 185 >
 186  </TD
 187 ></TR
 188 ><TR
 189 ><TD
 190 >          &#9642;  <A
 191 HREF="http://www.privoxy.org/   3.0.4/user-manual/"
 192 TARGET="_top"
 193 >Documentation</A
 194 >
 195  </TD
 196 ></TR
 197 ></TBODY
 198 ></TABLE
 199 ><P
 200 ></P
 201 ></PRE
 202 ></TD
 203 ></TR
 204 ></TABLE
 205 ><P
 206 > This should be self-explanatory. Note the first item leads to an editor for the
 207  <A
 208 HREF="actions-file.html"
 209 >actions files</A
 210 >, which is where the ad, banner,
 211  cookie, and URL blocking magic is configured as well as other advanced features of
 212  <SPAN
 213 CLASS="APPLICATION"
 214 >Privoxy</SPAN
 215 >. This is an easy way to adjust various
 216  aspects of <SPAN
 217 CLASS="APPLICATION"
 218 >Privoxy</SPAN
 219 > configuration. The actions
 220  file, and other configuration files, are explained in detail below. </P
 221 ><P
 222 > <SPAN
 223 CLASS="QUOTE"
 224 >"Toggle Privoxy On or Off"</SPAN
 225 > is handy for sites that might
 226  have problems with your current actions and filters. You can in fact use
 227  it as a test to see whether it is <SPAN
 228 CLASS="APPLICATION"
 229 >Privoxy</SPAN
 230 >
 231  causing the problem or not. <SPAN
 232 CLASS="APPLICATION"
 233 >Privoxy</SPAN
 234 > continues
 235  to run as a proxy in this case, but all manipulation is disabled, i.e.
 236  <SPAN
 237 CLASS="APPLICATION"
 238 >Privoxy</SPAN
 239 > acts like a normal forwarding proxy. There
 240  is even a toggle <A
 241 HREF="appendix.html#BOOKMARKLETS"
 242 >Bookmarklet</A
 243 > offered, so
 244  that you can toggle <SPAN
 245 CLASS="APPLICATION"
 246 >Privoxy</SPAN
 247 > with one click from
 248  your browser.</P
 249 ></DIV
 250 ><DIV
 251 CLASS="SECT2"
 252 ><H2
 253 CLASS="SECT2"
 254 ><A
 255 NAME="CONFOVERVIEW"
 256 ></A
 257 >6.2. Configuration Files Overview</H2
 258 ><P
 259 > For Unix, *BSD and Linux, all configuration files are located in
 260  <TT
 261 CLASS="FILENAME"
 262 >/etc/privoxy/</TT
 263 > by default. For MS Windows, OS/2, and
 264  AmigaOS these are all in the same directory as the
 265  <SPAN
 266 CLASS="APPLICATION"
 267 >Privoxy</SPAN
 268 > executable.  The name
 269  and number of configuration files has changed from previous versions, and is
 270  subject to change as development progresses.</P
 271 ><P
 272 > The installed defaults provide a reasonable starting point, though
 273  some settings may be aggressive by some standards. For the time being, the
 274  principle configuration files are:</P
 275 ><P
 276 > <P
 277 ></P
 278 ><UL
 279 ><LI
 280 ><P
 281 >     The <A
 282 HREF="config.html"
 283 >main configuration file</A
 284 > is named <TT
 285 CLASS="FILENAME"
 286 >config</TT
 287 >
 288      on Linux, Unix, BSD, OS/2, and AmigaOS and <TT
 289 CLASS="FILENAME"
 290 >config.txt</TT
 291 >
 292      on Windows. This is a required file.
 293    </P
 294 ></LI
 295 ><LI
 296 ><P
 297 >    <TT
 298 CLASS="FILENAME"
 299 >default.action</TT
 300 > (the main <A
 301 HREF="actions-file.html"
 302 >actions file</A
 303 >)
 304     is used to define which <SPAN
 305 CLASS="QUOTE"
 306 >"actions"</SPAN
 307 > relating to banner-blocking, images, pop-ups,
 308     content modification, cookie handling etc should be applied by default. It also defines many
 309     exceptions (both positive and negative) from this default set of actions that enable
 310     <SPAN
 311 CLASS="APPLICATION"
 312 >Privoxy</SPAN
 313 > to selectively eliminate the junk, and only the junk, on
 314     as many websites as possible.
 315    </P
 316 ><P
 317 >    Multiple actions files may be defined in <TT
 318 CLASS="FILENAME"
 319 >config</TT
 320 >. These
 321     are processed in the order they are defined. Local customizations and locally
 322     preferred exceptions to the default policies  as defined in
 323     <TT
 324 CLASS="FILENAME"
 325 >default.action</TT
 326 > (which you will most probably want
 327     to define sooner or later) are probably best applied in
 328     <TT
 329 CLASS="FILENAME"
 330 >user.action</TT
 331 >, where you can preserve them across
 332     upgrades. <TT
 333 CLASS="FILENAME"
 334 >standard.action</TT
 335 > is for
 336     <SPAN
 337 CLASS="APPLICATION"
 338 >Privoxy's</SPAN
 339 > internal use.
 340    </P
 341 ><P
 342 >
 343     There is also a web based editor that can be accessed from
 344     <A
 345 HREF="http://config.privoxy.org/show-status"
 346 TARGET="_top"
 347 >http://config.privoxy.org/show-status</A
 348 >
 349     (Shortcut: <A
 350 HREF="http://p.p/show-status"
 351 TARGET="_top"
 352 >http://p.p/show-status</A
 353 >) for the
 354     various actions files.
 355    </P
 356 ></LI
 357 ><LI
 358 ><P
 359 >    <SPAN
 360 CLASS="QUOTE"
 361 >"Filter files"</SPAN
 362 > (the <A
 363 HREF="filter-file.html"
 364 >filter
 365     file</A
 366 >) can be used to re-write the raw page content, including
 367     viewable text as well as embedded HTML and JavaScript, and whatever else
 368     lurks on any given web page. The filtering jobs are only pre-defined here;
 369     whether to apply them or not is up to the actions files.
 370     <TT
 371 CLASS="FILENAME"
 372 >default.filter</TT
 373 > includes various filters made
 374     available for use by the developers. Some are much more intrusive than
 375     others, and all should be used with caution. You may define additional
 376     filter files in <TT
 377 CLASS="FILENAME"
 378 >config</TT
 379 > as you can with
 380     actions files. We suggest <TT
 381 CLASS="FILENAME"
 382 >user.filter</TT
 383 > for any
 384     locally defined filters or customizations.
 385    </P
 386 ></LI
 387 ></UL
 388 ></P
 389 ><P
 390 > The syntax of all configuration files has remained the same throughout the
 391  3.x series. There have been enhancements, but no changes that would preclude
 392  the use of any configuration file from one version to the next.</P
 393 ><P
 394 > All files use the <SPAN
 395 CLASS="QUOTE"
 396 >"<TT
 397 CLASS="LITERAL"
 398 >#</TT
 399 >"</SPAN
 400 > character to denote a
 401  comment (the rest of the line will be ignored) and understand line continuation
 402  through placing a backslash ("<TT
 403 CLASS="LITERAL"
 404 >\</TT
 405 >") as the very last character
 406  in a line. If the <TT
 407 CLASS="LITERAL"
 408 >#</TT
 409 > is preceded by a backslash, it looses
 410  its special function. Placing a <TT
 411 CLASS="LITERAL"
 412 >#</TT
 413 > in front of an otherwise
 414  valid configuration line to prevent it from being interpreted is called "commenting
 415  out" that line.</P
 416 ><P
 417 > The actions files and filter files
 418  can use Perl style <A
 419 HREF="appendix.html#REGEX"
 420 >regular expressions</A
 421 > for
 422  maximum flexibility. </P
 423 ><P
 424 > After making any changes, there is no need to restart
 425  <SPAN
 426 CLASS="APPLICATION"
 427 >Privoxy</SPAN
 428 > in order for the changes to take
 429  effect. <SPAN
 430 CLASS="APPLICATION"
 431 >Privoxy</SPAN
 432 > detects such changes
 433  automatically. Note, however, that it may take one or two additional
 434  requests for the change to take effect. When changing the listening address
 435  of <SPAN
 436 CLASS="APPLICATION"
 437 >Privoxy</SPAN
 438 >, these <SPAN
 439 CLASS="QUOTE"
 440 >"wake up"</SPAN
 441 > requests
 442  must obviously be sent to the <SPAN
 443 CLASS="emphasis"
 444 ><I
 445 CLASS="EMPHASIS"
 446 >old</I
 447 ></SPAN
 448 > listening address.</P
 449 ><P
 450 > While under development, the configuration content is subject to change.
 451  The below documentation may not be accurate by the time you read this.
 452  Also, what constitutes a <SPAN
 453 CLASS="QUOTE"
 454 >"default"</SPAN
 455 > setting, may change, so
 456  please check all your configuration files on important issues.</P
 457 ></DIV
 458 ></DIV
 459 ><DIV
 460 CLASS="NAVFOOTER"
 461 ><HR
 462 ALIGN="LEFT"
 463 WIDTH="100%"><TABLE
 464 SUMMARY="Footer navigation table"
 465 WIDTH="100%"
 466 BORDER="0"
 467 CELLPADDING="0"
 468 CELLSPACING="0"
 469 ><TR
 470 ><TD
 471 WIDTH="33%"
 472 ALIGN="left"
 473 VALIGN="top"
 474 ><A
 475 HREF="startup.html"
 476 ACCESSKEY="P"
 477 >Prev</A
 478 ></TD
 479 ><TD
 480 WIDTH="34%"
 481 ALIGN="center"
 482 VALIGN="top"
 483 ><A
 484 HREF="index.html"
 485 ACCESSKEY="H"
 486 >Home</A
 487 ></TD
 488 ><TD
 489 WIDTH="33%"
 490 ALIGN="right"
 491 VALIGN="top"
 492 ><A
 493 HREF="config.html"
 494 ACCESSKEY="N"
 495 >Next</A
 496 ></TD
 497 ></TR
 498 ><TR
 499 ><TD
 500 WIDTH="33%"
 501 ALIGN="left"
 502 VALIGN="top"
 503 >Starting <SPAN
 504 CLASS="APPLICATION"
 505 >Privoxy</SPAN
 506 ></TD
 507 ><TD
 508 WIDTH="34%"
 509 ALIGN="center"
 510 VALIGN="top"
 511 >&nbsp;</TD
 512 ><TD
 513 WIDTH="33%"
 514 ALIGN="right"
 515 VALIGN="top"
 516 >The Main Configuration File</TD
 517 ></TR
 518 ></TABLE
 519 ></DIV
 520 ></BODY
 521 ></HTML
 522 >