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