Regenerate docs for upcoming 3.0.1 release.
[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.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.0.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"
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 >   If upgrading, from versions before 2.9.16, please back up any configuration
89    files. See the <A
90 HREF="upgradersnote.html"
91 >Note to Upgraders</A
92 > Section.
93  </P
94 ></LI
95 ><LI
96 ><P
97 >  Install <SPAN
98 CLASS="APPLICATION"
99 >Privoxy</SPAN
100 >. See the <A
101 HREF="installation.html"
102 >Installation Section</A
103 > below for platform specific
104   information. 
105  </P
106 ></LI
107 ><LI
108 ><P
109 >   Advanced users and those who want to offer <SPAN
110 CLASS="APPLICATION"
111 >Privoxy</SPAN
112 >
113    service to more than just their local machine should check the <A
114 HREF="config.html"
115 >main config file</A
116 >, especially the <A
117 HREF="config.html#ACCESS-CONTROL"
118 >security-relevant</A
119 > options. These are 
120    off by default.
121   </P
122 ></LI
123 ><LI
124 ><P
125 >  Start <SPAN
126 CLASS="APPLICATION"
127 >Privoxy</SPAN
128 >, if the installation program has
129   not done this already (may vary according to platform). See the section
130   <A
131 HREF="startup.html"
132 >Starting <SPAN
133 CLASS="APPLICATION"
134 >Privoxy</SPAN
135 ></A
136 >.
137   </P
138 ></LI
139 ><LI
140 ><P
141 >   Set your browser to use <SPAN
142 CLASS="APPLICATION"
143 >Privoxy</SPAN
144 > as HTTP and
145    HTTPS (SSL) proxy by setting the proxy configuration for address of
146    <TT
147 CLASS="LITERAL"
148 >127.0.0.1</TT
149 > and port <TT
150 CLASS="LITERAL"
151 >8118</TT
152 >.
153    (<SPAN
154 CLASS="APPLICATION"
155 >Junkbuster</SPAN
156 > and earlier versions of
157    <SPAN
158 CLASS="APPLICATION"
159 >Privoxy</SPAN
160 > used port 8000.) See the section <A
161 HREF="startup.html"
162 >Starting <SPAN
163 CLASS="APPLICATION"
164 >Privoxy</SPAN
165 ></A
166 > below
167    for more details on this.
168   </P
169 ></LI
170 ><LI
171 ><P
172 >    Flush your browser's disk and memory caches, to remove any cached ad images.
173     If using <SPAN
174 CLASS="APPLICATION"
175 >Privoxy</SPAN
176 > to manage cookies, you should 
177     remove any currently stored cookies too.
178   </P
179 ></LI
180 ><LI
181 ><P
182 >   A default installation should provide a reasonable starting point for 
183    most. There will undoubtedly be occasions where you will want to adjust the
184    configuration, but that can be dealt with as the need arises. Little 
185    to no initial configuration is required in most cases.
186   </P
187 ><P
188 >   See the <A
189 HREF="configuration.html"
190 >Configuration section</A
191 > for more
192    configuration options, and how to customize your installation.
193  
194   </P
195 ></LI
196 ><LI
197 ><P
198 >    If you experience ads that slipped through, innocent images that are
199     blocked, or otherwise feel the need to fine-tune
200     <SPAN
201 CLASS="APPLICATION"
202 >Privoxy's</SPAN
203 > behaviour, take a look at the <A
204 HREF="actions-file.html"
205 >actions files</A
206 >. As a quick start, you might
207     find the <A
208 HREF="actions-file.html#ACT-EXAMPLES"
209 >richly commented examples</A
210 >
211     helpful. You can also view and edit the actions files through the <A
212 HREF="http://config.privoxy.org"
213 TARGET="_top"
214 >web-based user interface</A
215 >. The
216     Appendix <SPAN
217 CLASS="QUOTE"
218 >"<A
219 HREF="appendix.html#ACTIONSANAT"
220 >Anatomy of an
221     Action</A
222 >"</SPAN
223 > has hints how to debug actions that
224     <SPAN
225 CLASS="QUOTE"
226 >"misbehave"</SPAN
227 >.
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 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="AEN454"
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="upgradersnote.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 >Note to Upgraders</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 >