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