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 2.9.18 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 2.9.18 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 recommended.</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. Furthermore, 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 an 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 so 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 of
 411    some kind, can we replace it with an image of our choosing, instead of the
 412    <SPAN
 413 CLASS="APPLICATION"
 414 >Privoxy</SPAN
 415 > BLOCKED page (which would only result in
 416    a <SPAN
 417 CLASS="QUOTE"
 418 >"broken image"</SPAN
 419 > icon). There are some limitations to this
 420    though. For instance, you can't just brute-force an image substitution for
 421    an entire HTML page in most situations.
 422   </P
 423 ></LI
 424 ><LI
 425 ><P
 426 >   <TT
 427 CLASS="LITERAL"
 428 ><A
 429 HREF="actions-file.html#SET-IMAGE-BLOCKER"
 430 >set-image-blocker</A
 431 ></TT
 432 > - tells
 433    <SPAN
 434 CLASS="APPLICATION"
 435 >Privoxy</SPAN
 436 > what to display in place of an ad image that
 437    has hit a block rule. For this to come into play, the URL must match a
 438    <TT
 439 CLASS="LITERAL"
 440 ><A
 441 HREF="actions-file.html#BLOCK"
 442 >block</A
 443 ></TT
 444 > action somewhere in the
 445    configuration, <I
 446 CLASS="EMPHASIS"
 447 >and</I
 448 >, it must also match an
 449    <TT
 450 CLASS="LITERAL"
 451 ><A
 452 HREF="actions-file.html#HANDLE-AS-IMAGE"
 453 >handle-as-image</A
 454 ></TT
 455 > action.
 456   </P
 457 ><P
 458 >   The configuration options on what to display instead of the ad are:
 459   </P
 460 ><P
 461 ></P
 462 ><TABLE
 463 BORDER="0"
 464 ><TBODY
 465 ><TR
 466 ><TD
 467 >       <I
 468 CLASS="EMPHASIS"
 469 >pattern</I
 470 > - a checkerboard pattern, so that an ad
 471     replacement is obvious. This is the default.
 472    </TD
 473 ></TR
 474 ></TBODY
 475 ></TABLE
 476 ><P
 477 ></P
 478 ><P
 479 ></P
 480 ><TABLE
 481 BORDER="0"
 482 ><TBODY
 483 ><TR
 484 ><TD
 485 >       <I
 486 CLASS="EMPHASIS"
 487 >blank</I
 488 > - A very small empty GIF image is displayed.
 489     This is the so-called <SPAN
 490 CLASS="QUOTE"
 491 >"invisible"</SPAN
 492 > configuration option.
 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 >       <I
 507 CLASS="EMPHASIS"
 508 >http://&#60;URL&#62;</I
 509 > - A redirect to any image anywhere
 510     of the user's choosing (advanced usage).
 511    </TD
 512 ></TR
 513 ></TBODY
 514 ></TABLE
 515 ><P
 516 ></P
 517 ></LI
 518 ></UL
 519 ></P
 520 ><P
 521 > The quickest way to adjust any of these settings is with your browser through
 522  the special <SPAN
 523 CLASS="APPLICATION"
 524 >Privoxy</SPAN
 525 > editor at <A
 526 HREF="http://config.privoxy.org/show-status"
 527 TARGET="_top"
 528 >http://config.privoxy.org/show-status</A
 529 >
 530  (shortcut: <A
 531 HREF="http://p.p/"
 532 TARGET="_top"
 533 >http://p.p/show-status</A
 534 >). This
 535  is an internal page, and does not require Internet access. Select the
 536  appropriate <SPAN
 537 CLASS="QUOTE"
 538 >"actions"</SPAN
 539 > file, and click
 540  <SPAN
 541 CLASS="QUOTE"
 542 >"<SPAN
 543 CLASS="GUIBUTTON"
 544 >Edit</SPAN
 545 >"</SPAN
 546 >. It is best to put personal or
 547  local preferences in <TT
 548 CLASS="FILENAME"
 549 >user.action</TT
 550 > since this is not
 551  meant to be overwritten during upgrades, and will over-ride the settings in
 552  other files. Here you can insert new <SPAN
 553 CLASS="QUOTE"
 554 >"actions"</SPAN
 555 >, and URLs for ad
 556  blocking or other purposes, and make other adjustments to the configuration.
 557  <SPAN
 558 CLASS="APPLICATION"
 559 >Privoxy</SPAN
 560 > will detect these changes automatically.</P
 561 ><P
 562 > A quick and simple step by step example:</P
 563 ><P
 564 > <P
 565 ></P
 566 ><UL
 567 ><LI
 568 ><P
 569 >     Right click on the ad image to be blocked, then select
 570      <SPAN
 571 CLASS="QUOTE"
 572 >"<SPAN
 573 CLASS="GUIMENUITEM"
 574 >Copy Link Location</SPAN
 575 >"</SPAN
 576 > from the
 577      pop-up menu.
 578    </P
 579 ></LI
 580 ><LI
 581 ><P
 582 >    Set your browser to
 583     <A
 584 HREF="http://config.privoxy.org/show-status"
 585 TARGET="_top"
 586 >http://config.privoxy.org/show-status</A
 587 >
 588    </P
 589 ></LI
 590 ><LI
 591 ><P
 592 >    Find <TT
 593 CLASS="FILENAME"
 594 >user.action</TT
 595 > in the top section, and click
 596     on <SPAN
 597 CLASS="QUOTE"
 598 >"<SPAN
 599 CLASS="GUIBUTTON"
 600 >Edit</SPAN
 601 >"</SPAN
 602 >:
 603    </P
 604 ><P
 605 >  <DIV
 606 CLASS="FIGURE"
 607 ><A
 608 NAME="AEN384"
 609 ></A
 610 ><P
 611 ><B
 612 >Figure 1. Actions Files in Use</B
 613 ></P
 614 ><DIV
 615 CLASS="MEDIAOBJECT"
 616 ><P
 617 ><IMG
 618 SRC="../images/files-in-use.jpg"
 619 ALT="[ Screenshot of Actions Files in Use ]"
 620 ></IMG
 621 ></P
 622 ></DIV
 623 ></DIV
 624 >
 625  </P
 626 ></LI
 627 ><LI
 628 ><P
 629 >   You should have a section with only
 630    <TT
 631 CLASS="LITERAL"
 632 ><A
 633 HREF="actions-file.html#BLOCK"
 634 >block</A
 635 ></TT
 636 > listed under
 637    <SPAN
 638 CLASS="QUOTE"
 639 >"Actions:"</SPAN
 640 >.
 641    If not, click a <SPAN
 642 CLASS="QUOTE"
 643 >"<SPAN
 644 CLASS="GUIBUTTON"
 645 >Insert new section below</SPAN
 646 >"</SPAN
 647 >
 648    button, and in the new section that just appeared, click the
 649    <SPAN
 650 CLASS="GUIBUTTON"
 651 >Edit</SPAN
 652 > button right under the word <SPAN
 653 CLASS="QUOTE"
 654 >"Actions:"</SPAN
 655 >.
 656    This will bring up a list of all actions. Find
 657    <TT
 658 CLASS="LITERAL"
 659 ><A
 660 HREF="actions-file.html#BLOCK"
 661 >block</A
 662 ></TT
 663 > near the top, and click
 664    in the <SPAN
 665 CLASS="QUOTE"
 666 >"Enabled"</SPAN
 667 > column, then <SPAN
 668 CLASS="QUOTE"
 669 >"<SPAN
 670 CLASS="GUIBUTTON"
 671 >Submit</SPAN
 672 >"</SPAN
 673 >
 674    just below the list.
 675   </P
 676 ></LI
 677 ><LI
 678 ><P
 679 >   Now, in the <TT
 680 CLASS="LITERAL"
 681 ><A
 682 HREF="actions-file.html#BLOCK"
 683 >block</A
 684 ></TT
 685 > actions section,
 686    click the <SPAN
 687 CLASS="QUOTE"
 688 >"<SPAN
 689 CLASS="GUIBUTTON"
 690 >Add</SPAN
 691 >"</SPAN
 692 > button, and paste the URL the
 693    browser got from <SPAN
 694 CLASS="QUOTE"
 695 >"<SPAN
 696 CLASS="GUIMENUITEM"
 697 >Copy Link Location</SPAN
 698 >"</SPAN
 699 >.
 700    Remove the <TT
 701 CLASS="LITERAL"
 702 >http://</TT
 703 > at the beginning of the URL. Then, click
 704    <SPAN
 705 CLASS="QUOTE"
 706 >"<SPAN
 707 CLASS="GUIBUTTON"
 708 >Submit</SPAN
 709 >"</SPAN
 710 > (or
 711    <SPAN
 712 CLASS="QUOTE"
 713 >"<SPAN
 714 CLASS="GUIBUTTON"
 715 >OK</SPAN
 716 >"</SPAN
 717 > if in a pop-up window).
 718   </P
 719 ></LI
 720 ><LI
 721 ><P
 722 >   Now go back to the original page, and press <B
 723 CLASS="KEYCAP"
 724 >SHIFT-Reload</B
 725 >
 726    (or flush all browser caches). The image should be gone now.
 727   </P
 728 ></LI
 729 ></UL
 730 ></P
 731 ><P
 732 > This is a very crude and simple example. There might be good reasons to use a
 733  wildcard pattern match to include potentially similar images from the same
 734  site. For a more extensive explanation of <SPAN
 735 CLASS="QUOTE"
 736 >"patterns"</SPAN
 737 >, and
 738  the entire actions concept, see <A
 739 HREF="actions-file.html"
 740 >the Actions
 741  section</A
 742 >.</P
 743 ><P
 744 > For advanced users who want to hand edit their config files, you might want
 745  to now go to the <A
 746 HREF="actions-file.html#ACT-EXAMPLES"
 747 >Actions Files Tutorial</A
 748 >.
 749  The ideas explained therein also apply to the web-based editor.</P
 750 ></DIV
 751 ></DIV
 752 ><DIV
 753 CLASS="NAVFOOTER"
 754 ><HR
 755 ALIGN="LEFT"
 756 WIDTH="100%"><TABLE
 757 WIDTH="100%"
 758 BORDER="0"
 759 CELLPADDING="0"
 760 CELLSPACING="0"
 761 ><TR
 762 ><TD
 763 WIDTH="33%"
 764 ALIGN="left"
 765 VALIGN="top"
 766 ><A
 767 HREF="upgradersnote.html"
 768 >Prev</A
 769 ></TD
 770 ><TD
 771 WIDTH="34%"
 772 ALIGN="center"
 773 VALIGN="top"
 774 ><A
 775 HREF="index.html"
 776 >Home</A
 777 ></TD
 778 ><TD
 779 WIDTH="33%"
 780 ALIGN="right"
 781 VALIGN="top"
 782 ><A
 783 HREF="startup.html"
 784 >Next</A
 785 ></TD
 786 ></TR
 787 ><TR
 788 ><TD
 789 WIDTH="33%"
 790 ALIGN="left"
 791 VALIGN="top"
 792 >Note to Upgraders</TD
 793 ><TD
 794 WIDTH="34%"
 795 ALIGN="center"
 796 VALIGN="top"
 797 >&nbsp;</TD
 798 ><TD
 799 WIDTH="33%"
 800 ALIGN="right"
 801 VALIGN="top"
 802 >Starting <SPAN
 803 CLASS="APPLICATION"
 804 >Privoxy</SPAN
 805 ></TD
 806 ></TR
 807 ></TABLE
 808 ></DIV
 809 ></BODY
 810 ></HTML
 811 >