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