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