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