SquidGuard Howto Guide

Mandrake Linux 10.0
Copyright Aerospace Software Ltd, GPL, 2004.

Scope

This document describes how to install SquidGuard to clean up the internet. SquidGuard is a very fast filter, for use with the Squid proxy. It is a collaborative project which uses robots and users suggestions to create a large set of blacklists, which are then used to block obnoxious content.

Mandrake Linux comes with squidGuard, so you could get it off the CDROMs, but compiling it yourself is more adventurous. Both versions are mentioned below, so you can figure out how to configure it whichever way you want to do it.

First of all, install and configure Squid and make sure it works by testing it with a browser. Don't bother with SquidGuard before you aren't sure Squid works properly.

Where to get it

Get SquidGuard from http://www.squidguard.org.

Download the source tarball and the robot generated blacklists. Put everything in /root/squidguard.

Installation

Uncompress the tarball and configure. We assume that you already have a recent copy of Berkeley DB from Sleepycat since it is used by SpamProbe. See our SpamProbe Howto for details.

# tar -zxvf sq*
# cd sq[tab]
# ./configure --with-db=/usr/local/BerkeleyDB.4.1
# make
# make install
or that is the idea anyway.

Everything works till we try to make it. Apparently we need an OLD copy of BerkeleyDB, so Yo Ho Ho, off to Sleepycat I go...

BerkeleyDB

Go to http://www.SleepyCat.com and get DB version 2.7.7. You can have multiple versions of DB on your system since the newer versions put the version number in the path in /usr/local. Save it in /root/berkeleydb, uncompress and compile it:

# tar -zxvf db*
# cd db[tab]
# cd dist_unix
# ../dist/configure
# make
# make install

It will end up in /usr/local/BerkeleyDB.

Try again...

This time, the default path to the DB should be fine, so no more --with-yadda-yadda...

# cd ~/sq[tab]squidG[tab]
# ./configure
# make
# make install

Aaaahhhh - that is better.

SquidGuard Configuration Files

SquidGuard uses the following files by default:

/usr/local/bin/squidGuard
/usr/local/squidGuard/log/squidGuard.log
/usr/local/squidGuard/squidGuard.conf

with BerkeleyDB version 2.7.

However, the version of squidGuard that comes with Mandrake Linux uses the following files:

/usr/bin/squidGuard
/var/log/squidGuard/log/squidGuard.log
/etc/squidGuard/squidGuard.conf

with BerkeleyDB 3.3.1, which you would also need to get off your CDROMs to get squidGuard to work.

You can figure out what is going on by typing:

# /usr/bin/squidGuard -v
# /usr/local/bin/squidGuard -v

Or you can run it and watch it fail:

# /usr/local/bin/squidGuard
 /usr/local/bin/squidGuard: can't write to logfile /usr/local/squidGuard/log/squidGuard.log
 /usr/local/bin/squidGuard: can't open configfile  /usr/local/squidGuard/squidGuard.conf
 going into emergency mode

Press Ctrl-C to quit it.

To get it to work, you have to create the log file and the conf file and somewhere to put the database files:

# mkdir /usr/local/squidGuard
# touch /usr/local/squidGuard/squidGuard.conf
# mkdir /usr/local/squidGuard/log
# touch /usr/local/squidGuard/log/squidGuard.log
# mkdir /usr/local/squidGuard/db

The configuration file now exists but is empty, so squidGuard should now be able to run and do nothing:

# /usr/local/bin/squidGuard

and it should run without complaining. Again press Ctrl-C to quit it.

Configuration

Move the blacklist archive to /usr/local/squidGuard/db and unpack it:

# mv /root/squidguard/blacklists.tar.gz /usr/local/squidGuard/db/.
# cd /usr/local/squidGuard/db/
# tar -zxvf blacklists.tar.gz

You'll now have a ton of blacklist data:

# ls blacklists
ads/  aggressive/  audio-video/  drugs/  gambling/  hacking/  
mail/  porn/  proxy/  README  violence/  warez/

Each directory will typically have a domains and urls file and some have an expressions file as well - be careful. At the time of writing, mail only has a domains file and porn also has an expressions file, the rest have domains and urls. This affects the destination specifications in the configuration file.

Here is a sample squidGuard.conf:

# SquidGuard.conf
# The AerospaceSoftware sanitizer project
# Copyright Aerospace Software Ltd, GPL, Summer 2004
# Mandrake Linux 10.0
# Sanitizing the internet, not only makes it cleaner, it also makes it a lot faster
# by suppressing all the junk that would otherwise suck up your bandwidth.

# The recommended structure for squidGuard.conf is: 
# Path declarations 
#  (i.e. logdir and dbhome) 
#  (optional) 
# Time space declarations 
#  (i.e. time zones) 
#  (optional) 
# Source group declarations 
#  (i.e. clients) 
#  (optional) 
# Destination group declarations 
#  (i.e. URLs) 
#  (optional) 
# Rewrite rule group declarations 
#  (optional) 
# Access control rule declarations 
#  (required) 


