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="Installation"
  14 HREF="installation.html"><LINK
  15 REL="NEXT"
  16 TITLE="Privoxy Configuration"
  17 HREF="configuration.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="installation.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="configuration.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 ><DIV
  80 CLASS="SECT2"
  81 ><H2
  82 CLASS="SECT2"
  83 ><A
  84 NAME="UPGRADERSNOTE"
  85 >4.1. Note to Upgraders</A
  86 ></H2
  87 ><P
  88 > There are very significant changes from older versions of
  89  <SPAN
  90 CLASS="APPLICATION"
  91 >Junkbuster</SPAN
  92 > to the current
  93  <SPAN
  94 CLASS="APPLICATION"
  95 >Privoxy</SPAN
  96 >. Configuration is substantially
  97  changed. <SPAN
  98 CLASS="APPLICATION"
  99 >Junkbuster 2.0.x</SPAN
 100 > and earlier
 101  configuration files will not migrate. The functionality of the old
 102  <TT
 103 CLASS="FILENAME"
 104 >blockfile</TT
 105 >, <TT
 106 CLASS="FILENAME"
 107 >cookiefile</TT
 108 > and
 109  <TT
 110 CLASS="FILENAME"
 111 >imagelist</TT
 112 >, are now combined into the
 113  <SPAN
 114 CLASS="QUOTE"
 115 >"actions file"</SPAN
 116 >  (<TT
 117 CLASS="FILENAME"
 118 >default.action</TT
 119 >
 120  for most installations).</P
 121 ><P
 122 > A <SPAN
 123 CLASS="QUOTE"
 124 >"filter file"</SPAN
 125 > (typically <TT
 126 CLASS="FILENAME"
 127 >default.filter</TT
 128 >)
 129  is new as of <SPAN
 130 CLASS="APPLICATION"
 131 >Privoxy 2.9.x</SPAN
 132 >, and provides some
 133  of the new sophistication (explained below). <TT
 134 CLASS="FILENAME"
 135 >config</TT
 136 > is
 137  much the same as before.</P
 138 ><P
 139 > If upgrading from a 2.0.x version, you will have to use the new config
 140  files, and possibly adapt any personal rules from your older files.
 141  When porting personal rules over from the old <TT
 142 CLASS="FILENAME"
 143 >blockfile</TT
 144 >
 145  to the new actions file, please note that even the pattern syntax has
 146  changed. If upgrading from 2.9.x development versions, it is still
 147  recommended to use the new configuration files.</P
 148 ><P
 149 > A quick list of things to be aware of before upgrading: </P
 150 ><P
 151 > <P
 152 ></P
 153 ><UL
 154 ><LI
 155 ><P
 156 >   The default listening port is now 8118 due to a conflict with another
 157    service (NAS).
 158   </P
 159 ></LI
 160 ><LI
 161 ><P
 162 >
 163     Some installers may remove earlier versions completely. Save any
 164     important configuration files!
 165   </P
 166 ></LI
 167 ><LI
 168 ><P
 169 >   <SPAN
 170 CLASS="APPLICATION"
 171 >Privoxy</SPAN
 172 > is controllable with a web browser
 173    at the special URL: <A
 174 HREF="http://config.privoxy.org/"
 175 TARGET="_top"
 176 >http://config.privoxy.org/</A
 177 >
 178    (Shortcut: <A
 179 HREF="http://p.p/"
 180 TARGET="_top"
 181 >http://p.p/</A
 182 >). Many
 183    aspects of configuration can be done here, including temporarily disabling
 184    <SPAN
 185 CLASS="APPLICATION"
 186 >Privoxy</SPAN
 187 >.
 188   </P
 189 ></LI
 190 ><LI
 191 ><P
 192 >   The primary configuration file for cookie management, ad and banner
 193    blocking, and many other aspects of <SPAN
 194 CLASS="APPLICATION"
 195 >Privoxy</SPAN
 196 >
 197    configuration is <TT
 198 CLASS="FILENAME"
 199 >default.action</TT
 200 >. It is strongly
 201    recommended to become familiar with the new actions concept below,
 202    before modifying this file.
 203   </P
 204 ></LI
 205 ><LI
 206 ><P
 207 >
 208    Some installers may not automatically start
 209    <SPAN
 210 CLASS="APPLICATION"
 211 >Privoxy</SPAN
 212 > after installation.
 213   </P
 214 ></LI
 215 ></UL
 216 ></P
 217 ></DIV
 218 ><DIV
 219 CLASS="SECT2"
 220 ><H2
 221 CLASS="SECT2"
 222 ><A
 223 NAME="STARTUP"
 224 >4.2. Starting <SPAN
 225 CLASS="APPLICATION"
 226 >Privoxy</SPAN
 227 ></A
 228 ></H2
 229 ><P
 230 > Before launching <SPAN
 231 CLASS="APPLICATION"
 232 >Privoxy</SPAN
 233 > for the first time, you
 234  will want to configure your browser(s) to use <SPAN
 235 CLASS="APPLICATION"
 236 >Privoxy</SPAN
 237 >
 238  as a HTTP and HTTPS proxy. The default is localhost for the proxy address,
 239  and port 8118 (earlier versions used port 8000). This is the one
 240  configuration step that must be done! </P
 241 ><P
 242 >
 243  With <SPAN
 244 CLASS="APPLICATION"
 245 >Netscape</SPAN
 246 > (and
 247  <SPAN
 248 CLASS="APPLICATION"
 249 >Mozilla</SPAN
 250 >), this can be set under <TT
 251 CLASS="LITERAL"
 252 >Edit
 253  -&#62; Preferences -&#62; Advanced -&#62; Proxies -&#62; HTTP Proxy</TT
 254 >.
 255  For <SPAN
 256 CLASS="APPLICATION"
 257 >Internet Explorer</SPAN
 258 >: <TT
 259 CLASS="LITERAL"
 260 >Tools -&#62;
 261  Internet Properties -&#62; Connections -&#62; LAN Setting</TT
 262 >. Then,
 263  check <SPAN
 264 CLASS="QUOTE"
 265 >"Use Proxy"</SPAN
 266 > and fill in the appropriate info (Address:
 267  localhost, Port: 8118). Include if HTTPS proxy support too.</P
 268 ><P
 269 > After doing this, flush your browser's disk and memory caches to force a
 270  re-reading of all pages and to get rid of any ads that may be cached. You
 271  are now ready to start enjoying the benefits of using
 272  <SPAN
 273 CLASS="APPLICATION"
 274 >Privoxy</SPAN
 275 >!</P
 276 ><P
 277 > <SPAN
 278 CLASS="APPLICATION"
 279 >Privoxy</SPAN
 280 > is typically started by specifying the
 281  main configuration file to be used on the command line. Example Unix startup
 282  command:</P
 283 ><P
 284 > <TABLE
 285 BORDER="0"
 286 BGCOLOR="#E0E0E0"
 287 WIDTH="100%"
 288 ><TR
 289 ><TD
 290 ><PRE
 291 CLASS="SCREEN"
 292 >
 293  # /usr/sbin/privoxy /etc/privoxy/config
 294
 295  </PRE
 296 ></TD
 297 ></TR
 298 ></TABLE
 299 ></P
 300 ><P
 301 > See <A
 302 HREF="quickstart.html#CMDOPTIONS"
 303 >below</A
 304 > for other command line options.</P
 305 ><P
 306 > An init script is provided for SuSE and Red Hat.</P
 307 ><P
 308 > For for SuSE: <B
 309 CLASS="COMMAND"
 310 >rcprivoxy start</B
 311 ></P
 312 ><P
 313 > For Red Hat and Debian: <B
 314 CLASS="COMMAND"
 315 >/etc/rc.d/init.d/privoxy start</B
 316 ></P
 317 ><P
 318 > If no configuration file is specified on the command line,
 319  <SPAN
 320 CLASS="APPLICATION"
 321 >Privoxy</SPAN
 322 > will look for a file named
 323  <TT
 324 CLASS="FILENAME"
 325 >config</TT
 326 > in the current directory. Except on Win32 where
 327  it will try <TT
 328 CLASS="FILENAME"
 329 >config.txt</TT
 330 >. If no file is specified on the
 331  command line and no default configuration file can be found,
 332  <SPAN
 333 CLASS="APPLICATION"
 334 >Privoxy</SPAN
 335 > will fail to start.</P
 336 ><P
 337 > The included default configuration files should give a reasonable starting
 338  point. Most of the per site configuration is done in the
 339  <SPAN
 340 CLASS="QUOTE"
 341 >"actions"</SPAN
 342 > files. These are where various cookie actions are
 343  defined, ad and banner blocking, and other aspects of
 344  <SPAN
 345 CLASS="APPLICATION"
 346 >Privoxy</SPAN
 347 > configuration. There are several such
 348  files included, with varying levels of aggressiveness. </P
 349 ><P
 350 > You will probably want to keep an eye out for sites that require persistent
 351  cookies, and add these to <TT
 352 CLASS="FILENAME"
 353 >default.action</TT
 354 > as needed. By
 355  default, most of these will be accepted only during the current browser
 356  session (aka <SPAN
 357 CLASS="QUOTE"
 358 >"session cookies"</SPAN
 359 >), until you add them to the
 360  configuration. If you want the browser to handle this instead, you will need
 361  to edit <TT
 362 CLASS="FILENAME"
 363 >default.action</TT
 364 > and disable this feature. If you
 365  use more than one browser, it would make more sense to let
 366  <SPAN
 367 CLASS="APPLICATION"
 368 >Privoxy</SPAN
 369 > handle this. In which case, the
 370  browser(s) should be set to accept all cookies.</P
 371 ><P
 372 > Another feature where you will probably want to define exceptions for trusted
 373  sites is the popup-killing (through the <TT
 374 CLASS="LITERAL"
 375 >+popup</TT
 376 > and
 377  <TT
 378 CLASS="LITERAL"
 379 >+filter{popups}</TT
 380 > actions), because your favorite shopping,
 381  banking, or leisure site may need popups. </P
 382 ><P
 383 > <SPAN
 384 CLASS="APPLICATION"
 385 >Privoxy</SPAN
 386 > is HTTP/1.1 compliant,  but not all of
 387  the optional 1.1 features are as yet supported. In the unlikely event that
 388  you experience inexplicable problems with browsers that use HTTP/1.1 per default
 389  (like <SPAN
 390 CLASS="APPLICATION"
 391 >Mozilla</SPAN
 392 > or recent versions of I.E.), you might
 393  try to force HTTP/1.0 compatibility. For Mozilla, look under <TT
 394 CLASS="LITERAL"
 395 >Edit -&#62;
 396  Preferences -&#62; Debug -&#62; Networking</TT
 397 >.
 398  Alternatively, set the <SPAN
 399 CLASS="QUOTE"
 400 >"+downgrade"</SPAN
 401 > config option in
 402  <TT
 403 CLASS="FILENAME"
 404 >default.action</TT
 405 > which will downgrade your browser's HTTP
 406  requests from HTTP/1.1 to HTTP/1.0 before processing them.</P
 407 ><P
 408 > After running <SPAN
 409 CLASS="APPLICATION"
 410 >Privoxy</SPAN
 411 > for a while, you can
 412  start to fine tune the configuration to suit your personal, or site,
 413  preferences and requirements. There are many, many aspects that can
 414  be customized. <SPAN
 415 CLASS="QUOTE"
 416 >"Actions"</SPAN
 417 > (as specified in <TT
 418 CLASS="FILENAME"
 419 >default.action</TT
 420 >)
 421  can be adjusted by pointing your browser to
 422  <A
 423 HREF="http://config.privoxy.org/"
 424 TARGET="_top"
 425 >http://config.privoxy.org/</A
 426 >
 427  (shortcut: <A
 428 HREF="http://p.p/"
 429 TARGET="_top"
 430 >http://p.p/</A
 431 >),
 432  and then follow the link to <SPAN
 433 CLASS="QUOTE"
 434 >"edit the actions list"</SPAN
 435 >.
 436  (This is an internal page and does not require Internet access.)</P
 437 ><P
 438 > In fact, various aspects of <SPAN
 439 CLASS="APPLICATION"
 440 >Privoxy</SPAN
 441 >
 442  configuration can be viewed from this page, including
 443  current configuration parameters, source code version numbers,
 444  the browser's request headers, and <SPAN
 445 CLASS="QUOTE"
 446 >"actions"</SPAN
 447 > that apply
 448  to a given URL. In addition to the <TT
 449 CLASS="FILENAME"
 450 >default.action</TT
 451 > file
 452  editor mentioned above, <SPAN
 453 CLASS="APPLICATION"
 454 >Privoxy</SPAN
 455 > can also
 456  be turned <SPAN
 457 CLASS="QUOTE"
 458 >"on"</SPAN
 459 > and <SPAN
 460 CLASS="QUOTE"
 461 >"off"</SPAN
 462 > (toggled) from this page.</P
 463 ><P
 464 > If you encounter problems, try loading the page without
 465  <SPAN
 466 CLASS="APPLICATION"
 467 >Privoxy</SPAN
 468 >. If that helps, enter the URL where
 469  you have the problems into <A
 470 HREF="http://p.p/show-url-info"
 471 TARGET="_top"
 472 >the browser
 473  based rule tracing utility</A
 474 >. See which rules apply and why, and
 475  then try turning them off for that site one after the other, until the problem
 476  is gone. When you have found the culprit, you might want to turn the rest on
 477  again.</P
 478 ><P
 479 > If the above paragraph sounds gibberish to you, you might want to <A
 480 HREF="configuration.html#ACTIONSFILE"
 481 TARGET="_top"
 482 >read more about the actions concept</A
 483 >
 484  or even dive deep into the <A
 485 HREF="appendix.html#ACTIONSANAT"
 486 TARGET="_top"
 487 >Appendix
 488  on actions</A
 489 >.</P
 490 ><P
 491 > If you can't get rid of the problem at all, think you've found a bug in
 492  Privoxy, want to propose a new feature or smarter rules, please see the
 493  chapter "Contacting the Developers, .." below.</P
 494 ></DIV
 495 ><DIV
 496 CLASS="SECT2"
 497 ><H2
 498 CLASS="SECT2"
 499 ><A
 500 NAME="CMDOPTIONS"
 501 >4.3. Command Line Options</A
 502 ></H2
 503 ><P
 504 > <SPAN
 505 CLASS="APPLICATION"
 506 >Privoxy</SPAN
 507 > may be invoked with the following
 508  command-line options:</P
 509 ><P
 510 > <P
 511 ></P
 512 ><UL
 513 ><LI
 514 ><P
 515 >    <I
 516 CLASS="EMPHASIS"
 517 >--version</I
 518 >
 519   </P
 520 ><P
 521 >     Print version info and exit. Unix only.
 522   </P
 523 ></LI
 524 ><LI
 525 ><P
 526 >    <I
 527 CLASS="EMPHASIS"
 528 >--help</I
 529 >
 530   </P
 531 ><P
 532 >   Print short usage info and exit. Unix only.
 533   </P
 534 ></LI
 535 ><LI
 536 ><P
 537 >   <I
 538 CLASS="EMPHASIS"
 539 >--no-daemon</I
 540 >
 541   </P
 542 ><P
 543 >   Don't become a daemon, i.e. don't fork and become process group
 544    leader, and don't detach from controlling tty. Unix only.
 545   </P
 546 ></LI
 547 ><LI
 548 ><P
 549 >   <I
 550 CLASS="EMPHASIS"
 551 >--pidfile FILE</I
 552 >
 553
 554   </P
 555 ><P
 556 >   On startup, write the process ID to <I
 557 CLASS="EMPHASIS"
 558 >FILE</I
 559 >. Delete the
 560    <I
 561 CLASS="EMPHASIS"
 562 >FILE</I
 563 > on exit. Failure to create or delete the
 564    <I
 565 CLASS="EMPHASIS"
 566 >FILE</I
 567 > is non-fatal. If no <I
 568 CLASS="EMPHASIS"
 569 >FILE</I
 570 >
 571    option is given, no PID file will be used. Unix only.
 572   </P
 573 ></LI
 574 ><LI
 575 ><P
 576 >   <I
 577 CLASS="EMPHASIS"
 578 >--user USER[.GROUP]</I
 579 >
 580
 581   </P
 582 ><P
 583 >   After (optionally) writing the PID file, assume the user  ID  of
 584    <I
 585 CLASS="EMPHASIS"
 586 >USER</I
 587 >, and if included the GID of GROUP.  Exit if the
 588    privileges are not sufficient to do so. Unix only.
 589   </P
 590 ></LI
 591 ><LI
 592 ><P
 593 >    <I
 594 CLASS="EMPHASIS"
 595 >configfile</I
 596 >
 597   </P
 598 ><P
 599 >    If no <I
 600 CLASS="EMPHASIS"
 601 >configfile</I
 602 > is included on the command line,
 603     <SPAN
 604 CLASS="APPLICATION"
 605 >Privoxy</SPAN
 606 > will look for a file named
 607     <SPAN
 608 CLASS="QUOTE"
 609 >"config"</SPAN
 610 > in the current directory (except on Win32
 611     where it will look for <SPAN
 612 CLASS="QUOTE"
 613 >"config.txt"</SPAN
 614 > instead). Specify
 615     full path to avoid confusion. If no config file is found,
 616     <SPAN
 617 CLASS="APPLICATION"
 618 >Privoxy</SPAN
 619 > will fail to start.
 620   </P
 621 ></LI
 622 ></UL
 623 ></P
 624 ></DIV
 625 ></DIV
 626 ><DIV
 627 CLASS="NAVFOOTER"
 628 ><HR
 629 ALIGN="LEFT"
 630 WIDTH="100%"><TABLE
 631 WIDTH="100%"
 632 BORDER="0"
 633 CELLPADDING="0"
 634 CELLSPACING="0"
 635 ><TR
 636 ><TD
 637 WIDTH="33%"
 638 ALIGN="left"
 639 VALIGN="top"
 640 ><A
 641 HREF="installation.html"
 642 >Prev</A
 643 ></TD
 644 ><TD
 645 WIDTH="34%"
 646 ALIGN="center"
 647 VALIGN="top"
 648 ><A
 649 HREF="index.html"
 650 >Home</A
 651 ></TD
 652 ><TD
 653 WIDTH="33%"
 654 ALIGN="right"
 655 VALIGN="top"
 656 ><A
 657 HREF="configuration.html"
 658 >Next</A
 659 ></TD
 660 ></TR
 661 ><TR
 662 ><TD
 663 WIDTH="33%"
 664 ALIGN="left"
 665 VALIGN="top"
 666 >Installation</TD
 667 ><TD
 668 WIDTH="34%"
 669 ALIGN="center"
 670 VALIGN="top"
 671 >&nbsp;</TD
 672 ><TD
 673 WIDTH="33%"
 674 ALIGN="right"
 675 VALIGN="top"
 676 ><SPAN
 677 CLASS="APPLICATION"
 678 >Privoxy</SPAN
 679 > Configuration</TD
 680 ></TR
 681 ></TABLE
 682 ></DIV
 683 ></BODY
 684 ></HTML
 685 >