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