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