doc/source/user-manual.sgml

   1 <!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
   2 <!--
   3 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   4  File        :  $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
   5
   6  Purpose     :  user manual
   7                 This file belongs into
   8                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
   9
  10  $Id: user-manual.sgml,v 1.13 2001/10/10 17:28:33 hal9 Exp $
  11
  12  Written by and Copyright (C) 2001 the SourceForge
  13  IJBSWA team.  http://ijbswa.sourceforge.net
  14
  15  Based on the Internet Junkbuster originally written
  16  by and Copyright (C) 1997 Anonymous Coders and
  17  Junkbusters Corporation.  http://www.junkbusters.com
  18 -->
  19
  20 <!--
  21 Sun 09/23/01 08:53:31 PM
  22
  23 This is an unfinished, rough draft. Anyone reading this, believe let me
  24 know errors!!!!! Stefan, especially you!
  25
  26 Hal Burgiss <hal@foobox.net>
  27 -->
  28
  29 <article id="index">
  30 <artheader>
  31 <title>Junkbuster User Manual</title>
  32
  33 <pubdate>$Id: user-manual.sgml,v 1.13 2001/10/10 17:28:33 hal9 Exp $</pubdate>
  34
  35 <authorgroup>
  36  <author>
  37   <affiliation>
  38    <orgname>By: Junkbuster Developers</orgname>
  39    </affiliation>
  40  </author>
  41 </authorgroup>
  42
  43 <abstract>
  44  <para>
  45   The user manual gives the users information on how to install and configure
  46   <application>Internet Junkbuster</application>. <application>Internet
  47   Junkbuster</application> is an application that provides privacy and
  48   security to users of the World Wide Web.
  49  </para>
  50  <para>
  51 You can find the latest version of the user manual at  <ulink url="http://ijbswa.sourceforge.net/doc/user-manual/">http://ijbswa.sourceforge.net/doc/user-manual/</ulink>.
  52  </para>
  53
  54  <para>
  55   Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>.
  56  </para>
  57 </abstract>
  58
  59 </artheader>
  60
  61
  62 <!--   ~~~~~       New section      ~~~~~     -->
  63
  64 <sect1 id="introduction"><title>Introduction</title>
  65 <para>
  66  <application>Internet Junkbuster</application> is a web proxy with advanced
  67  filtering capabilities for protecting privacy, filtering web page content,
  68  managing cookies and removing ads, banners, pop-ups and other obnoxious
  69  Internet Junk. <application>Junkbuster</application> has a very flexible
  70  configuration and can be customized to suit individual needs and tastes.
  71  <application>Internet Junkbuster</application> has application for both
  72  stand-alone systems and multi-user networks.
  73 </para>
  74
  75 <para>
  76  This documentation is included with the current development version of
  77  <application>Internet Junkbuster</application> and is incomplete at this
  78  point. The most up to date reference for the time being is still the comments
  79  in the source files and in the individual configuration files. Development
  80  of version 3.0 is currently underway, and includes significant changes and
  81  enhancements over earlier verions. The target release date for stable v3.0 is
  82  December 2001.
  83 </para>
  84
  85 <para>
  86  Since this is a development version, some features are in the process of
  87  being implemented. This documentation may be slightly out of sync as a
  88  result. And there <emphasis>are</emphasis> bugs!
  89 </para>
  90
  91
  92 <!--   ~~~~~       New section      ~~~~~     -->
  93 <sect2>
  94 <title>New Features</title>
  95 <para>
  96  In addition to <application>Junkbuster's</application> traditional features
  97  of ad and banner blocking and cookie management, this is a list of new
  98  features currently under development:
  99 </para>
 100
 101 <para>
 102  <itemizedlist>
 103
 104  <listitem>
 105   <para>
 106    Modularized configuration that will allow for system wide settings, and
 107    individual user settings.
 108   </para>
 109  </listitem>
 110
 111  <listitem>
 112   <para>
 113    A browser based GUI configuration utility.
 114   </para>
 115  </listitem>
 116
 117  <listitem>
 118   <para>
 119     Blocking of annoying pop-up browser windows (previously available as a
 120     patch).
 121   </para>
 122  </listitem>
 123
 124  <listitem>
 125   <para>
 126    Partial support for HTTP/1.1.
 127   </para>
 128  </listitem>
 129
 130  <listitem>
 131   <para>
 132    Support for Perl Compatible Regular Expressions in the configuration files, and
 133    generally a more sophisticated configuration syntax over previous versions.
 134   </para>
 135  </listitem>
 136
 137  <listitem>
 138   <para>
 139    Web page content filtering.
 140   </para>
 141  </listitem>
 142
 143  <listitem>
 144   <para>
 145    Multi-threaded.
 146   </para>
 147  </listitem>
 148
 149  </itemizedlist>
 150 </para>
 151
 152 </sect2>
 153
 154 </sect1>
 155
 156 <!--  ~  End section  ~  -->
 157
 158
 159 <!--   ~~~~~       New section      ~~~~~     -->
 160 <sect1 id="installation"><title>Installation</title>
 161 <para>
 162  <application>Junkbuster</application> is available as raw source code, or
 163  pre-compiled binaries. See the <ulink
 164  url="http://sourceforge.net/projects/ijbswa/">Junkbuster Home Page</ulink>
 165  for current releases. <application>Junkbuster</application> is also available
 166  via <ulink
 167  url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/current/">CVS</ulink>.
 168  This is the recommended approach at this time. But please be aware that CVS
 169  is constantly changing, and it may break in mysterious ways.
 170 </para>
 171
 172 <!--   ~~~~~       New section      ~~~~~     -->
 173 <sect2 id="installation-source"><title>Source</title>
 174 <para>
 175  For gzipped tar archives, unpack the source:
 176 </para>
 177
 178 <para>
 179  <screen>
 180  tar zxvf ijb_source_2.9*
 181  cd ijb_source_2.9*
 182  </screen>
 183 </para>
 184
 185 <para>
 186  For retrieving the current CVS sources, you'll need the CVS
 187  package installed first. To download CVS source:
 188 </para>
 189
 190 <para>
 191  <screen>
 192   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
 193   cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co current
 194   cd current
 195  </screen>
 196 </para>
 197
 198 <para>
 199  This will create a directory named <filename>current/</filename>, which will
 200  contain the source tree.
 201 </para>
 202
 203 <para>
 204  Then, in either case, to build from source:
 205 </para>
 206
 207 <para>
 208  <screen>
 209  ./configure
 210  make
 211  su
 212  make install
 213  </screen>
 214 </para>
 215
 216 <para>
 217  For Redhat and SuSE Linux RPM packages, see below.
 218 </para>
 219
 220 </sect2>
 221
 222
 223 <!--   ~~~~~       New section      ~~~~~     -->
 224 <sect2 id="installation-rh"><title>Red Hat</title>
 225 <para>
 226  To build Redhat RPM packages, install source as above. Then:
 227 </para>
 228
 229 <para>
 230  <screen>
 231  ./configure
 232  make redhat-dist
 233  </screen>
 234 </para>
 235
 236 <para>
 237  This will create both binary and src RPMs in the usual places. Example:
 238 </para>
 239
 240 <para>
 241  &nbsp;&nbsp;&nbsp;/usr/src/redhat/RPMS/i686/junkbuster-2.9.8-1.i686.rpm
 242 </para>
 243 <para>
 244  &nbsp;&nbsp;&nbsp;/usr/src/redhat/SRPMS/junkbuster-2.9.8-1.src.rpm
 245 </para>
 246
 247 <para>
 248  To install, of course:
 249 </para>
 250
 251 <para>
 252  <screen>
 253  rpm -Uvv /usr/src/redhat/RPMS/i686/junkbuster-2.9.8-1.i686.rpm
 254  </screen>
 255 </para>
 256
 257 <para>
 258  This will place the <application>Junkbuster</application> configuration
 259  files in <filename>/etc/junkbuster/</filename>, and log files in
 260  <filename>/var/log/junkbuster/</filename>.
 261 </para>
 262
 263 </sect2>
 264
 265 <!--   ~~~~~       New section      ~~~~~     -->
 266 <sect2 id="installation-suse"><title>SuSE</title>
 267 <para>
 268  To build SuSE RPM packages, install source as above. Then:
 269 </para>
 270
 271 <para>
 272  <screen>
 273  ./configure
 274  make suse-dist
 275  </screen>
 276 </para>
 277
 278 <para>
 279  This will create both binary and src RPMs in the usual places. Example:
 280 </para>
 281
 282 <para>
 283  &nbsp;&nbsp;&nbsp;/usr/src/suse/RPMS/i686/junkbuster-2.9.8-1.i686.rpm
 284 </para>
 285 <para>
 286  &nbsp;&nbsp;&nbsp;/usr/src/suse/SRPMS/junkbuster-2.9.8-1.src.rpm
 287 </para>
 288
 289 <para>
 290  To install, of course:
 291 </para>
 292
 293 <para>
 294  <screen>
 295  rpm -Uvv /usr/src/suse/RPMS/i686/junkbuster-2.9.8-1.i686.rpm
 296  </screen>
 297 </para>
 298
 299 <para>
 300  This will place the <application>Junkbuster</application> configuration
 301  files in <filename>/etc/junkbuster/</filename>, and log files in
 302  <filename>/var/log/junkbuster/</filename>.
 303 </para>
 304
 305 </sect2>
 306
 307
 308 <!--   ~~~~~       New section      ~~~~~     -->
 309 <sect2 id="installation-os2"><title>OS/2</title>
 310
 311 <!--
 312 Thanx David Schmidt!
 313 -->
 314
 315 <para>
 316  The OS/2 version of <application>Junkbuster</application> requires the EMX
 317  runtime library to be installed.  The EMX runtime library is available on
 318  the hobbes OS/2 archive, among many other locations:
 319  <ulink url="http://hobbes.nmsu.edu/cgi-bin/h-search?sh=1&amp;button=Search&amp;key=emxrt.zip&amp;stype=all&amp;sort=type&amp;dir=%2Fpub%2Fos2%2Fdev%2Femx%2Fv0.9d">http://hobbes.nmsu.edu/cgi-bin/h-search?sh=1&amp;button=Search&amp;key=emxrt.zip&amp;stype=all&amp;sort=type&amp;dir=%2Fpub%2Fos2%2Fdev%2Femx%2Fv0.9d</ulink>
 320 </para>
 321
 322 <para>
 323  <application>Junkbuster</application> is packaged in a WarpIN self-
 324  installing archive.  The self-installing program will be named depending
 325  on the release version, something like:
 326  <filename>ijbos123.exe</filename>.  In order to install it, simply run
 327  this executable or double-click on its icon and follow the WarpIN
 328  installation panels.  A shadow of the <application>Junkbuster</application>
 329  executable will be placed in your startup folder so it will start
 330  automatically whenever OS/2 starts.
 331 </para>
 332
 333 <para>
 334  The directory you choose to install <application>Junkbuster</application>
 335  into will contain all of the configuration files.
 336 </para>
 337
 338 <para>
 339  If you would like to build binary images on OS/2 yourself, you will need
 340  a working EMX/GCC environment, plus several Unix-like tools.  The Hobbes
 341  OS/2 archive is a good place to start when building such an environment.
 342  A set of Unix-like tools named gnupack is located here:
 343  <ulink url="http://hobbes.nmsu.edu/cgi-bin/h-search?sh=1&amp;key=gnupack&amp;stype=all&amp;sort=type&amp;dir=%2Fpub%2Fos2%2Fapps">http://hobbes.nmsu.edu/cgi-bin/h-search?sh=1&amp;key=gnupack&amp;stype=all&amp;sort=type&amp;dir=%2Fpub%2Fos2%2Fapps</ulink>
 344 </para>
 345 <para>
 346  Once you have the source code unpacked as above, you can build the binaries
 347  from the <filename>current/</filename> directory:
 348 </para>
 349
 350 <para>
 351  <screen>
 352  autoconf
 353  sh configure
 354  make
 355  </screen>
 356 </para>
 357
 358 </sect2>
 359
 360
 361 <!--   ~~~~~       New section      ~~~~~     -->
 362 <sect2 id="installation-win"><title>Windows</title>
 363 <para>I need help on this. Not a clue here. Also for
 364 configuration section below.
 365 </para>
 366 </sect2>
 367
 368 <!--   ~~~~~       New section      ~~~~~     -->
 369 <sect2 id="installation-other"><title>Other</title>
 370 <para>
 371  Some quick notes on other Operating Systems.
 372 </para>
 373
 374 <para>
 375  For FreeBSD (and other *BSDs?), the build will need <command>gmake</command>
 376  instead of the included <command>make</command>. <command>gmake</command> is
 377  available from <ulink url="http://www.gnu.org">http://www.gnu.org</ulink>.
 378  The rest should be the same as above for Linux/Unix.
 379 </para>
 380
 381 </sect2>
 382
 383 </sect1>
 384
 385 <!--  ~  End section  ~  -->
 386
 387
 388 <!--   ~~~~~       New section      ~~~~~     -->
 389 <sect1 id="configuration"><title>Junkbuster Configuration</title>
 390 <para>
 391  For Unix, *BSD and Linux, all configuraton files are located in
 392  <filename>/etc/junkbuster/</filename> by default. For MS Windows and OS/2,
 393  these are all in the same directory as the
 394  <application>Junkbuster</application> executable. The name and number of
 395  configuration files has changed from previous versions, and is subject to
 396  change as development progresses.
 397 </para>
 398
 399 <para>
 400  The installed defaults provide a reasonable starting point. For the
 401  time being, there are only three default configuration files (this will
 402  change in time):
 403 </para>
 404
 405 <para>
 406  <itemizedlist>
 407
 408   <listitem>
 409    <para>
 410      The main configuration file is named <filename>config</filename>
 411      on Linux, Unix, BSD, and OS/2, and <filename>junkbustr.txt</filename> on
 412      Windows.
 413    </para>
 414   </listitem>
 415
 416   <listitem>
 417    <para>
 418     The <filename>actionsfile</filename> file is used  to define various
 419     actions relating to images, banners, pop-ups, banners and cookies.
 420    </para>
 421   </listitem>
 422
 423   <listitem>
 424    <para>
 425     The <filename>re_filterfile</filename> file can be used to rewrite the raw
 426     page content, including text as well as embedded HTML and JavaScript.
 427    </para>
 428   </listitem>
 429
 430  </itemizedlist>
 431 </para>
 432
 433 <para>
 434  <filename>actionsfile</filename> and <filename>re_filterfile</filename>
 435  can use Perl style regular expressions for maximum flexibility. All files use
 436  the <quote><literal>#</literal></quote> character to denote a comment. Such
 437  lines are not processed by <application>Junkbuster</application>. After
 438  making any changes, restart <application>Junkbuster</application> in order
 439  for the changes to take effect.
 440 </para>
 441
 442
 443 <!--   ~~~~~       New section      ~~~~~     -->
 444
 445 <sect2>
 446 <title>The Main Configuration File</title>
 447 <para>
 448  Again, the main configuration file is named <filename>config</filename> on
 449  Linux/Unix/BSD and OS/2, and <filename>junkbustr.txt</filename> on Windows.
 450  Configuration lines consist of an initial keyword followed by a list of
 451  values, all separated by whitespace (any number of spaces or tabs). For
 452  example:
 453 </para>
 454
 455 <para>
 456  <literal>
 457   <MSGText>
 458    <literallayout>
 459   <emphasis>blockfile blocklist.ini</emphasis>
 460    </literallayout>
 461   </MSGText>
 462  </literal>
 463 </para>
 464
 465 <para>
 466  Indicates that the blockfile is named <quote>blocklist.ini</quote>.
 467 </para>
 468
 469 <para>
 470  The <quote><literal>#</literal></quote> indicates a comment.  Any part of a
 471  line following a <quote><literal>#</literal></quote> is ignored, except if
 472  the <quote><literal>#</literal></quote> is preceded by a
 473  <quote><literal>\</literal></quote>.
 474 </para>
 475
 476 <para>
 477  Thus, by placing a <quote><literal>#</literal></quote> at the start of an
 478  existing configuration line, you can make it a comment and it will be treated
 479  as if it weren't there. This is called <quote>commenting out</quote> an
 480  option and can be useful to turn off features: If you comment out the
 481  <quote>logfile</quote> line, <application>junkbuster</application> will not
 482  log to a file at all. Watch for the <quote>default:</quote> section in each
 483  explanation to see what happens if the option is left unset (or commented
 484  out).
 485 </para>
 486
 487 <para>
 488  Long lines can be continued on the next line by using a
 489  <quote><literal>\</literal></quote> as the very last character.
 490 </para>
 491
 492 <para>
 493  There are various aspects of <application>Junkbuster</application> behavior
 494  that can be adjusted.
 495 </para>
 496
 497
 498 <!--   ~~~~~       New section      ~~~~~     -->
 499
 500 <sect3>
 501 <title>Defining Other Configuration Files</title>
 502
 503 <para>
 504  <application>Junkbuster</application> can use a number of other files to tell it
 505  what ads to block, what cookies to accept, etc.  This section of the
 506  configuration file tells <application>Junkbuster</application> where to find
 507  all those other files.
 508 </para>
 509
 510 <para>
 511  On <application>Windows</application>, <application>Junkbuster</application>
 512  looks for these files in the same directory as the executable.  On Unix and
 513  OS/2, <application>Junkbuster</application> looks for these files in the current
 514  working directory.  In either case, an absolute path name can be used to
 515  avoid problems.
 516 </para>
 517
 518 <para>
 519  When development goes modular and multiuser, the blocker, filter, and
 520  per-user config will be stored in subdirectories of <quote>confdir</quote>.
 521  For now, only <filename>confdir/templates</filename> is used for storing HTML
 522  templates for CGI results.
 523 </para>
 524
 525 <para>
 526  The location of the configuration files:
 527 </para>
 528
 529 <para>
 530  <literal>
 531   <MSGText>
 532    <literallayout>
 533   <emphasis>confdir  /etc/junkbuster</emphasis>       # No trailing /, please.
 534    </literallayout>
 535   </MSGText>
 536  </literal>
 537 </para>
 538
 539 <para>
 540  The directory where all logging (i.e. <filename>logfile</filename> and
 541  <filename>jarfile</filename>) takes place. No trailing
 542  <quote><literal>/</literal></quote>, please:
 543 </para>
 544
 545 <para>
 546  <literal>
 547   <MSGText>
 548    <literallayout>
 549   <emphasis>logdir  /var/log/junkbuster</emphasis>
 550    </literallayout>
 551   </MSGText>
 552  </literal>
 553 </para>
 554
 555 <para>
 556  Note that all file specifications below are relative to
 557  the above two directories!
 558 </para>
 559
 560 <para>
 561  The <quote>actionsfile</quote> contains patterns to specify the actions to
 562  apply to requests for each site. Default: Cookies to and from all
 563  destinations are filtered. Popups are disabled for all sites. All sites are
 564  filtered if re_filterfile specified. No sites are blocked. An empty image is
 565  displayed for filtered ads and other images (formerly
 566  <quote>tinygif</quote>). The syntax of this file is explained in detail
 567  <link linkend="actionsfile">below</link>.
 568 </para>
 569
 570 <para>
 571  <literal>
 572   <MSGText>
 573    <literallayout>
 574   <emphasis>actionsfile  actionsfile</emphasis>
 575    </literallayout>
 576   </MSGText>
 577  </literal>
 578 </para>
 579
 580 <para>
 581  The <quote>re_filterfile</quote> file contains content modification rules.
 582  These rules permit powerful changes on the content of Web pages, e.g., you
 583  could disable your favourite JavaScript annoyances, rewrite the actual
 584  content, or just have some fun replacing <quote>Microsoft</quote> with
 585  <quote>MicroSuck</quote> wherever it appears on a Web page. Default: No
 586  content modification, or whatever the developers are playing with :-/
 587 </para>
 588
 589 <para>
 590  <literal>
 591   <MSGText>
 592    <literallayout>
 593   <emphasis>re_filterfile  re_filterfile</emphasis>
 594    </literallayout>
 595   </MSGText>
 596  </literal>
 597 </para>
 598
 599 <para>
 600  The logfile is where all logging and error messages are written. The logfile
 601  can be useful for tracking down a problem with
 602  <application>Junkbuster</application> (e.g., it's not blocking an ad you
 603  think it should block) but in most cases you probably will never look at it.
 604 </para>
 605
 606 <para>
 607  Your logfile will grow indefinitely, and you will probably want to
 608  periodically remove it.  On Unix systems, you can do this with a cron job
 609  (see <quote>man cron</quote>). For Redhat, a <command>logrotate</command>
 610  script has been included.
 611 </para>
 612
 613 <para>
 614  On SuSE Linux systems, you can place a line like <quote>/var/log/junkbuster.*
 615  +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
 616  the effect that cron.daily will automatically archive, gzip, and empty the
 617  log, when it exceeds 1M size.
 618 </para>
 619
 620 <para>
 621  Default: Log to the a file named <filename>logfile</filename>.
 622  Comment out to disable logging.
 623 </para>
 624
 625 <para>
 626  <literal>
 627   <MSGText>
 628    <literallayout>
 629   <emphasis>logfile  logfile</emphasis>
 630    </literallayout>
 631   </MSGText>
 632  </literal>
 633 </para>
 634
 635 <para>
 636  The <quote>jarfile</quote> defines where
 637  <application>Junkbuster</application> stores the cookies it intercepts.  Note
 638  that if you use a <quote>jarfile</quote>, it may grow quite large. Default:
 639  Don't store intercepted cookies.
 640 </para>
 641
 642 <para>
 643  <literal>
 644   <MSGText>
 645    <literallayout>
 646   <emphasis>#jarfile  jarfile</emphasis>
 647    </literallayout>
 648   </MSGText>
 649  </literal>
 650 </para>
 651
 652 <para>
 653  If you specify a <quote>trustfile</quote>,
 654  <application>Junkbuster</application> will only allow access to sites that
 655  are named in the trustfile. You can also mark sites as trusted referrers,
 656  with the effect that access to untrusted sites will be granted, if a link
 657  from a trusted referrer was used. The link target will then be added to the
 658  <quote>trustfile</quote>. This is a very restrictive feature that typical
 659  users most propably want to leave disabled. Default: Disabled, don't use the
 660  trust mechanism.
 661 </para>
 662
 663 <para>
 664  <literal>
 665   <MSGText>
 666    <literallayout>
 667   <emphasis>#trustfile  trust</emphasis>
 668    </literallayout>
 669   </MSGText>
 670  </literal>
 671 </para>
 672
 673 <para>
 674  If you use the trust mechanism, it is a good idea to write up some online
 675  documentation about your blocking policy and to specify the URL(s) here. They
 676  will appear on the page that your users receive when they try to access
 677  untrusted content. Use multiple times for multiple URLs. Default: Don't
 678  display links on the <quote>untrusted</quote> info page.
 679 </para>
 680
 681 <para>
 682  <literal>
 683   <MSGText>
 684    <literallayout>
 685   <emphasis>trust-info-url http://www.your-site.com/why_we_block.html</emphasis>
 686   <emphasis>trust-info-url http://www.your-site.com/what_we_allow.html</emphasis>
 687    </literallayout>
 688   </MSGText>
 689  </literal>
 690 </para>
 691
 692 </sect3>
 693
 694 <!--  ~  End section  ~  -->
 695
 696
 697
 698 <!--   ~~~~~       New section      ~~~~~     -->
 699
 700 <sect3>
 701 <title>Other Configuration Options</title>
 702
 703 <para>
 704  This part of the configuration file contains options that control how
 705  <application>Junkbuster</application> operates.
 706 </para>
 707
 708 <para>
 709  <quote>Admin-address</quote> should be set to the email address of the proxy
 710  administrator. It is used in many of the proxy-generated pages. Default:
 711  fill@me.in.please.
 712 </para>
 713
 714 <para>
 715  <literal>
 716   <MSGText>
 717    <literallayout>
 718   <emphasis>#admin-address  fill@me.in.please</emphasis>
 719    </literallayout>
 720   </MSGText>
 721  </literal>
 722 </para>
 723
 724 <para>
 725  <quote>Proxy-info-url</quote> can be set to a URL that contains more info
 726  about this <application>Junkbuster</application> installation, it's
 727  configuration and policies. It is used in many of the proxy-generated pages
 728  and its use is highly recommended in multi-user installations, since your
 729  users will want to know why certain content is blocked or modified. Default:
 730  Don't show a link to online documentation.
 731 </para>
 732
 733 <para>
 734  <literal>
 735   <MSGText>
 736    <literallayout>
 737   <emphasis>proxy-info-url  http://www.your-site.com/proxy.html</emphasis>
 738    </literallayout>
 739   </MSGText>
 740  </literal>
 741 </para>
 742
 743 <para>
 744  <quote>Listen-address</quote> specifies the address and port where
 745  <application>Junkbuster</application> will listen for connections from your
 746  Web browser.  The default is to listen on the localhost port 8000, and
 747  this is suitable for most users.  (In your web browser, under proxy
 748  configuration, list the proxy server as <quote>localhost</quote> and the
 749  port as <quote>8000</quote>).
 750 </para>
 751
 752 <para>
 753  If you already have another service running on port 8000, or if you want to
 754  serve requests from other machines (e.g. on your local network) as well, you
 755  will need to override the default. The syntax is
 756  <quote>listen-address [&lt;ip-address&gt;]:&lt;port&gt;</quote>. If you leave
 757  out the IP adress, <application>junkbuster</application> will bind to all
 758  interfaces (addresses) on your machine and may become reachable from the
 759  internet. In that case, consider using access control lists (acl's) (see
 760  <quote>aclfile</quote> above).
 761 </para>
 762
 763 <para>
 764  For example, suppose you are running <application>Junkbuster</application> on
 765  a machine which has the address 192.168.0.1 on your local private network
 766  (192.168.0.0) and has another outside connection with a different address.
 767  You want it to serve requests from inside only:
 768 </para>
 769
 770 <para>
 771  <literal>
 772   <MSGText>
 773    <literallayout>
 774   <emphasis>listen-address  192.168.0.1:8000</emphasis>
 775    </literallayout>
 776   </MSGText>
 777  </literal>
 778 </para>
 779
 780 <para>
 781  If you want it to listen on all addresses (including the outside
 782  connection):
 783 </para>
 784
 785 <para>
 786  <literal>
 787   <MSGText>
 788    <literallayout>
 789   <emphasis>listen-address  :8000</emphasis>
 790    </literallayout>
 791   </MSGText>
 792  </literal>
 793 </para>
 794
 795 <para>
 796  If you do this, consider using ACLs (see <quote>aclfile</quote> above). Note:
 797  you will need to point your browser(s) to the address and port that you have
 798  configured here. Default: localhost:8000 (127.0.0.1:8000).
 799 </para>
 800
 801 <para>
 802  The debug option sets the level of debugging information to log in the
 803  logfile (and to the console in the Windows version).  A debug level of 1 is
 804  informative because it will show you each request as it happens.  Higher
 805  levels of debug are probably only of interest to developers.
 806 </para>
 807
 808 <Para>
 809  <Literal>
 810   <MSGText>
 811    <LiteralLayout>
 812   debug         1 # GPC   = show each GET/POST/CONNECT request
 813   debug         2 # CONN  = show each connection status
 814   debug         4 # IO    = show I/O status
 815   debug         8 # HDR   = show header parsing
 816   debug        16 # LOG   = log all data into the logfile
 817   debug        32 # FRC   = debug force feature
 818   debug        64 # REF   = debug regular expression filter
 819   debug       128 #       = debug fast redirects
 820   debug       256 #       = debug GIF deanimation
 821   debug       512 # CLF   = Common Log Format
 822   debug      1024 #       = debug kill popups
 823   debug      4096 # INFO  = Startup banner and warnings.
 824   debug      8192 # ERROR = Non-fatal errors
 825     </LiteralLayout>
 826   </MSGText>
 827  </Literal>
 828 </Para>
 829
 830 <para>
 831  It is <emphasis>highly recommended</emphasis> that you enable ERROR
 832  reporting (debug 8192), at least until the next stable release.
 833 </para>
 834
 835 <para>
 836  The reporting of FATAL errors (i.e. ones which crash
 837  <application>JunkBuster</application>) is always on and cannot be disabled.
 838 </para>
 839
 840 <para>
 841  If you want to use CLF (Common Log Format), you should set <quote>debug
 842  512</quote> ONLY, do not enable anything else.
 843 </para>
 844
 845 <para>
 846  Multiple <quote>debug</quote> directives, are OK - they're logical-OR'd
 847  together.
 848 </para>
 849
 850 <para>
 851  <literal>
 852   <MSGText>
 853    <literallayout>
 854   <emphasis>debug    15     # same as setting the first 4 listed above</emphasis>
 855    </literallayout>
 856   </MSGText>
 857  </literal>
 858 </para>
 859
 860 <para>
 861  Default:
 862 </para>
 863
 864 <para>
 865  <literal>
 866   <MSGText>
 867    <literallayout>
 868   <emphasis>debug   1     # URLs</emphasis>
 869   <emphasis>debug   4096  # Info</emphasis>
 870   <emphasis>debug   8192  # Errors - *we highly recommended enabling this*</emphasis>
 871    </literallayout>
 872   </MSGText>
 873  </literal>
 874 </para>
 875
 876 <para>
 877  <application>Junkbuster</application> normally uses
 878  <quote>multi-threading</quote>, a software technique that permits it to
 879  handle many different requests simultaneously. In some cases you may wish to
 880  disable this -- particularly if you're trying to debug a problem.  The
 881  <quote>single-threaded</quote> option forces
 882  <application>Junkbuster</application> to handle requests sequentially.
 883  Default: Multi-threaded mode.
 884 </para>
 885
 886 <para>
 887  <literal>
 888   <MSGText>
 889    <literallayout>
 890   <emphasis>#single-threaded</emphasis>
 891    </literallayout>
 892   </MSGText>
 893  </literal>
 894 </para>
 895
 896 <para>
 897  <quote>toggle</quote> allows you to temporarily disable all
 898  <application>Junkbuster's</application>  filtering. Just set <quote>toggle
 899  0</quote>.
 900 </para>
 901
 902 <para>
 903  The Windows version of <application>Junkbuster</application> puts an icon in
 904  the system tray, which allows you to change this option without having to
 905  edit this file.  If you right-click on that icon (or select the
 906  <quote>Options</quote> menu), one choice is <quote>Enable</quote>. Clicking
 907  on enable toggles <application>Junkbuster</application> on and off. This is
 908  useful if you want to temporarily disable
 909  <application>Junkbuster</application>, e.g., to access a site that requires
 910  cookies which you normally have blocked.
 911 </para>
 912
 913 <para>
 914  <quote>toggle 1</quote> means <application>Junkbuster</application> runs
 915  normally, <quote>toggle 0</quote> means that
 916  <application>Junkbuster</application> becomes a non-anonymizing non-blocking
 917  proxy. Default: 1.
 918 </para>
 919
 920 <para>
 921  <literal>
 922   <MSGText>
 923    <literallayout>
 924   <emphasis>toggle    1</emphasis>
 925    </literallayout>
 926   </MSGText>
 927  </literal>
 928 </para>
 929
 930 </sect3>
 931
 932 <!--  ~  End section  ~  -->
 933
 934
 935 <!--   ~~~~~       New section      ~~~~~     -->
 936
 937 <sect3>
 938 <title>Access Control List (ACL)</title>
 939 <para>
 940  Access controls are included at the request of some ISPs and systems
 941  administrators, and are not usually needed by individual users. Please note
 942  the warnings in the FAQ that this proxy is not intended to be a substitute
 943  for a firewall or to encourage anyone to defer addressing basic security
 944  weaknesses.
 945 </para>
 946
 947 <para>
 948  If no access settings are specified, the proxy talks to anyone that
 949  connects. If any access settings file are specified, then the proxy
 950  talks only to IP addresses permitted somewhere in this file and not
 951  denied later in this file.
 952 </para>
 953
 954 <para>
 955  Summary -- if using an ACL:
 956 </para>
 957
 958  <simplelist>
 959   <member>
 960    Client must have permission to receive service.
 961   </member>
 962  </simplelist>
 963  <simplelist>
 964   <member>
 965    LAST match in ACL wins.
 966   </member>
 967  </simplelist>
 968  <simplelist>
 969   <member>
 970    Default behavior is to deny service.
 971   </member>
 972  </simplelist>
 973
 974 <para>
 975  The syntax for an entry in the Access Control List is:
 976 </para>
 977
 978 <para>
 979  <literal>
 980   <MSGText>
 981    <literallayout>
 982   ACTION    SRC_ADDR[/SRC_MASKLEN]    [ DST_ADDR[/DST_MASKLEN] ]
 983    </literallayout>
 984   </MSGText>
 985  </literal>
 986 </para>
 987
 988 <para>
 989  Where the individual fields are:
 990 </para>
 991
 992 <para>
 993  <literal>
 994   <MSGText>
 995    <literallayout>
 996  <emphasis>ACTION</emphasis>      = <quote>permit-access</quote> or <quote>deny-access</quote>
 997
 998  <emphasis>SRC_ADDR</emphasis>    = client hostname or dotted IP address
 999  <emphasis>SRC_MASKLEN</emphasis> = number of bits in the subnet mask for the source
