Style Cleanup Required
This article does not follow the style standards in the Wiki Guide. More info...


Needs Expansion
This article is incomplete, and needs to be expanded. More info...

This howto describes the process of setting up Squid and SquidGuard for the purpose of internet content filtering. It is revised for Karmic 9.10 and Squid 2.7 in the repositories with it. Older versions work a little different.

There are many different configuration options available. The settings used in this howto are very simplistic and may not suit your needs. In any case it will get you up and running. More complex settings can be added afterwards.


Squid is a proxy server, HTTP requests are sent to Squid instead of being sent directly to the internet.

SquidGuard is a web filter plugin for Squid which is used to restrict access to domains/URLs based upon access control lists. When SquidGuard receives a request it is examined and will either allow the page to load or will redirect to a predetermined “block” page or script. SquidGuard makes its decisions based upon the use of access control lists and databases of domains, URLs, and expressions.


If you'd like to host your own block page, install apache2

sudo apt-get install apache2

Install Squid

Make sure you have the Universe repository enabled

Install SquidGuard

sudo apt-get install squidguard

Key File Locations




Squid configuration file


Squid access log file


SquidGuard configuration file


SquidGuard database files


SquidGuard log file

Squid Configuration

The squid.conf file is huge, with hundreds of options. In this howto we will only be changing a few settings. Open the squid.conf file for editing using sudo and a text editor. You can use graphical sudo (gksudo) and gedit for this task, or sudo nano

gksudo gedit /etc/squid/squid.conf

Turn on line numbers in gedit (Edit > Preferences)

Find the http_port tag. By default it reads # http_port 3128 This is the default port that Squid will listen on for requests. If you want to change it, uncomment the line and set the correct port. If you want Squid to listen only on one specific NIC, you can also change the IP address – for example

Now we need to tell squid where squidguard is. Find the TAG: url_rewrite_program heading. There is no default setting here, so we need to add our own line:

url_rewrite_program /usr/bin/squidGuard –c /etc/squid/squidGuard.conf

Now we'll setup who is allowed access to the proxy. Find the TAG: http_access heading and below it the 'INSERT YOUR OWN RULE(S) HERE...' Uncomment the line

#http_access allow localnet

And we need to define who is in the localnet. Find the TAG: ACL heading. Way down you will find

#acl localnet src (and a bunch of other IP subnets)

You'll need to uncomment that line if necessary, and change that IP address to match your network. /24 signifies the block of IP addresses from to You can also delete any extra IP blocks out of the examples you are not using.

if you get a startup error :- 'FATAL: Could not determine fully qualified hostname. Please set visible_hostname' you will also need to add a visible_hostname tag, or uncomment it if you can find one in there already :-

visible_hostname localhost

Save the file and close gedit

SquidGuard Configuration

For the purposes of this howto we will use a very simple configuration for SquidGuard, with only one category of sites that we want to block. More complex and useful configurations are explained on the official SquidGuard site.

First we will create a list of domains we want to block

sudo mkdir /var/lib/squidguard/db/ads/
gksudo gedit /var/lib/squidguard/db/ads/domains

Insert the following, then save the file.


proxy must own the db, config, and log files

sudo chown proxy:proxy /etc/squid/squidGuard.conf
sudo chown -R proxy:proxy /var/lib/squidguard/db
sudo chown -R proxy:proxy /var/log/squid/

Now we edit our squidGuard.conf file.

gksudo gedit /etc/squid/squidGuard.conf

Delete everything after the line: logdir /var/log/squid

Replace the deleted text with the following:

