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.64
   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 WIDTH="100%"
  32 BORDER="0"
  33 CELLPADDING="0"
  34 CELLSPACING="0"
  35 ><TR
  36 ><TH
  37 COLSPAN="3"
  38 ALIGN="center"
  39 >Privoxy User Manual</TH
  40 ></TR
  41 ><TR
  42 ><TD
  43 WIDTH="10%"
  44 ALIGN="left"
  45 VALIGN="bottom"
  46 ><A
  47 HREF="startup.html"
  48 >Prev</A
  49 ></TD
  50 ><TD
  51 WIDTH="80%"
  52 ALIGN="center"
  53 VALIGN="bottom"
  54 ></TD
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="right"
  58 VALIGN="bottom"
  59 ><A
  60 HREF="config.html"
  61 >Next</A
  62 ></TD
  63 ></TR
  64 ></TABLE
  65 ><HR
  66 ALIGN="LEFT"
  67 WIDTH="100%"></DIV
  68 ><DIV
  69 CLASS="SECT1"
  70 ><H1
  71 CLASS="SECT1"
  72 ><A
  73 NAME="CONFIGURATION"
  74 >6. <SPAN
  75 CLASS="APPLICATION"
  76 >Privoxy</SPAN
  77 > Configuration</A
  78 ></H1
  79 ><P
  80 >  All <SPAN
  81 CLASS="APPLICATION"
  82 >Privoxy</SPAN
  83 > configuration is stored
  84   in text files. These files can be edited with a text editor.
  85   Many important aspects of <SPAN
  86 CLASS="APPLICATION"
  87 >Privoxy</SPAN
  88 > can
  89   also be controlled easily with a web browser.
  90  </P
  91 ><DIV
  92 CLASS="SECT2"
  93 ><H2
  94 CLASS="SECT2"
  95 ><A
  96 NAME="AEN481"
  97 >6.1. Controlling <SPAN
  98 CLASS="APPLICATION"
  99 >Privoxy</SPAN
 100 > with Your Web Browser</A
 101 ></H2
 102 ><P
 103 > <SPAN
 104 CLASS="APPLICATION"
 105 >Privoxy</SPAN
 106 >'s user interface can be reached through the special
 107  URL <A
 108 HREF="http://config.privoxy.org/"
 109 TARGET="_top"
 110 >http://config.privoxy.org/</A
 111 >
 112  (shortcut: <A
 113 HREF="http://p.p/"
 114 TARGET="_top"
 115 >http://p.p/</A
 116 >),
 117  which is a built-in page and works without Internet access.
 118  You will see the following section:&#13;</P
 119 ><TABLE
 120 BORDER="0"
 121 BGCOLOR="#E0E0E0"
 122 WIDTH="100%"
 123 ><TR
 124 ><TD
 125 ><PRE
 126 CLASS="SCREEN"
 127 > <H3
 128 CLASS="BRIDGEHEAD"
 129 >Privoxy Menu</H3
 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"
 239 >6.2. Configuration Files Overview</A
 240 ></H2
 241 ><P
 242 > For Unix, *BSD and Linux, all configuration files are located in
 243  <TT
 244 CLASS="FILENAME"
 245 >/etc/privoxy/</TT
 246 > by default. For MS Windows, OS/2, and
 247  AmigaOS these are all in the same directory as the
 248  <SPAN
 249 CLASS="APPLICATION"
 250 >Privoxy</SPAN
 251 > executable.  The name
 252  and number of configuration files has changed from previous versions, and is
 253  subject to change as development progresses.</P
 254 ><P
 255 > The installed defaults provide a reasonable starting point, though
 256  some settings may be aggressive by some standards. For the time being, the
 257  principle configuration files are:</P
 258 ><P
 259 > <P
 260 ></P
 261 ><UL
 262 ><LI
 263 ><P
 264 >     The <A
 265 HREF="config.html"
 266 >main configuration file</A
 267 > is named <TT
 268 CLASS="FILENAME"
 269 >config</TT
 270 >
 271      on Linux, Unix, BSD, OS/2, and AmigaOS and <TT
 272 CLASS="FILENAME"
 273 >config.txt</TT
 274 >
 275      on Windows. This is a required file.
 276    </P
 277 ></LI
 278 ><LI
 279 ><P
 280 >    <TT
 281 CLASS="FILENAME"
 282 >default.action</TT
 283 > (the main <A
 284 HREF="actions-file.html"
 285 >actions file</A
 286 >)
 287     is used to define which <SPAN
 288 CLASS="QUOTE"
 289 >"actions"</SPAN
 290 > relating to banner-blocking, images, pop-ups,
 291     content modification, cookie handling etc should be applied by default. It also defines many
 292     exceptions (both positive and negative) from this default set of actions that enable
 293     <SPAN
 294 CLASS="APPLICATION"
 295 >Privoxy</SPAN
 296 > to selectively eliminate the junk, and only the junk, on
 297     as many websites as possible.
 298    </P
 299 ><P
 300 >    Multiple actions files may be defined in <TT
 301 CLASS="FILENAME"
 302 >config</TT
 303 >. These
 304     are processed in the order they are defined. Local customizations and locally
 305     preferred exceptions to the default policies  as defined in
 306     <TT
 307 CLASS="FILENAME"
 308 >default.action</TT
 309 > (which you will most probably want
 310     to define sooner or later) are probably best applied in
 311     <TT
 312 CLASS="FILENAME"
 313 >user.action</TT
 314 >, where you can preserve them across
 315     upgrades. <TT
 316 CLASS="FILENAME"
 317 >standard.action</TT
 318 > is for
 319     <SPAN
 320 CLASS="APPLICATION"
 321 >Privoxy's</SPAN
 322 > internal use.
 323    </P
 324 ><P
 325 >
 326     There is also a web based editor that can be accessed from
 327     <A
 328 HREF="http://config.privoxy.org/show-status"
 329 TARGET="_top"
 330 >http://config.privoxy.org/show-status</A
 331 >
 332     (Shortcut: <A
 333 HREF="http://p.p/show-status"
 334 TARGET="_top"
 335 >http://p.p/show-status</A
 336 >) for the
 337     various actions files.
 338    </P
 339 ></LI
 340 ><LI
 341 ><P
 342 >    <TT
 343 CLASS="FILENAME"
 344 >default.filter</TT
 345 > (the <A
 346 HREF="filter-file.html"
 347 >filter
 348     file</A
 349 >) can be used to re-write the raw page content, including
 350     viewable text as well as embedded HTML and JavaScript, and whatever else
 351     lurks on any given web page. The filtering jobs are only pre-defined here;
 352     whether to apply them or not is up to the actions files.
 353    </P
 354 ></LI
 355 ></UL
 356 ></P
 357 ><P
 358 > All files use the <SPAN
 359 CLASS="QUOTE"
 360 >"<TT
 361 CLASS="LITERAL"
 362 >#</TT
 363 >"</SPAN
 364 > character to denote a
 365  comment (the rest of the line will be ignored) and understand line continuation
 366  through placing a backslash ("<TT
 367 CLASS="LITERAL"
 368 >\</TT
 369 >") as the very last character
 370  in a line. If the <TT
 371 CLASS="LITERAL"
 372 >#</TT
 373 > is preceded by a backslash, it looses
 374  its special function. Placing a <TT
 375 CLASS="LITERAL"
 376 >#</TT
 377 > in front of an otherwise
 378  valid configuration line to prevent it from being interpreted is called "commenting
 379  out" that line.</P
 380 ><P
 381 > The actions files and <TT
 382 CLASS="FILENAME"
 383 >default.filter</TT
 384 >
 385  can use Perl style <A
 386 HREF="appendix.html#REGEX"
 387 >regular expressions</A
 388 > for
 389  maximum flexibility. </P
 390 ><P
 391 > After making any changes, there is no need to restart
 392  <SPAN
 393 CLASS="APPLICATION"
 394 >Privoxy</SPAN
 395 > in order for the changes to take
 396  effect. <SPAN
 397 CLASS="APPLICATION"
 398 >Privoxy</SPAN
 399 > detects such changes
 400  automatically. Note, however, that it may take one or two additional
 401  requests for the change to take effect. When changing the listening address
 402  of <SPAN
 403 CLASS="APPLICATION"
 404 >Privoxy</SPAN
 405 >, these <SPAN
 406 CLASS="QUOTE"
 407 >"wake up"</SPAN
 408 > requests
 409  must obviously be sent to the <I
 410 CLASS="EMPHASIS"
 411 >old</I
 412 > listening address.</P
 413 ><P
 414 > While under development, the configuration content is subject to change.
 415  The below documentation may not be accurate by the time you read this.
 416  Also, what constitutes a <SPAN
 417 CLASS="QUOTE"
 418 >"default"</SPAN
 419 > setting, may change, so
 420  please check all your configuration files on important issues.</P
 421 ></DIV
 422 ></DIV
 423 ><DIV
 424 CLASS="NAVFOOTER"
 425 ><HR
 426 ALIGN="LEFT"
 427 WIDTH="100%"><TABLE
 428 WIDTH="100%"
 429 BORDER="0"
 430 CELLPADDING="0"
 431 CELLSPACING="0"
 432 ><TR
 433 ><TD
 434 WIDTH="33%"
 435 ALIGN="left"
 436 VALIGN="top"
 437 ><A
 438 HREF="startup.html"
 439 >Prev</A
 440 ></TD
 441 ><TD
 442 WIDTH="34%"
 443 ALIGN="center"
 444 VALIGN="top"
 445 ><A
 446 HREF="index.html"
 447 >Home</A
 448 ></TD
 449 ><TD
 450 WIDTH="33%"
 451 ALIGN="right"
 452 VALIGN="top"
 453 ><A
 454 HREF="config.html"
 455 >Next</A
 456 ></TD
 457 ></TR
 458 ><TR
 459 ><TD
 460 WIDTH="33%"
 461 ALIGN="left"
 462 VALIGN="top"
 463 >Starting <SPAN
 464 CLASS="APPLICATION"
 465 >Privoxy</SPAN
 466 ></TD
 467 ><TD
 468 WIDTH="34%"
 469 ALIGN="center"
 470 VALIGN="top"
 471 >&nbsp;</TD
 472 ><TD
 473 WIDTH="33%"
 474 ALIGN="right"
 475 VALIGN="top"
 476 >The Main Configuration File</TD
 477 ></TR
 478 ></TABLE
 479 ></DIV
 480 ></BODY
 481 ></HTML
 482 >