# Standard paths
logdir /usr/local/squidGuard/logs
dbhome /usr/local/squidGuard/db

# Time periods
time businesshours
{
	weekly mtwhf 08:00-17:00
}

time familyhours
{
	weekly	mtwhfas	06:00-23:00
}

# User Groups
src businessusers
{
	userlist businessusers.txt
}

src familyusers
{
	userlist	familyusers.txt
}

src religioususers
{
	userlist	religioususers.txt
}

# Destination lists
# Addresses are relative to the db directory
dest porn 
{
        domainlist 	blacklists/porn/domains
        urllist    	blacklists/porn/urls
	expressionlist  blacklists/porn/expressions
}

dest ads
{
	domainlist	blacklists/ads/domains
	urllist		blacklists/ads/urls
}

dest audio-video
{
	domainlist	blacklists/audio-video/domains
	urllist		blacklists/audio-video/urls
}

dest aggressive
{
	domainlist	blacklists/aggressive/domains
	urllist		blacklists/aggressive/urls
}

dest drugs
{
	domainlist	blacklists/drugs/domains
	urllist		blacklists/drugs/urls
}

dest gambling
{
	domainlist	blacklists/gambling/domains
	urllist		blacklists/gambling/urls
}

dest hacking
{
	domainlist	blacklists/hacking/domains
	urllist		blacklists/hacking/urls
}

dest mail
{
	domainlist	blacklists/mail/domains
}

dest proxy
{
	domainlist	blacklists/proxy/domains
	urllist		blacklists/proxy/urls
}

dest violence
{
	domainlist	blacklists/violence/domains
	domainlist	blacklists/violence/urls
}

dest warez
{
	domainlist	blacklists/warez/domains
	urllist		blacklists/warez/urls
}

# Access Control
acl 
{
	# During Business hours
	# Stop the embarassing stuff and speed up the connection
        businessusers within businesshours
	{
	        pass !ads !porn !proxy all
        }
	else
	{
		pass all
	}

	# During family hours
	# Stop the embarassing stuff and speed up the connection
	familyusers within familyhours
	{
		pass !ads !aggressive !drugs !hacking !porn !proxy !violence !warez all
	}
	else
	{
		pass all
	}

	# Religioususers
	# Always stop embarassing stuff and speed up connection
	#religioususers
	#{
	#	pass !ads !aggressive !audio-video !drugs !gambling !hacking !porn !proxy !violence !warez all
	#}

        default 
	{
             pass none
             redirect http://www.AerospaceSoftware.com
        }
}

Configure Squid

Well, after all that, you need to configure Squid. Also make sure that all the things that you have defined do have files to match. Don't refer to non-existent files in squidGuard.conf.

Tell Squid to use squidGuard as the redirector by uncommenting and changing the following tags in squid.conf to:

redirect_program /usr/local/bin/squidGuard

Finally restart Squid:

# squid -k reconfigure

and test it with a browser.

Open a tail on the squidGuard log file and watch for error messages. SquidGuard will conveniently refer you to the line number it doesn't like in the configuration file:

# tail -f /usr/local/squidGuard/log/squidGuard.log

Fix whatever errors crop up until it stops complaining and works properly. Happy clean surfing!

Squid Authentication

The easiest way to authenticate users is with ncsa_auth and htpasswd. The ncsa_auth program is part of Squid, while htpasswd is part of Apache. If you haven't got ncsa_auth already, do this:

$ su -
password
# cd ~/squid
# tar -zxvf squid*
# cd squid[tab]
# ./configure
# cd help[tab]
# cd basic[tab]
# cd ncsa[tab]
# make
# make install
# cd /usr/sbin
# ln -s usr/local/squid/libexec/ncsa_auth  ncsa_auth

Now make a password file, using the -c flag the first time:

# cd /etc/squid
# htpasswd -c passwd username
password
password

Now you ca add more users without the -c:

# htpasswd -c passwd username
password
password

Edit file /etc/squid/squid.conf and add the following lines. Note that the help files and lots of entries in the Squid FAQ are wrong. The authenticate_program and authenticate_children parameters are deprecated. Even the comments inside squid.conf are wrong:

auth_param basic program /usr/sbin/ncsa_auth /etc/squid/passwd
auth_param basic children 5
auth_param basic realm Squid proxy-caching web server
auth_param basic credentialsttl 2 hours

restart Squid and Bob's your uncle...

# service squid restart

Now when a user first connects to Squid, it will ask for a username and password.

NCSA Auth Debug

Run ncsa_auth from the command line to test it:

# /usr/sbin/ncsa_auth /etc/squid/passwd
username password
OK

Press Ctrl-C to quit.

Confirm the traffic really is being authorized by tailing access.log. The username should be present.