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