1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
5 >Quickstart to Using Privoxy</TITLE
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
10 TITLE="Privoxy 3.0.27 User Manual"
11 HREF="index.html"><LINK
13 TITLE="What's New in this Release"
14 HREF="whatsnew.html"><LINK
16 TITLE="Starting Privoxy"
17 HREF="startup.html"><LINK
20 HREF="../p_doc.css"><META
21 HTTP-EQUIV="Content-Type"
24 <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css">
36 SUMMARY="Header navigation table"
45 >Privoxy 3.0.27 User Manual</TH
82 >4. Quickstart to Using Privoxy</A
93 HREF="installation.html"
94 >Installation Section</A
95 > below for platform specific
101 > Advanced users and those who want to offer <SPAN
105 service to more than just their local machine should check the <A
109 HREF="config.html#ACCESS-CONTROL"
110 >security-relevant</A
120 >, if the installation program has
121 not done this already (may vary according to platform). See the section
133 > Set your browser to use <SPAN
138 HREF="http://en.wikipedia.org/wiki/Proxy_server"
142 by setting the proxy configuration for address of
156 > activate proxying for <TT
160 any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
161 browser from using these protocols.
166 > Flush your browser's disk and memory caches, to remove any cached ad images.
172 HREF="http://en.wikipedia.org/wiki/Browser_cookie"
176 you should remove any currently stored cookies too.
181 > A default installation should provide a reasonable starting point for
182 most. There will undoubtedly be occasions where you will want to adjust the
183 configuration, but that can be dealt with as the need arises. Little
184 to no initial configuration is required in most cases, you may want
187 HREF="config.html#ENABLE-EDIT-ACTIONS"
189 >web-based action editor</A
191 Be sure to read the warnings first.
195 HREF="configuration.html"
196 >Configuration section</A
198 configuration options, and how to customize your installation.
199 You might also want to look at the <A
200 HREF="quickstart.html#QUICKSTART-AD-BLOCKING"
203 introduction to how <SPAN
211 > If you experience ads that slip through, innocent images that are
212 blocked, or otherwise feel the need to fine-tune
216 > behavior, take a look at the <A
217 HREF="actions-file.html"
219 >. As a quick start, you might
221 HREF="actions-file.html#ACT-EXAMPLES"
222 >richly commented examples</A
224 helpful. You can also view and edit the actions files through the <A
225 HREF="http://config.privoxy.org"
227 >web-based user interface</A
232 HREF="appendix.html#ACTIONSANAT"
233 >Troubleshooting: Anatomy of an
236 > has hints on how to understand and debug actions that
245 > Please see the section <A
249 > on how to report bugs, problems with websites or to get
255 > Now enjoy surfing with enhanced control, comfort and privacy!
264 NAME="QUICKSTART-AD-BLOCKING"
265 >4.1. Quickstart to Ad Blocking</A
268 > Ad blocking is but one of <SPAN
272 array of features. Many of these features are for the technically minded advanced
273 user. But, ad and banner blocking is surely common ground for everybody.</P
275 > This section will provide a quick summary of ad blocking so
276 you can get up to speed quickly without having to read the more extensive
277 information provided below, though this is highly recommended.</P
279 > First a bit of a warning ... blocking ads is much like blocking SPAM: the
280 more aggressive you are about it, the more likely you are to block
281 things that were not intended. And the more likely that some things
282 may not work as intended. So there is a trade off here. If you want
283 extreme ad free browsing, be prepared to deal with more
287 > sites, and to spend more time adjusting the
288 configuration to solve these unintended consequences. In short, there is
289 not an easy way to eliminate <SPAN
296 the easy way and settle for <SPAN
302 > ads blocked with the
303 default configuration, or jump in and tweak it for your personal surfing
304 habits and preferences.</P
306 > Secondly, a brief explanation of <SPAN
316 > in this context, are
317 the directives we use to tell <SPAN
321 some task relating to HTTP transactions (i.e. web browsing). We tell
329 action has a unique name and function. While there are many potential
337 arsenal, only a few are used for ad blocking. <A
338 HREF="actions-file.html#ACTIONS"
341 HREF="actions-file.html"
343 configuration files</A
344 >, are explained in depth below.</P
346 > Actions are specified in <SPAN
350 followed by one or more URLs to which the action should apply. URLs
351 can actually be URL type <A
352 HREF="actions-file.html#AF-PATTERNS"
355 wildcards so they can apply potentially to a range of similar URLs. The
356 actions, together with the URL patterns are called a section.</P
358 > When you connect to a website, the full URL will either match one or more
359 of the sections as defined in <SPAN
363 or not. If so, then <SPAN
367 respective actions. If not, then nothing special happens. Furthermore, web
368 pages may contain embedded, secondary URLs that your web browser will
369 use to load additional components of the page, as it parses the
370 original page's HTML content. An ad image for instance, is just an URL
371 embedded in the page somewhere. The image itself may be on the same server,
372 or a server somewhere else on the Internet. Complex web pages will have many
373 such embedded URLs. <SPAN
376 > can deal with each URL individually, so, for
377 instance, the main page text is not touched, but images from such-and-such
378 server are blocked.</P
380 > The most important actions for basic ad blocking are: <TT
383 HREF="actions-file.html#BLOCK"
389 HREF="actions-file.html#HANDLE-AS-IMAGE"
396 HREF="actions-file.html#HANDLE-AS-EMPTY-DOCUMENT"
397 >handle-as-empty-document</A
403 HREF="actions-file.html#SET-IMAGE-BLOCKER"
404 >set-image-blocker</A
415 HREF="actions-file.html#BLOCK"
419 the single most used action, and is particularly important for ad blocking.
420 This action stops any contact between your browser and any URL patterns
421 that match this action's configuration. It can be used for blocking ads,
422 but also anything that is determined to be unwanted. By itself, it simply
423 stops any communication with the remote server and sends
427 >'s own built-in BLOCKED page instead to
428 let you now what has happened (with some exceptions, see below).
436 HREF="actions-file.html#HANDLE-AS-IMAGE"
443 > to treat this URL as an image.
447 >'s default configuration already does this
448 for all common image types (e.g. GIF), but there are many situations where this
449 is not so easy to determine. So we'll force it in these cases. This is particularly
450 important for ad blocking, since only if we know that it's an image of
451 some kind, can we replace it with an image of our choosing, instead of the
455 > BLOCKED page (which would only result in
458 >"broken image"</SPAN
459 > icon). There are some limitations to this
460 though. For instance, you can't just brute-force an image substitution for
461 an entire HTML page in most situations.
469 HREF="actions-file.html#HANDLE-AS-EMPTY-DOCUMENT"
470 >handle-as-empty-document</A
473 sends an empty document instead of <SPAN
477 normal BLOCKED HTML page. This is useful for file types that are neither
478 HTML nor images, such as blocking JavaScript files.
486 HREF="actions-file.html#SET-IMAGE-BLOCKER"
487 >set-image-blocker</A
493 > what to display in place of an ad image that
494 has hit a block rule. For this to come into play, the URL must match a
498 HREF="actions-file.html#BLOCK"
501 > action somewhere in the
508 >, it must also match an
512 HREF="actions-file.html#HANDLE-AS-IMAGE"
518 > The configuration options on what to display instead of the ad are:
533 > - a checkerboard pattern, so that an ad
534 replacement is obvious. This is the default.
554 > - A very small empty GIF image is displayed.
555 This is the so-called <SPAN
558 > configuration option.
576 >http://<URL></I
578 > - A redirect to any image anywhere
579 of the user's choosing (advanced usage).
589 > Advanced users will eventually want to explore <SPAN
596 HREF="actions-file.html#FILTER"
600 are very different from <TT
603 HREF="actions-file.html#BLOCK"
610 > blocks a site, page, or unwanted contented. Filters
611 are a way of filtering or modifying what is actually on the page. An example
612 filter usage: a text replacement of <SPAN
619 >. That is a very simple example. This process can be
620 used for ad blocking, but it is more in the realm of advanced usage and has
621 some pitfalls to be wary off.</P
623 > The quickest way to adjust any of these settings is with your browser through
628 HREF="http://config.privoxy.org/show-status"
630 >http://config.privoxy.org/show-status</A
635 >http://p.p/show-status</A
637 is an internal page, and does not require Internet access.</P
639 > Note that as of <SPAN
643 action editor is disabled by default. Check the
645 HREF="config.html#ENABLE-EDIT-ACTIONS"
648 section in the configuration file</A
649 > to learn why and in which
650 cases it's safe to enable again.</P
652 > If you decided to enable the action editor, select the appropriate
663 >. It is best to put personal or
664 local preferences in <TT
668 meant to be overwritten during upgrades, and will over-ride the settings in
669 other files. Here you can insert new <SPAN
673 blocking or other purposes, and make other adjustments to the configuration.
677 > will detect these changes automatically.</P
679 > A quick and simple step by step example:</P
685 > Right click on the ad image to be blocked, then select
690 >Copy Link Location</SPAN
698 > Set your browser to
700 HREF="http://config.privoxy.org/show-status"
702 >http://config.privoxy.org/show-status</A
711 > in the top section, and click
727 >Figure 1. Actions Files in Use</B
733 SRC="files-in-use.jpg"></P
739 > You should have a section with only
743 HREF="actions-file.html#BLOCK"
751 If not, click a <SPAN
755 >Insert new section below</SPAN
758 button, and in the new section that just appeared, click the
762 > button right under the word <SPAN
766 This will bring up a list of all actions. Find
770 HREF="actions-file.html#BLOCK"
773 > near the top, and click
792 HREF="actions-file.html#BLOCK"
802 > button, and paste the URL the
803 browser got from <SPAN
807 >Copy Link Location</SPAN
813 > at the beginning of the URL. Then, click
827 > if in a pop-up window).
832 > Now go back to the original page, and press <B
836 (or flush all browser caches). The image should be gone now.
841 > This is a very crude and simple example. There might be good reasons to use a
842 wildcard pattern match to include potentially similar images from the same
843 site. For a more extensive explanation of <SPAN
847 the entire actions concept, see <A
848 HREF="actions-file.html"
853 > For advanced users who want to hand edit their config files, you might want
855 HREF="actions-file.html#ACT-EXAMPLES"
856 >Actions Files Tutorial</A
858 The ideas explained therein also apply to the web-based editor.</P
860 > There are also various
862 HREF="actions-file.html#FILTER"
864 > that can be used for ad blocking
865 (filters are a special subset of actions). These
869 > usage category, and are explained in
870 depth in later sections.</P
878 SUMMARY="Footer navigation table"
917 >What's New in this Release</TD
927 >Starting Privoxy</TD