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