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.25 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.25 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="AEN859"></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.25/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. The name and number
 164           of configuration files has changed from previous versions, and is
 165           subject to change as development progresses.
 166         </p>
 167         <p>
 168           The installed defaults provide a reasonable starting point, though
 169           some settings may be aggressive by some standards. For the time
 170           being, the principle configuration files are:
 171         </p>
 172         <p>
 173         </p>
 174         <ul>
 175           <li>
 176             <p>
 177               The <a href="config.html">main configuration file</a> is named
 178               <tt class="FILENAME">config</tt> on Linux, Unix, BSD, OS/2, and
 179               AmigaOS and <tt class="FILENAME">config.txt</tt> on Windows.
 180               This is a required file.
 181             </p>
 182           </li>
 183           <li>
 184             <p>
 185               <tt class="FILENAME">match-all.action</tt> is used to define
 186               which <span class="QUOTE">"actions"</span> relating to
 187               banner-blocking, images, pop-ups, content modification, cookie
 188               handling etc should be applied by default. It should be the
 189               first actions file loaded.
 190             </p>
 191             <p>
 192               <tt class="FILENAME">default.action</tt> defines many
 193               exceptions (both positive and negative) from the default set of
 194               actions that's configured in <tt class=
 195               "FILENAME">match-all.action</tt>. It should be the second
 196               actions file loaded and shouldn't be edited by the user.
 197             </p>
 198             <p>
 199               Multiple actions files may be defined in <tt class=
 200               "FILENAME">config</tt>. These are processed in the order they
 201               are defined. Local customizations and locally preferred
 202               exceptions to the default policies as defined in <tt class=
 203               "FILENAME">match-all.action</tt> (which you will most probably
 204               want to define sooner or later) are best applied in <tt class=
 205               "FILENAME">user.action</tt>, where you can preserve them across
 206               upgrades. The file isn't installed by all installers, but you
 207               can easily create it yourself with a text editor.
 208             </p>
 209             <p>
 210               There is also a web based editor that can be accessed from <a
 211               href="http://config.privoxy.org/show-status" target=
 212               "_top">http://config.privoxy.org/show-status</a> (Shortcut: <a
 213               href="http://p.p/show-status" target=
 214               "_top">http://p.p/show-status</a>) for the various actions
 215               files.
 216             </p>
 217           </li>
 218           <li>
 219             <p>
 220               <span class="QUOTE">"Filter files"</span> (the <a href=
 221               "filter-file.html">filter file</a>) can be used to re-write the
 222               raw page content, including viewable text as well as embedded
 223               HTML and JavaScript, and whatever else lurks on any given web
 224               page. The filtering jobs are only pre-defined here; whether to
 225               apply them or not is up to the actions files. <tt class=
 226               "FILENAME">default.filter</tt> includes various filters made
 227               available for use by the developers. Some are much more
 228               intrusive than others, and all should be used with caution. You
 229               may define additional filter files in <tt class=
 230               "FILENAME">config</tt> as you can with actions files. We
 231               suggest <tt class="FILENAME">user.filter</tt> for any locally
 232               defined filters or customizations.
 233             </p>
 234           </li>
 235         </ul>
 236
 237         <p>
 238           The syntax of the configuration and filter files may change between
 239           different Privoxy versions, unfortunately some enhancements cost
 240           backwards compatibility.
 241         </p>
 242         <p>
 243           All files use the <span class="QUOTE">"<tt class=
 244           "LITERAL">#</tt>"</span> character to denote a comment (the rest of
 245           the line will be ignored) and understand line continuation through
 246           placing a backslash ("<tt class="LITERAL">\</tt>") as the very last
 247           character in a line. If the <tt class="LITERAL">#</tt> is preceded
 248           by a backslash, it looses its special function. Placing a <tt
 249           class="LITERAL">#</tt> in front of an otherwise valid configuration
 250           line to prevent it from being interpreted is called "commenting
 251           out" that line. Blank lines are ignored.
 252         </p>
 253         <p>
 254           The actions files and filter files can use Perl style <a href=
 255           "appendix.html#REGEX">regular expressions</a> for maximum
 256           flexibility.
 257         </p>
 258         <p>
 259           After making any changes, there is no need to restart <span class=
 260           "APPLICATION">Privoxy</span> in order for the changes to take
 261           effect. <span class="APPLICATION">Privoxy</span> detects such
 262           changes automatically. Note, however, that it may take one or two
 263           additional requests for the change to take effect. When changing
 264           the listening address of <span class="APPLICATION">Privoxy</span>,
 265           these <span class="QUOTE">"wake up"</span> requests must obviously
 266           be sent to the <span class="emphasis"><i class=
 267           "EMPHASIS">old</i></span> listening address.
 268         </p>
 269         <p>
 270           While under development, the configuration content is subject to
 271           change. The below documentation may not be accurate by the time you
 272           read this. Also, what constitutes a <span class=
 273           "QUOTE">"default"</span> setting, may change, so please check all
 274           your configuration files on important issues.
 275         </p>
 276       </div>
 277     </div>
 278     <div class="NAVFOOTER">
 279       <hr align="LEFT" width="100%">
 280       <table summary="Footer navigation table" width="100%" border="0"
 281       cellpadding="0" cellspacing="0">
 282         <tr>
 283           <td width="33%" align="left" valign="top">
 284             <a href="startup.html" accesskey="P">Prev</a>
 285           </td>
 286           <td width="34%" align="center" valign="top">
 287             <a href="index.html" accesskey="H">Home</a>
 288           </td>
 289           <td width="33%" align="right" valign="top">
 290             <a href="config.html" accesskey="N">Next</a>
 291           </td>
 292         </tr>
 293         <tr>
 294           <td width="33%" align="left" valign="top">
 295             Starting Privoxy
 296           </td>
 297           <td width="34%" align="center" valign="top">
 298             &nbsp;
 299           </td>
 300           <td width="33%" align="right" valign="top">
 301             The Main Configuration File
 302           </td>
 303         </tr>
 304       </table>
 305     </div>
 306   </body>
 307 </html>
 308