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