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