BannerFilter v1.21
Copyright (C) 2002 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, don't try to use BannerFilter!

INSTALLATION:

1) Move the contents of the www directory to somewhere accessible
on your Web server.  These files must be accessible to Squid via HTTP.
TIP:  If you untar into /usr/local/squid and move the contents of the
www directory so they're accessible at http://127.0.0.1/bannerfilter/
you can skip steps 2 and 3 and use the default configuration.

2) Move everything else to someplace useful on the machine that is
running Squid.

3) Move bannerfilter.conf to /etc (or somewhere else that
redirector.pl will find it) and edit it as needed (see below).

4) 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.  Yes, this step is important.  If you get an error, fix it
before proceeding.

5) Add a line to squid.conf:
redirect_program /path/to/redirector.pl
For example, if you followed the tip in step 1:
redirect_program /usr/local/squid/bannerfilter-1.21/redirector.pl

6) Restart Squid, and make sure everything works.  You should be able to
go to http://bannerfilter.internal/test.html and get a Web page; if so,
installation was successful.

7) 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.

That's it!

CONFIGURATION FILE:
The configuration file is bannerfilter.conf and should be placed in
/etc or one of the other locations listed in redirector.pl.  For
testing purposes, you can also specify the path to the file on the
command line: "/path/to/redirector.pl -c /path/to/bannerfilter.conf".
The format is "label = value" on each line where "label" is
case-insensitive and whitespace before and after the "=" is optional.
Blank lines and comments (lines beginning with "#") are ignored.

CONFIGURATION DIRECTIVES:
WWW is the URL pointing to wherever you moved the www directory to.
This URL only has to be accessible to Squid; it will not be accessed
directly by any clients.  DATA is the path to the data files.  LOG
is the path to the log file so you can see what BannerFilter is
actually blocking, or you can leave it blank or set it to 0 if
you don't want a log.  BANNERGIF is the name of the graphic file
to use to block ad banners; this should be banner.gif if you want
to see the word "Blocked" or null.gif if you don't.

UPDATES:
To download the most recent updates to the data files, simply run
the update.sh script in the same directory as the data files.  If you'd
like, you can automate this with a nightly 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.
The script also tries to killall -HUP redirector.pl, which tells the
redirector.pl script to reload the files; 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 comment out the last line and take care of
that yourself.

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:
I've just added 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 later.

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 URL in there to make sure I haven't already taken care
of it.

THANKS:
Thomas B. Fox (nexus@donia.org) and Miroslav Pragl
(miroslav.pragl@omega-optix.cz) suggested the local.data files.  Dan
Everton (dan@conditioned.org) suggested the transparent 1x1 GIF option.
Marcel J.E. Mol (marcel@mesa.nl) submitted a patch with minor code
improvements.  Aaron D. Marasco (aaron@marasco.com) suggested several
optimizations and improvements.

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

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.
