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