Just regenerating to get fresh version in place of very dated versions.
[privoxy.git] / doc / webserver / user-manual / quickstart.html
1 <HTML
2 ><HEAD
3 ><TITLE
4 >Quickstart to Using Privoxy</TITLE
5 ><META
6 NAME="GENERATOR"
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
8 "><LINK
9 REL="HOME"
10 TITLE="Privoxy 3.1.1 User Manual"
11 HREF="index.html"><LINK
12 REL="PREVIOUS"
13 TITLE="Note to Upgraders"
14 HREF="upgradersnote.html"><LINK
15 REL="NEXT"
16 TITLE="Starting Privoxy"
17 HREF="startup.html"><LINK
18 REL="STYLESHEET"
19 TYPE="text/css"
20 HREF="../p_doc.css"></HEAD
21 ><BODY
22 CLASS="SECT1"
23 BGCOLOR="#EEEEEE"
24 TEXT="#000000"
25 LINK="#0000FF"
26 VLINK="#840084"
27 ALINK="#0000FF"
28 ><DIV
29 CLASS="NAVHEADER"
30 ><TABLE
31 SUMMARY="Header navigation table"
32 WIDTH="100%"
33 BORDER="0"
34 CELLPADDING="0"
35 CELLSPACING="0"
36 ><TR
37 ><TH
38 COLSPAN="3"
39 ALIGN="center"
40 >Privoxy 3.1.1 User Manual</TH
41 ></TR
42 ><TR
43 ><TD
44 WIDTH="10%"
45 ALIGN="left"
46 VALIGN="bottom"
47 ><A
48 HREF="upgradersnote.html"
49 ACCESSKEY="P"
50 >Prev</A
51 ></TD
52 ><TD
53 WIDTH="80%"
54 ALIGN="center"
55 VALIGN="bottom"
56 ></TD
57 ><TD
58 WIDTH="10%"
59 ALIGN="right"
60 VALIGN="bottom"
61 ><A
62 HREF="startup.html"
63 ACCESSKEY="N"
64 >Next</A
65 ></TD
66 ></TR
67 ></TABLE
68 ><HR
69 ALIGN="LEFT"
70 WIDTH="100%"></DIV
71 ><DIV
72 CLASS="SECT1"
73 ><H1
74 CLASS="SECT1"
75 ><A
76 NAME="QUICKSTART">4. Quickstart to Using <SPAN
77 CLASS="APPLICATION"
78 >Privoxy</SPAN
79 ></H1
80 ><P
81 > <P
82 ></P
83 ><UL
84 ><LI
85 ><P
86 >   If upgrading, from versions before 2.9.16, please back up any configuration
87    files. See the <A
88 HREF="upgradersnote.html"
89 >Note to Upgraders</A
90 > Section.
91  </P
92 ></LI
93 ><LI
94 ><P
95 >  Install <SPAN
96 CLASS="APPLICATION"
97 >Privoxy</SPAN
98 >. See the <A
99 HREF="installation.html"
100 >Installation Section</A
101 > below for platform specific
102   information. 
103  </P
104 ></LI
105 ><LI
106 ><P
107 >   Advanced users and those who want to offer <SPAN
108 CLASS="APPLICATION"
109 >Privoxy</SPAN
110 >
111    service to more than just their local machine should check the <A
112 HREF="config.html"
113 >main config file</A
114 >, especially the <A
115 HREF="config.html#ACCESS-CONTROL"
116 >security-relevant</A
117 > options. These are 
118    off by default.
119   </P
120 ></LI
121 ><LI
122 ><P
123 >  Start <SPAN
124 CLASS="APPLICATION"
125 >Privoxy</SPAN
126 >, if the installation program has
127   not done this already (may vary according to platform). See the section
128   <A
129 HREF="startup.html"
130 >Starting <SPAN
131 CLASS="APPLICATION"
132 >Privoxy</SPAN
133 ></A
134 >.
135   </P
136 ></LI
137 ><LI
138 ><P
139 >   Set your browser to use <SPAN
140 CLASS="APPLICATION"
141 >Privoxy</SPAN
142 > as HTTP and
143    HTTPS proxy by setting the proxy configuration for address of
144    <TT
145 CLASS="LITERAL"
146 >127.0.0.1</TT
147 > and port <TT
148 CLASS="LITERAL"
149 >8118</TT
150 >.
151    (<SPAN
152 CLASS="APPLICATION"
153 >Junkbuster</SPAN
154 > and earlier versions of
155    <SPAN
156 CLASS="APPLICATION"
157 >Privoxy</SPAN
158 > used port 8000.) See the section <A
159 HREF="startup.html"
160 >Starting <SPAN
161 CLASS="APPLICATION"
162 >Privoxy</SPAN
163 ></A
164 > below
165    for more details on this.
166   </P
167 ></LI
168 ><LI
169 ><P
170 >    Flush your browser's disk and memory caches, to remove any cached ad images.
171   </P
172 ></LI
173 ><LI
174 ><P
175 >   A default installation should provide a reasonable starting point for 
176    most. There will undoubtedly be occasions where you will want to adjust the
177    configuration, but that can be dealt with as the need arises. Little 
178    to no initial configuration is required in most cases.
179   </P
180 ><P
181 >   See the <A
182 HREF="configuration.html"
183 >Configuration section</A
184 > for more
185    configuration options, and how to customize your installation.
186  
187   </P
188 ></LI
189 ><LI
190 ><P
191 >    If you experience ads that slipped through, innocent images that are
192     blocked, or otherwise feel the need to fine-tune
193     <SPAN
194 CLASS="APPLICATION"
195 >Privoxy's</SPAN
196 > behaviour, take a look at the <A
197 HREF="actions-file.html"
198 >actions files</A
199 >. As a quick start, you might
200     find the <A
201 HREF="actions-file.html#ACT-EXAMPLES"
202 >richly commented examples</A
203 >
204     helpful. You can also view and edit the actions files through the <A
205 HREF="http://config.privoxy.org"
206 TARGET="_top"
207 >web-based user interface</A
208 >. The
209     Appendix <SPAN
210 CLASS="QUOTE"
211 >"<A
212 HREF="appendix.html#ACTIONSANAT"
213 >Anatomy of an
214     Action</A
215 >"</SPAN
216 > has hints how to debug actions that
217     <SPAN
218 CLASS="QUOTE"
219 >"misbehave"</SPAN
220 >.
221   </P
222 ></LI
223 ><LI
224 ><P
225 >   Please see the section <A
226 HREF="contact.html"
227 >Contacting the
228    Developers</A
229 > on how to report bugs or problems with websites or to get
230    help. 
231   </P
232 ></LI
233 ><LI
234 ><P
235 >   Now enjoy surfing with enhanced comfort and privacy!
236   </P
237 ></LI
238 ></UL
239 ></P
240 ><DIV
241 CLASS="SECT2"
242 ><H2
243 CLASS="SECT2"
244 ><A
245 NAME="QUICKSTART-AD-BLOCKING">4.1. Quickstart to Ad Blocking</H2
246 ><P
247 > Ad blocking is but one of <SPAN
248 CLASS="APPLICATION"
249 >Privoxy's</SPAN
250 >
251  array of features. Many of these features are for the technically minded advanced 
252  user. But, ad and banner blocking is surely common ground for everybody.</P
253 ><P
254
255  This section will provide a quick summary of ad blocking so 
256  you can get up to speed quickly without having to read the more extensive
257  information provided below, though this is highly recommended.</P
258 ><P
259 > First a bit of a warning ... blocking ads is much like blocking SPAM: the
260  more aggressive you are about it, the more likely you are to block 
261  things that were not intended. So there is a trade off here. If you want
262  extreme ad free browsing, be prepared to deal with more
263  <SPAN
264 CLASS="QUOTE"
265 >"problem"</SPAN
266 > sites, and to spend more time adjusting the
267  configuration to solve these unintended consequences. In short, there is 
268  not an easy way to eliminate <SPAN
269 CLASS="emphasis"
270 ><I
271 CLASS="EMPHASIS"
272 >all</I
273 ></SPAN
274 > ads. Either take 
275  the easy way and settle for <SPAN
276 CLASS="emphasis"
277 ><I
278 CLASS="EMPHASIS"
279 >most</I
280 ></SPAN
281 > ads blocked with the
282  default configuration, or jump in and tweak it for your personal surfing
283  habits and preferences.</P
284 ><P
285 > Secondly, a brief explanation of <SPAN
286 CLASS="APPLICATION"
287 >Privoxy's </SPAN
288 >
289  <SPAN
290 CLASS="QUOTE"
291 >"actions"</SPAN
292 >. <SPAN
293 CLASS="QUOTE"
294 >"Actions"</SPAN
295 > in this context, are 
296  the directives we use to tell <SPAN
297 CLASS="APPLICATION"
298 >Privoxy</SPAN
299 > to perform
300  some task relating to HTTP transactions (i.e. web browsing). We tell
301  <SPAN
302 CLASS="APPLICATION"
303 >Privoxy</SPAN
304 > to take some <SPAN
305 CLASS="QUOTE"
306 >"action"</SPAN
307 >. Each
308  action has a unique name and function. While there are many potential
309  <SPAN
310 CLASS="APPLICATION"
311 >actions</SPAN
312 > in <SPAN
313 CLASS="APPLICATION"
314 >Privoxy's</SPAN
315 >
316  arsenal, only a few are used for ad blocking. <A
317 HREF="actions-file.html#ACTIONS"
318 >Actions</A
319 >, and <A
320 HREF="actions-file.html"
321 >action
322  configuration files</A
323 >, are explained in depth below.</P
324 ><P
325 > Actions are specified in <SPAN
326 CLASS="APPLICATION"
327 >Privoxy's</SPAN
328 > configuration,
329  followed by one or more URLs to which the action should apply. URLs 
330  can actually be URL type <A
331 HREF="actions-file.html#AF-PATTERNS"
332 >patterns</A
333 > that use
334  wildcards so they can apply potentially to a range of similar URLs. The
335  actions, together with the URL patterns are called a section.</P
336 ><P
337 > When you connect to a website, the full URL will either match one or more
338  of the sections as defined in <SPAN
339 CLASS="APPLICATION"
340 >Privoxy's</SPAN
341 > configuration,
342  or not. If so, then <SPAN
343 CLASS="APPLICATION"
344 >Privoxy</SPAN
345 > will perform the
346  respective actions. If not, then nothing special happens. Furthermore, web
347  pages may contain embedded, secondary URLs that your web browser will
348  use to load additional components of the page, as it parses the
349  original page's HTML content. An ad image for instance, is just an URL
350  embedded in the page somewhere. The image itself may be on the same server,
351  or a server somewhere else on the Internet. Complex web pages will have many
352  such embedded URLs.</P
353 ><P
354 > The actions we need to know about for ad blocking are:  <TT
355 CLASS="LITERAL"
356 ><A
357 HREF="actions-file.html#BLOCK"
358 >block</A
359 ></TT
360 >, <TT
361 CLASS="LITERAL"
362 ><A
363 HREF="actions-file.html#HANDLE-AS-IMAGE"
364 >handle-as-image</A
365 ></TT
366 >, and
367  <TT
368 CLASS="LITERAL"
369 ><A
370 HREF="actions-file.html#SET-IMAGE-BLOCKER"
371 >set-image-blocker</A
372 ></TT
373 >:</P
374 ><P
375 > <P
376 ></P
377 ><UL
378 ><LI
379 ><P
380 >   <TT
381 CLASS="LITERAL"
382 ><A
383 HREF="actions-file.html#BLOCK"
384 >block</A
385 ></TT
386 > - this action stops
387    any contact between your browser and any URL patterns that match this
388    action's configuration. It can be used for blocking ads, but also anything
389    that is determined to be unwanted. By itself, it simply stops any
390    communication with the remote server and sends <SPAN
391 CLASS="APPLICATION"
392 >Privoxy</SPAN
393 >'s
394    own built-in BLOCKED page instead to let you now what has happened.
395   </P
396 ></LI
397 ><LI
398 ><P
399 >   <TT
400 CLASS="LITERAL"
401 ><A
402 HREF="actions-file.html#HANDLE-AS-IMAGE"
403 >handle-as-image</A
404 ></TT
405 > - 
406    tells <SPAN
407 CLASS="APPLICATION"
408 >Privoxy</SPAN
409 > to treat this URL as an image.
410    <SPAN
411 CLASS="APPLICATION"
412 >Privoxy</SPAN
413 >'s default configuration already does this
414    for all common image types (e.g. GIF), but there are many situations where this
415    is not so easy to determine. So we'll force it in these cases. This is particularly
416    important for ad blocking, since  only if we know that it's an image of
417    some kind, can we replace it with an image of our choosing, instead of the 
418    <SPAN
419 CLASS="APPLICATION"
420 >Privoxy</SPAN
421 > BLOCKED page (which would only result in
422    a <SPAN
423 CLASS="QUOTE"
424 >"broken image"</SPAN
425 > icon). There are some limitations to this
426    though. For instance, you can't just brute-force an image substitution for
427    an entire HTML page in most situations.
428   </P
429 ></LI
430 ><LI
431 ><P
432 >   <TT
433 CLASS="LITERAL"
434 ><A
435 HREF="actions-file.html#SET-IMAGE-BLOCKER"
436 >set-image-blocker</A
437 ></TT
438 > - tells
439    <SPAN
440 CLASS="APPLICATION"
441 >Privoxy</SPAN
442 > what to display in place of an ad image that
443    has hit a block rule. For this to come into play, the URL must match a
444    <TT
445 CLASS="LITERAL"
446 ><A
447 HREF="actions-file.html#BLOCK"
448 >block</A
449 ></TT
450 > action somewhere in the
451    configuration, <SPAN
452 CLASS="emphasis"
453 ><I
454 CLASS="EMPHASIS"
455 >and</I
456 ></SPAN
457 >, it must also match an
458    <TT
459 CLASS="LITERAL"
460 ><A
461 HREF="actions-file.html#HANDLE-AS-IMAGE"
462 >handle-as-image</A
463 ></TT
464 > action.
465   </P
466 ><P
467 >   The configuration options on what to display instead of the ad are:
468   </P
469 ><P
470 ></P
471 ><TABLE
472 BORDER="0"
473 ><TBODY
474 ><TR
475 ><TD
476 >    Â Â Â <SPAN
477 CLASS="emphasis"
478 ><I
479 CLASS="EMPHASIS"
480 >pattern</I
481 ></SPAN
482 > - a checkerboard pattern, so that an ad 
483     replacement is obvious. This is the default.
484    </TD
485 ></TR
486 ></TBODY
487 ></TABLE
488 ><P
489 ></P
490 ><P
491 ></P
492 ><TABLE
493 BORDER="0"
494 ><TBODY
495 ><TR
496 ><TD
497 >    Â Â Â <SPAN
498 CLASS="emphasis"
499 ><I
500 CLASS="EMPHASIS"
501 >blank</I
502 ></SPAN
503 > - A very small empty GIF image is displayed.
504     This is the so-called <SPAN
505 CLASS="QUOTE"
506 >"invisible"</SPAN
507 > configuration option.
508    </TD
509 ></TR
510 ></TBODY
511 ></TABLE
512 ><P
513 ></P
514 ><P
515 ></P
516 ><TABLE
517 BORDER="0"
518 ><TBODY
519 ><TR
520 ><TD
521 >    Â Â Â <SPAN
522 CLASS="emphasis"
523 ><I
524 CLASS="EMPHASIS"
525 >http://&#60;URL&#62;</I
526 ></SPAN
527 > - A redirect to any image anywhere
528     of the user's choosing (advanced usage).
529    </TD
530 ></TR
531 ></TBODY
532 ></TABLE
533 ><P
534 ></P
535 ></LI
536 ></UL
537 ></P
538 ><P
539 > The quickest way to adjust any of these settings is with your browser through
540  the special <SPAN
541 CLASS="APPLICATION"
542 >Privoxy</SPAN
543 > editor at <A
544 HREF="http://config.privoxy.org/show-status"
545 TARGET="_top"
546 >http://config.privoxy.org/show-status</A
547 >
548  (shortcut: <A
549 HREF="http://p.p/"
550 TARGET="_top"
551 >http://p.p/show-status</A
552 >). This 
553  is an internal page, and does not require Internet access. Select the
554  appropriate <SPAN
555 CLASS="QUOTE"
556 >"actions"</SPAN
557 > file, and click
558  <SPAN
559 CLASS="QUOTE"
560 >"<SPAN
561 CLASS="GUIBUTTON"
562 >Edit</SPAN
563 >"</SPAN
564 >. It is best to put personal or
565  local preferences in <TT
566 CLASS="FILENAME"
567 >user.action</TT
568 > since this is not
569  meant to be overwritten during upgrades, and will over-ride the settings in
570  other files. Here you can insert new <SPAN
571 CLASS="QUOTE"
572 >"actions"</SPAN
573 >, and URLs for ad
574  blocking or other purposes, and make other adjustments to the configuration.
575  <SPAN
576 CLASS="APPLICATION"
577 >Privoxy</SPAN
578 > will detect these changes automatically.</P
579 ><P
580 > A quick and simple step by step example:</P
581 ><P
582 > <P
583 ></P
584 ><UL
585 ><LI
586 ><P
587 >     Right click on the ad image to be blocked, then select 
588      <SPAN
589 CLASS="QUOTE"
590 >"<SPAN
591 CLASS="GUIMENUITEM"
592 >Copy Link Location</SPAN
593 >"</SPAN
594 > from the
595      pop-up menu. 
596    </P
597 ></LI
598 ><LI
599 ><P
600 >    Set your browser to 
601     <A
602 HREF="http://config.privoxy.org/show-status"
603 TARGET="_top"
604 >http://config.privoxy.org/show-status</A
605 >
606    </P
607 ></LI
608 ><LI
609 ><P
610 >    Find <TT
611 CLASS="FILENAME"
612 >user.action</TT
613 > in the top section, and click 
614     on <SPAN
615 CLASS="QUOTE"
616 >"<SPAN
617 CLASS="GUIBUTTON"
618 >Edit</SPAN
619 >"</SPAN
620 >:
621    </P
622 ><P
623 >  <DIV
624 CLASS="FIGURE"
625 ><A
626 NAME="AEN391"><P
627 ><B
628 >Figure 1. Actions Files in Use</B
629 ></P
630 ><DIV
631 CLASS="MEDIAOBJECT"
632 ><P
633 ><IMG
634 SRC="../images/files-in-use.jpg"></P
635 ></DIV
636 ></DIV
637 >
638  </P
639 ></LI
640 ><LI
641 ><P
642 >   You should have a section with only
643    <TT
644 CLASS="LITERAL"
645 ><A
646 HREF="actions-file.html#BLOCK"
647 >block</A
648 ></TT
649 > listed under 
650    <SPAN
651 CLASS="QUOTE"
652 >"Actions:"</SPAN
653 >.
654    If not, click a <SPAN
655 CLASS="QUOTE"
656 >"<SPAN
657 CLASS="GUIBUTTON"
658 >Insert new section below</SPAN
659 >"</SPAN
660 >
661    button, and in the new section that just appeared, click the 
662    <SPAN
663 CLASS="GUIBUTTON"
664 >Edit</SPAN
665 > button right under the word <SPAN
666 CLASS="QUOTE"
667 >"Actions:"</SPAN
668 >.
669    This will bring up a list of all actions. Find
670    <TT
671 CLASS="LITERAL"
672 ><A
673 HREF="actions-file.html#BLOCK"
674 >block</A
675 ></TT
676 > near the top, and click
677    in the <SPAN
678 CLASS="QUOTE"
679 >"Enabled"</SPAN
680 > column, then <SPAN
681 CLASS="QUOTE"
682 >"<SPAN
683 CLASS="GUIBUTTON"
684 >Submit</SPAN
685 >"</SPAN
686 >
687    just below the list.
688   </P
689 ></LI
690 ><LI
691 ><P
692 >   Now, in the <TT
693 CLASS="LITERAL"
694 ><A
695 HREF="actions-file.html#BLOCK"
696 >block</A
697 ></TT
698 > actions section,
699    click the <SPAN
700 CLASS="QUOTE"
701 >"<SPAN
702 CLASS="GUIBUTTON"
703 >Add</SPAN
704 >"</SPAN
705 > button, and paste the URL the
706    browser got from <SPAN
707 CLASS="QUOTE"
708 >"<SPAN
709 CLASS="GUIMENUITEM"
710 >Copy Link Location</SPAN
711 >"</SPAN
712 >.
713    Remove the <TT
714 CLASS="LITERAL"
715 >http://</TT
716 > at the beginning of the URL. Then, click
717    <SPAN
718 CLASS="QUOTE"
719 >"<SPAN
720 CLASS="GUIBUTTON"
721 >Submit</SPAN
722 >"</SPAN
723 > (or
724    <SPAN
725 CLASS="QUOTE"
726 >"<SPAN
727 CLASS="GUIBUTTON"
728 >OK</SPAN
729 >"</SPAN
730 > if in a pop-up window).
731   </P
732 ></LI
733 ><LI
734 ><P
735 >   Now go back to the original page, and press <B
736 CLASS="KEYCAP"
737 >SHIFT-Reload</B
738 >
739    (or flush all browser caches). The image should be gone now.
740   </P
741 ></LI
742 ></UL
743 ></P
744 ><P
745 > This is a very crude and simple example. There might be good reasons to use a 
746  wildcard pattern match to include potentially similar images from the same
747  site. For a more extensive explanation of <SPAN
748 CLASS="QUOTE"
749 >"patterns"</SPAN
750 >, and 
751  the entire actions concept, see <A
752 HREF="actions-file.html"
753 >the Actions
754  section</A
755 >.</P
756 ><P
757 > For advanced users who want to hand edit their config files, you might want
758  to now go to the <A
759 HREF="actions-file.html#ACT-EXAMPLES"
760 >Actions Files Tutorial</A
761 >.
762  The ideas explained therein also apply to the web-based editor.</P
763 ></DIV
764 ></DIV
765 ><DIV
766 CLASS="NAVFOOTER"
767 ><HR
768 ALIGN="LEFT"
769 WIDTH="100%"><TABLE
770 SUMMARY="Footer navigation table"
771 WIDTH="100%"
772 BORDER="0"
773 CELLPADDING="0"
774 CELLSPACING="0"
775 ><TR
776 ><TD
777 WIDTH="33%"
778 ALIGN="left"
779 VALIGN="top"
780 ><A
781 HREF="upgradersnote.html"
782 ACCESSKEY="P"
783 >Prev</A
784 ></TD
785 ><TD
786 WIDTH="34%"
787 ALIGN="center"
788 VALIGN="top"
789 ><A
790 HREF="index.html"
791 ACCESSKEY="H"
792 >Home</A
793 ></TD
794 ><TD
795 WIDTH="33%"
796 ALIGN="right"
797 VALIGN="top"
798 ><A
799 HREF="startup.html"
800 ACCESSKEY="N"
801 >Next</A
802 ></TD
803 ></TR
804 ><TR
805 ><TD
806 WIDTH="33%"
807 ALIGN="left"
808 VALIGN="top"
809 >Note to Upgraders</TD
810 ><TD
811 WIDTH="34%"
812 ALIGN="center"
813 VALIGN="top"
814 >&nbsp;</TD
815 ><TD
816 WIDTH="33%"
817 ALIGN="right"
818 VALIGN="top"
819 >Starting <SPAN
820 CLASS="APPLICATION"
821 >Privoxy</SPAN
822 ></TD
823 ></TR
824 ></TABLE
825 ></DIV
826 ></BODY
827 ></HTML
828 >