1000
1001  <emphasis>DST_ADDR</emphasis>    = server or forwarder hostname or dotted IP address
1002  <emphasis>DST_MASKLEN</emphasis> = number of bits in the subnet mask for the target
1003    </literallayout>
1004   </MSGText>
1005  </literal>
1006 </para>
1007
1008
1009 <para>
1010  The field separator (FS) is whitespace (space or tab).
1011 </para>
1012
1013 <para>
1014  IMPORTANT NOTE: If the <application>junkbuster</application> is using a
1015  forwarder (see below) or a gateway for a particular destination URL, the
1016  <literal>DST_ADDR</literal> that is examined is the address of the forwarder
1017  or the gateway and <emphasis>NOT</emphasis> the address of the ultimate
1018  target. This is necessary because it may be impossible for the local
1019  <application>Junkbuster</application> to determine the address of the
1020  ultimate target (that's often what gateways are used for).
1021 </para>
1022
1023 <para>
1024  Here are a few examples to show how the ACL features work:
1025 </para>
1026
1027 <para>
1028  <quote>localhost</quote> is OK -- no DST_ADDR implies that
1029  <emphasis>ALL</emphasis> destination addresses are OK:
1030 </para>
1031
1032 <para>
1033  <literal>
1034   <MSGText>
1035    <literallayout>
1036   <emphasis>permit-access  localhost</emphasis>
1037    </literallayout>
1038   </MSGText>
1039  </literal>
1040 </para>
1041
1042 <para>
1043  A silly example to illustrate permitting any host on the class-C subnet with
1044  <application>Junkbuster</application> to go anywhere:
1045 </para>
1046
1047 <para>
1048  <literal>
1049   <MSGText>
1050    <literallayout>
1051   <emphasis>permit-access    www.junkbusters.com/24</emphasis>
1052    </literallayout>
1053   </MSGText>
1054  </literal>
1055 </para>
1056
1057 <para>
1058  Except deny one particular IP address from using it at all:
1059 </para>
1060
1061 <para>
1062  <literal>
1063   <MSGText>
1064    <literallayout>
1065   <emphasis>deny-access      ident.junkbusters.com</emphasis>
1066    </literallayout>
1067   </MSGText>
1068  </literal>
1069 </para>
1070
1071 <para>
1072  You can also specify an explicit network address and subnet mask.
1073  Explicit addresses do not have to be resolved to be used.
1074 </para>
1075
1076 <para>
1077  <literal>
1078   <MSGText>
1079    <literallayout>
1080   <emphasis>permit-access    207.153.200.0/24</emphasis>
1081    </literallayout>
1082   </MSGText>
1083  </literal>
1084 </para>
1085
1086 <para>
1087  A subnet mask of 0 matches anything, so the next line permits everyone.
1088 </para>
1089
1090 <para>
1091  <literal>
1092   <MSGText>
1093    <literallayout>
1094   <emphasis>permit-access    0.0.0.0/0</emphasis>
1095    </literallayout>
1096   </MSGText>
1097  </literal>
1098 </para>
1099
1100 <para>
1101  Note, you <emphasis>cannot</emphasis> say:
1102 </para>
1103
1104 <para>
1105  <literal>
1106   <MSGText>
1107    <literallayout>
1108   <emphasis>permit-access    .org</emphasis>
1109    </literallayout>
1110   </MSGText>
1111  </literal>
1112 </para>
1113
1114 <para>
1115  to allow all *.org domains. Every IP address listed must resolve fully.
1116 </para>
1117
1118 <para>
1119  An ISP may want to provide a <application>Junkbuster</application> that is
1120  accessible by <quote>the world</quote> and yet restrict use of some of their
1121  private content to hosts on its internal network (i.e. its own subscribers).
1122  Say, for instance the ISP owns the Class-B IP address block 123.124.0.0 (a 16
1123  bit netmask). This is how they could do it:
1124 </para>
1125
1126 <para>
1127  <literal>
1128   <MSGText>
1129    <literallayout>
1130  <emphasis>permit-access 0.0.0.0/0   0.0.0.0/0</emphasis>   # other clients can go anywhere
1131                                        # with the following exceptions:
1132
1133  <emphasis>deny-access</emphasis>   0.0.0.0/0   123.124.0.0/16 # block all external requests for
1134                                           # sites on the ISP's network
1135
1136  <emphasis>permit 0.0.0.0/0   www.my_isp.com</emphasis>        # except for the ISP's main
1137                                           # web site
1138
1139  <emphasis>permit 123.124.0.0/16 0.0.0.0/0</emphasis>          # the ISP's clients can go
1140                                           # anywhere
1141    </literallayout>
1142   </MSGText>
1143  </literal>
1144 </para>
1145
1146 <para>
1147  Note that if some hostnames are listed with multiple IP addresses,
1148  the primary value returned by DNS (via gethostbyname()) is used. Default:
1149  Anyone can access the proxy.
1150 </para>
1151
1152 </sect3>
1153
1154 <!--  ~  End section  ~  -->
1155
1156
1157 <!--   ~~~~~       New section      ~~~~~     -->
1158
1159 <sect3>
1160 <title>Forwarding</title>
1161
1162 <para>
1163  This feature allows routing of HTTP requests via multiple proxies.
1164  It can be used to better protect privacy and confidentiality when
1165  accessing specific domains by routing requests to those domains
1166  to a special purpose filtering proxy such as lpwa.com.
1167 </para>
1168
1169 <para>
1170  It can also be used in an environment with multiple networks to route
1171  requests via multiple gateways allowing transparent access to multiple
1172  networks without having to modify browser configurations.
1173 </para>
1174
1175 <para>
1176  Also specified here are SOCKS proxies. <application>Junkbuster</application>
1177  SOCKS 4 and SOCKS 4A. The difference is that SOCKS 4A will resolve the target
1178  hostname using DNS on the SOCKS server, not our local DNS client.
1179 </para>
1180
1181 <para>
1182  The syntax of each line is:
1183 </para>
1184
1185 <para>
1186  <literal>
1187   <MSGText>
1188    <literallayout>
1189  <emphasis>forward target_domain[:port] http_proxy_host[:port]</emphasis>
1190  <emphasis>forward-socks4  target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port]</emphasis>
1191  <emphasis>forward-socks4a target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port]</emphasis>
1192    </literallayout>
1193   </MSGText>
1194  </literal>
1195 </para>
1196
1197 <para>
1198  If http_proxy_host is <quote>.</quote>, then requests are not forwarded to a
1199  HTTP proxy but are made directly to the web servers.
1200 </para>
1201
1202 <para>
1203  Lines are checked in sequence, and the last match wins.
1204 </para>
1205
1206 <para>
1207  There is an implicit line equivalent to the following, which specifies that
1208  anything not finding a match on the list is to go out without forwarding
1209  or gateway protocol, like so:
1210 </para>
1211
1212 <para>
1213  <literal>
1214   <MSGText>
1215    <literallayout>
1216   <emphasis>forward   .*   .       </emphasis># implicit
1217    </literallayout>
1218   </MSGText>
1219  </literal>
1220 </para>
1221
1222 <para>
1223  In the following common configuration, everything goes to Lucent's LPWA,
1224  except SSL on port 443 (which it doesn't handle):
1225 </para>
1226
1227 <para>
1228  <literal>
1229   <MSGText>
1230    <literallayout>
1231  <emphasis>forward   .*     lpwa.com:8000</emphasis>
1232  <emphasis>forward   :443   .</emphasis>
1233    </literallayout>
1234   </MSGText>
1235  </literal>
1236 </para>
1237
1238 <para>
1239  See the FAQ for instructions on how to automate the login procedure for LPWA.
1240  Some users have reported difficulties related to LPWA's use of
1241  <quote>.</quote> as the last element of the domain, and have said that this
1242  can be fixed with this:
1243 </para>
1244
1245 <para>
1246  <literal>
1247   <MSGText>
1248    <literallayout>
1249   <emphasis>forward   lpwa.  lpwa.com:8000</emphasis>
1250    </literallayout>
1251   </MSGText>
1252  </literal>
1253 </para>
1254
1255 <para>
1256  (NOTE: the syntax for specifiying target_domain has changed since the
1257  previous paragraph was written -- it will not work now.  More information
1258  is welcome.)
1259 </para>
1260
1261 <para>
1262  In this fictitious example, everything goes via an ISP's caching proxy,
1263  except requests to that ISP:
1264 </para>
1265
1266 <para>
1267  <literal>
1268   <MSGText>
1269    <literallayout>
1270  <emphasis>forward    .*         caching.myisp.net:8000</emphasis>
1271  <emphasis>forward    myisp.net  .</emphasis>
1272    </literallayout>
1273   </MSGText>
1274  </literal>
1275 </para>
1276
1277 <para>
1278  For the @home network, we're told the forwarding configuration is this:
1279 </para>
1280
1281
1282 <para>
1283  <literal>
1284   <MSGText>
1285    <literallayout>
1286   <emphasis>forward    .*    proxy:8080</emphasis>
1287    </literallayout>
1288   </MSGText>
1289  </literal>
1290 </para>
1291
1292 <para>
1293  Also, we're told they insist on getting cookies and JavaScript, so you need
1294  to add home.com to the cookie file. We consider JavaScript a security risk.
1295  Java need not be enabled.
1296 </para>
1297
1298 <para>
1299  In this example direct connections are made to all <quote>internal</quote>
1300  domains, but everything else goes through Lucent's LPWA by way of the
1301  company's SOCKS gateway to the Internet.
1302 </para>
1303
1304 <para>
1305  <literal>
1306   <MSGText>
1307    <literallayout>
1308  <emphasis>forward_socks4  .*  lpwa.com:8000  firewall.my_company.com:1080</emphasis>
1309  <emphasis>forward    my_company.com  .</emphasis>
1310    </literallayout>
1311   </MSGText>
1312  </literal>
1313 </para>
1314
1315 <para>
1316  This is how you could set up a site that always uses SOCKS but no forwarders:
1317 </para>
1318
1319 <para>
1320  <literal>
1321   <MSGText>
1322    <literallayout>
1323   <emphasis>forward_socks4a   .*  .  firewall.my_company.com:1080</emphasis>
1324    </literallayout>
1325   </MSGText>
1326  </literal>
1327 </para>
1328
1329 <para>
1330  An advanced example for network administrators:
1331 </para>
1332
1333 <para>
1334  If you have links to multiple ISPs that provide various special content to
1335  their subscribers, you can configure forwarding to pass requests to the
1336  specific host that's connected to that ISP so that everybody can see all
1337  of the content on all of the ISPs.
1338 </para>
1339
1340 <para>
1341  This is a bit tricky, but here's an example:
1342 </para>
1343
1344
1345 <para>
1346  host-a has a PPP connection to isp-a.com. And host-b has a PPP connection to
1347  isp-b.com. host-a can run a <application>Junkbuster</application> proxy with
1348  forwarding like this:
1349 </para>
1350
1351 <para>
1352  <literal>
1353   <MSGText>
1354    <literallayout>
1355  <emphasis>forward    .*         .</emphasis>
1356  <emphasis>forward    isp-b.com  host-b:8000</emphasis>
1357    </literallayout>
1358   </MSGText>
1359  </literal>
1360 </para>
1361
1362 <para>
1363  host-b can run a <application>Junkbuster</application> proxy with forwarding
1364  like this:
1365 </para>
1366
1367 <para>
1368  <literal>
1369   <MSGText>
1370    <literallayout>
1371  <emphasis>forward    .*          .</emphasis>
1372  <emphasis>forward    isp-a.com   host-a:8000</emphasis>
1373    </literallayout>
1374   </MSGText>
1375  </literal>
1376 </para>
1377
1378 <para>
1379  Now, <emphasis>anyone</emphasis> on the Internet (including users on host-a
1380  and host-b) can set their browser's proxy to <emphasis>either</emphasis>
1381  host-a or host-b and be able to browse the content on isp-a or isp-b.
1382 </para>
1383
1384 <para>
1385  Here's another practical example, for University of Kent at
1386  Canterbury students with a network connection in their room, who
1387  need to use the University's Squid web cache.
1388 </para>
1389
1390 <para>
1391  <literal>
1392   <MSGText>
1393    <literallayout>
1394  <emphasis>forward  *. ssbcache.ukc.ac.uk:3128</emphasis>  # Use the proxy, except for:
1395  <emphasis>forward  .ukc.ac.uk            .    </emphasis> # Anything on the same domain as us
1396  <emphasis>forward  *                     .    </emphasis> # Host with no domain specified
1397  <emphasis>forward  129.12.*.*            .    </emphasis> # A dotted IP on our /16 network.
1398  <emphasis>forward  127.*.*.*             .    </emphasis> # Loopback address
1399  <emphasis>forward  localhost.localdomain .    </emphasis> # Loopback address
1400  <emphasis>forward  www.ukc.mirror.ac.uk  .    </emphasis> # Specific host
1401    </literallayout>
1402   </MSGText>
1403  </literal>
1404 </para>
1405
1406 <para>
1407  If you intend to chain <application>Junkbuster</application> and
1408  <application>squid</application> locally, then chain as
1409  <literal>browser -> squid -> junkbuster</literal> is the recommended way.
1410 </para>
1411
1412 <para>
1413  Your squid configuration could then look like this:
1414 </para>
1415
1416 <para>
1417  <literal>
1418   <MSGText>
1419    <literallayout>
1420   # Define junkbuster as parent cache
1421   cache_peer 127.0.0.1 8000 parent 0 no-query
1422
1423   # Define ACL for protocol FTP
1424   acl FTP proto FTP
1425
1426   # Do not forward ACL FTP to junkbuster
1427   always_direct allow FTP
1428
1429   # Do not forward ACL CONNECT (https) to junkbuster
1430   always_direct allow CONNECT
1431
1432   # Forward the rest to junkbuster
1433   never_direct allow all
1434    </literallayout>
1435   </MSGText>
1436  </literal>
1437 </para>
1438
1439 </sect3>
1440
1441 <!--  ~  End section  ~  -->
1442
1443
1444 <!--   ~~~~~       New section      ~~~~~     -->
1445
1446 <sect3>
1447 <title>Windows GUI Options</title>
1448 <!--
1449 Removed references to Win32. HB 09/23/01
1450 -->
1451 <para>
1452  <application>Junkbuster</application> has a number of options specific to the
1453  Windows GUI interface:
1454 </para>
1455
1456 <para>
1457  If <quote>activity-animation</quote> is set to 1, the
1458  <application>Junkbuster</application> icon will animate when
1459  <quote>Junkbuster</quote> is active. To turn off, set to 0.
1460 </para>
1461
1462 <para>
1463  <literal>
1464   <MSGText>
1465    <literallayout>
1466   <emphasis>activity-animation   1</emphasis>
1467    </literallayout>
1468   </MSGText>
1469  </literal>
1470 </para>
1471
1472 <para>
1473  If <quote>log-messages</quote> is set to 1,
1474  <application>Junkbuster</application> will log messages to the console
1475  window:
1476 </para>
1477
1478 <para>
1479  <literal>
1480   <MSGText>
1481    <literallayout>
1482   <emphasis>log-messages       1</emphasis>
1483    </literallayout>
1484   </MSGText>
1485  </literal>
1486 </para>
1487
1488 <para>
1489  If <quote>log-buffer-size</quote> is set to 1, the size of the log buffer,
1490  i.e. the amount of memory used for the log messages displayed in the
1491  console window, will be limited to <quote>log-max-lines</quote> (see below).
1492 </para>
1493
1494 <para>
1495  Warning: Setting this to 0 will result in the buffer to grow infinitely and
1496  eat up all your memory!
1497 </para>
1498
1499 <para>
1500  <literal>
1501   <MSGText>
1502    <literallayout>
1503   <emphasis>log-buffer-size      1</emphasis>
1504    </literallayout>
1505   </MSGText>
1506  </literal>
1507 </para>
1508
1509 <para>
1510  <application>log-max-lines</application> is the maximum number of lines held
1511  in the log buffer. See above.
1512 </para>
1513
1514 <para>
1515  <literal>
1516   <MSGText>
1517    <literallayout>
1518   <emphasis>log-max-lines      200</emphasis>
1519    </literallayout>
1520   </MSGText>
1521  </literal>
1522 </para>
1523
1524 <para>
1525  If <quote>log-highlight-messages</quote> is set to 1,
1526  <application>Junkbuster</application> will highlight portions of the log
1527  messages with a bold-faced font:
1528 </para>
1529
1530 <para>
1531  <literal>
1532   <MSGText>
1533    <literallayout>
1534   <emphasis>log-highlight-messages   1</emphasis>
1535    </literallayout>
1536   </MSGText>
1537  </literal>
1538 </para>
1539
1540 <para>
1541  The font used in the console window:
1542 </para>
1543
1544 <para>
1545  <literal>
1546   <MSGText>
1547    <literallayout>
1548   <emphasis>log-font-name        Comic Sans MS</emphasis>
1549    </literallayout>
1550   </MSGText>
1551  </literal>
1552 </para>
1553
1554 <para>
1555  Font size used in the console window:
1556 </para>
1557
1558 <para>
1559  <literal>
1560   <MSGText>
1561    <literallayout>
1562   <emphasis>log-font-size        8</emphasis>
1563    </literallayout>
1564   </MSGText>
1565  </literal>
1566 </para>
1567
1568 <para>
1569  <quote>show-on-task-bar</quote> controls whether or not
1570  <application>Junkbuster</application> will appear as a button on the Task bar
1571  when minimized:
1572 </para>
1573
1574 <para>
1575  <literal>
1576   <MSGText>
1577    <literallayout>
1578   <emphasis>show-on-task-bar     0</emphasis>
1579    </literallayout>
1580   </MSGText>
1581  </literal>
1582 </para>
1583
1584 <para>
1585  If <quote>close-button-minimizes</quote> is set to 1, the Windows close
1586  button will minimize <application>Junkbuster</application> instead of closing
1587  the program (close with the exit option on the File menu).
1588 </para>
1589
1590 <para>
1591  <literal>
1592   <MSGText>
1593    <literallayout>
1594   <emphasis>close-button-minimizes  1</emphasis>
1595    </literallayout>
1596   </MSGText>
1597  </literal>
1598 </para>
1599
1600 <para>
1601  The <quote>hide-console</quote> option is specific to the MS-Win console
1602  version of <application>JunkBuster</application>. If this option is used,
1603  <application>Junkbuster</application> will disconnect from and hide  the
1604  command console.
1605 </para>
1606
1607 <para>
1608  <literal>
1609   <MSGText>
1610    <literallayout>
1611   #hide-console
1612    </literallayout>
1613   </MSGText>
1614  </literal>
1615 </para>
1616
1617 </sect3>
1618 </sect2>
1619
1620 <!--  ~  End section  ~  -->
1621
1622
1623 <!--   ~~~~~       New section      ~~~~~     -->
1624 <sect2 id="actionsfile">
1625 <title>The Actions File</title>
1626
1627 <para>
1628  The <quote>actionsfile</quote> is used to define what actions
1629  <application>Junkbuster</application> takes, and thus determines how images,
1630  cookies and various other aspects of HTTP content and transactions are
1631  handled. Images can be anything you want, including ads, banners, or just
1632  some obnoxious image that you would rather not see. Cookies can be accepted
1633  or rejected. The default file is in fact named <filename>actionsfile</filename>.
1634 </para>
1635
1636 <para>
1637  To determine which actions apply to a request, the URL of the request is
1638  compared to all patterns in this file. Every time it matches, the list of
1639  applicable actions for the URL is incrementally updated. You can trace
1640  this process by visiting <ulink
1641  url="http://i.j.b/show-url-info">http://i.j.b/show-url-info</ulink>.
1642 </para>
1643
1644 <para>
1645  There are four types of lines in this file: comments (begin with a
1646  <quote>#</quote> character), actions, aliases and patterns, all of which are
1647  explained below.
1648 </para>
1649
1650
1651 <!--   ~~~~~       New section      ~~~~~     -->
1652 <sect3>
1653 <title>URL Domain and Path Syntax</title>
1654 <para>
1655  Generally, a pattern has the form &lt;domain&gt;/&lt;path&gt;, where both the
1656  &lt;domain&gt; and &lt;path&gt; part are optional. If you only specify a
1657  domain part, the <quote>/</quote> can be left out:
1658 </para>
1659
1660 <para>
1661  <emphasis>www.example.com</emphasis> - is a domain only pattern and will match any request to
1662  <quote>www.example.com</quote>.
1663 </para>
1664
1665 <para>
1666  <emphasis>www.example.com/</emphasis> - means exactly the same.
1667 </para>
1668
1669 <para>
1670  <emphasis>www.example.com/index.html</emphasis> - matches only the single
1671  document <quote>/index.html</quote> on <quote>www.example.com</quote>.
1672 </para>
1673
1674 <para>
1675  <emphasis>/index.html</emphasis> - matches the document <quote>/index.html</quote>, regardless of
1676  the domain.
1677 </para>
1678
1679 <para>
1680  <emphasis>index.html</emphasis> - matches nothing, since it would be
1681  interpreted as a domain name and there is no top-level domain called
1682  <quote>.html</quote>.
1683 </para>
1684
1685 <para>
1686  The matching of the domain part offers some flexible options: if the
1687  domain starts or ends with a dot, it becomes unanchored at that end.
1688  For example:
1689 </para>
1690
1691 <para>
1692  <emphasis>.example.com</emphasis> - matches any domain that <emphasis>ENDS</emphasis> in
1693  <quote>.example.com</quote>.
1694 </para>
1695
1696 <para>
1697  <emphasis>www.</emphasis> - matches any domain that <emphasis>STARTS</emphasis> with
1698  <quote>www</quote>.
1699 </para>
1700
1701 <para>
1702  Additionally, there are wildcards that you can use in the domain names
1703  themselves. They work pretty similar to shell wildcards: <quote>*</quote>
1704  stands for zero or more arbitrary characters, <quote>?</quote> stands for
1705  any single character. And you can define charachter classes in square
1706  brackets and they can be freely mixed:
1707 </para>
1708
1709 <para>
1710  <emphasis>ad*.example.com</emphasis> - matches <quote>adserver.example.com</quote>,
1711  <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>.
1712 </para>
1713
1714 <para>
1715  <emphasis>*ad*.example.com</emphasis> - matches all of the above, and then some.
1716 </para>
1717
1718 <para>
1719  <emphasis>.?pix.com</emphasis> - matches <quote>www.ipix.com</quote>,
1720  <quote>pictures.epix.com</quote>, <quote>a.b.c.d.e.upix.com</quote>, etc.
1721 </para>
1722
1723 <para>
1724  <emphasis>www[1-9a-ez].example.com</emphasis> - matches <quote>www1.example.com</quote>,
1725  <quote>www4.example.com</quote>, <quote>wwwd.example.com</quote>,
1726  <quote>wwwz.example.com</quote>, etc., but <emphasis>not</emphasis>
1727  <quote>wwww.example.com</quote>.
1728 </para>
1729
1730 <para>
1731  If <application>Junkbuster</application> was compiled with
1732  <quote>pcre</quote> support (default), Perl compatible regular expressions
1733  can be used. See the <filename>pcre/docs/</filename> direcory or <quote>man
1734  perlre</quote> (also available on  <ulink
1735  url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>)
1736  for details. A brief discussion of regular expressions is in the
1737  <link linkend="regex">Appendix</link>. For instance:
1738 </para>
1739
1740 <para>
1741  <emphasis>/.*/advert[0-9]+\.jpe?g</emphasis>  - would match a URL from any
1742  domain, with any path that includes <quote>advert</quote> followed
1743  immediately by one or more digits, then a <quote>.</quote> and ending in
1744  either <quote>jpeg</quote> or <quote>jpg</quote>. So we match
1745  <quote>example.com/ads/advert2.jpg</quote>, and
1746  <quote>www.example.com/ads/banners/advert39.jpeg</quote>, but not
1747  <quote>www.example.com/ads/banners/advert39.gif</quote> (no gifs in the
1748  example pattern).
1749 </para>
1750
1751 <para>
1752  Please note that matching in the path is case
1753  <emphasis>INSENSITIVE</emphasis> by default, but you can switch to case
1754  sensitive at any point in the pattern by using the
1755  <quote>(?-i)</quote> switch:
1756 </para>
1757
1758 <para>
1759  <emphasis>www.example.com/(?-i)PaTtErN.*</emphasis> - will match only
1760  documents whose path starts with <quote>PaTtErN</quote> in
1761  <emphasis>exactly</emphasis> this capitalization.
1762 </para>
1763
1764 </sect3>
1765
1766 <!--  ~  End section  ~  -->
1767
1768
1769
1770 <!--   ~~~~~       New section      ~~~~~     -->
1771
1772 <sect3>
1773 <title>Actions</title>
1774 <para>
1775  Actions are enabled if preceded with a <quote>+</quote>, and disabled if
1776  preceded with a <quote>-</quote>. Actions are invoked by enclosing the
1777  action name in curly braces (e.g. {+some_action}), followed by a list of
1778  URLs to which the action applies. There are three classes of actions:
1779 </para>
1780
1781 <para>
1782  <itemizedlist>
1783
1784  <listitem>
1785   <para>
1786    Boolean (e.g. <quote>+/-block</quote>):
1787   </para>
1788   <para>
1789    <literal>
1790     <MSGText>
1791      <literallayout>
1792   <emphasis>{+name}</emphasis>        # enable this action
1793   <emphasis>{-name}</emphasis>        # disable this action
1794      </literallayout>
1795     </MSGText>
1796    </literal>
1797   </para>
1798  </listitem>
1799
1800
1801  <listitem>
1802   <para>
1803    Parameterized (e.g. <quote>+/-hide-user-agent</quote>):
1804   </para>
1805   <para>
1806    <literal>
1807     <MSGText>
1808      <literallayout>
1809   <emphasis>{+name{param}}</emphasis>  # enable action and set parameter to <quote>param</quote>
1810   <emphasis>{-name}</emphasis>         # disable action
1811      </literallayout>
1812     </MSGText>
1813    </literal>
1814   </para>
1815  </listitem>
1816
1817  <listitem>
1818   <para>
1819    Multi-value (e.g. <quote>{+/-add-header{Name: value}}</quote>, <quote>{+/-wafer{name=value}}</quote>):
1820   </para>
1821   <para>
1822    <literal>
1823     <MSGText>
1824      <literallayout>
1825   <emphasis>{+name{param}}</emphasis>   # enable action and add parameter <quote>param</quote>
1826   <emphasis>{-name{param}}</emphasis>   # remove the parameter <quote>param</quote>
1827   <emphasis>{-name}</emphasis>          # disable this action totally
1828      </literallayout>
1829     </MSGText>
1830    </literal>
1831   </para>
1832  </listitem>
1833
1834  </itemizedlist>
1835 </para>
1836
1837 <para>
1838  If nothing is specified in this file, no <quote>actions</quote> are taken.
1839  So in this case <application>JunkBuster</application> would just be a
1840  normal, non-blocking, non-anonymizing proxy. You must specifically
1841  enable the privacy and blocking features you need (although the
1842  provided default <filename>actionsfile</filename> file will
1843  give a good starting point).
1844 </para>
1845
1846 <para>
1847  Later defined actions always over-ride earlier ones.  For multi-valued
1848  actions, the actions are applied in the order they are specified.
1849 </para>
1850
1851 <para>
1852  The list of valid <application>Junkbuster</application> <quote>actions</quote> are:
1853 </para>
1854
1855 <para>
1856  <itemizedlist>
1857
1858  <listitem>
1859   <para>
1860    Add the specified HTTP header, which is not checked for validity.
1861    You may specify this many times to specify many different headers:
1862   </para>
1863   <para>
1864    <literal>
1865     <MSGText>
1866      <literallayout>
1867   <emphasis>+add-header{Name: value}</emphasis>
1868      </literallayout>
1869     </MSGText>
1870    </literal>
1871   </para>
1872  </listitem>
1873
1874
1875  <listitem>
1876   <para>
1877    Block this URL totally.
1878   </para>
1879   <para>
1880    <literal>
1881     <MSGText>
1882      <literallayout>
1883   <emphasis>+block</emphasis>
1884      </literallayout>
1885     </MSGText>
1886    </literal>
1887   </para>
1888  </listitem>
1889
1890
1891  <listitem>
1892   <para>
1893    De-animate all animated GIF images, i.e. reduce them to their last frame.
1894    This will also shrink the images considerably (in bytes, not pixels!). If
1895    the option <quote>first</quote> is given, the first frame of the animation
1896    is used as the replacement. If <quote>last</quote> is given, the last frame
1897    of the animation is used instead, which propably makes more sense for most
1898    banner animations, but also has the risk of not showing the entire last
1899    frame (if it is only a delta to an earlier frame).
1900   </para>
1901   <para>
1902    <literal>
1903     <MSGText>
1904      <literallayout>
1905   <emphasis>+deanimate-gifs{last}</emphasis>
1906   <emphasis>+deanimate-gifs{first}</emphasis>
1907      </literallayout>
1908     </MSGText>
1909    </literal>
1910   </para>
1911  </listitem>
1912
1913  <listitem>
1914   <para>
1915    <quote>+downgrade</quote> will downgrade HTTP/1.1 client requests to
1916    HTTP/1.0 and downgrade the responses as well. Use this action for servers
1917    that use HTTP/1.1 protocol features that
1918    <application>Junkbuster</application> doesn't handle well yet. HTTP/1.1
1919    is only partially implemented. Default is not to downgrade requests.
1920   </para>
1921   <para>
1922    <literal>
1923     <MSGText>
1924      <literallayout>
1925   <emphasis>+downgrade</emphasis>
1926      </literallayout>
1927     </MSGText>
1928    </literal>
1929   </para>
1930  </listitem>
1931
1932  <listitem>
1933   <para>
1934    Many sites, like yahoo.com, don't just link to other sites. Instead, they
1935    will link to some script on their own server, giving the destination as a
1936    parameter, which will then redirect you to the final target. URLs resulting
1937    from this scheme typically look like:
1938    http://some.place/some_script?http://some.where-else.
1939   </para>
1940   <para>
1941    Sometimes, there are even multiple consecutive redirects encoded in the
1942    URL. These redirections via scripts make your web browing more traceable,
1943    since the server from which you follow such a link can see where you go to.
1944    Apart from that, valuable bandwidth and time is wasted, while your browser
1945    ask the server for one redirect after the other. Plus, it feeds the
1946    advertisers.
1947   </para>
1948   <para>
1949    The <quote>+fast-redirects</quote> option enables interception of these
1950    requests by <application>Junkbuster</application>, who will cut off all but
1951    the last valid URL in the request and send a local redirect back to your
1952    browser without contacting the remote site.
1953   </para>
1954   <para>
1955    <literal>
1956     <MSGText>
1957      <literallayout>
1958   <emphasis>+fast-redirects</emphasis>
1959      </literallayout>
1960     </MSGText>
1961    </literal>
1962   </para>
1963  </listitem>
1964
1965  <listitem>
1966   <para>
1967    Filter the website through the re_filterfile:
1968   </para>
1969   <para>
1970    <literal>
1971     <MSGText>
1972      <literallayout>
1973  <emphasis>+filter{filename}</emphasis>
1974      </literallayout>
1975     </MSGText>
1976    </literal>
1977   </para>
1978  </listitem>
1979
1980  <listitem>
1981   <para>
1982    Block any existing X-Forwarded-for header, and do not add a new one:
1983   </para>
1984   <para>
1985    <literal>
1986     <MSGText>
1987      <literallayout>
1988   <emphasis>+hide-forwarded</emphasis>
1989      </literallayout>
1990     </MSGText>
1991    </literal>
1992   </para>
1993  </listitem>
1994
1995  <listitem>
1996   <para>
1997    If the browser sends a <quote>From:</quote> header containing your e-mail
1998    address, this either completely removes the header (<quote>block</quote>), or
1999    changes it to the specified e-mail address.
2000   </para>
2001   <para>
2002    <literal>
2003     <MSGText>
2004      <literallayout>
2005   <emphasis>+hide-from{block}</emphasis>
2006   <emphasis>+hide-from{spam@sittingduck.xqq}</emphasis>
2007      </literallayout>
2008     </MSGText>
2009    </literal>
2010   </para>
2011  </listitem>
2012
2013  <listitem>
2014   <para>
2015    Don't send the <quote>Referer:</quote> (sic) header to the web site.  You
2016    can block it, forge a URL to the same server as the request (which is
2017    preferred because some sites will not send images otherwise) or set it to a
2018    constant string of your choice.
2019   </para>
2020   <para>
2021    <literal>
2022     <MSGText>
2023      <literallayout>
2024   <emphasis>+hide-referer{block}</emphasis>
2025   <emphasis>+hide-referer{forge}</emphasis>
2026   <emphasis>+hide-referer{http://nowhere.com}</emphasis>
2027      </literallayout>
2028     </MSGText>
2029    </literal>
2030   </para>
2031  </listitem>
2032
2033  <listitem>
2034   <para>
2035    Alternative spelling of <quote>+hide-referer</quote>.  It has the same
2036    parameters, and can be freely mixed with, <quote>+hide-referer</quote>.
2037    (<quote>referrer</quote> is the correct English spelling, however the HTTP
2038    specification has a bug - it requires it to be spelled <quote>referer</quote>.)
2039   </para>
2040   <para>
2041    <literal>
2042     <MSGText>
2043      <literallayout>
2044   <emphasis>+hide-referrer{...}</emphasis>
2045      </literallayout>
2046     </MSGText>
2047    </literal>
2048   </para>
2049  </listitem>
2050
2051  <listitem>
2052   <para>
2053    Change the <quote>User-Agent:</quote> header so web servers can't tell your
2054    browser type.  Warning! This breaks many web sites.  Specify the
2055    user-agent value you want. Example, pretend to be using Netscape on
2056    Linux:
2057   </para>
2058   <para>
2059    <literal>
2060     <MSGText>
2061      <literallayout>
2062   <emphasis>+hide-user-agent{Mozilla (X11; I; Linux 2.0.32 i586)}</emphasis>
2063      </literallayout>
2064     </MSGText>
2065    </literal>
2066   </para>
2067  <!--
2068   <para>
2069    Or to identify yourself explicitly as a <quote>Junkbuster</quote> user:
2070   </para>
2071   <para>
2072    <literal>
2073     <MSGText>
2074      <literallayout>
2075   <emphasis>+hide-user-agent{JunkBuster/1.0}</emphasis>
2076      </literallayout>
2077     </MSGText>
2078    </literal>
2079   </para>
2080    (Don't change the version number from 1.0 - after all, why tell them?)
2081   <para>
2082   </para>
2083   <para>
2084    <literal>
2085     <MSGText>
2086      <literallayout>
2087   <emphasis>+hide-user-agent{browser-type}</emphasis>
2088      </literallayout>
2089     </MSGText>
2090    </literal>
2091   </para>
2092 -->
2093  </listitem>
2094
2095  <listitem>
2096   <para>
2097    Treat this URL as an image.  This only matters if it's also <quote>+block</quote>ed,
2098     in which case a <quote>blocked</quote> image can be sent rather than a HTML page.
2099     See <quote>+image-blocker{}</quote> below for the control over what is actually sent.
2100   </para>
2101   <para>
2102    <literal>
2103     <MSGText>
2104      <literallayout>
2105   <emphasis>+image</emphasis>
2106      </literallayout>
2107     </MSGText>
2108    </literal>
2109   </para>
2110  </listitem>
2111
2112  <listitem>
2113   <para>
2114    Decides what to do with URLs that end up tagged with <quote>{+block
2115    +image}</quote>. There are 4 options.  <quote>-image-blocker</quote> will
2116    send a HTML <quote>blocked</quote> page, usually resulting in a
2117    <quote>broken image</quote> icon.  <quote>+image-blocker{logo}</quote> will
2118    send a <quote>JunkBuster</quote> image.
2119    <quote>+image-blocker{blank}</quote> will send a 1x1 transparent GIF image.
2120    And finally, <quote>+image-blocker{http://xyz.com}</quote> will send a HTTP
2121    temporary redirect to the specified image. This has the advantage of the
2122    icon being being cached by the browser, which will speed up the display.
2123   </para>
2124   <para>
2125    <literal>
2126     <MSGText>
2127      <literallayout>
2128   <emphasis>+image-blocker{logo}</emphasis>
2129   <emphasis>+image-blocker{blank}</emphasis>
2130   <emphasis>+image-blocker{http://i.j.b/send-banner}</emphasis>
2131      </literallayout>
2132     </MSGText>
2133    </literal>
2134   </para>
2135  </listitem>
2136
2137  <listitem>
2138    <para>
2139    By default (i.e. in the absence of a <quote>+limit-connect</quote>
2140    action), <application>Junkbuster</application> will only allow CONNECT
2141    requests to port 443, which is the standard port for https as a
2142    precaution.
2143   </para>
2144
2145   <para>
2146    The CONNECT methods exists in HTTP to allow access to secure websites
2147    (https:// URLs) through proxies. It works very simply: the proxy
2148    connects to the server on the specified port, and then short-circuits
2149    its connections to the client <emphasis>and</emphasis> to the remote proxy.
2150    This can be a big security hole, since CONNECT-enabled proxies can
2151    be abused as TCP relays very easily.
2152   </para>
2153
2154   <para>
2155    If you want to allow CONNECT for more ports than this, or want to forbid
2156    CONNECT altogether, you can specify a comma separated list of ports and
2157    port ranges (the latter using dashes, with the minimum defaulting to 0 and
2158    max to 65K):
2159   </para>
2160
2161   <para>
2162    <literal>
2163     <MSGText>
2164      <literallayout>
2165   <emphasis>+limit-connect{443}                 # This is the default and need no be specified.</emphasis>
2166   <emphasis>+limit-connect{80,443}              # Ports 80 and 443 are OK.</emphasis>
2167   <emphasis>+limit-connect{-3, 7, 20-100, 500-} # Port less than 3, 7, 20 to 100</emphasis>
2168   <emphasis>                                    #and above 500 are OK.</emphasis>
2169      </literallayout>
2170     </MSGText>
2171    </literal>
2172   </para>
2173
2174  </listitem>
2175
2176  <listitem>
2177   <para>
2178    <quote>+no-compression</quote> prevents the website from compressing the
2179    data. Some websites do this, which can be a problem for
2180    <application>Junkbuster</application>, since <quote>+filter</quote>,
2181    <quote>+no-popup</quote> and <quote>+gif-deanimate</quote> will not work on
2182    compressed data. This will slow down connections to those websites,
2183    though. Default is <quote>nocompression</quote> is turned on.
2184   </para>
2185
2186   <para>
2187    <literal>
2188     <MSGText>
2189      <literallayout>
2190   <emphasis>+nocompression</emphasis>
2191      </literallayout>
2192     </MSGText>
2193    </literal>
2194   </para>
2195  </listitem>
2196
2197  <listitem>
2198   <para>
2199    Prevent the website from reading cookies:
2200   </para>
2201   <para>
2202    <literal>
2203     <MSGText>
2204      <literallayout>
2205   <emphasis>+no-cookies-read</emphasis>
2206      </literallayout>
2207     </MSGText>
2208    </literal>
2209   </para>
2210  </listitem>
2211
2212  <listitem>
2213   <para>
2214    Prevent the website from setting cookies:
2215   </para>
2216   <para>
2217    <literal>
2218     <MSGText>
2219      <literallayout>
2220   <emphasis>+no-cookies-set</emphasis>
2221      </literallayout>
2222     </MSGText>
2223    </literal>
2224   </para>
2225  </listitem>
2226
2227  <listitem>
2228   <para>
2229    Filter the website through a built-in filter to disable those obnoxious
2230    JavaScript pop-up windows via window.open(), etc. The two alternative
2231    spellings are equivalent.
2232   </para>
2233   <para>
2234    <literal>
2235     <MSGText>
2236      <literallayout>
2237   <emphasis>+no-popup</emphasis>
2238   <emphasis>+no-popups</emphasis>
2239      </literallayout>
2240     </MSGText>
2241    </literal>
2242   </para>
2243  </listitem>
2244
2245  <listitem>
2246   <para>
2247    This action only applies if you are using a <filename>jarfile</filename>
2248    for saving cookies. It sends a cookie to every site stating that you do not
2249    accept any copyright on cookies sent to you, and asking them not to track
2250    you.  Of course, this is a (relatively) unique header they could use to
2251    track you.
2252   </para>
2253   <para>
2254    <literal>
2255     <MSGText>
2256      <literallayout>
2257   <emphasis>+vanilla-wafer</emphasis>
2258      </literallayout>
2259     </MSGText>
2260    </literal>
2261   </para>
2262  </listitem>
2263
2264  <listitem>
2265   <para>
2266    This allows you to add an arbitrary cookie. It can be specified multiple
2267    times in order to add as many cookies as you like.
2268   </para>
2269   <para>
2270    <literal>
2271     <MSGText>
2272      <literallayout>
2273   <emphasis>+wafer{name=value}</emphasis>
2274      </literallayout>
2275     </MSGText>
2276    </literal>
2277   </para>
2278  </listitem>
2279
2280  </itemizedlist>
2281 </para>
2282
2283 <para>
2284  The meaning of any of the above is reversed by preceding the action with a
2285  <quote>-</quote>, in place of the <quote>+</quote>.
2286 </para>
2287
2288 <para>
2289  Some examples:
2290 </para>
2291
2292 <para>
2293  Turn off cookies by default, then allow a few through for specified sites:
2294 </para>
2295
2296 <para>
2297  <literal>
2298   <MSGText>
2299    <literallayout>
2300  # Turn off all cookies
2301  { +no-cookies-read }
2302  { +no-cookies-set }
2303
2304  # Execeptions to the above, sites that need cookies
2305  { -no-cookies-read }
2306  { -no-cookies-set }
2307  .javasoft.com
2308  .sun.com
2309  .yahoo.com
2310  .msdn.microsoft.com
2311  .redhat.com
2312
2313  # Alternative way of saying the same thing
2314  {-no-cookies-set -no-cookies-read}
2315  .sourceforge.net
2316  .sf.net
2317    </literallayout>
2318   </MSGText>
2319  </literal>
2320 </para>
2321
2322 <para>
2323  Now turn off <quote>fast redirects</quote>, and then we allow two exceptions:
2324 </para>
2325
2326 <para>
2327  <literal>
2328   <MSGText>
2329    <literallayout>
2330  # Turn them off!
2331  {+fast-redirects}
2332
2333  # Reverse it for these two sites, which don't work right without it.
2334  {-fast-redirects}
2335  www.ukc.ac.uk/cgi-bin/wac\.cgi\?
2336  login.yahoo.com
2337    </literallayout>
2338   </MSGText>
2339  </literal>
2340 </para>
2341
2342 <para>
2343  Turn on page filtering, with one exception for sourceforge:
2344 </para>
2345
2346 <para>
2347  <literal>
2348   <MSGText>
2349    <literallayout>
2350  # Run everything through the default filter file (<filename>re_filterfile</filename>):
2351  {+filter}
2352
2353  # But please don't re_filter code from sourceforge!
2354  {-filter}
2355  .cvs.sourceforge.net
2356    </literallayout>
2357   </MSGText>
2358  </literal>
2359 </para>
2360
2361 <para>
2362  Now some URLs that we want <quote>blocked</quote>, ie we won't see them.
2363  Many of these use regular expressions that will expand to match multiple
2364  URLs:
2365 </para>
2366
2367 <para>
2368  <literal>
2369   <MSGText>
2370    <literallayout>
2371   # Blocklist:
2372   {+block}
2373   /.*/(.*[-_.])?ads?[0-9]?(/|[-_.].*|\.(gif|jpe?g))
2374   /.*/(.*[-_.])?count(er)?(\.cgi|\.dll|\.exe|[?/])
2375   /.*/(ng)?adclient\.cgi
2376   /.*/(plain|live|rotate)[-_.]?ads?/
2377   /.*/(sponsor)s?[0-9]?/
2378   /.*/_?(plain|live)?ads?(-banners)?/
2379   /.*/abanners/
2380   /.*/ad(sdna_image|gifs?)/
2381   /.*/ad(server|stream|juggler)\.(cgi|pl|dll|exe)
2382   /.*/adbanners/
2383   /.*/adserver
2384   /.*/adstream\.cgi
2385   /.*/adv((er)?ts?|ertis(ing|ements?))?/
2386   /.*/banner_?ads/
2387   /.*/banners?/
2388   /.*/banners?\.cgi/
2389   /.*/cgi-bin/centralad/getimage
2390   /.*/images/addver\.gif
2391   /.*/images/marketing/.*\.(gif|jpe?g)
2392   /.*/popupads/
2393   /.*/siteads/
2394   /.*/sponsor.*\.gif
2395   /.*/sponsors?[0-9]?/
2396   /.*/advert[0-9]+\.jpg
2397   /Media/Images/Adds/
2398   /ad_images/
2399   /adimages/
2400   /.*/ads/
2401   /bannerfarm/
2402   /grafikk/annonse/
2403   /graphics/defaultAd/
2404   /image\.ng/AdType
2405   /image\.ng/transactionID
2406   /images/.*/.*_anim\.gif # alvin brattli
2407   /ip_img/.*\.(gif|jpe?g)
2408   /rotateads/
2409   /rotations/
2410   /worldnet/ad\.cgi
2411   /cgi-bin/nph-adclick.exe/
2412   /.*/Image/BannerAdvertising/
2413   /.*/ad-bin/
2414   /.*/adlib/server\.cgi
2415   /autoads/
2416    </literallayout>
2417   </MSGText>
2418  </literal>
2419 </para>
2420
2421 </sect3>
2422
2423 <!--  ~  End section  ~  -->
2424
2425
2426 <!--   ~~~~~       New section      ~~~~~     -->
2427 <sect3>
2428 <title>Aliases</title>
2429 <para>
2430  Custom <quote>actions</quote>, known to <application>Junkbuster</application>
2431  as <quote>aliases</quote>, can be defined by combing other <quote>actions</quote>.
2432  These can in turn be invoked just like the built-in <quote>actions</quote>.
2433  Currently, an alias can contain any character except space, tab, <quote>=</quote>,
2434  <quote>{</quote> or <quote>}</quote>. But please use only <quote>a</quote>-
2435  <quote>z</quote>, <quote>0</quote>-<quote>9</quote>, <quote>+</quote>, and
2436  <quote>-</quote>. Alias names are not case sensitive, and must be defined
2437  before they are used.
2438 </para>
2439
2440 <para>
2441  Now let's define a few aliases:
2442 </para>
2443
2444 <para>
2445  <literal>
2446   <MSGText>
2447    <literallayout>
2448  # Aliases
2449  {{alias}}
2450
2451  # Useful aliases
2452  +no-cookies = +no-cookies-set +no-cookies-read
2453  -no-cookies = -no-cookies-set -no-cookies-read
2454  fragile     = -block -no-cookies -filter -fast-redirects -hide-referer -no-popups
2455  shop        = -no-cookies -filter -fast-redirects
2456  +imageblock = +block +image
2457
2458  #For people who don't like to type too much:  ;-)
2459  c0 = +no-cookies
2460  c1 = -no-cookies
2461  c2 = -no-cookies-set +no-cookies-read
2462  c3 = +no-cookies-set -no-cookies-read
2463  #... etc.  Customize to your heart's content.
2464    </literallayout>
2465   </MSGText>
2466  </literal>
2467 </para>
2468
2469 <para>
2470  Some examples using our <quote>shop</quote> and <quote>fragile</quote>
2471  aliases from above:
2472 </para>
2473
2474 <para>
2475  <literal>
2476   <MSGText>
2477    <literallayout>
2478  # These sites are very complex and require
2479  # minimal interference.
2480  {fragile}
2481  .office.microsoft.com
2482  .windowsupdate.microsoft.com
2483
2484  # Shopping sites - still want to block ads.
2485  {shop}
2486  .quietpc.com
2487  .worldpay.com   # for quietpc.com
2488  .jungle.com
2489  .scan.co.uk
2490
2491  # These shops require pop-ups
2492  {shop -no-popups}
2493  .dabs.com
2494  .overclockers.co.uk
2495    </literallayout>
2496   </MSGText>
2497  </literal>
2498 </para>
2499
2500 </sect3>
2501 </sect2>
2502
2503 <!--  ~  End section  ~  -->
2504
2505
2506 <!--   ~~~~~       New section      ~~~~~     -->
2507 <sect2 id="filterfile">
2508 <title>The Filter File</title>
2509 <para>
2510  The filter file defines what filtering of web pages
2511  <application>Junkbuster</application> does. The default filter file is
2512  <filename>re_filterfile</filename>, located in the config directory. In this
2513  file, <emphasis>any document content</emphasis>, whether viewable text or
2514  embedded non-visible content, can be changed.
2515 </para>
2516
2517 <para>
2518  This file uses regular expressions to alter or remove any string in the
2519  target page. Some examples from the included default <filename>re_filterfile</filename>:
2520 </para>
2521
2522 <para>
2523  Stop web pages from displaying annoying messages in the status bar by
2524  deleting such references:
2525 </para>
2526
2527 <para>
2528  <literal>
2529   <MSGText>
2530    <literallayout>
2531  # The status bar is for displaying link targets, not pointless buzzwords.
2532  # Again, check it out on http://www.airport-cgn.de/.
2533  s/status='.*?';*//ig
2534    </literallayout>
2535   </MSGText>
2536  </literal>
2537 </para>
2538
2539 <para>
2540  Just for kicks, replace any occurrence of <quote>Microsoft</quote> with
2541  <quote>MicroSuck</quote>:
2542 </para>
2543
2544 <para>
2545  <literal>
2546   <MSGText>
2547    <literallayout>
2548  s/microsoft(?!.com)/MicroSuck/ig
2549    </literallayout>
2550   </MSGText>
2551  </literal>
2552 </para>
2553
2554 <para>
2555  Kill those auto-refresh tags:
2556 </para>
2557
2558 <para>
2559  <literal>
2560   <MSGText>
2561    <literallayout>
2562  # Kill refresh tags. I like to refresh myself. Manually.
2563  # check it out on http://www.airport-cgn.de/ and go to the arrivals page.
2564  #
2565  s/&lt;meta[^&gt;]*http-equiv[^&gt;]*refresh.*URL=([^&gt;]*?)"?&gt;/&lt;link rev="x-refresh" href=$1&gt;/i
2566  s/&lt;meta[^&gt;]*http-equiv="?page-enter"?[^&gt;]*content=[^&gt;]*&gt;/&lt;!--no page enter for me--&gt;/i
2567    </literallayout>
2568   </MSGText>
2569  </literal>
2570 </para>
2571
2572 </sect2>
2573
2574 </sect1>
2575
2576 <!--   ~~~~~       New section      ~~~~~     -->
2577 <sect1 id="quickstart"><title>Quickstart to Using Junkbuster</title>
2578 <para>
2579  Install package, then run and enjoy! Be sure your browser is set to use
2580  the proxy which is by default at localhost, port 8000. With
2581  <application>Netscape</application> (and <application>Mozilla</application>),
2582  this can be set under <literal>Edit -&gt; Preferences -&gt; Advanced -&gt;
2583  Proxies -&gt; HTTP Proxy</literal>. For <application>Internet
2584  Explorer</application>: <literal>Internet Properties -&gt; Connections -&gt;
2585  LAN Setting</literal>. Then, check <quote>Use Proxy</quote> and fill in the
2586  appropriate info (Address: localhost, Port: 8000).
2587 </para>
2588
2589 <para>
2590  The included default configuration files should give a reasonable starting
2591  point, though may be somewhat aggressive in blocking junk. You will probably
2592  want to keep an eye out for sites that require cookies, and add these to
2593  <filename>actionsfile</filename> as needed. By default, most of these will
2594  be blocked until you add them to the configuration. If you want the browser
2595  to handle this instead, you will need to edit
2596  <filename>actionsfile</filename> and disable this feature. If you use more
2597  than one browser, it would make more sense to let
2598  <application>Junkbuster</application> handle this. In which case, the
2599  browser(s) should be set to accept all cookies.
2600 </para>
2601
2602 <para>
2603  HTTP/1.1 support is not fully implemented. If browsers that
2604  support HTTP/1.1 (like Mozilla or recent versions of I.E.) experience
2605  problems, you might try to force HTTP/1.0 compatiblity. For Mozilla, look under <literal>Edit -&gt;
2606  Preferences -&gt; Debug -&gt; Networking</literal>. Or set the
2607  <quote>+downgrade</quote> config option in <filename>actionsfile</filename>.
2608 </para>
2609
2610 <para>
2611  After running <application>Junkbuster</application> for a while, you can
2612  start to fine tune the configuration to suit your personal, or site,
2613  preferences and requirements. There are many, many aspects that can
2614  be customized.
2615 </para>
2616
2617 <para>
2618  If you encounter problems, please verify it is a
2619  <application>Junkbuster</application> bug, by disabling
2620  <application>Junkbuster</application>, and then trying the same page.
2621  Also, try another browser if possible to eliminate browser or site
2622  problems. Before reporting it as a bug, see if there is not a configuration
2623  option that is enabled that is causing the page not to load. You can
2624  then add an exception for that page or site. If a bug, please report it to
2625  the developers (see below).
2626 </para>
2627
2628 </sect1>
2629
2630
2631 <!--   ~~~~~       New section      ~~~~~     -->
2632 <sect1 id="contact"><title>Contact the Developers</title>
2633 <para>
2634 <!--
2635 To be filled. mention the support forums as the primary channel of
2636 communication (bugs, feature requests, etc.)
2637 -->
2638  Feature requests and other questions should be posted to the <ulink
2639  url="http://sourceforge.net/tracker/?atid=361118&amp;group_id=11118&amp;func=browse">Feature
2640  request page</ulink> at SourceForge. There is also an archive there.
2641 </para>
2642
2643 <para>
2644  Anyone interested in actively participating in development and related
2645  discussions can join the appropriate mailing list
2646  <ulink url="http://sourceforge.net/mail/?group_id=11118">here</ulink>.
2647  Archives are available here too.
2648 </para>
2649
2650 <para>
2651  Please report bugs, using the form at
2652  <ulink url="http://sourceforge.net/tracker/?group_id=11118&amp;atid=111118">Sourceforge</ulink>.
2653  Please try to verify that it is a <application>Junkbuster</application> bug,
2654  and not a browser or site bug first. Also, check to make sure this is not
2655  already a known bug.
2656 </para>
2657
2658 </sect1>
2659
2660
2661 <!--   ~~~~~       New section      ~~~~~     -->
2662 <sect1 id="copyright"><title>Copyright and History</title>
2663
2664 <sect2>
2665 <title>License</title>
2666 <para>
2667  <application>Internet Junkbuster</application> is free software; you can
2668  redistribute it and/or modify it under the terms of the GNU General Public
2669  License as published by the Free Software Foundation; either version 2 of the
2670  License, or (at your option) any later version.
2671 </para>
2672
2673 <para>
2674  This program is distributed in the hope that it will be useful, but WITHOUT
2675  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
2676  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
2677  details, which is available from <ulink
2678  url="http://www.gnu.org/copyleft/gpl.html">the Free Software Foundation,
2679  Inc</ulink>, 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
2680 </para>
2681
2682 </sect2>
2683
2684 <!--  ~  End section  ~  -->
2685
2686
2687 <!--   ~~~~~       New section      ~~~~~     -->
2688
2689 <sect2>
2690 <title>History</title>
2691 <para>
2692  <application>Junkbuster</application> was originally written by Anonymous
2693  Coders and <ulink
2694  url="http://www.junkbusters.com/ht/en/ijbfaq.html">JunkBusters
2695  Corporation</ulink>, and was released as free open-source software under the
2696  GNU GPL. <ulink url="http://www.waldherr.org/junkbuster/">Stefan
2697  Waldherr</ulink> made many improvements, and started the <ulink
2698  url="http://sourceforge.net/projects/ijbswa/">SourceForge project</ulink> to
2699  rekindle development. The last stable release was v2.0.2, which has now
2700  grown whiskers ;-).
2701 </para>
2702
2703 </sect2>
2704
2705 </sect1>
2706
2707 <!--   ~~~~~       New section      ~~~~~     -->
2708 <sect1 id="seealso"><title>See also</title>
2709 <para>To be filled. What should go here :/
2710 </para>
2711 </sect1>
2712
2713
2714
2715 <!--   ~~~~~       New section      ~~~~~     -->
2716 <sect1 id="appendix"><title>Appendix</title>
2717
2718
2719 <!--   ~~~~~       New section      ~~~~~     -->
2720 <sect2 id="regex">
2721 <title>Regular Expressions</title>
2722 <para>
2723  <application>Junkbuster</application> can use <quote>regular expressions</quote>
2724  in various config files. Assuming support for <quote>pcre</quote> (Perl
2725  Compatible Regular Expressions) is compiled in, which is the default. Such
2726  configuration directives do not require regular expressions, but they can be
2727  used to increase flexibility by matching a pattern with wildcards against
2728  URLs.
2729 </para>
2730
2731 <para>
2732  If you are reading this, you probably don't understand what <quote>regular
2733  expressions</quote> are, or what they can do. So this will be a very brief
2734  introduction only. A full explanation would require a book ;-)
2735 </para>
2736
2737 <para>
2738  <quote>Regular expressions</quote> is a way of matching one character
2739  expression against another to see if it matches or not. One of the
2740  <quote>expressions</quote> is a literal string of readable characters
2741  (letter, numbers, etc), and the other is a complex string of literal
2742  characters combined with wildcards, and other special characters, called
2743  metacharacters. The <quote>metacharacters</quote> have special meanings and
2744  are used to build the complex pattern to be matched against. Perl Compatible
2745  Regular Expressions is an enhanced form of the regular expression language
2746  with backward compatibility.
2747 </para>
2748
2749 <para>
2750  To make a simple analogy, we do something similar when we use wildcard
2751  characters when listing files with the <command>dir</command> command in DOS.
2752  <literal>*.*</literal> matches all filenames. The <quote>special</quote>
2753  character here is the asterik which matches any and all characters. We can be
2754  more specific and use <literal>?</literal> to match just individual
2755  characters. So <quote>dir file?.text</quote> would match
2756  <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
2757  matching, using a similar technique to <quote>regular expressions</quote>!
2758 </para>
2759
2760 <para>
2761  Regular expressions do essentially the same thing, but are much, much more
2762  powerful. There are many more <quote>special characters</quote> and ways of
2763  building complex patterns however. Let's look at a few of the common ones,
2764  and then some examples:
2765 </para>
2766
2767 <simplelist>
2768  <member>
2769   <emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
2770   <quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
2771  </member>
2772 </simplelist>
2773
2774 <simplelist>
2775  <member>
2776   <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
2777   times. Either/or.
2778  </member>
2779 </simplelist>
2780
2781 <simplelist>
2782  <member>
2783   <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
2784   times.
2785  </member>
2786 </simplelist>
2787
2788 <simplelist>
2789  <member>
2790   <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
2791   times.
2792  </member>
2793 </simplelist>
2794
2795 <simplelist>
2796  <member>
2797   <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
2798   the following character should be taken literally. This is used where one of the
2799   special characters (e.g. <quote>.</quote>) needs to be taken literally and
2800   not as a special metacharacter.
2801  </member>
2802 </simplelist>
2803
2804 <simplelist>
2805  <member>
2806   <emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
2807   any of the enclosed characters are encountered.
2808  </member>
2809 </simplelist>
2810
2811 <simplelist>
2812  <member>
2813   <emphasis>()</emphasis> - Pararentheses are used to group a sub-expression,
2814   or multiple sub-expressions.
2815  </member>
2816 </simplelist>
2817
2818 <simplelist>
2819  <member>
2820   <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
2821   <quote>or</quote> conditional statement. A match is successful if the
2822   sub-expression on either side of <quote>|</quote> matches.
2823  </member>
2824 </simplelist>
2825
2826 <simplelist>
2827  <member>
2828   <emphasis>s/string1/string2/g</emphasis> - This is used to rewrite strings of text.
2829   <quote>string1</quote> is replaced by <quote>string2</quote> in this
2830   example.
2831  </member>
2832 </simplelist>
2833
2834 <para>
2835  These are just some of the ones you are likely to use when matching URLs with
2836  <application>Junkbuster</application>, and is a long way from a definitive
2837  list. This is enough to get us started with a few simple examples which may
2838  be more illuminating:
2839 </para>
2840
2841 <para>
2842  <emphasis><literal>/.*/banners/.*</literal></emphasis> - A  simple example
2843  that uses the common combination of <quote>.</quote> and <quote>*</quote> to
2844  denote any character, zero or more times. In other words, any string at all.
2845  So we start with a literal forward slash, then our regular expression pattern
2846  (<quote>.*</quote>) another literal forward slash, the string
2847  <quote>banners</quote>, another forward slash, and lastly another
2848  <quote>.*</quote>. We are building
2849  a directory path here. This will match any file with the path that has a
2850  directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
2851  any characters, and this could conceivably be more forward slashes, so it
2852  might expand into a much longer looking path. For example, this could match:
2853  <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
2854  <quote>/banners/annoying.html</quote>, or almost an infinite number of other
2855  possible combinations, just so it has <quote>banners</quote> in the path
2856  somewhere.
2857 </para>
2858
2859 <para>
2860  A now something a little more complex:
2861 </para>
2862
2863 <para>
2864  <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> -
2865  We have several literal forward slashes again (<quote>/</quote>), so we are
2866  building another expression that is a file path statement. We have another
2867  <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
2868  it matches our expression. The only true literal that <emphasis>must
2869  match</emphasis> our pattern is <application>adv</application>, together with
2870  the forward slashes. What comes after the <quote>adv</quote> string is the
2871  interesting part.
2872 </para>
2873
2874 <para>
2875  Remember the <quote>?</quote> means the preceding expression (either a
2876  literal character or anything grouped with <quote>(...)</quote> in this case)
2877  can exist or not, since this means either zero or one match. So
2878  <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
2879  individual sub-expressions: <quote>(er)</quote>,
2880  <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
2881  means <quote>or</quote>. We have two of those. For instance,
2882  <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote>
2883  <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
2884  attempt at matching as many variations of <quote>advertisement</quote>, and
2885  similar, as possible. So this would expand to match just <quote>adv</quote>,
2886  or <quote>advert</quote>, or <quote>adverts</quote>, or
2887  <quote>advertising</quote>, or <quote>advertisement</quote>, or
2888  <quote>advertisements</quote>. You get the idea. But it would not match
2889  <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
2890  changing our regular expression to:
2891  <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
2892  either spelling.
2893 </para>
2894
2895 <para>
2896  <emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
2897  another path statement with forward slashes. Anything in the square brackets
2898  <quote>[]</quote> can be matched. This is using <quote>0-9</quote> as a
2899  shorthand expression to mean any digit one through nine. It is the same as
2900  saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
2901  means one or more of the preceding expression must be included. The preceding
2902  expression here is what is in the square brackets -- in this case, any digit
2903  one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>.
2904  This includes a <quote>|</quote>, so this needs to match the expression on
2905  either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
2906  side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
2907  since the <quote>?</quote> means the letter <quote>e</quote> is optional and
2908  can be matched once or not at all. So we are building an expression here to
2909  match image GIF or JPEG type image file. It must include the literal
2910  string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
2911  (which is now a literal, and not a special character, since it is escaped
2912  with <quote>\</quote>), and lastly either <quote>gif</quote>, or
2913  <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
2914  include: <quote>//advert1.jpg</quote>,
2915  <quote>/nasty/ads/advert1234.gif</quote>,
2916  <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
2917  <quote>advert1.gif</quote> (no leading slash), or
2918  <quote>/adverts232.jpg</quote> (the expression does not include an
2919  <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
2920  in the expression anywhere).
2921 </para>
2922
2923 <para>
2924  <emphasis><literal>s/microsoft(?!.com)/MicroSuck/i</literal></emphasis> - This is
2925  a substitution. <quote>MicroSuck</quote> will replace any occurence of
2926  <quote>microsoft</quote>.  The <quote>i</quote> at the end of the expression
2927  means ignore case. The <quote>(?!.com)</quote> means
2928  the match should fail if <quote>microsoft</quote> is followed by
2929  <quote>.com</quote>. In other words, this acts like a <quote>NOT</quote>
2930  modifier. In case this is a hyperlink, we don't want to break it ;-).
2931 </para>
2932
2933 <para>
2934  We are barely scratching the surface of regular expressions here so that you
2935  can understand the default <application>Junkbuster</application>
2936  configuration files, and maybe use this knowledge to customize your own
2937  installation. There is much, much more that can be done with regular
2938  expressions. Now that you know enough to get started, you can learn more on
2939  your own :/
2940 </para>
2941
2942 <para>
2943  More reading on Perl Compatible Regular expressions:
2944  <ulink url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>
2945 </para>
2946
2947 </sect2>
2948
2949 </sect1>
2950
2951  <!--
2952
2953  This program is free software; you can redistribute it
2954  and/or modify it under the terms of the GNU General
2955  Public License as published by the Free Software
2956  Foundation; either version 2 of the License, or (at
2957  your option) any later version.
2958
2959  This program is distributed in the hope that it will
2960  be useful, but WITHOUT ANY WARRANTY; without even the
2961  implied warranty of MERCHANTABILITY or FITNESS FOR A
2962  PARTICULAR PURPOSE.  See the GNU General Public
2963  License for more details.
2964
2965  The GNU General Public License should be included with
2966  this file.  If not, you can view it at
2967  http://www.gnu.org/copyleft/gpl.html
2968  or write to the Free Software Foundation, Inc., 59
2969  Temple Place - Suite 330, Boston, MA  02111-1307, USA.
2970
2971  $Log: user-manual.sgml,v $
2972  Revision 1.13  2001/10/10 17:28:33  hal9
2973  Very minor changes.
2974
2975  Revision 1.12  2001/09/28 02:57:04  hal9
2976  Ditto :/
2977
2978  Revision 1.11  2001/09/28 02:25:20  hal9
2979  Ditto.
2980
2981  Revision 1.9  2001/09/27 23:50:29  hal9
2982  A few changes. A short section on regular expression in appendix.
2983
2984  Revision 1.8  2001/09/25 00:34:59  hal9
2985  Some additions, and re-arranging.
2986
2987  Revision 1.7  2001/09/24 14:31:36  hal9
2988  Diddling.
2989
2990  Revision 1.6  2001/09/24 14:10:32  hal9
2991  Including David's OS/2 installation instructions.
2992
2993  Revision 1.2  2001/09/13 15:27:40  swa
2994  cosmetics
2995
2996  Revision 1.1  2001/09/12 15:36:41  swa
2997  source files for junkbuster documentation
2998
2999  Revision 1.3  2001/09/10 17:43:59  swa
3000  first proposal of a structure.
3001
3002  Revision 1.2  2001/06/13 14:28:31  swa
3003  docs should have an author.
3004
3005  Revision 1.1  2001/06/13 14:20:37  swa
3006  first import of project's documentation for the webserver.
3007
3008  -->
3009
3010 </article>