BannerFilter v1.31
Copyright (C) 2004 Andy Lyttle
E-mail:  bannerfilter@phroggy.com
Web:  http://phroggy.com/bannerfilter/

----------------------------------------------------------------------

PURPOSE:
--------
This script blocks advertising banners on the Web.  If you have
a slow Internet connection, it will speed up your surfing, since
the banners are not downloaded from the Internet at all.

FEATURES:
---------
Unlike most other similar solutions, BannerFilter does more than simply
block advertising graphics.  It also blocks advertising frames on a few
sites, and automatically closes pop-up windows.  A script can automatically
download updated data files off the Web, and notify you when a new version
is available.

REQUIREMENTS:
-------------
A working installation of the Squid proxy server, available from
http://www.squid-cache.org/, Perl, and a web server.  If you don't have
Squid already installed and running, do that first!  BannerFilter should
work on any platform that can run Squid and Perl; Windows users should see
Windows.txt for additional information about that platform.

QUICK INSTALLATION:
-------------------
1) Unzip the bannerfilter-1.31 directory in a useful place on the machine
that runs Squid.  You may want to put it under the squid directory, e.g.
/usr/local/squid/bannerfilter-1.31.

2) Move the contents of the www directory so they are accessible at
http://127.0.0.1/bannerfilter/.  If you want to put them somewhere else
(which you'd need to do if your web server is not the same machine that
runs Squid), edit bannerfilter.conf and give the correct URL.

3) Test redirector.pl by running the script, typing something, and making
sure you get something back (generally the same thing you typed).  Press
Ctrl-C to stop.  If you get an error, fix it before proceeding.

4) Add a line to squid.conf:
redirect_program /path/to/redirector.pl
For example:
redirect_program /usr/local/squid/bannerfilter-1.31/redirector.pl
Then restart Squid.

5) Go to http://bannerfilter.internal/test.html from one of your client
machines and see if it works.  If not, figure out why.

6) Run the update.sh script to make sure you have the latest version of the
data files (see below).  I update the data files far more often than I
update the tarball, so what's included with the release you downloaded is
probably pretty out of date.  See below.

CONFIGURATION FILE:
-------------------
The configuration file, bannerfilter.conf, may be kept in the same
location as redirector.pl, or may be moved to wherever you'd like to
put it.  The redirect script will look for it in all the reasonable
places I could think of; if you want to put it somewhere else, you can
specify the path to the configuration file on the command line (in
squid.conf) with the -c option, for example:
redirector.pl -c /mnt/config/bannerfilter.conf

The file contains configuration directives in the form "label = value";
blank lines and lines beginning with # or ; are ignored.  The label
is case-insensitive and whitespace before and after the = is optional.
All the configuration directives should be explained by the comments
in the file.

UPDATES:
--------
To download the most recent updates to the data files, simply run
the update.sh script from the same directory as the data files.  If you'd
like, you can automate this with a nightly or weekly cron job (be sure to
cd to the appropriate directory first, then run ./update.sh).  Sometimes new
versions of the data files require that you upgrade to a new version
of BannerFilter; if an update is required, update.sh will notify you.
If the files have changed, the script will overwrite them and tell
BannerFilter to reload the data files via "killall -HUP redirector.pl".
If you're running update.sh as a non-root user (other than the user Squid
is running as), or if you don't have killall, you'll want to set RELOAD=0
in update.sh and take care of that yourself.  Also, if you don't have
lynx, set CMD to your preferred HTTP downloader.

CUSTOMIZING:
------------
If there are certain URLs that you would like blocked that aren't
listed, you can edit the local.data files.  These will not be overwritten
by the update script.  If there are URLs that you want never to be
blocked, you can list them in exceptions.local.data.

WILDCARDS:
----------
BannerFilter has (rather poor) support for wildcards.  URL substrings in
the data files can contain an asterisk (*), and anything that contains
both the part to the left of the asterisk and the part to the right of
the asterisk will be blocked.  I will be improving this eventually.

FEEDBACK:
---------
If you find banners that should be blocked and aren't, legitimate pages
that are being blocked and shouldn't be, or if you just have comments or
questions, e-mail me at bannerfilter@phroggy.com.  Please do not ask me
for help installing Squid.  Before you e-mail me about URLs you'd like
to have added or removed, go to http://phroggy.com/pages/checkbanner.html
and paste the full URL in there to make sure I haven't already taken care
of it.

THANKS:
-------
Thomas B. Fox and Miroslav Pragl suggested the local.data files.  Dan
Everton suggested the transparent 1x1 GIF option.  Marcel J.E. Mol
submitted a patch with minor code improvements.  Aaron D. Marasco
suggested several optimizations and improvements.  Steven Lynn suggested
making the DATA configuration directive optional, looking in the same
directory as the script by default.  Frequency suggested Getopt.

----------------------------------------------------------------------

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.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
