1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
2 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
5 <meta name="generator" content="HTML Tidy, see www.w3.org">
7 Quickstart to Using Privoxy
9 <meta name="GENERATOR" content=
10 "Modular DocBook HTML Stylesheet Version 1.79">
11 <link rel="HOME" title="Privoxy 3.0.18 User Manual" href="index.html">
12 <link rel="PREVIOUS" title="What's New in this Release" href=
14 <link rel="NEXT" title="Starting Privoxy" href="startup.html">
15 <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
16 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
17 <link rel="STYLESHEET" type="text/css" href="p_doc.css">
18 <style type="text/css">
20 background-color: #EEEEEE;
23 :link { color: #0000FF }
24 :visited { color: #840084 }
25 :active { color: #0000FF }
26 p.c2 {font-weight: bold}
27 hr.c1 {text-align: left}
31 <div class="NAVHEADER">
32 <table summary="Header navigation table" width="100%" border="0"
33 cellpadding="0" cellspacing="0">
35 <th colspan="3" align="center">
36 Privoxy 3.0.18 User Manual
40 <td width="10%" align="left" valign="bottom">
41 <a href="whatsnew.html" accesskey="P">Prev</a>
43 <td width="80%" align="center" valign="bottom">
45 <td width="10%" align="right" valign="bottom">
46 <a href="startup.html" accesskey="N">Next</a>
50 <hr width="100%" class="c1">
54 <a name="QUICKSTART">4. Quickstart to Using Privoxy</a>
61 Install <span class="APPLICATION">Privoxy</span>. See the <a
62 href="installation.html">Installation Section</a> below for
63 platform specific information.
68 Advanced users and those who want to offer <span class=
69 "APPLICATION">Privoxy</span> service to more than just their
70 local machine should check the <a href="config.html">main config
71 file</a>, especially the <a href=
72 "config.html#ACCESS-CONTROL">security-relevant</a> options. These
78 Start <span class="APPLICATION">Privoxy</span>, if the
79 installation program has not done this already (may vary
80 according to platform). See the section <a href=
81 "startup.html">Starting <span class=
82 "APPLICATION">Privoxy</span></a>.
87 Set your browser to use <span class="APPLICATION">Privoxy</span>
88 as HTTP and HTTPS (SSL) <a href=
89 "http://en.wikipedia.org/wiki/Proxy_server" target=
90 "_top">proxy</a> by setting the proxy configuration for address
91 of <tt class="LITERAL">127.0.0.1</tt> and port <tt class=
92 "LITERAL">8118</tt>. <span class="emphasis"><i class=
93 "EMPHASIS">DO NOT</i></span> activate proxying for <tt class=
94 "LITERAL">FTP</tt> or any protocols besides HTTP and HTTPS (SSL)
95 unless you intend to prevent your browser from using these
101 Flush your browser's disk and memory caches, to remove any cached
102 ad images. If using <span class="APPLICATION">Privoxy</span> to
103 manage <a href="http://en.wikipedia.org/wiki/Browser_cookie"
104 target="_top">cookies</a>, you should remove any currently stored
110 A default installation should provide a reasonable starting point
111 for most. There will undoubtedly be occasions where you will want
112 to adjust the configuration, but that can be dealt with as the
113 need arises. Little to no initial configuration is required in
114 most cases, you may want to enable the <a href=
115 "config.html#ENABLE-EDIT-ACTIONS" target="_top">web-based action
116 editor</a> though. Be sure to read the warnings first.
119 See the <a href="configuration.html">Configuration section</a>
120 for more configuration options, and how to customize your
121 installation. You might also want to look at the <a href=
122 "quickstart.html#QUICKSTART-AD-BLOCKING">next section</a> for a
123 quick introduction to how <span class=
124 "APPLICATION">Privoxy</span> blocks ads and banners.
129 If you experience ads that slip through, innocent images that are
130 blocked, or otherwise feel the need to fine-tune <span class=
131 "APPLICATION">Privoxy's</span> behavior, take a look at the <a
132 href="actions-file.html">actions files</a>. As a quick start, you
133 might find the <a href="actions-file.html#ACT-EXAMPLES">richly
134 commented examples</a> helpful. You can also view and edit the
135 actions files through the <a href="http://config.privoxy.org"
136 target="_top">web-based user interface</a>. The Appendix <span
137 class="QUOTE">"<a href=
138 "appendix.html#ACTIONSANAT">Troubleshooting: Anatomy of an
139 Action</a>"</span> has hints on how to understand and debug
140 actions that <span class="QUOTE">"misbehave"</span>.
145 Please see the section <a href="contact.html">Contacting the
146 Developers</a> on how to report bugs, problems with websites or
152 Now enjoy surfing with enhanced control, comfort and privacy!
159 <a name="QUICKSTART-AD-BLOCKING">4.1. Quickstart to Ad Blocking</a>
162 Ad blocking is but one of <span class=
163 "APPLICATION">Privoxy's</span> array of features. Many of these
164 features are for the technically minded advanced user. But, ad and
165 banner blocking is surely common ground for everybody.
168 This section will provide a quick summary of ad blocking so you can
169 get up to speed quickly without having to read the more extensive
170 information provided below, though this is highly recommended.
173 First a bit of a warning ... blocking ads is much like blocking
174 SPAM: the more aggressive you are about it, the more likely you are
175 to block things that were not intended. And the more likely that
176 some things may not work as intended. So there is a trade off here.
177 If you want extreme ad free browsing, be prepared to deal with more
178 <span class="QUOTE">"problem"</span> sites, and to spend more time
179 adjusting the configuration to solve these unintended consequences.
180 In short, there is not an easy way to eliminate <span class=
181 "emphasis"><i class="EMPHASIS">all</i></span> ads. Either take the
182 easy way and settle for <span class="emphasis"><i class=
183 "EMPHASIS">most</i></span> ads blocked with the default
184 configuration, or jump in and tweak it for your personal surfing
185 habits and preferences.
188 Secondly, a brief explanation of <span class=
189 "APPLICATION">Privoxy's</span> <span class=
190 "QUOTE">"actions"</span>. <span class="QUOTE">"Actions"</span> in
191 this context, are the directives we use to tell <span class=
192 "APPLICATION">Privoxy</span> to perform some task relating to HTTP
193 transactions (i.e. web browsing). We tell <span class=
194 "APPLICATION">Privoxy</span> to take some <span class=
195 "QUOTE">"action"</span>. Each action has a unique name and
196 function. While there are many potential <span class=
197 "APPLICATION">actions</span> in <span class=
198 "APPLICATION">Privoxy's</span> arsenal, only a few are used for ad
199 blocking. <a href="actions-file.html#ACTIONS">Actions</a>, and <a
200 href="actions-file.html">action configuration files</a>, are
201 explained in depth below.
204 Actions are specified in <span class="APPLICATION">Privoxy's</span>
205 configuration, followed by one or more URLs to which the action
206 should apply. URLs can actually be URL type <a href=
207 "actions-file.html#AF-PATTERNS">patterns</a> that use wildcards so
208 they can apply potentially to a range of similar URLs. The actions,
209 together with the URL patterns are called a section.
212 When you connect to a website, the full URL will either match one
213 or more of the sections as defined in <span class=
214 "APPLICATION">Privoxy's</span> configuration, or not. If so, then
215 <span class="APPLICATION">Privoxy</span> will perform the
216 respective actions. If not, then nothing special happens.
217 Furthermore, web pages may contain embedded, secondary URLs that
218 your web browser will use to load additional components of the
219 page, as it parses the original page's HTML content. An ad image
220 for instance, is just an URL embedded in the page somewhere. The
221 image itself may be on the same server, or a server somewhere else
222 on the Internet. Complex web pages will have many such embedded
223 URLs. <span class="APPLICATION">Privoxy</span> can deal with each
224 URL individually, so, for instance, the main page text is not
225 touched, but images from such-and-such server are blocked.
228 The most important actions for basic ad blocking are: <tt class=
229 "LITERAL"><a href="actions-file.html#BLOCK">block</a></tt>, <tt
230 class="LITERAL"><a href=
231 "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt>, <tt
232 class="LITERAL"><a href=
233 "actions-file.html#HANDLE-AS-EMPTY-DOCUMENT">handle-as-empty-document</a></tt>,and
234 <tt class="LITERAL"><a href=
235 "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a></tt>:
242 <tt class="LITERAL"><a href=
243 "actions-file.html#BLOCK">block</a></tt> - this is perhaps the
244 single most used action, and is particularly important for ad
245 blocking. This action stops any contact between your browser
246 and any URL patterns that match this action's configuration. It
247 can be used for blocking ads, but also anything that is
248 determined to be unwanted. By itself, it simply stops any
249 communication with the remote server and sends <span class=
250 "APPLICATION">Privoxy</span>'s own built-in BLOCKED page
251 instead to let you now what has happened (with some exceptions,
257 <tt class="LITERAL"><a href=
258 "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt> -
259 tells <span class="APPLICATION">Privoxy</span> to treat this
260 URL as an image. <span class="APPLICATION">Privoxy</span>'s
261 default configuration already does this for all common image
262 types (e.g. GIF), but there are many situations where this is
263 not so easy to determine. So we'll force it in these cases.
264 This is particularly important for ad blocking, since only if
265 we know that it's an image of some kind, can we replace it with
266 an image of our choosing, instead of the <span class=
267 "APPLICATION">Privoxy</span> BLOCKED page (which would only
268 result in a <span class="QUOTE">"broken image"</span> icon).
269 There are some limitations to this though. For instance, you
270 can't just brute-force an image substitution for an entire HTML
271 page in most situations.
276 <tt class="LITERAL"><a href=
277 "actions-file.html#HANDLE-AS-EMPTY-DOCUMENT">handle-as-empty-document</a></tt>
278 - sends an empty document instead of <span class=
279 "APPLICATION">Privoxy's</span> normal BLOCKED HTML page. This
280 is useful for file types that are neither HTML nor images, such
281 as blocking JavaScript files.
286 <tt class="LITERAL"><a href=
287 "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a></tt>
288 - tells <span class="APPLICATION">Privoxy</span> what to
289 display in place of an ad image that has hit a block rule. For
290 this to come into play, the URL must match a <tt class=
291 "LITERAL"><a href="actions-file.html#BLOCK">block</a></tt>
292 action somewhere in the configuration, <span class=
293 "emphasis"><i class="EMPHASIS">and</i></span>, it must also
294 match an <tt class="LITERAL"><a href=
295 "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt>
299 The configuration options on what to display instead of the ad
306 <span class="emphasis"><i class=
307 "EMPHASIS">pattern</i></span> - a checkerboard pattern,
308 so that an ad replacement is obvious. This is the
318 <span class="emphasis"><i class=
319 "EMPHASIS">blank</i></span> - A very small empty GIF
320 image is displayed. This is the so-called <span class=
321 "QUOTE">"invisible"</span> configuration option.
330 <span class="emphasis"><i class=
331 "EMPHASIS">http://<URL></i></span> - A redirect to
332 any image anywhere of the user's choosing (advanced
342 Advanced users will eventually want to explore <span class=
343 "APPLICATION">Privoxy</span> <tt class="LITERAL"><a href=
344 "actions-file.html#FILTER">filters</a></tt> as well. Filters are
345 very different from <tt class="LITERAL"><a href=
346 "actions-file.html#BLOCK">blocks</a></tt>. A <span class=
347 "QUOTE">"block"</span> blocks a site, page, or unwanted contented.
348 Filters are a way of filtering or modifying what is actually on the
349 page. An example filter usage: a text replacement of <span class=
350 "QUOTE">"no-no"</span> for <span class="QUOTE">"nasty-word"</span>.
351 That is a very simple example. This process can be used for ad
352 blocking, but it is more in the realm of advanced usage and has
353 some pitfalls to be wary off.
356 The quickest way to adjust any of these settings is with your
357 browser through the special <span class=
358 "APPLICATION">Privoxy</span> editor at <a href=
359 "http://config.privoxy.org/show-status" target=
360 "_top">http://config.privoxy.org/show-status</a> (shortcut: <a
361 href="http://p.p/" target="_top">http://p.p/show-status</a>). This
362 is an internal page, and does not require Internet access.
365 Note that as of <span class="APPLICATION">Privoxy</span> 3.0.7 beta
366 the action editor is disabled by default. Check the <a href=
367 "config.html#ENABLE-EDIT-ACTIONS" target="_top">enable-edit-actions
368 section in the configuration file</a> to learn why and in which
369 cases it's safe to enable again.
372 If you decided to enable the action editor, select the appropriate
373 <span class="QUOTE">"actions"</span> file, and click <span class=
374 "QUOTE">"<span class="GUIBUTTON">Edit</span>"</span>. It is best to
375 put personal or local preferences in <tt class=
376 "FILENAME">user.action</tt> since this is not meant to be
377 overwritten during upgrades, and will over-ride the settings in
378 other files. Here you can insert new <span class=
379 "QUOTE">"actions"</span>, and URLs for ad blocking or other
380 purposes, and make other adjustments to the configuration. <span
381 class="APPLICATION">Privoxy</span> will detect these changes
385 A quick and simple step by step example:
392 Right click on the ad image to be blocked, then select <span
393 class="QUOTE">"<span class="GUIMENUITEM">Copy Link
394 Location</span>"</span> from the pop-up menu.
399 Set your browser to <a href=
400 "http://config.privoxy.org/show-status" target=
401 "_top">http://config.privoxy.org/show-status</a>
406 Find <tt class="FILENAME">user.action</tt> in the top section,
407 and click on <span class="QUOTE">"<span class=
408 "GUIBUTTON">Edit</span>"</span>:
413 <a name="AEN687"></a>
415 Figure 1. Actions Files in Use
417 <div class="MEDIAOBJECT">
419 <img src="files-in-use.jpg">
426 You should have a section with only <tt class="LITERAL"><a
427 href="actions-file.html#BLOCK">block</a></tt> listed under
428 <span class="QUOTE">"Actions:"</span>. If not, click a <span
429 class="QUOTE">"<span class="GUIBUTTON">Insert new section
430 below</span>"</span> button, and in the new section that just
431 appeared, click the <span class="GUIBUTTON">Edit</span> button
432 right under the word <span class="QUOTE">"Actions:"</span>.
433 This will bring up a list of all actions. Find <tt class=
434 "LITERAL"><a href="actions-file.html#BLOCK">block</a></tt> near
435 the top, and click in the <span class="QUOTE">"Enabled"</span>
436 column, then <span class="QUOTE">"<span class=
437 "GUIBUTTON">Submit</span>"</span> just below the list.
442 Now, in the <tt class="LITERAL"><a href=
443 "actions-file.html#BLOCK">block</a></tt> actions section, click
444 the <span class="QUOTE">"<span class=
445 "GUIBUTTON">Add</span>"</span> button, and paste the URL the
446 browser got from <span class="QUOTE">"<span class=
447 "GUIMENUITEM">Copy Link Location</span>"</span>. Remove the <tt
448 class="LITERAL">http://</tt> at the beginning of the URL. Then,
449 click <span class="QUOTE">"<span class=
450 "GUIBUTTON">Submit</span>"</span> (or <span class=
451 "QUOTE">"<span class="GUIBUTTON">OK</span>"</span> if in a
457 Now go back to the original page, and press <b class=
458 "KEYCAP">SHIFT-Reload</b> (or flush all browser caches). The
459 image should be gone now.
465 This is a very crude and simple example. There might be good
466 reasons to use a wildcard pattern match to include potentially
467 similar images from the same site. For a more extensive explanation
468 of <span class="QUOTE">"patterns"</span>, and the entire actions
469 concept, see <a href="actions-file.html">the Actions section</a>.
472 For advanced users who want to hand edit their config files, you
473 might want to now go to the <a href=
474 "actions-file.html#ACT-EXAMPLES">Actions Files Tutorial</a>. The
475 ideas explained therein also apply to the web-based editor.
478 There are also various <a href=
479 "actions-file.html#FILTER">filters</a> that can be used for ad
480 blocking (filters are a special subset of actions). These fall into
481 the <span class="QUOTE">"advanced"</span> usage category, and are
482 explained in depth in later sections.
486 <div class="NAVFOOTER">
487 <hr width="100%" class="c1">
488 <table summary="Footer navigation table" width="100%" border="0"
489 cellpadding="0" cellspacing="0">
491 <td width="33%" align="left" valign="top">
492 <a href="whatsnew.html" accesskey="P">Prev</a>
494 <td width="34%" align="center" valign="top">
495 <a href="index.html" accesskey="H">Home</a>
497 <td width="33%" align="right" valign="top">
498 <a href="startup.html" accesskey="N">Next</a>
502 <td width="33%" align="left" valign="top">
503 What's New in this Release
505 <td width="34%" align="center" valign="top">
508 <td width="33%" align="right" valign="top">