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