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