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.7 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
21 <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css">
33 SUMMARY="Header navigation table"
42 >Privoxy 3.0.7 User Manual</TH
79 >4. Quickstart to Using Privoxy</A
91 HREF="installation.html"
92 >Installation Section</A
93 > below for platform specific
99 > Advanced users and those who want to offer <SPAN
103 service to more than just their local machine should check the <A
107 HREF="config.html#ACCESS-CONTROL"
108 >security-relevant</A
118 >, if the installation program has
119 not done this already (may vary according to platform). See the section
131 > Set your browser to use <SPAN
136 HREF="http://en.wikipedia.org/wiki/Proxy_server"
140 by setting the proxy configuration for address of
154 > activate proxying for <TT
158 any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
159 browser from using these protocols.
164 > Flush your browser's disk and memory caches, to remove any cached ad images.
170 HREF="http://en.wikipedia.org/wiki/Browser_cookie"
174 you should remove any currently stored cookies too.
179 > A default installation should provide a reasonable starting point for
180 most. There will undoubtedly be occasions where you will want to adjust the
181 configuration, but that can be dealt with as the need arises. Little
182 to no initial configuration is required in most cases, you may want
185 HREF="config.html#ENABLE-EDIT-ACTIONS"
187 >web-based action editor</A
189 Be sure to read the warnings first.
193 HREF="configuration.html"
194 >Configuration section</A
196 configuration options, and how to customize your installation.
197 You might also want to look at the <A
198 HREF="quickstart.html#QUICKSTART-AD-BLOCKING"
201 introduction to how <SPAN
209 > If you experience ads that slip through, innocent images that are
210 blocked, or otherwise feel the need to fine-tune
214 > behavior, take a look at the <A
215 HREF="actions-file.html"
217 >. As a quick start, you might
219 HREF="actions-file.html#ACT-EXAMPLES"
220 >richly commented examples</A
222 helpful. You can also view and edit the actions files through the <A
223 HREF="http://config.privoxy.org"
225 >web-based user interface</A
230 HREF="appendix.html#ACTIONSANAT"
231 >Troubleshooting: Anatomy of an
234 > has hints on how to understand and debug actions that
243 > Please see the section <A
247 > on how to report bugs, problems with websites or to get
253 > Now enjoy surfing with enhanced control, comfort and privacy!
263 NAME="QUICKSTART-AD-BLOCKING"
264 >4.1. Quickstart to Ad Blocking</A
267 > Ad blocking is but one of <SPAN
271 array of features. Many of these features are for the technically minded advanced
272 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
416 HREF="actions-file.html#BLOCK"
420 the single most used action, and is particularly important for ad blocking.
421 This action stops any contact between your browser and any URL patterns
422 that match this action's configuration. It can be used for blocking ads,
423 but also anything that is determined to be unwanted. By itself, it simply
424 stops any communication with the remote server and sends
428 >'s own built-in BLOCKED page instead to
429 let you now what has happened (with some exceptions, see below).
437 HREF="actions-file.html#HANDLE-AS-IMAGE"
444 > to treat this URL as an image.
448 >'s default configuration already does this
449 for all common image types (e.g. GIF), but there are many situations where this
450 is not so easy to determine. So we'll force it in these cases. This is particularly
451 important for ad blocking, since only if we know that it's an image of
452 some kind, can we replace it with an image of our choosing, instead of the
456 > BLOCKED page (which would only result in
459 >"broken image"</SPAN
460 > icon). There are some limitations to this
461 though. For instance, you can't just brute-force an image substitution for
462 an entire HTML page in most situations.
470 HREF="actions-file.html#HANDLE-AS-EMPTY-DOCUMENT"
471 >handle-as-empty-document</A
474 sends an empty document instead of <SPAN
478 normal BLOCKED HTML page. This is useful for file types that are neither
479 HTML nor images, such as blocking JavaScript files.
487 HREF="actions-file.html#SET-IMAGE-BLOCKER"
488 >set-image-blocker</A
494 > what to display in place of an ad image that
495 has hit a block rule. For this to come into play, the URL must match a
499 HREF="actions-file.html#BLOCK"
502 > action somewhere in the
509 >, it must also match an
513 HREF="actions-file.html#HANDLE-AS-IMAGE"
519 > The configuration options on what to display instead of the ad are:
534 > - a checkerboard pattern, so that an ad
535 replacement is obvious. This is the default.
555 > - A very small empty GIF image is displayed.
556 This is the so-called <SPAN
559 > configuration option.
577 >http://<URL></I
579 > - A redirect to any image anywhere
580 of the user's choosing (advanced usage).
591 > Advanced users will eventually want to explore <SPAN
598 HREF="actions-file.html#FILTER"
602 are very different from <TT
605 HREF="actions-file.html#BLOCK"
612 > blocks a site, page, or unwanted contented. Filters
613 are a way of filtering or modifying what is actually on the page. An example
614 filter usage: a text replacement of <SPAN
621 >. That is a very simple example. This process can be
622 used for ad blocking, but it is more in the realm of advanced usage and has
623 some pitfalls to be wary off.</P
625 > The quickest way to adjust any of these settings is with your browser through
630 HREF="http://config.privoxy.org/show-status"
632 >http://config.privoxy.org/show-status</A
637 >http://p.p/show-status</A
639 is an internal page, and does not require Internet access.</P
641 > Note that as of <SPAN
645 action editor is disabled by default. Check the
647 HREF="config.html#ENABLE-EDIT-ACTIONS"
650 section in the configuration file</A
651 > to learn why and in which
652 cases it's safe to enable again.</P
654 > If you decided to enable the action editor, select the appropriate
665 >. It is best to put personal or
666 local preferences in <TT
670 meant to be overwritten during upgrades, and will over-ride the settings in
671 other files. Here you can insert new <SPAN
675 blocking or other purposes, and make other adjustments to the configuration.
679 > will detect these changes automatically.</P
681 > A quick and simple step by step example:</P
688 > Right click on the ad image to be blocked, then select
693 >Copy Link Location</SPAN
701 > Set your browser to
703 HREF="http://config.privoxy.org/show-status"
705 >http://config.privoxy.org/show-status</A
714 > in the top section, and click
731 >Figure 1. Actions Files in Use</B
737 SRC="files-in-use.jpg"></P
745 > You should have a section with only
749 HREF="actions-file.html#BLOCK"
757 If not, click a <SPAN
761 >Insert new section below</SPAN
764 button, and in the new section that just appeared, click the
768 > button right under the word <SPAN
772 This will bring up a list of all actions. Find
776 HREF="actions-file.html#BLOCK"
779 > near the top, and click
798 HREF="actions-file.html#BLOCK"
808 > button, and paste the URL the
809 browser got from <SPAN
813 >Copy Link Location</SPAN
819 > at the beginning of the URL. Then, click
833 > if in a pop-up window).
838 > Now go back to the original page, and press <B
842 (or flush all browser caches). The image should be gone now.
848 > This is a very crude and simple example. There might be good reasons to use a
849 wildcard pattern match to include potentially similar images from the same
850 site. For a more extensive explanation of <SPAN
854 the entire actions concept, see <A
855 HREF="actions-file.html"
860 > For advanced users who want to hand edit their config files, you might want
862 HREF="actions-file.html#ACT-EXAMPLES"
863 >Actions Files Tutorial</A
865 The ideas explained therein also apply to the web-based editor.</P
867 > There are also various
869 HREF="actions-file.html#FILTER"
871 > that can be used for ad blocking
872 (filters are a special subset of actions). These
876 > usage category, and are explained in
877 depth in later sections. </P
885 SUMMARY="Footer navigation table"
924 >What's New in this Release</TD
934 >Starting Privoxy</TD