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 >7. <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="AEN305"
  97 >7.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  <SPAN
 191 CLASS="QUOTE"
 192 >"actions list"</SPAN
 193 >, which is where the ad, banner, cookie,
 194  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 filtering is disabled. There
 219  is even a toggle <A
 220 HREF="appendix.html#BOOKMARKLETS"
 221 >Bookmarklet</A
 222 > offered, so
 223  that you can toggle <SPAN
 224 CLASS="APPLICATION"
 225 >Privoxy</SPAN
 226 > with one click from
 227  your browser.</P
 228 ></DIV
 229 ><DIV
 230 CLASS="SECT2"
 231 ><H2
 232 CLASS="SECT2"
 233 ><A
 234 NAME="CONFOVERVIEW"
 235 >7.2. Configuration Files Overview</A
 236 ></H2
 237 ><P
 238 > For Unix, *BSD and Linux, all configuration files are located in
 239  <TT
 240 CLASS="FILENAME"
 241 >/etc/privoxy/</TT
 242 > by default. For MS Windows, OS/2, and
 243  AmigaOS these are all in the same directory as the
 244  <SPAN
 245 CLASS="APPLICATION"
 246 >Privoxy</SPAN
 247 > executable.  The name
 248  and number of configuration files has changed from previous versions, and is
 249  subject to change as development progresses.</P
 250 ><P
 251 > The installed defaults provide a reasonable starting point, though
 252  some settings may be aggressive by some standards. For the time being, the
 253  principle configuration files are:</P
 254 ><P
 255 > <P
 256 ></P
 257 ><UL
 258 ><LI
 259 ><P
 260 >     The main configuration file is named <A
 261 HREF="config.html"
 262 >config</A
 263 >
 264      on Linux, Unix, BSD, OS/2, and AmigaOS and <TT
 265 CLASS="FILENAME"
 266 >config.txt</TT
 267 >
 268      on Windows. This is a required file.
 269    </P
 270 ></LI
 271 ><LI
 272 ><P
 273 >    <TT
 274 CLASS="FILENAME"
 275 >default.action</TT
 276 > (the main <A
 277 HREF="actions-file.html"
 278 >actions file</A
 279 >) is used to define
 280     the default settings for various <SPAN
 281 CLASS="QUOTE"
 282 >"actions"</SPAN
 283 > relating to images, banners,
 284     pop-ups, access restrictions, banners and cookies.
 285    </P
 286 ><P
 287 >    Multiple actions files may be defined in <TT
 288 CLASS="FILENAME"
 289 >config</TT
 290 >. These
 291     are processed in the order they are defined. Local customizations and locally
 292     preferred exceptions to the default policies as defined in
 293     <TT
 294 CLASS="FILENAME"
 295 >default.action</TT
 296 > are probably best applied in
 297     <TT
 298 CLASS="FILENAME"
 299 >user.action</TT
 300 >, which should be preserved across
 301     upgrades. <TT
 302 CLASS="FILENAME"
 303 >standard.action</TT
 304 > is also included. This is mostly
 305     for <SPAN
 306 CLASS="APPLICATION"
 307 >Privoxy's</SPAN
 308 > internal use.
 309    </P
 310 ><P
 311 >
 312     There is also a web based editor that can be accessed from
 313     <A
 314 HREF="http://config.privoxy.org/show-status/"
 315 TARGET="_top"
 316 >http://config.privoxy.org/show-status/</A
 317 >
 318     (Shortcut: <A
 319 HREF="http://p.p/show-status/"
 320 TARGET="_top"
 321 >http://p.p/show-status/</A
 322 >) for the
 323     various actions files.
 324    </P
 325 ></LI
 326 ><LI
 327 ><P
 328 >    <TT
 329 CLASS="FILENAME"
 330 >default.filter</TT
 331 > (the <A
 332 HREF="filter-file.html"
 333 >filter
 334     file</A
 335 >) can be used to re-write the raw page content, including
 336     viewable text as well as embedded HTML and JavaScript, and whatever else
 337     lurks on any given web page. The filtering jobs are only pre-defined here;
 338     whether to apply them or not is up to the actions files.
 339    </P
 340 ></LI
 341 ></UL
 342 ></P
 343 ><P
 344 > All files use the <SPAN
 345 CLASS="QUOTE"
 346 >"<TT
 347 CLASS="LITERAL"
 348 >#</TT
 349 >"</SPAN
 350 > character to denote a
 351  comment (the rest of the line will be ignored) angd understand line continuation
 352  through placing a backslash ("<TT
 353 CLASS="LITERAL"
 354 >\</TT
 355 >") as the very last character
 356  in a line. If the <TT
 357 CLASS="LITERAL"
 358 >#</TT
 359 > is preceded by a backslash, it looses
 360  its special function. Placing a <TT
 361 CLASS="LITERAL"
 362 >#</TT
 363 > in front of an otherwise
 364  valid configuration line to prevent it from being interpreted is called "commenting
 365  out" that line.</P
 366 ><P
 367 > The actions files and <TT
 368 CLASS="FILENAME"
 369 >default.filter</TT
 370 >
 371  can use Perl style <A
 372 HREF="appendix.html#REGEX"
 373 >regular expressions</A
 374 > for
 375  maximum flexibility. </P
 376 ><P
 377 > After making any changes, there is no need to restart
 378  <SPAN
 379 CLASS="APPLICATION"
 380 >Privoxy</SPAN
 381 > in order for the changes to take
 382  effect. <SPAN
 383 CLASS="APPLICATION"
 384 >Privoxy</SPAN
 385 > detects such changes
 386  automatically. Note, however, that it may take one or two additional
 387  requests for the change to take effect. When changing the listening address
 388  of <SPAN
 389 CLASS="APPLICATION"
 390 >Privoxy</SPAN
 391 >, these <SPAN
 392 CLASS="QUOTE"
 393 >"wake up"</SPAN
 394 > requests
 395  must obviously be sent to the <I
 396 CLASS="EMPHASIS"
 397 >old</I
 398 > listening address.</P
 399 ><P
 400 > While under development, the configuration content is subject to change.
 401  The below documentation may not be accurate by the time you read this.
 402  Also, what constitutes a <SPAN
 403 CLASS="QUOTE"
 404 >"default"</SPAN
 405 > setting, may change, so
 406  please check all your configuration files on important issues.</P
 407 ></DIV
 408 ></DIV
 409 ><DIV
 410 CLASS="NAVFOOTER"
 411 ><HR
 412 ALIGN="LEFT"
 413 WIDTH="100%"><TABLE
 414 WIDTH="100%"
 415 BORDER="0"
 416 CELLPADDING="0"
 417 CELLSPACING="0"
 418 ><TR
 419 ><TD
 420 WIDTH="33%"
 421 ALIGN="left"
 422 VALIGN="top"
 423 ><A
 424 HREF="startup.html"
 425 >Prev</A
 426 ></TD
 427 ><TD
 428 WIDTH="34%"
 429 ALIGN="center"
 430 VALIGN="top"
 431 ><A
 432 HREF="index.html"
 433 >Home</A
 434 ></TD
 435 ><TD
 436 WIDTH="33%"
 437 ALIGN="right"
 438 VALIGN="top"
 439 ><A
 440 HREF="config.html"
 441 >Next</A
 442 ></TD
 443 ></TR
 444 ><TR
 445 ><TD
 446 WIDTH="33%"
 447 ALIGN="left"
 448 VALIGN="top"
 449 >Starting <SPAN
 450 CLASS="APPLICATION"
 451 >Privoxy</SPAN
 452 ></TD
 453 ><TD
 454 WIDTH="34%"
 455 ALIGN="center"
 456 VALIGN="top"
 457 >&nbsp;</TD
 458 ><TD
 459 WIDTH="33%"
 460 ALIGN="right"
 461 VALIGN="top"
 462 >The Main Configuration File</TD
 463 ></TR
 464 ></TABLE
 465 ></DIV
 466 ></BODY
 467 ></HTML
 468 >