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