doc/webserver/user-manual/quickstart.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       Quickstart to Using Privoxy
   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="What's New in this Release" href=
  13     "whatsnew.html">
  14     <link rel="NEXT" title="Starting Privoxy" href="startup.html">
  15     <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
  16     <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  17     <link rel="STYLESHEET" type="text/css" href="p_doc.css">
  18 <style type="text/css">
  19  body {
  20   background-color: #EEEEEE;
  21   color: #000000;
  22  }
  23  :link { color: #0000FF }
  24  :visited { color: #840084 }
  25  :active { color: #0000FF }
  26  p.c2 {font-weight: bold}
  27  hr.c1 {text-align: left}
  28 </style>
  29   </head>
  30   <body class="SECT1">
  31     <div class="NAVHEADER">
  32       <table summary="Header navigation table" width="100%" border="0"
  33       cellpadding="0" cellspacing="0">
  34         <tr>
  35           <th colspan="3" align="center">
  36             Privoxy 3.0.18 User Manual
  37           </th>
  38         </tr>
  39         <tr>
  40           <td width="10%" align="left" valign="bottom">
  41             <a href="whatsnew.html" accesskey="P">Prev</a>
  42           </td>
  43           <td width="80%" align="center" valign="bottom">
  44           </td>
  45           <td width="10%" align="right" valign="bottom">
  46             <a href="startup.html" accesskey="N">Next</a>
  47           </td>
  48         </tr>
  49       </table>
  50       <hr width="100%" class="c1">
  51     </div>
  52     <div class="SECT1">
  53       <h1 class="SECT1">
  54         <a name="QUICKSTART">4. Quickstart to Using Privoxy</a>
  55       </h1>
  56       <p>
  57       </p>
  58       <ul>
  59         <li>
  60           <p>
  61             Install <span class="APPLICATION">Privoxy</span>. See the <a
  62             href="installation.html">Installation Section</a> below for
  63             platform specific information.
  64           </p>
  65         </li>
  66         <li>
  67           <p>
  68             Advanced users and those who want to offer <span class=
  69             "APPLICATION">Privoxy</span> service to more than just their
  70             local machine should check the <a href="config.html">main config
  71             file</a>, especially the <a href=
  72             "config.html#ACCESS-CONTROL">security-relevant</a> options. These
  73             are off by default.
  74           </p>
  75         </li>
  76         <li>
  77           <p>
  78             Start <span class="APPLICATION">Privoxy</span>, if the
  79             installation program has not done this already (may vary
  80             according to platform). See the section <a href=
  81             "startup.html">Starting <span class=
  82             "APPLICATION">Privoxy</span></a>.
  83           </p>
  84         </li>
  85         <li>
  86           <p>
  87             Set your browser to use <span class="APPLICATION">Privoxy</span>
  88             as HTTP and HTTPS (SSL) <a href=
  89             "http://en.wikipedia.org/wiki/Proxy_server" target=
  90             "_top">proxy</a> by setting the proxy configuration for address
  91             of <tt class="LITERAL">127.0.0.1</tt> and port <tt class=
  92             "LITERAL">8118</tt>. <span class="emphasis"><i class=
  93             "EMPHASIS">DO NOT</i></span> activate proxying for <tt class=
  94             "LITERAL">FTP</tt> or any protocols besides HTTP and HTTPS (SSL)
  95             unless you intend to prevent your browser from using these
  96             protocols.
  97           </p>
  98         </li>
  99         <li>
 100           <p>
 101             Flush your browser's disk and memory caches, to remove any cached
 102             ad images. If using <span class="APPLICATION">Privoxy</span> to
 103             manage <a href="http://en.wikipedia.org/wiki/Browser_cookie"
 104             target="_top">cookies</a>, you should remove any currently stored
 105             cookies too.
 106           </p>
 107         </li>
 108         <li>
 109           <p>
 110             A default installation should provide a reasonable starting point
 111             for most. There will undoubtedly be occasions where you will want
 112             to adjust the configuration, but that can be dealt with as the
 113             need arises. Little to no initial configuration is required in
 114             most cases, you may want to enable the <a href=
 115             "config.html#ENABLE-EDIT-ACTIONS" target="_top">web-based action
 116             editor</a> though. Be sure to read the warnings first.
 117           </p>
 118           <p>
 119             See the <a href="configuration.html">Configuration section</a>
 120             for more configuration options, and how to customize your
 121             installation. You might also want to look at the <a href=
 122             "quickstart.html#QUICKSTART-AD-BLOCKING">next section</a> for a
 123             quick introduction to how <span class=
 124             "APPLICATION">Privoxy</span> blocks ads and banners.
 125           </p>
 126         </li>
 127         <li>
 128           <p>
 129             If you experience ads that slip through, innocent images that are
 130             blocked, or otherwise feel the need to fine-tune <span class=
 131             "APPLICATION">Privoxy's</span> behavior, take a look at the <a
 132             href="actions-file.html">actions files</a>. As a quick start, you
 133             might find the <a href="actions-file.html#ACT-EXAMPLES">richly
 134             commented examples</a> helpful. You can also view and edit the
 135             actions files through the <a href="http://config.privoxy.org"
 136             target="_top">web-based user interface</a>. The Appendix <span
 137             class="QUOTE">"<a href=
 138             "appendix.html#ACTIONSANAT">Troubleshooting: Anatomy of an
 139             Action</a>"</span> has hints on how to understand and debug
 140             actions that <span class="QUOTE">"misbehave"</span>.
 141           </p>
 142         </li>
 143         <li>
 144           <p>
 145             Please see the section <a href="contact.html">Contacting the
 146             Developers</a> on how to report bugs, problems with websites or
 147             to get help.
 148           </p>
 149         </li>
 150         <li>
 151           <p>
 152             Now enjoy surfing with enhanced control, comfort and privacy!
 153           </p>
 154         </li>
 155       </ul>
 156
 157       <div class="SECT2">
 158         <h2 class="SECT2">
 159           <a name="QUICKSTART-AD-BLOCKING">4.1. Quickstart to Ad Blocking</a>
 160         </h2>
 161         <p>
 162           Ad blocking is but one of <span class=
 163           "APPLICATION">Privoxy's</span> array of features. Many of these
 164           features are for the technically minded advanced user. But, ad and
 165           banner blocking is surely common ground for everybody.
 166         </p>
 167         <p>
 168           This section will provide a quick summary of ad blocking so you can
 169           get up to speed quickly without having to read the more extensive
 170           information provided below, though this is highly recommended.
 171         </p>
 172         <p>
 173           First a bit of a warning ... blocking ads is much like blocking
 174           SPAM: the more aggressive you are about it, the more likely you are
 175           to block things that were not intended. And the more likely that
 176           some things may not work as intended. So there is a trade off here.
 177           If you want extreme ad free browsing, be prepared to deal with more
 178           <span class="QUOTE">"problem"</span> sites, and to spend more time
 179           adjusting the configuration to solve these unintended consequences.
 180           In short, there is not an easy way to eliminate <span class=
 181           "emphasis"><i class="EMPHASIS">all</i></span> ads. Either take the
 182           easy way and settle for <span class="emphasis"><i class=
 183           "EMPHASIS">most</i></span> ads blocked with the default
 184           configuration, or jump in and tweak it for your personal surfing
 185           habits and preferences.
 186         </p>
 187         <p>
 188           Secondly, a brief explanation of <span class=
 189           "APPLICATION">Privoxy's</span> <span class=
 190           "QUOTE">"actions"</span>. <span class="QUOTE">"Actions"</span> in
 191           this context, are the directives we use to tell <span class=
 192           "APPLICATION">Privoxy</span> to perform some task relating to HTTP
 193           transactions (i.e. web browsing). We tell <span class=
 194           "APPLICATION">Privoxy</span> to take some <span class=
 195           "QUOTE">"action"</span>. Each action has a unique name and
 196           function. While there are many potential <span class=
 197           "APPLICATION">actions</span> in <span class=
 198           "APPLICATION">Privoxy's</span> arsenal, only a few are used for ad
 199           blocking. <a href="actions-file.html#ACTIONS">Actions</a>, and <a
 200           href="actions-file.html">action configuration files</a>, are
 201           explained in depth below.
 202         </p>
 203         <p>
 204           Actions are specified in <span class="APPLICATION">Privoxy's</span>
 205           configuration, followed by one or more URLs to which the action
 206           should apply. URLs can actually be URL type <a href=
 207           "actions-file.html#AF-PATTERNS">patterns</a> that use wildcards so
 208           they can apply potentially to a range of similar URLs. The actions,
 209           together with the URL patterns are called a section.
 210         </p>
 211         <p>
 212           When you connect to a website, the full URL will either match one
 213           or more of the sections as defined in <span class=
 214           "APPLICATION">Privoxy's</span> configuration, or not. If so, then
 215           <span class="APPLICATION">Privoxy</span> will perform the
 216           respective actions. If not, then nothing special happens.
 217           Furthermore, web pages may contain embedded, secondary URLs that
 218           your web browser will use to load additional components of the
 219           page, as it parses the original page's HTML content. An ad image
 220           for instance, is just an URL embedded in the page somewhere. The
 221           image itself may be on the same server, or a server somewhere else
 222           on the Internet. Complex web pages will have many such embedded
 223           URLs. <span class="APPLICATION">Privoxy</span> can deal with each
 224           URL individually, so, for instance, the main page text is not
 225           touched, but images from such-and-such server are blocked.
 226         </p>
 227         <p>
 228           The most important actions for basic ad blocking are: <tt class=
 229           "LITERAL"><a href="actions-file.html#BLOCK">block</a></tt>, <tt
 230           class="LITERAL"><a href=
 231           "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt>, <tt
 232           class="LITERAL"><a href=
 233           "actions-file.html#HANDLE-AS-EMPTY-DOCUMENT">handle-as-empty-document</a></tt>,and
 234           <tt class="LITERAL"><a href=
 235           "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a></tt>:
 236         </p>
 237         <p>
 238         </p>
 239         <ul>
 240           <li>
 241             <p>
 242               <tt class="LITERAL"><a href=
 243               "actions-file.html#BLOCK">block</a></tt> - this is perhaps the
 244               single most used action, and is particularly important for ad
 245               blocking. This action stops any contact between your browser
 246               and any URL patterns that match this action's configuration. It
 247               can be used for blocking ads, but also anything that is
 248               determined to be unwanted. By itself, it simply stops any
 249               communication with the remote server and sends <span class=
 250               "APPLICATION">Privoxy</span>'s own built-in BLOCKED page
 251               instead to let you now what has happened (with some exceptions,
 252               see below).
 253             </p>
 254           </li>
 255           <li>
 256             <p>
 257               <tt class="LITERAL"><a href=
 258               "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt> -
 259               tells <span class="APPLICATION">Privoxy</span> to treat this
 260               URL as an image. <span class="APPLICATION">Privoxy</span>'s
 261               default configuration already does this for all common image
 262               types (e.g. GIF), but there are many situations where this is
 263               not so easy to determine. So we'll force it in these cases.
 264               This is particularly important for ad blocking, since only if
 265               we know that it's an image of some kind, can we replace it with
 266               an image of our choosing, instead of the <span class=
 267               "APPLICATION">Privoxy</span> BLOCKED page (which would only
 268               result in a <span class="QUOTE">"broken image"</span> icon).
 269               There are some limitations to this though. For instance, you
 270               can't just brute-force an image substitution for an entire HTML
 271               page in most situations.
 272             </p>
 273           </li>
 274           <li>
 275             <p>
 276               <tt class="LITERAL"><a href=
 277               "actions-file.html#HANDLE-AS-EMPTY-DOCUMENT">handle-as-empty-document</a></tt>
 278               - sends an empty document instead of <span class=
 279               "APPLICATION">Privoxy's</span> normal BLOCKED HTML page. This
 280               is useful for file types that are neither HTML nor images, such
 281               as blocking JavaScript files.
 282             </p>
 283           </li>
 284           <li>
 285             <p>
 286               <tt class="LITERAL"><a href=
 287               "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a></tt>
 288               - tells <span class="APPLICATION">Privoxy</span> what to
 289               display in place of an ad image that has hit a block rule. For
 290               this to come into play, the URL must match a <tt class=
 291               "LITERAL"><a href="actions-file.html#BLOCK">block</a></tt>
 292               action somewhere in the configuration, <span class=
 293               "emphasis"><i class="EMPHASIS">and</i></span>, it must also
 294               match an <tt class="LITERAL"><a href=
 295               "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt>
 296               action.
 297             </p>
 298             <p>
 299               The configuration options on what to display instead of the ad
 300               are:
 301             </p>
 302             <table border="0">
 303               <tbody>
 304                 <tr>
 305                   <td>
 306                     &nbsp;&nbsp;&nbsp;<span class="emphasis"><i class=
 307                     "EMPHASIS">pattern</i></span> - a checkerboard pattern,
 308                     so that an ad replacement is obvious. This is the
 309                     default.
 310                   </td>
 311                 </tr>
 312               </tbody>
 313             </table>
 314             <table border="0">
 315               <tbody>
 316                 <tr>
 317                   <td>
 318                     &nbsp;&nbsp;&nbsp;<span class="emphasis"><i class=
 319                     "EMPHASIS">blank</i></span> - A very small empty GIF
 320                     image is displayed. This is the so-called <span class=
 321                     "QUOTE">"invisible"</span> configuration option.
 322                   </td>
 323                 </tr>
 324               </tbody>
 325             </table>
 326             <table border="0">
 327               <tbody>
 328                 <tr>
 329                   <td>
 330                     &nbsp;&nbsp;&nbsp;<span class="emphasis"><i class=
 331                     "EMPHASIS">http://&lt;URL&gt;</i></span> - A redirect to
 332                     any image anywhere of the user's choosing (advanced
 333                     usage).
 334                   </td>
 335                 </tr>
 336               </tbody>
 337             </table>
 338           </li>
 339         </ul>
 340
 341         <p>
 342           Advanced users will eventually want to explore <span class=
 343           "APPLICATION">Privoxy</span> <tt class="LITERAL"><a href=
 344           "actions-file.html#FILTER">filters</a></tt> as well. Filters are
 345           very different from <tt class="LITERAL"><a href=
 346           "actions-file.html#BLOCK">blocks</a></tt>. A <span class=
 347           "QUOTE">"block"</span> blocks a site, page, or unwanted contented.
 348           Filters are a way of filtering or modifying what is actually on the
 349           page. An example filter usage: a text replacement of <span class=
 350           "QUOTE">"no-no"</span> for <span class="QUOTE">"nasty-word"</span>.
 351           That is a very simple example. This process can be used for ad
 352           blocking, but it is more in the realm of advanced usage and has
 353           some pitfalls to be wary off.
 354         </p>
 355         <p>
 356           The quickest way to adjust any of these settings is with your
 357           browser through the special <span class=
 358           "APPLICATION">Privoxy</span> editor at <a href=
 359           "http://config.privoxy.org/show-status" target=
 360           "_top">http://config.privoxy.org/show-status</a> (shortcut: <a
 361           href="http://p.p/" target="_top">http://p.p/show-status</a>). This
 362           is an internal page, and does not require Internet access.
 363         </p>
 364         <p>
 365           Note that as of <span class="APPLICATION">Privoxy</span> 3.0.7 beta
 366           the action editor is disabled by default. Check the <a href=
 367           "config.html#ENABLE-EDIT-ACTIONS" target="_top">enable-edit-actions
 368           section in the configuration file</a> to learn why and in which
 369           cases it's safe to enable again.
 370         </p>
 371         <p>
 372           If you decided to enable the action editor, select the appropriate
 373           <span class="QUOTE">"actions"</span> file, and click <span class=
 374           "QUOTE">"<span class="GUIBUTTON">Edit</span>"</span>. It is best to
 375           put personal or local preferences in <tt class=
 376           "FILENAME">user.action</tt> since this is not meant to be
 377           overwritten during upgrades, and will over-ride the settings in
 378           other files. Here you can insert new <span class=
 379           "QUOTE">"actions"</span>, and URLs for ad blocking or other
 380           purposes, and make other adjustments to the configuration. <span
 381           class="APPLICATION">Privoxy</span> will detect these changes
 382           automatically.
 383         </p>
 384         <p>
 385           A quick and simple step by step example:
 386         </p>
 387         <p>
 388         </p>
 389         <ul>
 390           <li>
 391             <p>
 392               Right click on the ad image to be blocked, then select <span
 393               class="QUOTE">"<span class="GUIMENUITEM">Copy Link
 394               Location</span>"</span> from the pop-up menu.
 395             </p>
 396           </li>
 397           <li>
 398             <p>
 399               Set your browser to <a href=
 400               "http://config.privoxy.org/show-status" target=
 401               "_top">http://config.privoxy.org/show-status</a>
 402             </p>
 403           </li>
 404           <li>
 405             <p>
 406               Find <tt class="FILENAME">user.action</tt> in the top section,
 407               and click on <span class="QUOTE">"<span class=
 408               "GUIBUTTON">Edit</span>"</span>:
 409             </p>
 410             <p>
 411             </p>
 412             <div class="FIGURE">
 413               <a name="AEN687"></a>
 414               <p class="c2">
 415                 Figure 1. Actions Files in Use
 416               </p>
 417               <div class="MEDIAOBJECT">
 418                 <p>
 419                   <img src="files-in-use.jpg">
 420                 </p>
 421               </div>
 422             </div>
 423           </li>
 424           <li>
 425             <p>
 426               You should have a section with only <tt class="LITERAL"><a
 427               href="actions-file.html#BLOCK">block</a></tt> listed under
 428               <span class="QUOTE">"Actions:"</span>. If not, click a <span
 429               class="QUOTE">"<span class="GUIBUTTON">Insert new section
 430               below</span>"</span> button, and in the new section that just
 431               appeared, click the <span class="GUIBUTTON">Edit</span> button
 432               right under the word <span class="QUOTE">"Actions:"</span>.
 433               This will bring up a list of all actions. Find <tt class=
 434               "LITERAL"><a href="actions-file.html#BLOCK">block</a></tt> near
 435               the top, and click in the <span class="QUOTE">"Enabled"</span>
 436               column, then <span class="QUOTE">"<span class=
 437               "GUIBUTTON">Submit</span>"</span> just below the list.
 438             </p>
 439           </li>
 440           <li>
 441             <p>
 442               Now, in the <tt class="LITERAL"><a href=
 443               "actions-file.html#BLOCK">block</a></tt> actions section, click
 444               the <span class="QUOTE">"<span class=
 445               "GUIBUTTON">Add</span>"</span> button, and paste the URL the
 446               browser got from <span class="QUOTE">"<span class=
 447               "GUIMENUITEM">Copy Link Location</span>"</span>. Remove the <tt
 448               class="LITERAL">http://</tt> at the beginning of the URL. Then,
 449               click <span class="QUOTE">"<span class=
 450               "GUIBUTTON">Submit</span>"</span> (or <span class=
 451               "QUOTE">"<span class="GUIBUTTON">OK</span>"</span> if in a
 452               pop-up window).
 453             </p>
 454           </li>
 455           <li>
 456             <p>
 457               Now go back to the original page, and press <b class=
 458               "KEYCAP">SHIFT-Reload</b> (or flush all browser caches). The
 459               image should be gone now.
 460             </p>
 461           </li>
 462         </ul>
 463
 464         <p>
 465           This is a very crude and simple example. There might be good
 466           reasons to use a wildcard pattern match to include potentially
 467           similar images from the same site. For a more extensive explanation
 468           of <span class="QUOTE">"patterns"</span>, and the entire actions
 469           concept, see <a href="actions-file.html">the Actions section</a>.
 470         </p>
 471         <p>
 472           For advanced users who want to hand edit their config files, you
 473           might want to now go to the <a href=
 474           "actions-file.html#ACT-EXAMPLES">Actions Files Tutorial</a>. The
 475           ideas explained therein also apply to the web-based editor.
 476         </p>
 477         <p>
 478           There are also various <a href=
 479           "actions-file.html#FILTER">filters</a> that can be used for ad
 480           blocking (filters are a special subset of actions). These fall into
 481           the <span class="QUOTE">"advanced"</span> usage category, and are
 482           explained in depth in later sections.
 483         </p>
 484       </div>
 485     </div>
 486     <div class="NAVFOOTER">
 487       <hr width="100%" class="c1">
 488       <table summary="Footer navigation table" width="100%" border="0"
 489       cellpadding="0" cellspacing="0">
 490         <tr>
 491           <td width="33%" align="left" valign="top">
 492             <a href="whatsnew.html" accesskey="P">Prev</a>
 493           </td>
 494           <td width="34%" align="center" valign="top">
 495             <a href="index.html" accesskey="H">Home</a>
 496           </td>
 497           <td width="33%" align="right" valign="top">
 498             <a href="startup.html" accesskey="N">Next</a>
 499           </td>
 500         </tr>
 501         <tr>
 502           <td width="33%" align="left" valign="top">
 503             What's New in this Release
 504           </td>
 505           <td width="34%" align="center" valign="top">
 506             &nbsp;
 507           </td>
 508           <td width="33%" align="right" valign="top">
 509             Starting Privoxy
 510           </td>
 511         </tr>
 512       </table>
 513     </div>
 514   </body>
 515 </html>
 516