doc/webserver/user-manual/configuration.html

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