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