1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
6 <meta name="generator" content=
7 "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
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=
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">
21 background-color: #EEEEEE;
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}
34 <div class="NAVHEADER">
35 <table summary="Header navigation table" width="100%" border="0"
36 cellpadding="0" cellspacing="0">
38 <th colspan="3" align="center">Privoxy 3.0.18 User Manual</th>
42 <td width="10%" align="left" valign="bottom"><a href="whatsnew.html"
43 accesskey="P">Prev</a></td>
45 <td width="80%" align="center" valign="bottom"></td>
47 <td width="10%" align="right" valign="bottom"><a href="startup.html"
48 accesskey="N">Next</a></td>
51 <hr class="c1" width="100%">
55 <h1 class="SECT1"><a name="QUICKSTART" id="QUICKSTART">4. Quickstart to
56 Using Privoxy</a></h1>
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>
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
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>
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
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
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
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
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>
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
139 <p>Now enjoy surfing with enhanced control, comfort and privacy!</p>
144 <h2 class="SECT2"><a name="QUICKSTART-AD-BLOCKING" id=
145 "QUICKSTART-AD-BLOCKING">4.1. Quickstart to Ad Blocking</a></h2>
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>
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>
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>
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>
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>
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>
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=
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>
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>
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>
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>
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>
264 <p>The configuration options on what to display instead of the ad
270 <td> <span class=
271 "emphasis EMPHASIS c2">pattern</span> - a checkerboard
272 pattern, so that an ad replacement is obvious. This is the
281 <td> <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>
292 <td> <span class=
293 "emphasis EMPHASIS c2">http://<URL></span> - A redirect
294 to any image anywhere of the user's choosing (advanced
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>
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>
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>
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
339 <p>A quick and simple step by step example:</p>
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>
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>
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>
360 <a name="AEN828" id="AEN828"></a>
362 <p class="c3">Figure 1. Actions Files in Use</p>
364 <div class="MEDIAOBJECT">
365 <p><img src="files-in-use.jpg"></p>
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>
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>
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>
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>
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>
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>
424 <div class="NAVFOOTER">
425 <hr class="c1" width="100%">
427 <table summary="Footer navigation table" width="100%" border="0"
428 cellpadding="0" cellspacing="0">
430 <td width="33%" align="left" valign="top"><a href="whatsnew.html"
431 accesskey="P">Prev</a></td>
433 <td width="34%" align="center" valign="top"><a href="index.html"
434 accesskey="H">Home</a></td>
436 <td width="33%" align="right" valign="top"><a href="startup.html"
437 accesskey="N">Next</a></td>
441 <td width="33%" align="left" valign="top">What's New in this
444 <td width="34%" align="center" valign="top"> </td>
446 <td width="33%" align="right" valign="top">Starting Privoxy</td>