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