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