asqredir - another squid redirect program

version 0.3

description
history
download
installing asqredir
editing the url file
testing asqredir
configuring squid
how it works
credits
why I wrote another redirect plugin
related sites
license

description

asqredir is a small, basic and fast redirect program for the almighty squid webcache. It can be used for filtering out advertisements from web sites or preventing proxy users to get certain files and redirect them to another url.

the url patterns and corresponding redirect urls are read into memory from a easy-to-maintain plaintext file on startup, when asqredir is invoked as redirect program by squid. asqredir is easy to configure and run, optional logging is available.

asqredir's redirect logic is based on urls only, it does not recognize ad banners by their image properties or similar. basically it is useful for you if you want redirects to happen based on matched url patterns.

asqredir is written in c and consists of one small source file offering the tiny functionality needed. it has been tested to run and perform well on openbsd and gnu/linux and should basically compile and run on any posix compliant system. see history for a list of changes since previous versions.

history

2001-03-09
- v0.1
- initial release
2001-04-12
- v0.2
- added signal handler for reconfiguration and applied other small changes.
2001-04-18
- v0.21
- bugfix release: small changes were enough to decrease memory consumption.
2001-10-07
- arno joins the asqredir project.
2003-01-24
- v0.3
- allows comments in url file (lines starting with '#')
- allows specifying url patterns which should always be allowed ('~')
- optional logging of redirects to file
- dynamic allocation of memory for url pattern list
- catches squid's EOF correctly, no more manual restarting (removed signal handler)
- Makefile included for more comfortable building

download

you can download the package asqredir-0.3.tar.gz containing the necessary files, or get asqredir.c and the files below individually.

installing asqredir

change to the directory where you downloaded the package and unpack it:

cd ~/downloads
gzip -dc asqredir-0.3.tar.gz | tar xvf -
cd asqredir-0.3

adapt the makefile if necessary and type:

make

to install the binary and a default url file to /usr/local/asqredir type:

make install

of course you can compile the source on your own or select your own locations for the binary and the url file. just invoke asqredir accordingly.

editing the url file

a sample url file is delivered with the distribution and copied to /usr/local/asqredir/urls.txt by default. in order to filter requests through asqredir you need to specify the rules in this file.

some sample rules are included but all of them are commented out by default. the url file consists of lines which either

are blank and therefore ignored.
start with a "#" and therefore are comments.
start with a "~" and are followed immediately by a url_pattern, for requests which should always be allowed.
contain a url_pattern and a redirect_url, separated by one space character, for requests which should be redirected to redirect_url.

# comment
~url_pattern
url_pattern redirect_url

url_pattern describes the pattern which should be matched in the request line in order to cause the desired action (pass or deny). url_pattern can be a substring or the whole url and you can use regular expressions to describe it, but you don't need to if you don't want. In other words, even if you do use regexp for your urls you don't have to care about consuming the whole string. By the way, using regexp (such as putting a "^" in front of "http" certainly helps to optimize the matches but is not necessary for correct operations.

some examples:

# all requests for urls containing the string "/adclick/" are redirected:
/adclick/ http://192.168.35.52/adbanner.png

# same for string "/admanager/":
/admanager/ http://192.168.35.52/adbanner.png

# always allow requests with the following pattern:
~goodads.com/admanager/

# always redirect "event.ng" requests, but this time to a html file:
/event.ng.* http://192.168.35.52/empty.html

# this is another comment

/image.ng http://192.168.35.52/adbanner.png
/image/ads/ http://192.168.35.52/adbanner.png

testing asqredir

call asqredir interactively by typing

/usr/local/asqredir/asqredir <urlfile>

where the optional argument is the path to the url file in case it's not installed in the default location.

now type a http request like squid would pass it for a non-blocked site:

http://www.slashdot.org 192.168.25.132 - GET

the output should be an empty new line. next, enter a url matching a pattern from your url file:

http://www.adsite.com/admanager/ad.gif 192.168.25.132 - GET

this should give you back the redirect url configured for the pattern wrapped up in the old request, such as:

http://my.local.web/empty.gif 192.168.25.132 - GET

test the non-blocked url again, see the blank new line again and continue installing :)

configuring squid

you have to specify asqredir as redirect_program in the squid config file (usually squid.conf):

redirect_program /usr/local/asqredir/asqredir /path/to/asqredir/urls.txt

maybe you'd like to change the amount of redirect processes squid forks, depending on your site's traffic:

redirect_children 5

if you make changes to the url file and want them to take effect, you can restart asqredir by reconfiguring squid:

squid -k reconfigure

all asqredir processes terminate on squid's shutdown or reconfiguration, so you don't have to worry (anymore) about killing them manually.

how it works

if asqredir is configured as redirect_program in squid.conf, squid will pipe all requests it gets through it.

every request coming from squid to asqredir has got the following format:

url src_address ident method
http://www.someurl.com/index.html 192.168.45.122 - GET

asqredir compares the url part against a set of regular expressions previously read into memory from a file. if there's a match for a pass rule, an empty string is given back to squid to indicate that no redirect should happen. if there's a match for a deny rule, the url is rewritten to the value specified in the url file. the client_address, ident and method values are passed out as they came in and the whole string is returned to squid. if there's no match, asqredir just returns an empty string to squid.

credits

special thanks go out to jb, ls and eduardo perez for their valuable feedback on previous versions of asqredir, to the squid people for their great product and to my project team mate arno for his great support.

why I wrote another redirect plugin

... instead of using one of the many already available packages serving the same purpose:

for the fun of writing it.
I wanted to have it fast.
I wanted to have it small.

license

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

Thomas Zippo < thomas at zippo dot ch >
2003-01-24