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