1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
2 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
6 Quickstart to Using Privoxy
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=
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">
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">
24 <th colspan="3" align="center">
25 Privoxy 3.0.25 User Manual
29 <td width="10%" align="left" valign="bottom">
30 <a href="whatsnew.html" accesskey="P">Prev</a>
32 <td width="80%" align="center" valign="bottom">
34 <td width="10%" align="right" valign="bottom">
35 <a href="startup.html" accesskey="N">Next</a>
39 <hr align="LEFT" width="100%">
43 <a name="QUICKSTART">4. Quickstart to Using Privoxy</a>
50 Install <span class="APPLICATION">Privoxy</span>. See the <a
51 href="installation.html">Installation Section</a> below for
52 platform specific information.
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
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>.
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
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
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.
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.
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>.
134 Please see the section <a href="contact.html">Contacting the
135 Developers</a> on how to report bugs, problems with websites or
141 Now enjoy surfing with enhanced control, comfort and privacy!
148 <a name="QUICKSTART-AD-BLOCKING">4.1. Quickstart to Ad Blocking</a>
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.
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.
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.
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.
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.
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.
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>:
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,
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.
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.
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>
288 The configuration options on what to display instead of the ad
295 <span class="emphasis"><i class=
296 "EMPHASIS">pattern</i></span> - a checkerboard pattern,
297 so that an ad replacement is obvious. This is the
307 <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.
319 <span class="emphasis"><i class=
320 "EMPHASIS">http://<URL></i></span> - A redirect to
321 any image anywhere of the user's choosing (advanced
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.
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.
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.
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
374 A quick and simple step by step example:
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.
388 Set your browser to <a href=
389 "http://config.privoxy.org/show-status" target=
390 "_top">http://config.privoxy.org/show-status</a>
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>:
402 <a name="AEN612"></a>
404 <b>Figure 1. Actions Files in Use</b>
406 <div class="MEDIAOBJECT">
408 <img src="files-in-use.jpg">
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.
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
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.
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>.
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.
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.
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">
480 <td width="33%" align="left" valign="top">
481 <a href="whatsnew.html" accesskey="P">Prev</a>
483 <td width="34%" align="center" valign="top">
484 <a href="index.html" accesskey="H">Home</a>
486 <td width="33%" align="right" valign="top">
487 <a href="startup.html" accesskey="N">Next</a>
491 <td width="33%" align="left" valign="top">
492 What's New in this Release
494 <td width="34%" align="center" valign="top">
497 <td width="33%" align="right" valign="top">