-<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<!--
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
- File : $Source: /cvsroot/ijbswa/current/doc/webserver/faq.html,v $
+ File : $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
- Purpose : FAQ
+ Purpose : user manual
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: faq.html,v 1.3 2001/09/10 17:43:59 swa Exp $
+ $Id: user-manual.sgml,v 1.46 2002/03/10 00:51:08 hal9 Exp $
Written by and Copyright (C) 2001 the SourceForge
IJBSWA team. http://ijbswa.sourceforge.net
Junkbusters Corporation. http://www.junkbusters.com
-->
+<!--
+Sat 03/02/02 04:53:47 PM
+
+This should be ready for BETA release.
+
+Hal Burgiss <hal@foobox.net>
+-->
+
<article id="index">
<artheader>
<title>Junkbuster User Manual</title>
-<pubdate>$Id: faq.html,v 1.3 2001/09/10 17:43:59 swa Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 1.46 2002/03/10 00:51:08 hal9 Exp $</pubdate>
<authorgroup>
<author>
<abstract>
<para>
- The user manual gives the users information on how to install and
-configure the Internet Junkbuster. The Internet Junkbuster is an application
-that provides privacy and security to the user of the world wide web.
+ The user manual gives users information on how to install, configure and use
+ <application>Internet Junkbuster</application>. <application>Internet
+ Junkbuster</application> is a web proxy with advanced filtering capabilities
+ for protecting privacy, filtering web page content, managing cookies,
+ controlling access, and removing ads, banners, pop-ups and other obnoxious
+ Internet Junk. Junkbuster has a very flexible configuration and can be
+ customized to suit individual needs and tastes. <application>Internet
+ Junkbuster</application> has application for both stand-alone systems and
+ multi-user networks.
</para>
<para>
-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>.
+You can find the latest version of the user manual at <ulink url="http://ijbswa.sourceforge.net/user-manual/">http://ijbswa.sourceforge.net/user-manual/</ulink>.
</para>
- <para>
- Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>.
- </para>
+<!-- <para> -->
+<!-- Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
+<!-- </para> -->
</abstract>
+
</artheader>
+
<!-- ~~~~~ New section ~~~~~ -->
+
<sect1 id="introduction"><title>Introduction</title>
-<para>To be filled.
+<para>
+ <application>Internet Junkbuster</application> is a web proxy with advanced
+ filtering capabilities for protecting privacy, filtering and modifying web
+ page content, managing cookies, controlling access, and removing ads,
+ banners, pop-ups and other obnoxious Internet Junk.
+ <application>Junkbuster</application> has a very flexible configuration and
+ can be customized to suit individual needs and tastes. <application>Internet
+ Junkbuster</application> has application for both stand-alone systems and
+ multi-user networks.
</para>
-</sect1>
+
+<para>
+ This documentation is included with the current BETA version of
+ <application>Internet Junkbuster</application> and is mostly complete at this
+ point. The most up to date reference for the time being is still the comments
+ in the source files and in the individual configuration files. Development
+ of version 3.0 is currently nearing completion, and includes many significant
+ changes and enhancements over earlier versions. The target release date for
+ stable v3.0 is <quote>soon</quote> ;-)
+</para>
+
+<para>
+ Since this is a BETA version, not all new features are well tested. This
+ documentation may be slightly out of sync as a result (especially with
+ CVS sources). And there <emphasis>may be</emphasis> bugs, though hopefully
+ not many!
+</para>
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="quickstart"><title>Quickstart to Using Junkbuster</title>
-<para>To be filled.
+<sect2>
+<title>New Features</title>
+<para>
+ In addition to <application>Junkbuster's</application> traditional features
+ of ad and banner blocking and cookie management, this is a list of new
+ features currently under development:
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Integrated browser based configuration and control utility (<ulink
+ url="http://i.j.b">http://i.j.b</ulink>). Browser-based tracing of rule
+ and filter effects.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Modularized configuration that will allow for system wide settings, and
+ individual user settings. (not implemented yet, probably a 3.1 feature)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Blocking of annoying pop-up browser windows.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ HTTP/1.1 compliant (most, but not all 1.1 features are supported).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Support for Perl Compatible Regular Expressions in the configuration files, and
+ generally a more sophisticated and flexible configuration syntax over
+ previous versions.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ GIF de-animation.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Web page content filtering (removes banners based on size,
+ invisible <quote>web-bugs</quote>, JavaScript, pop-ups, status bar abuse,
+ etc.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Bypass many click-tracking scripts (avoids script redirection).
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Multi-threaded (POSIX and native threads).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Auto-detection and re-reading of config file changes.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ User-customizable HTML templates (e.g. 404 error page).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Improved cookie management features (e.g. session based cookies).
+ </para>
+</listitem>
+
+ <listitem>
+ <para>
+ Builds from source on most UNIX-like systems. Packages available for: Linux
+ (RedHat, SuSE, or Debian), Windows, Sun Solaris, Mac OSX, OS/2, HP-UX 11 and AmigaOS.
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ In addition, the configuration is much more powerful and versatile over-all.
+ </para>
+</listitem>
+
+ </itemizedlist>
</para>
+
+</sect2>
+
</sect1>
+<!-- ~ End section ~ -->
+
+
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="installation"><title>Installation</title>
-<para>To be filled.
+<para>
+ <application>Junkbuster</application> is available as raw source code, or
+ pre-compiled binaries. See the <ulink
+ url="http://sourceforge.net/projects/ijbswa/">Junkbuster Home Page</ulink>
+ for binaries and current release info. <application>Junkbuster</application>
+ is also available via <ulink
+ url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/current/">CVS</ulink>.
+ This is the recommended approach at this time. But please be aware that CVS
+ is constantly changing, and it may break in mysterious ways.
+</para>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="installation-source"><title>Source</title>
+<para>
+ For gzipped tar archives, unpack the source:
+</para>
+
+<para>
+ <screen>
+ tar xzvf ijb_source_* [.tgz or .tar.gz]
+ cd ijb_source_2.9.11_beta
+ </screen>
+</para>
+
+<para>
+ For retrieving the current CVS sources, you'll need the CVS
+ package installed first. To download CVS source:
</para>
+<para>
+ <screen>
+ cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co current
+ cd current
+ </screen>
+</para>
+
+<para>
+ This will create a directory named <filename>current/</filename>, which will
+ contain the source tree.
+</para>
+
+<para>
+ Then, in either case, to build from tarball/CVS source:
+</para>
+
+<para>
+ <screen>
+ ./configure (--help to see options)
+ make (the make from gnu, gmake for *BSD)
+ su
+ make -n install (to see where all the files will go)
+ make install (to really install)
+ </screen>
+</para>
+
+<para>
+ For Redhat and SuSE Linux RPM packages, see below.
+</para>
+
+</sect2>
+
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="installation-rh"><title>Red Hat</title>
-<para>To be filled.
+<para>
+ To build Redhat RPM packages, install source as above. Then:
+</para>
+
+<para>
+ <screen>
+ autoheader [suggested for CVS source]
+ autoconf [suggested for CVS source]
+ ./configure
+ make redhat-dist
+ </screen>
+</para>
+
+<para>
+ This will create both binary and src RPMs in the usual places. Example:
+</para>
+
+<para>
+ /usr/src/redhat/RPMS/i686/junkbuster-2.9.11-1.i686.rpm
+</para>
+<para>
+ /usr/src/redhat/SRPMS/junkbuster-2.9.11-1.src.rpm
+</para>
+
+<para>
+ To install, of course:
+</para>
+
+<para>
+ <screen>
+ rpm -Uvv /usr/src/redhat/RPMS/i686/junkbuster-2.9.11-1.i686.rpm
+ </screen>
</para>
+
+<para>
+ This will place the <application>Junkbuster</application> configuration
+ files in <filename>/etc/junkbuster/</filename>, and log files in
+ <filename>/var/log/junkbuster/</filename>.
+</para>
+
</sect2>
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="installation-suse"><title>SuSE</title>
-<para>To be filled.
+<para>
+ To build SuSE RPM packages, install source as above. Then:
+</para>
+
+<para>
+ <screen>
+ autoheader [suggested for CVS source]
+ autoconf [suggested for CVS source]
+ ./configure
+ make suse-dist
+ </screen>
+</para>
+
+<para>
+ This will create both binary and src RPMs in the usual places. Example:
+</para>
+
+<para>
+ /usr/src/packages/RPMS/i686/junkbuster-2.9.11-1.i686.rpm
+</para>
+<para>
+ /usr/src/packages/SRPMS/junkbuster-2.9.11-1.src.rpm
+</para>
+
+<para>
+ To install, of course:
+</para>
+
+<para>
+ <screen>
+ rpm -Uvv /usr/src/packages/RPMS/i686/junkbuster-2.9.11-1.i686.rpm
+ </screen>
+</para>
+
+<para>
+ This will place the <application>Junkbuster</application> configuration
+ files in <filename>/etc/junkbuster/</filename>, and log files in
+ <filename>/var/log/junkbuster/</filename>.
+</para>
+
+</sect2>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="installation-os2"><title>OS/2</title>
+
+<!--
+Thanx David Schmidt!
+-->
+
+<para>
+ <application>Junkbuster</application> is packaged in a WarpIN self-
+ installing archive. The self-installing program will be named depending
+ on the release version, something like:
+ <filename>ijbos2_setup_1.2.3.exe</filename>. In order to install it, simply
+ run this executable or double-click on its icon and follow the WarpIN
+ installation panels. A shadow of the <application>Junkbuster</application>
+ executable will be placed in your startup folder so it will start
+ automatically whenever OS/2 starts.
+</para>
+
+<para>
+ The directory you choose to install <application>Junkbuster</application>
+ into will contain all of the configuration files.
+</para>
+
+<para>
+ If you would like to build binary images on OS/2 yourself, you will need
+ a few Unix-like tools: autoconf, autoheader and sh. These tools will be
+ used to create the required config.h file, which is not part of the
+ source distribution because it differs based on platform. You will also
+ need a compiler.
+ The distribution has been created using IBM VisualAge compilers, but you
+ can use any compiler you like. GCC/EMX has the disadvantage of needing
+ to be single-threaded due to a limitation of EMX's implementation of the
+ select() socket call.
+</para>
+
+<para>
+ In addition to needing the source code distribution as outlined earlier,
+ you will want to extract the <filename>os2seutp</filename> directory from CVS:
+ <screen>
+ cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
+ </screen>
+ This will create a directory named os2setup/, which will contain the
+ <filename>Makefile.vac</filename> makefile and <filename>os2build.cmd</filename>
+ which is used to completely create the binary distribution. The sequence
+ of events for building the executable for yourself goes something like this:
+ <screen>
+ cd current
+ autoheader
+ autoconf
+ sh configure
+ cd ..\os2setup
+ nmake -f Makefile.vac
+ </screen>
+ You will see this sequence laid out in <filename>os2build.cmd</filename>.
</para>
+
</sect2>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="installation-win"><title>Windows</title>
-<para>To be filled.
+<para>Click-click. (I need help on this. Not a clue here. Also for
+configuration section below. HB.)
</para>
</sect2>
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="installation-other"><title>Other</title>
-<para>To be filled.
+<para>
+ Some quick notes on other Operating Systems.
+</para>
+
+<para>
+ For FreeBSD (and other *BSDs?), the build will require <command>gmake</command>
+ instead of the included <command>make</command>. <command>gmake</command> is
+ available from <ulink url="http://www.gnu.org">http://www.gnu.org</ulink>.
+ The rest should be the same as above for Linux/Unix.
</para>
+
</sect2>
</sect1>
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="configuration"><title>JunkBuster Configuration</title>
+ <para>
+ All <application>JunkBuster</application> configuration is kept
+ in text files. These files can be edited with a text editor.
+ Many important aspects of <application>JunkBuster</application> can
+ also be controlled easily with a web browser.
+
+ </para>
+
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="configuration"><title>Configuration</title>
-<para>To be filled.
+
+<sect2>
+<title>Controlling Junkbuster with Your Web Browser</title>
+<para>
+ <application>JunkBuster</application> can be reached by the special
+ URL <ulink url="http://i.j.b/">http://i.j.b/</ulink> (or alternately
+ <ulink url="http://ijbswa.sourceforge.net/config/">http://ijbswa.sourceforge.net/config/</ulink>,
+ which is an internal page. You will see the following section:
+
</para>
-</sect1>
+
+<para>
+ <screen>
+
+Please choose from the following options:
+
+ * Show information about the current configuration
+ * Show the source code version numbers
+ * Show the client's request headers.
+ * Show which actions apply to a URL and why
+ * Toggle JunkBuster on or off
+ * Edit the actions list
+
+ </screen>
+</para>
+
+<para>
+ This should be self-explanatory. Note the last item is an editor for the
+ <quote>actions list</quote>, which is where much of the ad, banner, cookie,
+ and URL blocking magic is configured as well as other advanced features of
+ <application>Junkbuster</application>. This is an easy way to adjust various
+ aspects of <application>Junkbuster</application> configuration. The actions
+ file, and other configuration files, are explained in detail below.
+ <application>Junkbuster</application> will automatically detect any changes
+ to these files.
+</para>
+
+<para>
+ <quote>Toggle JunkBuster On or Off</quote> is handy for sites that might
+ have problems with your current actions and filters, or just to test if
+ a site misbehaves, whether it is <application>JunkBuster</application>
+ causing the problem or not. <application>Junkbuster</application> continues
+ to run as a proxy in this case, but all filtering is disabled.
+
+</para>
+
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="contact"><title>Contact the developers</title>
-<para>To be filled. mention the support forums as the primary channel of
-communication (bugs, feature requests, etc.)
+
+<sect2>
+<title>Configuration Files Overview</title>
+<para>
+ For Unix, *BSD and Linux, all configuration files are located in
+ <filename>/etc/junkbuster/</filename> by default. For MS Windows, OS/2, and
+ AmigaOS these are all in the same directory as the
+ <application>Junkbuster</application> executable. The name and number of
+ configuration files has changed from previous versions, and is subject to
+ change as development progresses.
</para>
-</sect1>
+
+<para>
+ The installed defaults provide a reasonable starting point, though possibly
+ aggressive by some standards. For the time being, there are only three
+ default configuration files (this will change in time):
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ The main configuration file is named <filename>config</filename>
+ on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
+ on Windows.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <filename>ijb.action</filename> file is used to define various
+ <quote>actions</quote> relating to images, banners, pop-ups, access
+ restrictions, banners and cookies. There is a CGI based editor for this
+ file that can be accessed via <ulink
+ url="http://i.j.b">http://i.j.b</ulink>. (Other actions
+ files are included as well with differing levels of filtering
+ and blocking, e.g. <filename>ijb-basic.action</filename>.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <filename>re_filterfile</filename> file can be used to rewrite the raw
+ page content, including text as well as embedded HTML and JavaScript.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+<para>
+ <filename>ijb.action</filename> and <filename>re_filterfile</filename>
+ can use Perl style regular expressions for maximum flexibility. All files use
+ the <quote><literal>#</literal></quote> character to denote a comment. Such
+ lines are not processed by <application>Junkbuster</application>. After
+ making any changes, there is no need to restart
+ <application>Junkbuster</application> in order for the changes to take
+ effect. <application>Junkbuster</application> should detect such changes
+ automatically.
+</para>
+
+<para>
+ While under development, the configuration content is subject to change.
+ The below documentation may not be accurate by the time you read this.
+ Also, what constitutes a <quote>default</quote> setting, may change, so
+ please check all your configuration files on important issues.
+</para>
+</sect2>
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="copyright"><title>Copyright and History</title>
-<para>To be filled.
+
+<sect2>
+<title>The Main Configuration File</title>
+<para>
+ Again, the main configuration file is named <filename>config</filename> on
+ Linux/Unix/BSD and OS/2, and <filename>config.txt</filename> on Windows.
+ Configuration lines consist of an initial keyword followed by a list of
+ values, all separated by whitespace (any number of spaces or tabs). For
+ example:
</para>
-</sect1>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>blockfile blocklist.ini</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Indicates that the blockfile is named <quote>blocklist.ini</quote>.
+</para>
+
+<para>
+ A <quote><literal>#</literal></quote> indicates a comment. Any part of a
+ line following a <quote><literal>#</literal></quote> is ignored, except if
+ the <quote><literal>#</literal></quote> is preceded by a
+ <quote><literal>\</literal></quote>.
+</para>
+
+<para>
+ Thus, by placing a <quote><literal>#</literal></quote> at the start of an
+ existing configuration line, you can make it a comment and it will be treated
+ as if it weren't there. This is called <quote>commenting out</quote> an
+ option and can be useful to turn off features: If you comment out the
+ <quote>logfile</quote> line, <application>junkbuster</application> will not
+ log to a file at all. Watch for the <quote>default:</quote> section in each
+ explanation to see what happens if the option is left unset (or commented
+ out).
+</para>
+
+<para>
+ Long lines can be continued on the next line by using a
+ <quote><literal>\</literal></quote> as the very last character.
+</para>
+
+<para>
+ There are various aspects of <application>Junkbuster</application> behavior
+ that can be tuned.
+</para>
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="seealso"><title>See also</title>
-<para>To be filled.
+
+<sect3>
+<title>Defining Other Configuration Files</title>
+
+<para>
+ <application>Junkbuster</application> can use a number of other files to tell it
+ what ads to block, what cookies to accept, etc. This section of the
+ configuration file tells <application>Junkbuster</application> where to find
+ all those other files.
</para>
-</sect1>
-<!-- hhmts end -->
- <!--
- Tue 09/11/01 06:38:14 PM EST: Test SGML doc by Hal Burgiss.
-
- Last modified: Mon Sep 10 19:22:09 CEST 2001
+<para>
+ On <application>Windows</application> and <application>AmigaOS</application>,
+ <application>Junkbuster</application> looks for these files in the same
+ directory as the executable. On Unix and OS/2,
+ <application>Junkbuster</application> looks for these files in the current
+ working directory. In either case, an absolute path name can be used to
+ avoid problems.
+</para>
+
+<para>
+ When development goes modular and multi-user, the blocker, filter, and
+ per-user config will be stored in subdirectories of <quote>confdir</quote>.
+ For now, only <filename>confdir/templates</filename> is used for storing HTML
+ templates for CGI results.
+</para>
+
+<para>
+ The location of the configuration files:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>confdir /etc/junkbuster</emphasis> # No trailing /, please.
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ The directory where all logging (i.e. <filename>logfile</filename> and
+ <filename>jarfile</filename>) takes place. No trailing
+ <quote><literal>/</literal></quote>, please:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>logdir /var/log/junkbuster</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Note that all file specifications below are relative to
+ the above two directories!
+</para>
+
+<para>
+ The <quote>ijb.action</quote> file contains patterns to specify the actions to
+ apply to requests for each site. Default: Cookies to and from all
+ destinations are kept only during the current browser session (i.e. they
+ are not saved to disk). Pop-ups are disabled for all sites. All sites are
+ filtered if <quote>re_filterfile</quote> specified according to the
+ contents of <quote>re_filterfile</quote>. No sites are blocked. The
+ JunkBuster logo is displayed for filtered ads and other images . The syntax
+ of this file is explained in detail <link
+ linkend="actionsfile">below</link>.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>actionsfile ijb.action</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ The <quote>re_filterfile</quote> file contains content modification rules.
+ These rules permit powerful changes on the content of Web pages, e.g., you
+ could disable your favorite JavaScript annoyances, rewrite the actual
+ content, or just have some fun replacing <quote>Microsoft</quote> with
+ <quote>MicroSuck</quote> wherever it appears on a Web page. Default: No
+ content modification, or whatever the developers are playing with :-/
+</para>
+
+<para>
+ Filtering requires buffering the page content, which may appear to slow down
+ page rendering since nothing is displayed until all content has passed
+ the filters. (It does not really take longer, but seems that way since
+ the page is not incrementally displayed.) This effect will be more noticeable
+ on slower connections.
+
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>re_filterfile re_filterfile</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ The logfile is where all logging and error messages are written. The logfile
+ can be useful for tracking down a problem with
+ <application>Junkbuster</application> (e.g., it's not blocking an ad you
+ think it should block) but in most cases you probably will never look at it.
+</para>
+
+<para>
+ Your logfile will grow indefinitely, and you will probably want to
+ periodically remove it. On Unix systems, you can do this with a cron job
+ (see <quote>man cron</quote>). For Redhat, a <command>logrotate</command>
+ script has been included.
+</para>
+
+<para>
+ On SuSE Linux systems, you can place a line like <quote>/var/log/junkbuster.*
+ +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
+ the effect that cron.daily will automatically archive, gzip, and empty the
+ log, when it exceeds 1M size.
+</para>
+
+<para>
+ Default: Log to the a file named <filename>logfile</filename>.
+ Comment out to disable logging.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>logfile logfile</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ The <quote>jarfile</quote> defines where
+ <application>Junkbuster</application> stores the cookies it intercepts. Note
+ that if you use a <quote>jarfile</quote>, it may grow quite large. Default:
+ Don't store intercepted cookies.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>#jarfile jarfile</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ If you specify a <quote>trustfile</quote>,
+ <application>Junkbuster</application> will only allow access to sites that
+ are named in the trustfile. You can also mark sites as trusted referrers,
+ with the effect that access to untrusted sites will be granted, if a link
+ from a trusted referrer was used. The link target will then be added to the
+ <quote>trustfile</quote>. This is a very restrictive feature that typical
+ users most probably want to leave disabled. Default: Disabled, don't use the
+ trust mechanism.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>#trustfile trust</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
- This program is free software; you can redistribute it
- and/or modify it under the terms of the GNU General
- Public License as published by the Free Software
- Foundation; either version 2 of the License, or (at
- your option) any later version.
+<para>
+ If you use the trust mechanism, it is a good idea to write up some on-line
+ documentation about your blocking policy and to specify the URL(s) here. They
+ will appear on the page that your users receive when they try to access
+ untrusted content. Use multiple times for multiple URLs. Default: Don't
+ display links on the <quote>untrusted</quote> info page.
+</para>
- This program is distributed in the hope that it will
- be useful, but WITHOUT ANY WARRANTY; without even the
- implied warranty of MERCHANTABILITY or FITNESS FOR A
- PARTICULAR PURPOSE. See the GNU General Public
- License for more details.
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>trust-info-url http://www.your-site.com/why_we_block.html</emphasis>
+ <emphasis>trust-info-url http://www.your-site.com/what_we_allow.html</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
- The GNU General Public License should be included with
- this file. If not, you can view it at
- http://www.gnu.org/copyleft/gpl.html
- or write to the Free Software Foundation, Inc., 59
- Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+</sect3>
-$Log: faq.html,v $
-Revision 1.3 2001/09/10 17:43:59 swa
-first proposal of a structure.
+<!-- ~ End section ~ -->
-Revision 1.2 2001/06/13 14:28:31 swa
-docs should have an author.
-Revision 1.1 2001/06/13 14:20:37 swa
-first import of project's documentation for the webserver.
--->
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3>
+<title>Other Configuration Options</title>
+
+<para>
+ This part of the configuration file contains options that control how
+ <application>Junkbuster</application> operates.
+</para>
+
+<para>
+ <quote>Admin-address</quote> should be set to the email address of the proxy
+ administrator. It is used in many of the proxy-generated pages. Default:
+ fill@me.in.please.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>#admin-address fill@me.in.please</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ <quote>Proxy-info-url</quote> can be set to a URL that contains more info
+ about this <application>Junkbuster</application> installation, it's
+ configuration and policies. It is used in many of the proxy-generated pages
+ and its use is highly recommended in multi-user installations, since your
+ users will want to know why certain content is blocked or modified. Default:
+ Don't show a link to on-line documentation.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>proxy-info-url http://www.your-site.com/proxy.html</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ <quote>Listen-address</quote> specifies the address and port where
+ <application>Junkbuster</application> will listen for connections from your
+ Web browser. The default is to listen on the localhost port 8118, and
+ this is suitable for most users. (In your web browser, under proxy
+ configuration, list the proxy server as <quote>localhost</quote> and the
+ port as <quote>8118</quote>).
+</para>
+
+<para>
+ If you already have another service running on port 8118, or if you want to
+ serve requests from other machines (e.g. on your local network) as well, you
+ will need to override the default. The syntax is
+ <quote>listen-address [<ip-address>]:<port></quote>. If you leave
+ out the IP address, <application>junkbuster</application> will bind to all
+ interfaces (addresses) on your machine and may become reachable from the
+ Internet. In that case, consider using access control lists (acl's) (see
+ <quote>aclfile</quote> above), or a firewall.
+</para>
+
+<para>
+ For example, suppose you are running <application>Junkbuster</application> on
+ a machine which has the address 192.168.0.1 on your local private network
+ (192.168.0.0) and has another outside connection with a different address.
+ You want it to serve requests from inside only:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>listen-address 192.168.0.1:8118</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ If you want it to listen on all addresses (including the outside
+ connection):
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>listen-address :8118</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ If you do this, consider using ACLs (see <quote>aclfile</quote> above). Note:
+ you will need to point your browser(s) to the address and port that you have
+ configured here. Default: localhost:8118 (127.0.0.1:8118).
+</para>
+
+<para>
+ The debug option sets the level of debugging information to log in the
+ logfile (and to the console in the Windows version). A debug level of 1 is
+ informative because it will show you each request as it happens. Higher
+ levels of debug are probably only of interest to developers.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ debug 1 # GPC = show each GET/POST/CONNECT request
+ debug 2 # CONN = show each connection status
+ debug 4 # IO = show I/O status
+ debug 8 # HDR = show header parsing
+ debug 16 # LOG = log all data into the logfile
+ debug 32 # FRC = debug force feature
+ debug 64 # REF = debug regular expression filter
+ debug 128 # = debug fast redirects
+ debug 256 # = debug GIF de-animation
+ debug 512 # CLF = Common Log Format
+ debug 1024 # = debug kill pop-ups
+ debug 4096 # INFO = Startup banner and warnings.
+ debug 8192 # ERROR = Non-fatal errors
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ It is <emphasis>highly recommended</emphasis> that you enable ERROR
+ reporting (debug 8192), at least until the next stable release.
+</para>
+
+<para>
+ The reporting of FATAL errors (i.e. ones which crash
+ <application>JunkBuster</application>) is always on and cannot be disabled.
+</para>
+
+<para>
+ If you want to use CLF (Common Log Format), you should set <quote>debug
+ 512</quote> ONLY, do not enable anything else.
+</para>
+
+<para>
+ Multiple <quote>debug</quote> directives, are OK - they're logical-OR'd
+ together.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>debug 15 # same as setting the first 4 listed above</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Default:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>debug 1 # URLs</emphasis>
+ <emphasis>debug 4096 # Info</emphasis>
+ <emphasis>debug 8192 # Errors - *we highly recommended enabling this*</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ <application>Junkbuster</application> normally uses
+ <quote>multi-threading</quote>, a software technique that permits it to
+ handle many different requests simultaneously. In some cases you may wish to
+ disable this -- particularly if you're trying to debug a problem. The
+ <quote>single-threaded</quote> option forces
+ <application>Junkbuster</application> to handle requests sequentially.
+ Default: Multi-threaded mode.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>#single-threaded</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ <quote>toggle</quote> allows you to temporarily disable all
+ <application>Junkbuster's</application> filtering. Just set <quote>toggle
+ 0</quote>.
+</para>
+
+<para>
+ The Windows version of <application>Junkbuster</application> puts an icon in
+ the system tray, which also allows you to change this option. If you
+ right-click on that icon (or select the <quote>Options</quote> menu), one
+ choice is <quote>Enable</quote>. Clicking on enable toggles
+ <application>Junkbuster</application> on and off. This is useful if you want
+ to temporarily disable <application>Junkbuster</application>, e.g., to access
+ a site that requires cookies which you would otherwise have blocked. This can also
+ be toggled via a web browser at the <application>Junkbuster</application>
+ internal address of <ulink url="http://i.j.b">http://i.j.b</ulink> on
+ any platform.
+</para>
+
+<para>
+ <quote>toggle 1</quote> means <application>Junkbuster</application> runs
+ normally, <quote>toggle 0</quote> means that
+ <application>Junkbuster</application> becomes a non-anonymizing non-blocking
+ proxy. Default: 1 (on).
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>toggle 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ For content filtering, i.e. the <quote>+filter</quote> and
+ <quote>+deanimate-gif</quote> actions, it is necessary that
+ <application>Junkbuster</application> buffers the entire document body.
+ This can be potentially dangerous, since a server could just keep sending
+ data indefinitely and wait for your RAM to exhaust. With nasty consequences.
+</para>
+
+<para>
+ The <application>buffer-limit</application> option lets you set the maximum
+ size in Kbytes that each buffer may use. When the documents buffer exceeds
+ this size, it is flushed to the client unfiltered and no further attempt to
+ filter the rest of it is made. Remember that there may multiple threads
+ running, which might require increasing the <quote>buffer-limit</quote>
+ Kbytes <emphasis>each</emphasis>, unless you have enabled
+ <quote>single-threaded</quote> above.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>buffer-limit 4069</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ To enable the web-based <filename>ijb.action</filename> file editor set
+ <application>enable-edit-actions</application> to 1, or 0 to disable. Note
+ that you must have compiled <application>JunkBuster</application> with
+ support for this feature, otherwise this option has no effect. This
+ internal page can be reached at <ulink
+ url="http://i.j.b">http://i.j.b</ulink>.
+ </para>
+
+<para>
+ Security note: If this is enabled, anyone who can use the proxy
+ can edit the actions file, and their changes will affect all users.
+ For shared proxies, you probably want to disable this. Default: enabled.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>enable-edit-actions 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Allow <application>JunkBuster</application> to be toggled on and off
+ remotely, using your web browser. Set <quote>enable-remote-toggle</quote>to
+ 1 to enable, and 0 to disable. Note that you must have compiled
+ <application>JunkBuster</application> with support for this feature,
+ otherwise this option has no effect.
+</para>
+
+<para>
+ Security note: If this is enabled, anyone who can use the proxy can toggle
+ it on or off (see <ulink url="http://i.j.b">http://i.j.b</ulink>), and
+ their changes will affect all users. For shared proxies, you probably want to
+ disable this. Default: enabled.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>enable-remote-toggle 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+</sect3>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3>
+<title>Access Control List (ACL)</title>
+<para>
+ Access controls are included at the request of some ISPs and systems
+ administrators, and are not usually needed by individual users. Please note
+ the warnings in the FAQ that this proxy is not intended to be a substitute
+ for a firewall or to encourage anyone to defer addressing basic security
+ weaknesses.
+</para>
+
+<para>
+ If no access settings are specified, the proxy talks to anyone that
+ connects. If any access settings file are specified, then the proxy
+ talks only to IP addresses permitted somewhere in this file and not
+ denied later in this file.
+</para>
+
+<para>
+ Summary -- if using an ACL:
+</para>
+
+ <simplelist>
+ <member>
+ Client must have permission to receive service.
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ LAST match in ACL wins.
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ Default behavior is to deny service.
+ </member>
+ </simplelist>
+
+<para>
+ The syntax for an entry in the Access Control List is:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ ACTION SRC_ADDR[/SRC_MASKLEN] [ DST_ADDR[/DST_MASKLEN] ]
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Where the individual fields are:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>ACTION</emphasis> = <quote>permit-access</quote> or <quote>deny-access</quote>
+
+ <emphasis>SRC_ADDR</emphasis> = client hostname or dotted IP address
+ <emphasis>SRC_MASKLEN</emphasis> = number of bits in the subnet mask for the source
+
+ <emphasis>DST_ADDR</emphasis> = server or forwarder hostname or dotted IP address
+ <emphasis>DST_MASKLEN</emphasis> = number of bits in the subnet mask for the target
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+
+<para>
+ The field separator (FS) is whitespace (space or tab).
+</para>
+
+<para>
+ IMPORTANT NOTE: If the <application>junkbuster</application> is using a
+ forwarder (see below) or a gateway for a particular destination URL, the
+ <literal>DST_ADDR</literal> that is examined is the address of the forwarder
+ or the gateway and <emphasis>NOT</emphasis> the address of the ultimate
+ target. This is necessary because it may be impossible for the local
+ <application>Junkbuster</application> to determine the address of the
+ ultimate target (that's often what gateways are used for).
+</para>
+
+<para>
+ Here are a few examples to show how the ACL features work:
+</para>
+
+<para>
+ <quote>localhost</quote> is OK -- no DST_ADDR implies that
+ <emphasis>ALL</emphasis> destination addresses are OK:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>permit-access localhost</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ A silly example to illustrate permitting any host on the class-C subnet with
+ <application>Junkbuster</application> to go anywhere:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>permit-access www.junkbusters.com/24</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Except deny one particular IP address from using it at all:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>deny-access ident.junkbusters.com</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ You can also specify an explicit network address and subnet mask.
+ Explicit addresses do not have to be resolved to be used.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>permit-access 207.153.200.0/24</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ A subnet mask of 0 matches anything, so the next line permits everyone.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>permit-access 0.0.0.0/0</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Note, you <emphasis>cannot</emphasis> say:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>permit-access .org</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ to allow all *.org domains. Every IP address listed must resolve fully.
+</para>
+
+<para>
+ An ISP may want to provide a <application>Junkbuster</application> that is
+ accessible by <quote>the world</quote> and yet restrict use of some of their
+ private content to hosts on its internal network (i.e. its own subscribers).
+ Say, for instance the ISP owns the Class-B IP address block 123.124.0.0 (a 16
+ bit netmask). This is how they could do it:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>permit-access 0.0.0.0/0 0.0.0.0/0</emphasis> # other clients can go anywhere
+ # with the following exceptions:
+
+ <emphasis>deny-access</emphasis> 0.0.0.0/0 123.124.0.0/16 # block all external requests for
+ # sites on the ISP's network
+
+ <emphasis>permit 0.0.0.0/0 www.my_isp.com</emphasis> # except for the ISP's main
+ # web site
+
+ <emphasis>permit 123.124.0.0/16 0.0.0.0/0</emphasis> # the ISP's clients can go
+ # anywhere
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Note that if some hostnames are listed with multiple IP addresses,
+ the primary value returned by DNS (via gethostbyname()) is used. Default:
+ Anyone can access the proxy.
+</para>
+
+</sect3>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3>
+<title>Forwarding</title>
+
+<para>
+ This feature allows chaining of HTTP requests via multiple proxies.
+ It can be used to better protect privacy and confidentiality when
+ accessing specific domains by routing requests to those domains
+ to a special purpose filtering proxy such as lpwa.com. Or to use
+ a caching proxy to speed up browsing.
+</para>
+
+<para>
+ It can also be used in an environment with multiple networks to route
+ requests via multiple gateways allowing transparent access to multiple
+ networks without having to modify browser configurations.
+</para>
+
+<para>
+ Also specified here are SOCKS proxies. <application>Junkbuster</application>
+ SOCKS 4 and SOCKS 4A. The difference is that SOCKS 4A will resolve the target
+ hostname using DNS on the SOCKS server, not our local DNS client.
+</para>
+
+<para>
+ The syntax of each line is:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward target_domain[:port] http_proxy_host[:port]</emphasis>
+ <emphasis>forward-socks4 target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port]</emphasis>
+ <emphasis>forward-socks4a target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port]</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ If http_proxy_host is <quote>.</quote>, then requests are not forwarded to a
+ HTTP proxy but are made directly to the web servers.
+</para>
+
+<para>
+ Lines are checked in sequence, and the last match wins.
+</para>
+
+<para>
+ There is an implicit line equivalent to the following, which specifies that
+ anything not finding a match on the list is to go out without forwarding
+ or gateway protocol, like so:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward .* . </emphasis># implicit
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ In the following common configuration, everything goes to Lucent's LPWA,
+ except SSL on port 443 (which it doesn't handle):
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward .* lpwa.com:8000</emphasis>
+ <emphasis>forward :443 .</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ See the FAQ for instructions on how to automate the login procedure for LPWA.
+ Some users have reported difficulties related to LPWA's use of
+ <quote>.</quote> as the last element of the domain, and have said that this
+ can be fixed with this:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward lpwa. lpwa.com:8000</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ (NOTE: the syntax for specifying target_domain has changed since the
+ previous paragraph was written -- it will not work now. More information
+ is welcome.)
+</para>
+
+<para>
+ In this fictitious example, everything goes via an ISP's caching proxy,
+ except requests to that ISP:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward .* caching.myisp.net:8000</emphasis>
+ <emphasis>forward myisp.net .</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ For the @home network, we're told the forwarding configuration is this:
+</para>
+
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward .* proxy:8080</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Also, we're told they insist on getting cookies and JavaScript, so you should
+ add home.com to the cookie file. We consider JavaScript a security risk.
+ Java need not be enabled.
+</para>
+
+<para>
+ In this example direct connections are made to all <quote>internal</quote>
+ domains, but everything else goes through Lucent's LPWA by way of the
+ company's SOCKS gateway to the Internet.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward-socks4 .* lpwa.com:8000 firewall.my_company.com:1080</emphasis>
+ <emphasis>forward my_company.com .</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ This is how you could set up a site that always uses SOCKS but no forwarders:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward-socks4a .* . firewall.my_company.com:1080</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ An advanced example for network administrators:
+</para>
+
+<para>
+ If you have links to multiple ISPs that provide various special content to
+ their subscribers, you can configure forwarding to pass requests to the
+ specific host that's connected to that ISP so that everybody can see all
+ of the content on all of the ISPs.
+</para>
+
+<para>
+ This is a bit tricky, but here's an example:
+</para>
+
+
+<para>
+ host-a has a PPP connection to isp-a.com. And host-b has a PPP connection to
+ isp-b.com. host-a can run a <application>Junkbuster</application> proxy with
+ forwarding like this:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward .* .</emphasis>
+ <emphasis>forward isp-b.com host-b:8118</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ host-b can run a <application>Junkbuster</application> proxy with forwarding
+ like this:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward .* .</emphasis>
+ <emphasis>forward isp-a.com host-a:8118</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Now, <emphasis>anyone</emphasis> on the Internet (including users on host-a
+ and host-b) can set their browser's proxy to <emphasis>either</emphasis>
+ host-a or host-b and be able to browse the content on isp-a or isp-b.
+</para>
+
+<para>
+ Here's another practical example, for University of Kent at
+ Canterbury students with a network connection in their room, who
+ need to use the University's Squid web cache.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward *. ssbcache.ukc.ac.uk:3128</emphasis> # Use the proxy, except for:
+ <emphasis>forward .ukc.ac.uk . </emphasis> # Anything on the same domain as us
+ <emphasis>forward * . </emphasis> # Host with no domain specified
+ <emphasis>forward 129.12.*.* . </emphasis> # A dotted IP on our /16 network.
+ <emphasis>forward 127.*.*.* . </emphasis> # Loopback address
+ <emphasis>forward localhost.localdomain . </emphasis> # Loopback address
+ <emphasis>forward www.ukc.mirror.ac.uk . </emphasis> # Specific host
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ If you intend to chain <application>Junkbuster</application> and
+ <application>squid</application> locally, then chain as
+ <literal>browser -> squid -> junkbuster</literal> is the recommended way.
+</para>
+
+<para>
+ Your squid configuration could then look like this:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ # Define junkbuster as parent cache
+ <!-- per feedback from user...
+ cache_peer 127.0.0.1 8118 parent 0 no-query
+ -->
+ cache_peer 127.0.0.1 parent 8118 0 no-query
+
+ # Define ACL for protocol FTP
+ acl FTP proto FTP
+
+ # Do not forward ACL FTP to junkbuster
+ always_direct allow FTP
+
+ # Do not forward ACL CONNECT (https) to junkbuster
+ always_direct allow CONNECT
+
+ # Forward the rest to junkbuster
+ never_direct allow all
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+</sect3>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3>
+<title>Windows GUI Options</title>
+<!--
+Removed references to Win32. HB 09/23/01
+-->
+<para>
+ <application>Junkbuster</application> has a number of options specific to the
+ Windows GUI interface:
+</para>
+
+<para>
+ If <quote>activity-animation</quote> is set to 1, the
+ <application>Junkbuster</application> icon will animate when
+ <quote>Junkbuster</quote> is active. To turn off, set to 0.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>activity-animation 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ If <quote>log-messages</quote> is set to 1,
+ <application>Junkbuster</application> will log messages to the console
+ window:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>log-messages 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ If <quote>log-buffer-size</quote> is set to 1, the size of the log buffer,
+ i.e. the amount of memory used for the log messages displayed in the
+ console window, will be limited to <quote>log-max-lines</quote> (see below).
+</para>
+
+<para>
+ Warning: Setting this to 0 will result in the buffer to grow infinitely and
+ eat up all your memory!
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>log-buffer-size 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ <application>log-max-lines</application> is the maximum number of lines held
+ in the log buffer. See above.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>log-max-lines 200</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ If <quote>log-highlight-messages</quote> is set to 1,
+ <application>Junkbuster</application> will highlight portions of the log
+ messages with a bold-faced font:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>log-highlight-messages 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ The font used in the console window:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>log-font-name Comic Sans MS</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Font size used in the console window:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>log-font-size 8</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ <quote>show-on-task-bar</quote> controls whether or not
+ <application>Junkbuster</application> will appear as a button on the Task bar
+ when minimized:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>show-on-task-bar 0</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ If <quote>close-button-minimizes</quote> is set to 1, the Windows close
+ button will minimize <application>Junkbuster</application> instead of closing
+ the program (close with the exit option on the File menu).
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>close-button-minimizes 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ The <quote>hide-console</quote> option is specific to the MS-Win console
+ version of <application>JunkBuster</application>. If this option is used,
+ <application>Junkbuster</application> will disconnect from and hide the
+ command console.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ #hide-console
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+</sect3>
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="actionsfile">
+<title>The Actions File</title>
+
+<para>
+ The <quote>ijb.action</quote> file (formerly
+ <filename>actionsfile</filename>) is used to define what actions
+ <application>Junkbuster</application> takes, and thus determines how images,
+ cookies and various other aspects of HTTP content and transactions are
+ handled. Images can be anything you want, including ads, banners, or just
+ some obnoxious image that you would rather not see. Cookies can be accepted
+ or rejected, or accepted only during the current browser session (i.e.
+ not written to disk). Changes to <filename>ijb.action</filename> should
+ be immediately visible to <application>Junkbuster</application> without
+ the need to restart.
+</para>
+
+<para>
+ To determine which actions apply to a request, the URL of the request is
+ compared to all patterns in this file. Every time it matches, the list of
+ applicable actions for the URL is incrementally updated. You can trace
+ this process by visiting <ulink
+ url="http://i.j.b/show-url-info">http://i.j.b/show-url-info</ulink>.
+</para>
+
+<para>
+ The actions file can be edited with a browser by loading
+ <ulink url="http://i.j.b/">http://i.j.b/</ulink>, and then select
+ <quote>Edit Actions</quote>.
+</para>
+
+<para>
+ There are four types of lines in this file: comments (begin with a
+ <quote>#</quote> character), actions, aliases and patterns, all of which are
+ explained below, as well as the configuration file syntax that
+ <application>Junkbuster</application> understands.
+
+</para>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3>
+<title>URL Domain and Path Syntax</title>
+<para>
+ Generally, a pattern has the form <domain>/<path>, where both the
+ <domain> and <path> part are optional. If you only specify a
+ domain part, the <quote>/</quote> can be left out:
+</para>
+
+<para>
+ <emphasis>www.example.com</emphasis> - is a domain only pattern and will match any request to
+ <quote>www.example.com</quote>.
+</para>
+
+<para>
+ <emphasis>www.example.com/</emphasis> - means exactly the same.
+</para>
+
+<para>
+ <emphasis>www.example.com/index.html</emphasis> - matches only the single
+ document <quote>/index.html</quote> on <quote>www.example.com</quote>.
+</para>
+
+<para>
+ <emphasis>/index.html</emphasis> - matches the document <quote>/index.html</quote>, regardless of
+ the domain.
+</para>
+
+<para>
+ <emphasis>index.html</emphasis> - matches nothing, since it would be
+ interpreted as a domain name and there is no top-level domain called
+ <quote>.html</quote>.
+</para>
+
+<para>
+ The matching of the domain part offers some flexible options: if the
+ domain starts or ends with a dot, it becomes unanchored at that end.
+ For example:
+</para>
+
+<para>
+ <emphasis>.example.com</emphasis> - matches any domain that <emphasis>ENDS</emphasis> in
+ <quote>.example.com</quote>.
+</para>
+
+<para>
+ <emphasis>www.</emphasis> - matches any domain that <emphasis>STARTS</emphasis> with
+ <quote>www</quote>.
+</para>
+
+<para>
+ Additionally, there are wild-cards that you can use in the domain names
+ themselves. They work pretty similar to shell wild-cards: <quote>*</quote>
+ stands for zero or more arbitrary characters, <quote>?</quote> stands for
+ any single character. And you can define character classes in square
+ brackets and they can be freely mixed:
+</para>
+
+<para>
+ <emphasis>ad*.example.com</emphasis> - matches <quote>adserver.example.com</quote>,
+ <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>.
+</para>
+
+<para>
+ <emphasis>*ad*.example.com</emphasis> - matches all of the above, and then some.
+</para>
+
+<para>
+ <emphasis>.?pix.com</emphasis> - matches <quote>www.ipix.com</quote>,
+ <quote>pictures.epix.com</quote>, <quote>a.b.c.d.e.upix.com</quote>, etc.
+</para>
+
+<para>
+ <emphasis>www[1-9a-ez].example.com</emphasis> - matches <quote>www1.example.com</quote>,
+ <quote>www4.example.com</quote>, <quote>wwwd.example.com</quote>,
+ <quote>wwwz.example.com</quote>, etc., but <emphasis>not</emphasis>
+ <quote>wwww.example.com</quote>.
+</para>
+
+<para>
+ If <application>Junkbuster</application> was compiled with
+ <quote>pcre</quote> support (default), Perl compatible regular expressions
+ can be used. See the <filename>pcre/docs/</filename> directory or <quote>man
+ perlre</quote> (also available on <ulink
+ url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>)
+ for details. A brief discussion of regular expressions is in the
+ <link linkend="regex">Appendix</link>. For instance:
+</para>
+
+<para>
+ <emphasis>/.*/advert[0-9]+\.jpe?g</emphasis> - would match a URL from any
+ domain, with any path that includes <quote>advert</quote> followed
+ immediately by one or more digits, then a <quote>.</quote> and ending in
+ either <quote>jpeg</quote> or <quote>jpg</quote>. So we match
+ <quote>example.com/ads/advert2.jpg</quote>, and
+ <quote>www.example.com/ads/banners/advert39.jpeg</quote>, but not
+ <quote>www.example.com/ads/banners/advert39.gif</quote> (no gifs in the
+ example pattern).
+</para>
+
+<para>
+ Please note that matching in the path is case
+ <emphasis>INSENSITIVE</emphasis> by default, but you can switch to case
+ sensitive at any point in the pattern by using the
+ <quote>(?-i)</quote> switch:
+</para>
+
+<para>
+ <emphasis>www.example.com/(?-i)PaTtErN.*</emphasis> - will match only
+ documents whose path starts with <quote>PaTtErN</quote> in
+ <emphasis>exactly</emphasis> this capitalization.
+</para>
+
+</sect3>
+
+<!-- ~ End section ~ -->
+
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3>
+<title>Actions</title>
+<para>
+ Actions are enabled if preceded with a <quote>+</quote>, and disabled if
+ preceded with a <quote>-</quote>. Actions are invoked by enclosing the
+ action name in curly braces (e.g. {+some_action}), followed by a list of
+ URLs to which the action applies. There are three classes of actions:
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Boolean (e.g. <quote>+/-block</quote>):
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>{+name}</emphasis> # enable this action
+ <emphasis>{-name}</emphasis> # disable this action
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ parameterized (e.g. <quote>+/-hide-user-agent</quote>):
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>{+name{param}}</emphasis> # enable action and set parameter to <quote>param</quote>
+ <emphasis>{-name}</emphasis> # disable action
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Multi-value (e.g. <quote>{+/-add-header{Name: value}}</quote>, <quote>{+/-wafer{name=value}}</quote>):
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>{+name{param}}</emphasis> # enable action and add parameter <quote>param</quote>
+ <emphasis>{-name{param}}</emphasis> # remove the parameter <quote>param</quote>
+ <emphasis>{-name}</emphasis> # disable this action totally
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+<para>
+ If nothing is specified in this file, no <quote>actions</quote> are taken.
+ So in this case <application>JunkBuster</application> would just be a
+ normal, non-blocking, non-anonymizing proxy. You must specifically
+ enable the privacy and blocking features you need (although the
+ provided default <filename>ijb.action</filename> file will
+ give a good starting point).
+</para>
+
+<para>
+ Later defined actions always over-ride earlier ones. For multi-valued
+ actions, the actions are applied in the order they are specified.
+</para>
+
+<para>
+ The list of valid <application>Junkbuster</application> <quote>actions</quote> are:
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Add the specified HTTP header, which is not checked for validity.
+ You may specify this many times to specify many different headers:
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+add-header{Name: value}</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ Block this URL totally.
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+block</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ De-animate all animated GIF images, i.e. reduce them to their last frame.
+ This will also shrink the images considerably (in bytes, not pixels!). If
+ the option <quote>first</quote> is given, the first frame of the animation
+ is used as the replacement. If <quote>last</quote> is given, the last frame
+ of the animation is used instead, which probably makes more sense for most
+ banner animations, but also has the risk of not showing the entire last
+ frame (if it is only a delta to an earlier frame).
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+deanimate-gifs{last}</emphasis>
+ <emphasis>+deanimate-gifs{first}</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <quote>+downgrade</quote> will downgrade HTTP/1.1 client requests to
+ HTTP/1.0 and downgrade the responses as well. Use this action for servers
+ that use HTTP/1.1 protocol features that
+ <application>Junkbuster</application> doesn't handle well yet. HTTP/1.1
+ is only partially implemented. Default is not to downgrade requests.
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+downgrade</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Many sites, like yahoo.com, don't just link to other sites. Instead, they
+ will link to some script on their own server, giving the destination as a
+ parameter, which will then redirect you to the final target. URLs resulting
+ from this scheme typically look like:
+ http://some.place/some_script?http://some.where-else.
+ </para>
+ <para>
+ Sometimes, there are even multiple consecutive redirects encoded in the
+ URL. These redirections via scripts make your web browsing more traceable,
+ since the server from which you follow such a link can see where you go to.
+ Apart from that, valuable bandwidth and time is wasted, while your browser
+ ask the server for one redirect after the other. Plus, it feeds the
+ advertisers.
+ </para>
+ <para>
+ The <quote>+fast-redirects</quote> option enables interception of these
+ requests by <application>Junkbuster</application>, who will cut off all but
+ the last valid URL in the request and send a local redirect back to your
+ browser without contacting the remote site.
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+fast-redirects</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Filter the website through the re_filterfile:
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+filter{filename}</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Block any existing X-Forwarded-for header, and do not add a new one:
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+hide-forwarded</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If the browser sends a <quote>From:</quote> header containing your e-mail
+ address, this either completely removes the header (<quote>block</quote>), or
+ changes it to the specified e-mail address.
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+hide-from{block}</emphasis>
+ <emphasis>+hide-from{spam@sittingduck.xqq}</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Don't send the <quote>Referer:</quote> (sic) header to the web site. You
+ can block it, forge a URL to the same server as the request (which is
+ preferred because some sites will not send images otherwise) or set it to a
+ constant string of your choice.
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+hide-referer{block}</emphasis>
+ <emphasis>+hide-referer{forge}</emphasis>
+ <emphasis>+hide-referer{http://nowhere.com}</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Alternative spelling of <quote>+hide-referer</quote>. It has the same
+ parameters, and can be freely mixed with, <quote>+hide-referer</quote>.
+ (<quote>referrer</quote> is the correct English spelling, however the HTTP
+ specification has a bug - it requires it to be spelled <quote>referer</quote>.)
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+hide-referrer{...}</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Change the <quote>User-Agent:</quote> header so web servers can't tell your
+ browser type. Warning! This breaks many web sites. Specify the
+ user-agent value you want. Example, pretend to be using Netscape on
+ Linux:
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+hide-user-agent{Mozilla (X11; I; Linux 2.0.32 i586)}</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ <!--
+ <para>
+ Or to identify yourself explicitly as a <quote>Junkbuster</quote> user:
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+hide-user-agent{JunkBuster/1.0}</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ (Don't change the version number from 1.0 - after all, why tell them?)
+ <para>
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+hide-user-agent{browser-type}</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+-->
+ </listitem>
+
+ <listitem>
+ <para>
+ Treat this URL as an image. This only matters if it's also <quote>+block</quote>ed,
+ in which case a <quote>blocked</quote> image can be sent rather than a HTML page.
+ See <quote>+image-blocker{}</quote> below for the control over what is actually sent.
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+image</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Decides what to do with URLs that end up tagged with <quote>{+block
+ +image}</quote>, e.g an advertizement. There are five options.
+ <quote>-image-blocker</quote> will send a HTML <quote>blocked</quote> page,
+ usually resulting in a <quote>broken image</quote> icon.
+ <quote>+image-blocker{logo}</quote> will send a <quote>JunkBuster</quote>
+ logo image. <quote>+image-blocker{blank}</quote> will send a 1x1
+ transparent GIF image. And finally,
+ <quote>+image-blocker{http://xyz.com}</quote> will send a HTTP temporary
+ redirect to the specified image. This has the advantage of the icon being
+ being cached by the browser, which will speed up the display.
+ <quote>+image-blocker{pattern}</quote> will send a checkboard type pattern,
+ which scales better than the logo (which can get blocky if the browser
+ enlarges it too much).
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+image-blocker{logo}</emphasis>
+ <emphasis>+image-blocker{blank}</emphasis>
+ <emphasis>+image-blocker{http://i.j.b/send-banner}</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ By default (i.e. in the absence of a <quote>+limit-connect</quote>
+ action), <application>Junkbuster</application> will only allow CONNECT
+ requests to port 443, which is the standard port for https as a
+ precaution.
+ </para>
+
+ <para>
+ The CONNECT methods exists in HTTP to allow access to secure websites
+ (https:// URLs) through proxies. It works very simply: the proxy
+ connects to the server on the specified port, and then short-circuits
+ its connections to the client <emphasis>and</emphasis> to the remote proxy.
+ This can be a big security hole, since CONNECT-enabled proxies can
+ be abused as TCP relays very easily.
+ </para>
+
+ <para>
+ If you want to allow CONNECT for more ports than this, or want to forbid
+ CONNECT altogether, you can specify a comma separated list of ports and
+ port ranges (the latter using dashes, with the minimum defaulting to 0 and
+ max to 65K):
+ </para>
+
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+limit-connect{443} # This is the default and need no be specified.</emphasis>
+ <emphasis>+limit-connect{80,443} # Ports 80 and 443 are OK.</emphasis>
+ <emphasis>+limit-connect{-3, 7, 20-100, 500-} # Port less than 3, 7, 20 to 100</emphasis>
+ <emphasis> #and above 500 are OK.</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+
+ </listitem>
+
+ <listitem>
+ <para>
+ <quote>+no-compression</quote> prevents the website from compressing the
+ data. Some websites do this, which can be a problem for
+ <application>Junkbuster</application>, since <quote>+filter</quote>,
+ <quote>+no-popup</quote> and <quote>+gif-deanimate</quote> will not work on
+ compressed data. This will slow down connections to those websites,
+ though. Default is <quote>nocompression</quote> is turned on.
+ </para>
+
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+nocompression</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If the website sets cookies, <quote>no-cookies-keep</quote> will make sure
+ they are erased when you exit and restart your web browser. This makes
+ profiling cookies useless, but won't break sites which require cookies so
+ that you can log in for transactions. Default: on.
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+no-cookies-keep</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Prevent the website from reading cookies:
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+no-cookies-read</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Prevent the website from setting cookies:
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+no-cookies-set</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Filter the website through a built-in filter to disable those obnoxious
+ JavaScript pop-up windows via window.open(), etc. The two alternative
+ spellings are equivalent.
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+no-popup</emphasis>
+ <emphasis>+no-popups</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ This action only applies if you are using a <filename>jarfile</filename>
+ for saving cookies. It sends a cookie to every site stating that you do not
+ accept any copyright on cookies sent to you, and asking them not to track
+ you. Of course, this is a (relatively) unique header they could use to
+ track you.
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+vanilla-wafer</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ This allows you to add an arbitrary cookie. It can be specified multiple
+ times in order to add as many cookies as you like.
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+wafer{name=value}</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+<para>
+ The meaning of any of the above is reversed by preceding the action with a
+ <quote>-</quote>, in place of the <quote>+</quote>.
+</para>
+
+<para>
+ Some examples:
+</para>
+
+<para>
+ Turn off cookies by default, then allow a few through for specified sites:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ # Turn off all persistent cookies
+ { +no-cookies-read }
+ { +no-cookies-set }
+ # Allow cookies for this browser session ONLY
+ { +no-cookies-keep }
+
+ # Exceptions to the above, sites that benefit from persistent cookies
+ { -no-cookies-read }
+ { -no-cookies-set }
+ { -no-cookies-keep }
+ .javasoft.com
+ .sun.com
+ .yahoo.com
+ .msdn.microsoft.com
+ .redhat.com
+
+ # Alternative way of saying the same thing
+ {-no-cookies-set -no-cookies-read -no-cookies-keep}
+ .sourceforge.net
+ .sf.net
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Now turn off <quote>fast redirects</quote>, and then we allow two exceptions:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ # Turn them off!
+ {+fast-redirects}
+
+ # Reverse it for these two sites, which don't work right without it.
+ {-fast-redirects}
+ www.ukc.ac.uk/cgi-bin/wac\.cgi\?
+ login.yahoo.com
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Turn on page filtering, with one exception for sourceforge:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ # Run everything through the default filter file (<filename>re_filterfile</filename>):
+ {+filter}
+
+ # But please don't re_filter code from sourceforge!
+ {-filter}
+ .cvs.sourceforge.net
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Now some URLs that we want <quote>blocked</quote>, ie we won't see them.
+ Many of these use regular expressions that will expand to match multiple
+ URLs:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ # Blocklist:
+ {+block}
+ /.*/(.*[-_.])?ads?[0-9]?(/|[-_.].*|\.(gif|jpe?g))
+ /.*/(.*[-_.])?count(er)?(\.cgi|\.dll|\.exe|[?/])
+ /.*/(ng)?adclient\.cgi
+ /.*/(plain|live|rotate)[-_.]?ads?/
+ /.*/(sponsor)s?[0-9]?/
+ /.*/_?(plain|live)?ads?(-banners)?/
+ /.*/abanners/
+ /.*/ad(sdna_image|gifs?)/
+ /.*/ad(server|stream|juggler)\.(cgi|pl|dll|exe)
+ /.*/adbanners/
+ /.*/adserver
+ /.*/adstream\.cgi
+ /.*/adv((er)?ts?|ertis(ing|ements?))?/
+ /.*/banner_?ads/
+ /.*/banners?/
+ /.*/banners?\.cgi/
+ /.*/cgi-bin/centralad/getimage
+ /.*/images/addver\.gif
+ /.*/images/marketing/.*\.(gif|jpe?g)
+ /.*/popupads/
+ /.*/siteads/
+ /.*/sponsor.*\.gif
+ /.*/sponsors?[0-9]?/
+ /.*/advert[0-9]+\.jpg
+ /Media/Images/Adds/
+ /ad_images/
+ /adimages/
+ /.*/ads/
+ /bannerfarm/
+ /grafikk/annonse/
+ /graphics/defaultAd/
+ /image\.ng/AdType
+ /image\.ng/transactionID
+ /images/.*/.*_anim\.gif # alvin brattli
+ /ip_img/.*\.(gif|jpe?g)
+ /rotateads/
+ /rotations/
+ /worldnet/ad\.cgi
+ /cgi-bin/nph-adclick.exe/
+ /.*/Image/BannerAdvertising/
+ /.*/ad-bin/
+ /.*/adlib/server\.cgi
+ /autoads/
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+</sect3>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3>
+<title>Aliases</title>
+<para>
+ Custom <quote>actions</quote>, known to <application>Junkbuster</application>
+ as <quote>aliases</quote>, can be defined by combining other <quote>actions</quote>.
+ These can in turn be invoked just like the built-in <quote>actions</quote>.
+ Currently, an alias can contain any character except space, tab, <quote>=</quote>,
+ <quote>{</quote> or <quote>}</quote>. But please use only <quote>a</quote>-
+ <quote>z</quote>, <quote>0</quote>-<quote>9</quote>, <quote>+</quote>, and
+ <quote>-</quote>. Alias names are not case sensitive, and
+ <emphasis>must be defined before anything</emphasis> else in the
+ <filename>ijb.action</filename>file ! And there can only be one set of
+ <quote>aliases</quote> defined.
+</para>
+
+<para>
+ Now let's define a few aliases:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ # Useful customer aliases we can use later. These must come first!
+ {{alias}}
+ +no-cookies = +no-cookies-set +no-cookies-read
+ -no-cookies = -no-cookies-set -no-cookies-read
+ fragile = -block -no-cookies -filter -fast-redirects -hide-referer -no-popups
+ shop = -no-cookies -filter -fast-redirects
+ +imageblock = +block +image
+
+ #For people who don't like to type too much: ;-)
+ c0 = +no-cookies
+ c1 = -no-cookies
+ c2 = -no-cookies-set +no-cookies-read
+ c3 = +no-cookies-set -no-cookies-read
+ #... etc. Customize to your heart's content.
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Some examples using our <quote>shop</quote> and <quote>fragile</quote>
+ aliases from above:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ # These sites are very complex and require
+ # minimal interference.
+ {fragile}
+ .office.microsoft.com
+ .windowsupdate.microsoft.com
+ .nytimes.com
+
+ # Shopping sites - still want to block ads.
+ {shop}
+ .quietpc.com
+ .worldpay.com # for quietpc.com
+ .jungle.com
+ .scan.co.uk
+
+ # These shops require pop-ups
+ {shop -no-popups}
+ .dabs.com
+ .overclockers.co.uk
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+</sect3>
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="filterfile">
+<title>The Filter File</title>
+<para>
+ Any web page can be dynamically modified with the filter file. This
+ modification can be removal, or re-writing, of any web page content,
+ including tags and non-visible content. The default filter file is
+ <filename>re_filterfile</filename>, located in the config directory.
+</para>
+
+<para>
+ This file uses regular expressions to alter or remove any string in the
+ target page. The expressions can only operate on one line at a time .Some
+ examples from the included default <filename>re_filterfile</filename>:
+</para>
+
+<para>
+ Stop web pages from displaying annoying messages in the status bar by
+ deleting such references:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ # The status bar is for displaying link targets, not pointless buzzwords.
+ # Again, check it out on http://www.airport-cgn.de/.
+ s/status='.*?';*//ig
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Just for kicks, replace any occurrence of <quote>Microsoft</quote> with
+ <quote>MicroSuck</quote>:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ s/microsoft(?!.com)/MicroSuck/ig
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Kill those auto-refresh tags:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ # Kill refresh tags. I like to refresh myself. Manually.
+ # check it out on http://www.airport-cgn.de/ and go to the arrivals page.
+ #
+ s/<meta[^>]*http-equiv[^>]*refresh.*URL=([^>]*?)"?>/<link rev="x-refresh" href=$1>/i
+ s/<meta[^>]*http-equiv="?page-enter"?[^>]*content=[^>]*>/<!--no page enter for me-->/i
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2>
+<title>Templates</title>
+<para>
+ When <application>Junkbuster</application> displays one of its internal
+ pages, such as a 404 Not Found error page, it uses the appropriate template.
+ On Linux, BSD, and Unix, these are located in
+ <filename>/etc/junkbuster/templates</filename> by default. These may be
+ customized, if desired.
+
+</para>
+</sect2>
+
+</sect1>
+
+<!-- ~ End section ~ -->
+
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="quickstart"><title>Quickstart to Using Junkbuster</title>
+<para>
+ Install package, then run and enjoy! <application>JunkBuster</application>
+ is typically started by specifying the main configuration file to be
+ used on the command line. Example Unix startup command:
+</para>
+
+<para>
+ <screen>
+
+ # /usr/sbin/junkbuster /etc/junkbuster/config
+
+ </screen>
+</para>
+
+<para>
+ An init script is provided for SuSE and Redhat.
+</para>
+
+<para>
+For for SuSE: /etc/rc.d/junkbuster start
+</para>
+
+<para>
+For RedHat: /etc/rc.d/init.d/junkbuster start
+</para>
+
+
+<para>
+ If no configuration file is specified on the command line,
+ <application>Junkbuster</application> will look for a file named
+ <filename>config</filename> in the current directory. Except on Win32 where
+ it will try <filename>config.txt</filename>. If no file is specified on the
+ command line and no default configuration file can be found,
+ <application>Junkbuster</application> will fail to start.
+</para>
+
+<para>
+ Be sure your browser is set to use the proxy which is by default at
+ localhost, port 8118. With <application>Netscape</application> (and
+ <application>Mozilla</application>), this can be set under <literal>Edit
+ -> Preferences -> Advanced -> Proxies -> HTTP Proxy</literal>.
+ For <application>Internet Explorer</application>: <literal>Tools >
+ Internet Properties -> Connections -> LAN Setting</literal>. Then,
+ check <quote>Use Proxy</quote> and fill in the appropriate info (Address:
+ localhost, Port: 8118). Include if HTTPS proxy support too.
+</para>
+
+<para>
+ The included default configuration files should give a reasonable starting
+ point, though may be somewhat aggressive in blocking junk. You will probably
+ want to keep an eye out for sites that require persistent cookies, and add these to
+ <filename>ijb.action</filename> as needed. By default, most of these will
+ be accepted only during the current browser session, until you add them to
+ the configuration. If you want the browser to handle this instead, you will
+ need to edit <filename>ijb.action</filename> and disable this feature. If you
+ use more than one browser, it would make more sense to let
+ <application>Junkbuster</application> handle this. In which case, the
+ browser(s) should be set to accept all cookies.
+</para>
+
+<para>
+ If a particular site shows problems loading properly, try adding it
+ to the <literal>{fragile}</literal> section of
+ <filename>ijb.action</filename>. This will turn off most actions for
+ this site.
+</para>
+
+<para>
+ <application>Junkbuster</application> is HTTP/1.1 compliant, but not all 1.1
+ features are as yet implemented. If browsers that support HTTP/1.1 (like
+ <application>Mozilla</application> or recent versions of I.E.) experience
+ problems, you might try to force HTTP/1.0 compatibility. For Mozilla, look
+ under <literal>Edit -> Preferences -> Debug -> Networking</literal>.
+ Or set the <quote>+downgrade</quote> config option in
+ <filename>ijb.action</filename>.
+</para>
+
+<para>
+ After running <application>Junkbuster</application> for a while, you can
+ start to fine tune the configuration to suit your personal, or site,
+ preferences and requirements. There are many, many aspects that can
+ be customized. <quote>Actions</quote> (as specified in <filename>ijb.action</filename>)
+ can be adjusted by pointing your browser to
+ <ulink url="http://i.j.b/">http://i.j.b/</ulink>,
+ and then follow the link to <quote>edit the actions list</quote>.
+ (This is an internal page and does not require Internet access.)
+</para>
+
+<para>
+ In fact, various aspects of <application>Junkbuster</application>
+ configuration can be viewed from this page, including
+ current configuration parameters, source code version numbers,
+ the browser's request headers, and <quote>actions</quote> that apply
+ to a given URL. In addition to the <filename>ijb.action</filename> file
+ editor mentioned above, <application>Junkbuster</application> can also
+ be turned <quote>on</quote> and <quote>off</quote> from this page.
+</para>
+
+<para>
+ If you encounter problems, please verify it is a
+ <application>Junkbuster</application> bug, by disabling
+ <application>Junkbuster</application>, and then trying the same page.
+ Also, try another browser if possible to eliminate browser or site
+ problems. Before reporting it as a bug, see if there is not a configuration
+ option that is enabled that is causing the page not to load. You can
+ then add an exception for that page or site. If a bug, please report it to
+ the developers (see below).
+</para>
+
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2>
+<title>Command Line Options</title>
+<para>
+ <application>JunkBuster</application> may be invoked with the following
+ command-line options:
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <emphasis>--version</emphasis>
+ </para>
+ <para>
+ Print version info and exit, Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--help</emphasis>
+ </para>
+ <para>
+ Print a short usage info and exit, Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--no-daemon</emphasis>
+ </para>
+ <para>
+ Don't become a daemon, i.e. don't fork and become process group
+ leader, don't detach from controlling tty. Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--pidfile FILE</emphasis>
+
+ </para>
+ <para>
+ On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
+ <emphasis>FILE</emphasis> on exit. Failiure to create or delete the
+ <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
+ option is given, no PID file will be used. Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--user USER[.GROUP]</emphasis>
+
+ </para>
+ <para>
+ After (optionally) writing the PID file, assume the user ID of
+ <emphasis>USER</emphasis>, and if included the GID of GROUP. Exit if the
+ privileges are not sufficient to do so. Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>configfile</emphasis>
+ </para>
+ <para>
+ If no <emphasis>configfile</emphasis> is included on the command line,
+ <application>JunkBuster</application> will look for a file named
+ <quote>config</quote> in the current directory (except on Win32
+ where it will look for <quote>config.txt</quote> instead). Specify
+ full path to avoid confusion.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+</sect2>
+
+</sect1>
+
+<!-- ~ End section ~ -->
+
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
+Requests</title>
+<para>
+We value your feedback. However, to provide you with the best support,
+please note:
+
+ <itemizedlist>
+
+ <listitem><para>Use the <ulink url="http://sourceforge.net/tracker/?group_id=11118&atid=211118">Sourceforge support forum</ulink> to get
+ help.</para></listitem>
+
+ <listitem><para>Submit bugs only thru our <ulink url="http://sourceforge.net/tracker/?group_id=11118&atid=111118">Sourceforge bug
+ forum</ulink>.
+Make sure that the bug has not already been submitted. Please try to
+verify that it is a <application>Junkbuster</application> bug, and not
+a browser or site bug first. If you are using your own custom configuration,
+please try the stock configs to see if the problem is a configuration
+related bug. And if not using the latest development snapshot, please
+try the latest one. Or even better, CVS sources.</para>
+</listitem>
+
+
+ <listitem><para>Submit feature requests only thru our <ulink
+ url="http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse">Sourceforge feature request forum</ulink>.</para></listitem>
+
+
+ </itemizedlist>
+
+</para>
+
+<para>
+For any other issues, feel free to use the <ulink url="http://sourceforge.net/mail/?group_id=11118">mailing lists</ulink>.
+</para>
+
+<para>
+ Anyone interested in actively participating in development and related
+ discussions can join the appropriate mailing list
+ <ulink url="http://sourceforge.net/mail/?group_id=11118">here</ulink>.
+ Archives are available here too.
+</para>
+
+</sect1>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="copyright"><title>Copyright and History</title>
+
+<sect2>
+<title>License</title>
+<para>
+ <application>Internet Junkbuster</application> is free software; you can
+ redistribute it and/or modify it under the terms of the GNU General Public
+ License as published by the Free Software Foundation; either version 2 of the
+ License, or (at your option) any later version.
+</para>
+
+<para>
+ This program is distributed in the hope that it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ details, which is available from <ulink
+ url="http://www.gnu.org/copyleft/gpl.html">the Free Software Foundation,
+ Inc</ulink>, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+</para>
+
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2>
+<title>History</title>
+<para>
+ <application>Junkbuster</application> was originally written by Anonymous
+ Coders and <ulink
+ url="http://www.junkbusters.com/ht/en/ijbfaq.html">Junkbuster's
+ Corporation</ulink>, and was released as free open-source software under the
+ GNU GPL. <ulink url="http://www.waldherr.org/junkbuster/">Stefan
+ Waldherr</ulink> made many improvements, and started the <ulink
+ url="http://sourceforge.net/projects/ijbswa/">SourceForge project</ulink> to
+ rekindle development. There are now several active developers contributing.
+ The last stable release was v2.0.2, which has now grown whiskers ;-).
+</para>
+
+</sect2>
+
+</sect1>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="seealso"><title>See also</title>
+<para>
+
+ <simplelist>
+ <member>
+ <ulink url="http://sourceforge.net/projects/ijbswa">http://sourceforge.net/projects/ijbswa</ulink>
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <ulink url="http://ijbswa.sourceforge.net/">http://ijbswa.sourceforge.net/</ulink>
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <ulink url="http://i.j.b/">http://i.j.b/</ulink>
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <ulink url="http://www.junkbusters.com/ht/en/cookies.html">http://www.junkbusters.com/ht/en/cookies.html</ulink>
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <ulink url="http://www.waldherr.org/junkbuster/">http://www.waldherr.org/junkbuster/</ulink>
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <ulink url="http://privacy.net/analyze/">http://privacy.net/analyze/</ulink>
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <ulink url="http://www.squid-cache.org/">http://www.squid-cache.org/</ulink>
+ </member>
+ </simplelist>
+
+</para>
+</sect1>
+
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="appendix"><title>Appendix</title>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="regex">
+<title>Regular Expressions</title>
+<para>
+ <application>Junkbuster</application> can use <quote>regular expressions</quote>
+ in various config files. Assuming support for <quote>pcre</quote> (Perl
+ Compatible Regular Expressions) is compiled in, which is the default. Such
+ configuration directives do not require regular expressions, but they can be
+ used to increase flexibility by matching a pattern with wild-cards against
+ URLs.
+</para>
+
+<para>
+ If you are reading this, you probably don't understand what <quote>regular
+ expressions</quote> are, or what they can do. So this will be a very brief
+ introduction only. A full explanation would require a book ;-)
+</para>
+
+<para>
+ <quote>Regular expressions</quote> is a way of matching one character
+ expression against another to see if it matches or not. One of the
+ <quote>expressions</quote> is a literal string of readable characters
+ (letter, numbers, etc), and the other is a complex string of literal
+ characters combined with wild-cards, and other special characters, called
+ meta-characters. The <quote>meta-characters</quote> have special meanings and
+ are used to build the complex pattern to be matched against. Perl Compatible
+ Regular Expressions is an enhanced form of the regular expression language
+ with backward compatibility.
+</para>
+
+<para>
+ To make a simple analogy, we do something similar when we use wild-card
+ characters when listing files with the <command>dir</command> command in DOS.
+ <literal>*.*</literal> matches all filenames. The <quote>special</quote>
+ character here is the asterisk which matches any and all characters. We can be
+ more specific and use <literal>?</literal> to match just individual
+ characters. So <quote>dir file?.text</quote> would match
+ <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
+ matching, using a similar technique to <quote>regular expressions</quote>!
+</para>
+
+<para>
+ Regular expressions do essentially the same thing, but are much, much more
+ powerful. There are many more <quote>special characters</quote> and ways of
+ building complex patterns however. Let's look at a few of the common ones,
+ and then some examples:
+</para>
+
+<simplelist>
+ <member>
+ <emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
+ <quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
+ times. Either/or.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
+ times.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
+ times.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
+ the following character should be taken literally. This is used where one of the
+ special characters (e.g. <quote>.</quote>) needs to be taken literally and
+ not as a special meta-character.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
+ any of the enclosed characters are encountered.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>()</emphasis> - parentheses are used to group a sub-expression,
+ or multiple sub-expressions.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
+ <quote>or</quote> conditional statement. A match is successful if the
+ sub-expression on either side of <quote>|</quote> matches.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>s/string1/string2/g</emphasis> - This is used to rewrite strings of text.
+ <quote>string1</quote> is replaced by <quote>string2</quote> in this
+ example.
+ </member>
+</simplelist>
+
+<para>
+ These are just some of the ones you are likely to use when matching URLs with
+ <application>Junkbuster</application>, and is a long way from a definitive
+ list. This is enough to get us started with a few simple examples which may
+ be more illuminating:
+</para>
+
+<para>
+ <emphasis><literal>/.*/banners/.*</literal></emphasis> - A simple example
+ that uses the common combination of <quote>.</quote> and <quote>*</quote> to
+ denote any character, zero or more times. In other words, any string at all.
+ So we start with a literal forward slash, then our regular expression pattern
+ (<quote>.*</quote>) another literal forward slash, the string
+ <quote>banners</quote>, another forward slash, and lastly another
+ <quote>.*</quote>. We are building
+ a directory path here. This will match any file with the path that has a
+ directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
+ any characters, and this could conceivably be more forward slashes, so it
+ might expand into a much longer looking path. For example, this could match:
+ <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
+ <quote>/banners/annoying.html</quote>, or almost an infinite number of other
+ possible combinations, just so it has <quote>banners</quote> in the path
+ somewhere.
+</para>
+
+<para>
+ A now something a little more complex:
+</para>
+
+<para>
+ <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> -
+ We have several literal forward slashes again (<quote>/</quote>), so we are
+ building another expression that is a file path statement. We have another
+ <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
+ it matches our expression. The only true literal that <emphasis>must
+ match</emphasis> our pattern is <application>adv</application>, together with
+ the forward slashes. What comes after the <quote>adv</quote> string is the
+ interesting part.
+</para>
+
+<para>
+ Remember the <quote>?</quote> means the preceding expression (either a
+ literal character or anything grouped with <quote>(...)</quote> in this case)
+ can exist or not, since this means either zero or one match. So
+ <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
+ individual sub-expressions: <quote>(er)</quote>,
+ <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
+ means <quote>or</quote>. We have two of those. For instance,
+ <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote>
+ <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
+ attempt at matching as many variations of <quote>advertisement</quote>, and
+ similar, as possible. So this would expand to match just <quote>adv</quote>,
+ or <quote>advert</quote>, or <quote>adverts</quote>, or
+ <quote>advertising</quote>, or <quote>advertisement</quote>, or
+ <quote>advertisements</quote>. You get the idea. But it would not match
+ <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
+ changing our regular expression to:
+ <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
+ either spelling.
+</para>
+
+<para>
+ <emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
+ another path statement with forward slashes. Anything in the square brackets
+ <quote>[]</quote> can be matched. This is using <quote>0-9</quote> as a
+ shorthand expression to mean any digit one through nine. It is the same as
+ saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
+ means one or more of the preceding expression must be included. The preceding
+ expression here is what is in the square brackets -- in this case, any digit
+ one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>.
+ This includes a <quote>|</quote>, so this needs to match the expression on
+ either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
+ side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
+ since the <quote>?</quote> means the letter <quote>e</quote> is optional and
+ can be matched once or not at all. So we are building an expression here to
+ match image GIF or JPEG type image file. It must include the literal
+ string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
+ (which is now a literal, and not a special character, since it is escaped
+ with <quote>\</quote>), and lastly either <quote>gif</quote>, or
+ <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
+ include: <quote>//advert1.jpg</quote>,
+ <quote>/nasty/ads/advert1234.gif</quote>,
+ <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
+ <quote>advert1.gif</quote> (no leading slash), or
+ <quote>/adverts232.jpg</quote> (the expression does not include an
+ <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
+ in the expression anywhere).
+</para>
+
+<para>
+ <emphasis><literal>s/microsoft(?!.com)/MicroSuck/i</literal></emphasis> - This is
+ a substitution. <quote>MicroSuck</quote> will replace any occurrence of
+ <quote>microsoft</quote>. The <quote>i</quote> at the end of the expression
+ means ignore case. The <quote>(?!.com)</quote> means
+ the match should fail if <quote>microsoft</quote> is followed by
+ <quote>.com</quote>. In other words, this acts like a <quote>NOT</quote>
+ modifier. In case this is a hyperlink, we don't want to break it ;-).
+</para>
+
+<para>
+ We are barely scratching the surface of regular expressions here so that you
+ can understand the default <application>Junkbuster</application>
+ configuration files, and maybe use this knowledge to customize your own
+ installation. There is much, much more that can be done with regular
+ expressions. Now that you know enough to get started, you can learn more on
+ your own :/
+</para>
+
+<para>
+ More reading on Perl Compatible Regular expressions:
+ <ulink url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>
+</para>
+
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2>
+<title>JunkBuster's Internal Pages</title>
+
+<para>
+ Since <application>JunkBuster</application> proxies each requested
+ web page, it is easy for <application>JunkBuster</application> to
+ trap certain URLs. In this way, we can talk directly to
+ <application>JunkBuster</application>, and see how it is
+ configured, see how our rules are being applied, change these
+ rules and other configuration options, and even turn
+ <application>JunkBuster</application> off.
+
+</para>
+
+<para>
+ The URLs listed below are the special ones that allow direct access
+ to <application>JunkBuster</application>. Of course,
+ <application>JunkBuster</application> must be running to access these. If
+ not, you will get a friendly error message.
+
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Junkbuster main page:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://ijbswa.sourceforge.net/config/">http://ijbswa.sourceforge.net/config/</ulink>
+ </para>
+ </blockquote>
+ <para>
+ Alternately, this may be reached at <ulink url="http://i.j.b/">http://i.j.b/</ulink>,
+ but this variation may not work as reliably as the above in some
+ configurations.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Show information about the current configuration:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://ijbswa.sourceforge.net/config/show-status">http://ijbswa.sourceforge.net/config/show-status</ulink>
+ </para>
+ </blockquote>
+ </listitem>
+
+ <listitem>
+ <para>
+ Show the source code version numbers:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://ijbswa.sourceforge.net/config/show-version">http://ijbswa.sourceforge.net/config/show-version</ulink>
+ </para>
+ </blockquote>
+ </listitem>
+
+ <listitem>
+ <para>
+ Show the client's request headers:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://ijbswa.sourceforge.net/config/show-request">http://ijbswa.sourceforge.net/config/show-request</ulink>
+ </para>
+ </blockquote>
+ </listitem>
+
+ <listitem>
+ <para>
+ Show which actions apply to a URL and why:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://ijbswa.sourceforge.net/config/show-url-info">http://ijbswa.sourceforge.net/config/show-url-info</ulink>
+ </para>
+ </blockquote>
+ </listitem>
+
+ <listitem>
+ <para>
+ Toggle JunkBuster on or off:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://ijbswa.sourceforge.net/config/toggle">http://ijbswa.sourceforge.net/config/toggle</ulink>
+ </para>
+ </blockquote>
+ <para>
+ Short cuts. Turn off, then on:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://ijbswa.sourceforge.net/config/toggle?set=disable">http://ijbswa.sourceforge.net/config/toggle?set=disable</ulink>
+ </para>
+ </blockquote>
+ <blockquote>
+ <para>
+ <ulink url="http://ijbswa.sourceforge.net/config/toggle?set=enable">http://ijbswa.sourceforge.net/config/toggle?set=enable</ulink>
+ </para>
+ </blockquote>
+ </listitem>
+
+ <listitem>
+ <para>
+ Edit the actions list file:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://ijbswa.sourceforge.net/config/edit-actions">http://ijbswa.sourceforge.net/config/edit-actions</ulink>
+ </para>
+ </blockquote>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+<para>
+ These may be bookmarked for quick reference.
+
+</para>
+
+</sect2>
+
+</sect1>
+
+ <!--
+
+ This program is free software; you can redistribute it
+ and/or modify it under the terms of the GNU General
+ Public License as published by the Free Software
+ Foundation; either version 2 of the License, or (at
+ your option) any later version.
+
+ This program is distributed in the hope that it will
+ be useful, but WITHOUT ANY WARRANTY; without even the
+ implied warranty of MERCHANTABILITY or FITNESS FOR A
+ PARTICULAR PURPOSE. See the GNU General Public
+ License for more details.
+
+ The GNU General Public License should be included with
+ this file. If not, you can view it at
+ http://www.gnu.org/copyleft/gpl.html
+ or write to the Free Software Foundation, Inc., 59
+ Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+ $Log: user-manual.sgml,v $
+ Revision 1.46 2002/03/10 00:51:08 hal9
+ Added section on JB internal pages in Appendix.
+
+ Revision 1.45 2002/03/09 17:43:53 swa
+ more distros
+
+ Revision 1.44 2002/03/09 17:08:48 hal9
+ New section on Jon's actions file editor, and move some stuff around.
+
+ Revision 1.43 2002/03/08 00:47:32 hal9
+ Added imageblock{pattern}.
+
+ Revision 1.42 2002/03/07 18:16:55 swa
+ looks better
+
+ Revision 1.41 2002/03/07 16:46:43 hal9
+ Fix a few markup problems for jade.
+
+ Revision 1.40 2002/03/07 16:28:39 swa
+ provide correct feedback channels
+
+ Revision 1.39 2002/03/06 16:19:28 hal9
+ Note on perceived filtering slowdown per FR.
+
+ Revision 1.38 2002/03/05 23:55:14 hal9
+ Stupid I did it again. Double hyphen in comment breaks jade.
+
+ Revision 1.37 2002/03/05 23:53:49 hal9
+ jade barfs on '- -' embedded in comments. - -user option broke it.
+
+ Revision 1.36 2002/03/05 22:53:28 hal9
+ Add new - - user option.
+
+ Revision 1.35 2002/03/05 00:17:27 hal9
+ Added section on command line options.
+
+ Revision 1.34 2002/03/04 19:32:07 oes
+ Changed default port to 8118
+
+ Revision 1.33 2002/03/03 19:46:13 hal9
+ Emphasis on where/how to report bugs, etc
+
+ Revision 1.32 2002/03/03 09:26:06 joergs
+ AmigaOS changes, config is now loaded from PROGDIR: instead of
+ AmiTCP:db/junkbuster/ if no configuration file is specified on the
+ command line.
+
+ Revision 1.31 2002/03/02 22:45:52 david__schmidt
+ Just tweaking
+
+ Revision 1.30 2002/03/02 22:00:14 hal9
+ Updated 'New Features' list. Ran through spell-checker.
+
+ Revision 1.29 2002/03/02 20:34:07 david__schmidt
+ Update OS/2 build section
+
+ Revision 1.28 2002/02/24 14:34:24 jongfoster
+ Formatting changes. Now changing the doctype to DocBook XML 4.1
+ will work - no other changes are needed.
+
+ Revision 1.27 2002/01/11 14:14:32 hal9
+ Added a very short section on Templates
+
+ Revision 1.26 2002/01/09 20:02:50 hal9
+ Fix bug re: auto-detect config file changes.
+
+ Revision 1.25 2002/01/09 18:20:30 hal9
+ Touch ups for *.action files.
+
+ Revision 1.24 2001/12/02 01:13:42 hal9
+ Fix typo.
+
+ Revision 1.23 2001/12/02 00:20:41 hal9
+ Updates for recent changes.
+
+ Revision 1.22 2001/11/05 23:57:51 hal9
+ Minor update for startup now daemon mode.
+
+ Revision 1.21 2001/10/31 21:11:03 hal9
+ Correct 2 minor errors
+
+ Revision 1.18 2001/10/24 18:45:26 hal9
+ *** empty log message ***
+
+ Revision 1.17 2001/10/24 17:10:55 hal9
+ Catching up with Jon's recent work, and a few other things.
+
+ Revision 1.16 2001/10/21 17:19:21 swa
+ wrong url in documentation
+
+ Revision 1.15 2001/10/14 23:46:24 hal9
+ Various minor changes. Fleshed out SEE ALSO section.
+
+ Revision 1.13 2001/10/10 17:28:33 hal9
+ Very minor changes.
+
+ Revision 1.12 2001/09/28 02:57:04 hal9
+ Ditto :/
+
+ Revision 1.11 2001/09/28 02:25:20 hal9
+ Ditto.
+
+ Revision 1.9 2001/09/27 23:50:29 hal9
+ A few changes. A short section on regular expression in appendix.
+
+ Revision 1.8 2001/09/25 00:34:59 hal9
+ Some additions, and re-arranging.
+
+ Revision 1.7 2001/09/24 14:31:36 hal9
+ Diddling.
+
+ Revision 1.6 2001/09/24 14:10:32 hal9
+ Including David's OS/2 installation instructions.
+
+ Revision 1.2 2001/09/13 15:27:40 swa
+ cosmetics
+
+ Revision 1.1 2001/09/12 15:36:41 swa
+ source files for junkbuster documentation
+
+ Revision 1.3 2001/09/10 17:43:59 swa
+ first proposal of a structure.
+
+ Revision 1.2 2001/06/13 14:28:31 swa
+ docs should have an author.
+
+ Revision 1.1 2001/06/13 14:20:37 swa
+ first import of project's documentation for the webserver.
+
+ -->
</article>
projects / privoxy.git / blobdiff