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