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