Tired of all the flashy ad banners on the Web? If you run Squid, then BannerFilter is for you! And yes, it's Free.

Be sure to run the update.sh script to download the latest data files, since I update those a lot more often than I update the tarball.

There is a Web interface to BannerFilter, so you can check to see whether a particular URL would be blocked, without installing BannerFilter. If you have a banner that isn't blocked and you think it should be, check it here before e-mailing it to me!

Purpose:

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.

Notes on Windows support for BannerFilter 1.31

BannerFilter runs on Microsoft Windows with SquidNT and ActivePerl. This document is intended to suppliment, not replace, the standard README file. You can open the README file in WordPad, or any other text editor which can read UNIX line endings (i.e. not Notepad).

SquidNT may be obtained from:
http://www.acmeconsulting.it/pagine/opensource/squid/SquidNT.htm

ActivePerl may be obtained from:
http://www.activestate.com/Products/ActivePerl/

Installation:

Unzip BannerFilter and place it in the C:\squid directory, or anywhere else you'd like. StuffIt Expander (http://www.stuffit.com/) and recent versions of WinZip (http://www.winzip.com/) should both handle tar-gzip files.

Add this line to C:\squid\etc\squid.conf:
redirect_program C:/perl/bin/perl.exe C:/squid/bannerfilter-1.31/redirector.pl

Notice the forward slashes (/) instead of backslashes (\), and be sure to enter that all on one line. Substitute the correct locations of perl.exe and redirector.pl if you've put them somewhere else.

Configuration:

To edit bannerfilter.conf or the data files, you'll need to use a decent text editor that handles UNIX line endings, or open the files in WordPad which will convert them to Windows line endings (once you've saved them in WordPad you can re-open them in Notepad if you prefer).

For file paths in the configuration file, you can use either forward slashes (/) or backslashes (\).

If you're using IIS as your web server, you can either move the contents of the www directory to C:\Inetpub\wwwroot\bannerfilter, or create a virtual directory pointing to C:\squid\bannerfilter-1.31\www. Of course you can do something similar in Apache or whatever web server you're using.

Updates:

The update script is not officially supported on Windows, but update.sh can be made to work using Cygwin (http://www.cygwin.com/). You'll need to install wget, or something else that can do HTTP downloads, and turn off the RELOAD option in the update script (or change it to something that works). If SquidNT is installed as a service, you can restart it with:
net stop squidnt
net start squidnt

Acknowledgements:

Thanks to Andre Swanepoel for inspiration and ideas.

If you don't already have Squid installed and configured, do that first. I recommend SquidMan.

Download the Mac OS X Installer package, which will install the various parts of BannerFilter to these locations:

• /Library/BannerFilter
• /Library/WebServer/Documents/bannerfilter
• /Library/Documentation/BannerFilter

Make sure the Personal Web Service is enabled. In System Preferences, click Sharing, and under the Services tab check the box for Personal Web Sharing. Then, add this line to your squid configuration (if you use SquidMan, go to Preferences and click the Template tab):

Read the README file for more information. Of course, you can follow the standard UNIX installation procedure if you prefer, instead of using the Installer package.