dest ads {
        domainlist ads/domains

acl {
        default {
                pass !ads all
                redirect http://yourip/block.html

Time to compile the domains list into a database

sudo squidGuard –C all

Create a page to redirect blocked requests to. If you can write raw html in a text editor do

sudo nano /var/www/block.html

If not, use a WYSIWYG editor, and copy the files into the /var/www directory. REMEMBER, this 'block.html' page points to the default web servers directories, probably Apache as installed above. You must have a web server running on the machine for this to work! Or you get an error message with the redirect on the client's PC. You could also redirect it to another server running a web server and let it host the error pages. Put whatever message you want in this page.

Fire up squid and squidguard

sudo /etc/init.d/squid start|restart|stop
sudo squid -k reconfigure

If you change your block page after you have visited it, Squid will have cached it, and will not refetch the new version until its default cache expiration time has been reached (generally 1 week). If you'd like to purge the Squid cache to fetch your revised block page, see the Squid Page.


Change all your client browser settings to use your new proxy.

If you are using Firefox, this is done via Edit > Preferences > Connection Settings. Enter the IP address of your new Proxy server, and the port number you previously configure.

The 3 domains we added to our domains file should be blocked.


It is fairly common to run into problems. 99% of the time, it comes down to permissions or ownership of files.

First of all, lets check what processes are running.

ps -e | grep squid

You should see 1 or 2 squid processes, and 5 squidGuard processes. If not then lets restart Squid. If you previously had an abort when you were trying to reconfigure, then squid crashed and you need to start it again, else skip to the reconfigure step...

sudo /etc/init.d/squid start
sudo squid -k reconfigure

Again, check what processes are running.

Still having problems? Check what's being written to the squidGuard.log file

sudo tail /var/log/squid/squidGuard.log

You might see something here that mentions that SquidGuard has gone into emergency mode. You also might see a generic error like 'Error db_open: Permission denied'. If either is the case, the following may help.

It is often useful to run squidGuard directly from the command line to see what it is doing. An example is:

sudo echo "http://www.ubuntu.com {client ip address}/ - - GET" | squidGuard -d -c /etc/squid/squidGuard.conf

You can change the URL to whatever you'd like to test for access or denial. The IP address is the address of the computer you want to simulate as surfing the net from.

SquidGuard Emergency Mode

When squidguard starts up, it tries to do the following things:

  1. Read the configuration file
  2. Read the database or text files with the lists of sites to block
  3. Write to its log file

If it fails to do any of these things, it goes into "emergency mode"; effectively this means that it doesn't do anything.

The following problems will cause either 1, 2, or 3 to fail:

  • The configuration file is not in the place specified in squid.conf. Make sure squidguard is started with this line in squid.conf:

redirect_program /usr/bin/squidGuard –c /etc/squid/squidGuard.conf
  • The database files are not in the place defined in squidGuard.conf. Make sure the following is one of the first lines in squidGuard.conf:

  • The ownership of the configuration file, logfiles, or blacklist files is not correct. These files should be owned by the user and group under which the squid program runs. In the case of Ubuntu, that user is proxy (I think this is no longer accurate. To get squid to read the domain and db files, I had to set the permissions to 777, setting to 775 would not work. While unsafe, this indicates squid is not running as user 'proxy'. I will edit this if I can determine the actual user name.)

  • To make sure the ownership is correct, run the following commands:

sudo chown proxy:proxy /etc/squid/squidGuard.conf
sudo chown -R proxy:proxy /var/lib/squidguard/db
sudo chown -R proxy:proxy /var/log/squid/
  • The permissions of the configuration file, logfiles, or blacklist files is not correct. Set the permissions as follows:

chmod 644 /etc/squid/squidGuard.conf
chmod -R 640 /var/lib/squidguard/db
chmod -R 644 /var/log/squid/
find /var/lib/squidguard/db -type d -exec chmod 755 \{\} \; -print
chmod 755 /var/log/squid
  • There is a line-end before the "{" character in source or dest lists: Bad:

dest ads
  • Good:

dest ads {

After fixing these problems issue the command to restart with the new settings

sudo squid –k reconfigure

You also need to create Swap directories with 'sudo squid -z' If you still have errors you can start squid with 'squid -NCd1' which starts in debug/verbose mode which will show any errors. As above, the most likely will be permissions.

In Need Of Further Documentation

  • More sophisticated configurations (source groups, time settings, more destination groups, urls, expressions)
  • Using diff files
  • Using Ident

CategoryNetworking CategorySecurity

SquidGuard (last edited 2009-11-23 01:41:05 by cpe-72-181-194-67)