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