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="AEN790"
  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="AEN798"
 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.  The name
 276  and number of configuration files has changed from previous versions, and is
 277  subject to change as development progresses.</P
 278 ><P
 279 > The installed defaults provide a reasonable starting point, though
 280  some settings may be aggressive by some standards. For the time being, the
 281  principle configuration files are:</P
 282 ><P
 283 > <P
 284 ></P
 285 ><UL
 286 ><LI
 287 ><P
 288 >     The <A
 289 HREF="config.html"
 290 >main configuration file</A
 291 > is named <TT
 292 CLASS="FILENAME"
 293 >config</TT
 294 >
 295      on Linux, Unix, BSD, OS/2, and AmigaOS and <TT
 296 CLASS="FILENAME"
 297 >config.txt</TT
 298 >
 299      on Windows. This is a required file.
 300    </P
 301 ></LI
 302 ><LI
 303 ><P
 304 >    <TT
 305 CLASS="FILENAME"
 306 >default.action</TT
 307 > (the main <A
 308 HREF="actions-file.html"
 309 >actions file</A
 310 >)
 311     is used to define which <SPAN
 312 CLASS="QUOTE"
 313 >"actions"</SPAN
 314 > relating to banner-blocking, images, pop-ups,
 315     content modification, cookie handling etc should be applied by default. It also defines many
 316     exceptions (both positive and negative) from this default set of actions that enable
 317     <SPAN
 318 CLASS="APPLICATION"
 319 >Privoxy</SPAN
 320 > to selectively eliminate the junk, and only the junk, on
 321     as many websites as possible.
 322    </P
 323 ><P
 324 >    Multiple actions files may be defined in <TT
 325 CLASS="FILENAME"
 326 >config</TT
 327 >. These
 328     are processed in the order they are defined. Local customizations and locally
 329     preferred exceptions to the default policies  as defined in
 330     <TT
 331 CLASS="FILENAME"
 332 >default.action</TT
 333 > (which you will most probably want
 334     to define sooner or later) are probably best applied in
 335     <TT
 336 CLASS="FILENAME"
 337 >user.action</TT
 338 >, where you can preserve them across
 339     upgrades. <TT
 340 CLASS="FILENAME"
 341 >standard.action</TT
 342 > is only for
 343     <SPAN
 344 CLASS="APPLICATION"
 345 >Privoxy's</SPAN
 346 > internal use.
 347    </P
 348 ><P
 349 >
 350     There is also a web based editor that can be accessed from
 351     <A
 352 HREF="http://config.privoxy.org/show-status"
 353 TARGET="_top"
 354 >http://config.privoxy.org/show-status</A
 355 >
 356     (Shortcut: <A
 357 HREF="http://p.p/show-status"
 358 TARGET="_top"
 359 >http://p.p/show-status</A
 360 >) for the
 361     various actions files.
 362    </P
 363 ></LI
 364 ><LI
 365 ><P
 366 >    <SPAN
 367 CLASS="QUOTE"
 368 >"Filter files"</SPAN
 369 > (the <A
 370 HREF="filter-file.html"
 371 >filter
 372     file</A
 373 >) can be used to re-write the raw page content, including
 374     viewable text as well as embedded HTML and JavaScript, and whatever else
 375     lurks on any given web page. The filtering jobs are only pre-defined here;
 376     whether to apply them or not is up to the actions files.
 377     <TT
 378 CLASS="FILENAME"
 379 >default.filter</TT
 380 > includes various filters made
 381     available for use by the developers. Some are much more intrusive than
 382     others, and all should be used with caution. You may define additional
 383     filter files in <TT
 384 CLASS="FILENAME"
 385 >config</TT
 386 > as you can with
 387     actions files. We suggest <TT
 388 CLASS="FILENAME"
 389 >user.filter</TT
 390 > for any
 391     locally defined filters or customizations.
 392    </P
 393 ></LI
 394 ></UL
 395 ></P
 396 ><P
 397 > The syntax of the configuration and filter files may change between different
 398  Privoxy versions, unfortunately some enhancements cost backwards compatibility.
 399  </P
 400 ><P
 401 > All files use the <SPAN
 402 CLASS="QUOTE"
 403 >"<TT
 404 CLASS="LITERAL"
 405 >#</TT
 406 >"</SPAN
 407 > character to denote a
 408  comment (the rest of the line will be ignored) and understand line continuation
 409  through placing a backslash ("<TT
 410 CLASS="LITERAL"
 411 >\</TT
 412 >") as the very last character
 413  in a line. If the <TT
 414 CLASS="LITERAL"
 415 >#</TT
 416 > is preceded by a backslash, it looses
 417  its special function. Placing a <TT
 418 CLASS="LITERAL"
 419 >#</TT
 420 > in front of an otherwise
 421  valid configuration line to prevent it from being interpreted is called "commenting
 422  out" that line. Blank lines are ignored.</P
 423 ><P
 424 > The actions files and filter files
 425  can use Perl style <A
 426 HREF="appendix.html#REGEX"
 427 >regular expressions</A
 428 > for
 429  maximum flexibility. </P
 430 ><P
 431 > After making any changes, there is no need to restart
 432  <SPAN
 433 CLASS="APPLICATION"
 434 >Privoxy</SPAN
 435 > in order for the changes to take
 436  effect. <SPAN
 437 CLASS="APPLICATION"
 438 >Privoxy</SPAN
 439 > detects such changes
 440  automatically. Note, however, that it may take one or two additional
 441  requests for the change to take effect. When changing the listening address
 442  of <SPAN
 443 CLASS="APPLICATION"
 444 >Privoxy</SPAN
 445 >, these <SPAN
 446 CLASS="QUOTE"
 447 >"wake up"</SPAN
 448 > requests
 449  must obviously be sent to the <SPAN
 450 CLASS="emphasis"
 451 ><I
 452 CLASS="EMPHASIS"
 453 >old</I
 454 ></SPAN
 455 > listening address.</P
 456 ><P
 457 > While under development, the configuration content is subject to change.
 458  The below documentation may not be accurate by the time you read this.
 459  Also, what constitutes a <SPAN
 460 CLASS="QUOTE"
 461 >"default"</SPAN
 462 > setting, may change, so
 463  please check all your configuration files on important issues.</P
 464 ></DIV
 465 ></DIV
 466 ><DIV
 467 CLASS="NAVFOOTER"
 468 ><HR
 469 ALIGN="LEFT"
 470 WIDTH="100%"><TABLE
 471 SUMMARY="Footer navigation table"
 472 WIDTH="100%"
 473 BORDER="0"
 474 CELLPADDING="0"
 475 CELLSPACING="0"
 476 ><TR
 477 ><TD
 478 WIDTH="33%"
 479 ALIGN="left"
 480 VALIGN="top"
 481 ><A
 482 HREF="startup.html"
 483 ACCESSKEY="P"
 484 >Prev</A
 485 ></TD
 486 ><TD
 487 WIDTH="34%"
 488 ALIGN="center"
 489 VALIGN="top"
 490 ><A
 491 HREF="index.html"
 492 ACCESSKEY="H"
 493 >Home</A
 494 ></TD
 495 ><TD
 496 WIDTH="33%"
 497 ALIGN="right"
 498 VALIGN="top"
 499 ><A
 500 HREF="config.html"
 501 ACCESSKEY="N"
 502 >Next</A
 503 ></TD
 504 ></TR
 505 ><TR
 506 ><TD
 507 WIDTH="33%"
 508 ALIGN="left"
 509 VALIGN="top"
 510 >Starting Privoxy</TD
 511 ><TD
 512 WIDTH="34%"
 513 ALIGN="center"
 514 VALIGN="top"
 515 >&nbsp;</TD
 516 ><TD
 517 WIDTH="33%"
 518 ALIGN="right"
 519 VALIGN="top"
 520 >The Main Configuration File</TD
 521 ></TR
 522 ></TABLE
 523 ></DIV
 524 ></BODY
 525 ></HTML
 526 >