doc/webserver/user-manual/configuration.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
   2 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4   <head>
   5     <meta name="generator" content="HTML Tidy, see www.w3.org">
   6     <title>
   7       Privoxy Configuration
   8     </title>
   9     <meta name="GENERATOR" content=
  10     "Modular DocBook HTML Stylesheet Version 1.79">
  11     <link rel="HOME" title="Privoxy 3.0.18 User Manual" href="index.html">
  12     <link rel="PREVIOUS" title="Starting Privoxy" href="startup.html">
  13     <link rel="NEXT" title="The Main Configuration File" href="config.html">
  14     <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
  15     <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  16     <link rel="STYLESHEET" type="text/css" href="p_doc.css">
  17 <style type="text/css">
  18  body {
  19   background-color: #EEEEEE;
  20   color: #000000;
  21  }
  22  :link { color: #0000FF }
  23  :visited { color: #840084 }
  24  :active { color: #0000FF }
  25  hr.c1 {text-align: left}
  26 </style>
  27   </head>
  28   <body class="SECT1">
  29     <div class="NAVHEADER">
  30       <table summary="Header navigation table" width="100%" border="0"
  31       cellpadding="0" cellspacing="0">
  32         <tr>
  33           <th colspan="3" align="center">
  34             Privoxy 3.0.18 User Manual
  35           </th>
  36         </tr>
  37         <tr>
  38           <td width="10%" align="left" valign="bottom">
  39             <a href="startup.html" accesskey="P">Prev</a>
  40           </td>
  41           <td width="80%" align="center" valign="bottom">
  42           </td>
  43           <td width="10%" align="right" valign="bottom">
  44             <a href="config.html" accesskey="N">Next</a>
  45           </td>
  46         </tr>
  47       </table>
  48       <hr width="100%" class="c1">
  49     </div>
  50     <div class="SECT1">
  51       <h1 class="SECT1">
  52         <a name="CONFIGURATION">6. Privoxy Configuration</a>
  53       </h1>
  54       <p>
  55         All <span class="APPLICATION">Privoxy</span> configuration is stored
  56         in text files. These files can be edited with a text editor. Many
  57         important aspects of <span class="APPLICATION">Privoxy</span> can
  58         also be controlled easily with a web browser.
  59       </p>
  60       <div class="SECT2">
  61         <h2 class="SECT2">
  62           <a name="AEN933">6.1. Controlling Privoxy with Your Web Browser</a>
  63         </h2>
  64         <p>
  65           <span class="APPLICATION">Privoxy</span>'s user interface can be
  66           reached through the special URL <a href=
  67           "http://config.privoxy.org/" target=
  68           "_top">http://config.privoxy.org/</a> (shortcut: <a href=
  69           "http://p.p/" target="_top">http://p.p/</a>), which is a built-in
  70           page and works without Internet access. You will see the following
  71           section:&#13;
  72         </p>
  73         <table border="0" bgcolor="#E0E0E0" width="100%">
  74           <tr>
  75             <td>
  76 <pre class="SCREEN">
  77
  78 </pre>
  79               <h2 class="BRIDGEHEAD">
  80                 <a name="AEN941"></a>&nbsp;&nbsp;&nbsp;&nbsp;Privoxy Menu
  81               </h2>
  82 <pre>
  83 </pre>
  84               <table border="0">
  85                 <tbody>
  86                   <tr>
  87                     <td>
  88                       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#9642;&nbsp;&nbsp;<a
  89                        href="http://config.privoxy.org/show-status" target=
  90                       "_top">View &amp; change the current configuration</a>
  91                     </td>
  92                   </tr>
  93                   <tr>
  94                     <td>
  95                       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#9642;&nbsp;&nbsp;<a
  96                        href="http://config.privoxy.org/show-version" target=
  97                       "_top">View the source code version numbers</a>
  98                     </td>
  99                   </tr>
 100                   <tr>
 101                     <td>
 102                       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#9642;&nbsp;&nbsp;<a
 103                        href="http://config.privoxy.org/show-request" target=
 104                       "_top">View the request headers.</a>
 105                     </td>
 106                   </tr>
 107                   <tr>
 108                     <td>
 109                       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#9642;&nbsp;&nbsp;<a
 110                        href="http://config.privoxy.org/show-url-info" target=
 111                       "_top">Look up which actions apply to a URL and why</a>
 112
 113                     </td>
 114                   </tr>
 115                   <tr>
 116                     <td>
 117                       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#9642;&nbsp;&nbsp;<a
 118                        href="http://config.privoxy.org/toggle" target=
 119                       "_top">Toggle Privoxy on or off</a>
 120                     </td>
 121                   </tr>
 122                   <tr>
 123                     <td>
 124                       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#9642;&nbsp;&nbsp;<a
 125                        href="http://www.privoxy.org/3.0.18/user-manual/"
 126                       target="_top">Documentation</a>
 127                     </td>
 128                   </tr>
 129                 </tbody>
 130               </table>
 131 <pre>
 132 </pre>
 133             </td>
 134           </tr>
 135         </table>
 136         <p>
 137           This should be self-explanatory. Note the first item leads to an
 138           editor for the <a href="actions-file.html">actions files</a>, which
 139           is where the ad, banner, cookie, and URL blocking magic is
 140           configured as well as other advanced features of <span class=
 141           "APPLICATION">Privoxy</span>. This is an easy way to adjust various
 142           aspects of <span class="APPLICATION">Privoxy</span> configuration.
 143           The actions file, and other configuration files, are explained in
 144           detail below.
 145         </p>
 146         <p>
 147           <span class="QUOTE">"Toggle Privoxy On or Off"</span> is handy for
 148           sites that might have problems with your current actions and
 149           filters. You can in fact use it as a test to see whether it is
 150           <span class="APPLICATION">Privoxy</span> causing the problem or
 151           not. <span class="APPLICATION">Privoxy</span> continues to run as a
 152           proxy in this case, but all manipulation is disabled, i.e. <span
 153           class="APPLICATION">Privoxy</span> acts like a normal forwarding
 154           proxy. There is even a toggle <a href=
 155           "appendix.html#BOOKMARKLETS">Bookmarklet</a> offered, so that you
 156           can toggle <span class="APPLICATION">Privoxy</span> with one click
 157           from your browser.
 158         </p>
 159         <p>
 160           Note that several of the features described above are disabled by
 161           default in <span class="APPLICATION">Privoxy</span> 3.0.7 beta and
 162           later. Check the <a href="config.html" target="_top">configuration
 163           file</a> to learn why and in which cases it's safe to enable them
 164           again.
 165         </p>
 166       </div>
 167       <div class="SECT2">
 168         <h2 class="SECT2">
 169           <a name="CONFOVERVIEW">6.2. Configuration Files Overview</a>
 170         </h2>
 171         <p>
 172           For Unix, *BSD and Linux, all configuration files are located in
 173           <tt class="FILENAME">/etc/privoxy/</tt> by default. For MS Windows,
 174           OS/2, and AmigaOS these are all in the same directory as the <span
 175           class="APPLICATION">Privoxy</span> executable. The name and number
 176           of configuration files has changed from previous versions, and is
 177           subject to change as development progresses.
 178         </p>
 179         <p>
 180           The installed defaults provide a reasonable starting point, though
 181           some settings may be aggressive by some standards. For the time
 182           being, the principle configuration files are:
 183         </p>
 184         <p>
 185         </p>
 186         <ul>
 187           <li>
 188             <p>
 189               The <a href="config.html">main configuration file</a> is named
 190               <tt class="FILENAME">config</tt> on Linux, Unix, BSD, OS/2, and
 191               AmigaOS and <tt class="FILENAME">config.txt</tt> on Windows.
 192               This is a required file.
 193             </p>
 194           </li>
 195           <li>
 196             <p>
 197               <tt class="FILENAME">match-all.action</tt> is used to define
 198               which <span class="QUOTE">"actions"</span> relating to
 199               banner-blocking, images, pop-ups, content modification, cookie
 200               handling etc should be applied by default. It should be the
 201               first actions file loaded.
 202             </p>
 203             <p>
 204               <tt class="FILENAME">default.action</tt> defines many
 205               exceptions (both positive and negative) from the default set of
 206               actions that's configured in <tt class=
 207               "FILENAME">match-all.action</tt>. It should be the second
 208               actions file loaded and shouldn't be edited by the user.
 209             </p>
 210             <p>
 211               Multiple actions files may be defined in <tt class=
 212               "FILENAME">config</tt>. These are processed in the order they
 213               are defined. Local customizations and locally preferred
 214               exceptions to the default policies as defined in <tt class=
 215               "FILENAME">match-all.action</tt> (which you will most probably
 216               want to define sooner or later) are best applied in <tt class=
 217               "FILENAME">user.action</tt>, where you can preserve them across
 218               upgrades. The file isn't installed by all installers, but you
 219               can easily create it yourself with a text editor.
 220             </p>
 221             <p>
 222               There is also a web based editor that can be accessed from <a
 223               href="http://config.privoxy.org/show-status" target=
 224               "_top">http://config.privoxy.org/show-status</a> (Shortcut: <a
 225               href="http://p.p/show-status" target=
 226               "_top">http://p.p/show-status</a>) for the various actions
 227               files.
 228             </p>
 229           </li>
 230           <li>
 231             <p>
 232               <span class="QUOTE">"Filter files"</span> (the <a href=
 233               "filter-file.html">filter file</a>) can be used to re-write the
 234               raw page content, including viewable text as well as embedded
 235               HTML and JavaScript, and whatever else lurks on any given web
 236               page. The filtering jobs are only pre-defined here; whether to
 237               apply them or not is up to the actions files. <tt class=
 238               "FILENAME">default.filter</tt> includes various filters made
 239               available for use by the developers. Some are much more
 240               intrusive than others, and all should be used with caution. You
 241               may define additional filter files in <tt class=
 242               "FILENAME">config</tt> as you can with actions files. We
 243               suggest <tt class="FILENAME">user.filter</tt> for any locally
 244               defined filters or customizations.
 245             </p>
 246           </li>
 247         </ul>
 248
 249         <p>
 250           The syntax of the configuration and filter files may change between
 251           different Privoxy versions, unfortunately some enhancements cost
 252           backwards compatibility.
 253         </p>
 254         <p>
 255           All files use the <span class="QUOTE">"<tt class=
 256           "LITERAL">#</tt>"</span> character to denote a comment (the rest of
 257           the line will be ignored) and understand line continuation through
 258           placing a backslash ("<tt class="LITERAL">\</tt>") as the very last
 259           character in a line. If the <tt class="LITERAL">#</tt> is preceded
 260           by a backslash, it looses its special function. Placing a <tt
 261           class="LITERAL">#</tt> in front of an otherwise valid configuration
 262           line to prevent it from being interpreted is called "commenting
 263           out" that line. Blank lines are ignored.
 264         </p>
 265         <p>
 266           The actions files and filter files can use Perl style <a href=
 267           "appendix.html#REGEX">regular expressions</a> for maximum
 268           flexibility.
 269         </p>
 270         <p>
 271           After making any changes, there is no need to restart <span class=
 272           "APPLICATION">Privoxy</span> in order for the changes to take
 273           effect. <span class="APPLICATION">Privoxy</span> detects such
 274           changes automatically. Note, however, that it may take one or two
 275           additional requests for the change to take effect. When changing
 276           the listening address of <span class="APPLICATION">Privoxy</span>,
 277           these <span class="QUOTE">"wake up"</span> requests must obviously
 278           be sent to the <span class="emphasis"><i class=
 279           "EMPHASIS">old</i></span> listening address.
 280         </p>
 281         <p>
 282           While under development, the configuration content is subject to
 283           change. The below documentation may not be accurate by the time you
 284           read this. Also, what constitutes a <span class=
 285           "QUOTE">"default"</span> setting, may change, so please check all
 286           your configuration files on important issues.
 287         </p>
 288       </div>
 289     </div>
 290     <div class="NAVFOOTER">
 291       <hr width="100%" class="c1">
 292       <table summary="Footer navigation table" width="100%" border="0"
 293       cellpadding="0" cellspacing="0">
 294         <tr>
 295           <td width="33%" align="left" valign="top">
 296             <a href="startup.html" accesskey="P">Prev</a>
 297           </td>
 298           <td width="34%" align="center" valign="top">
 299             <a href="index.html" accesskey="H">Home</a>
 300           </td>
 301           <td width="33%" align="right" valign="top">
 302             <a href="config.html" accesskey="N">Next</a>
 303           </td>
 304         </tr>
 305         <tr>
 306           <td width="33%" align="left" valign="top">
 307             Starting Privoxy
 308           </td>
 309           <td width="34%" align="center" valign="top">
 310             &nbsp;
 311           </td>
 312           <td width="33%" align="right" valign="top">
 313             The Main Configuration File
 314           </td>
 315         </tr>
 316       </table>
 317     </div>
 318   </body>
 319 </html>
 320