Thursday, 24 November 2011

Installing Squid Guard

Installing squidGuard

  1. Unpack the source
 tar xvzf squidGuard-1.2.1.tar.gz

  1. Compiling
    Let's assume it is squidGuard-1.2.1 we are trying to install:
 cd squidGuard-1.2.1

If no errors occurred squidGuard is now installed in /usr/local/. There are a couple of option you can use when running ./configure. For example:
Installing in a different location
 ./configure --prefix=/some/other/directory

BerkeleyDB not in /usr/local/BerkeleyDB installed
 ./configure  --with-db=/directory/of/BerkeleyDB/installation

When installed from the sources the BerkeleyDB will be located in /usr/local/BerkeleyDBx.y with x.y denoting the version number.
Annotation: Make sure that the shared library of your BerkeleyDB installation is known by your system (check /etc/, add your BerkeleyDB library path if it is not already there and run ldconfig).
See all ./configure options
 ./configure --help

  1. Installing
 su -
make install

  1. Installing the blacklists

    Copy your blacklists into the desired blacklist directory (default: /usr/local/squidGuard/db) and unpack them. In the table below we assume that the default location is used. Make sure that you have the proper permissions to write to that directory.
 cp /path/to/your/blacklist.tar.gz /usr/local/squidGuard/db
cd /usr/local/squidGuard/db
gzip -d blacklist.tar.gz
tar xfv blacklist.tar

Now the blacklists should be ready to use.

Congratulation. You have just completed the installation of squidGuard. The next step is to configure the software according to your needs. After this you should verify your installation before you finally modify your squid configuration to work with squidGuard.

Once SquidGuard is successfully installed, you want to configure the software according to your needs. A sample configuration has been installed in the default directory  /usr/local/squidGuard (or whatever directory you pointed your installation to).
Below you find three examples for the basic configuration of SquidGuard.
  1. Most simple configuration
Most simple config uration: one category, one rule for all
dbhome /usr/local/squidGuard/db
logdir /usr/local/squidGuard/logs
dest porn {
        domainlist porn/domains
        urllist porn/urls
acl {
        default {
               pass !porn all
                redirect http://localhost/block.html

  1. Make always sure that the very first line of your squidGuard.conf is not empty!
    The entries have the following meaning:
Location of the blacklists
Location of the logfiles
Definition of a category to block. You can enter the domain and url file along with a regular expression list (talk about regular expressions later on).
The actual blocking defintion. In our example only the default is displayed. You can have more than one acl in place. The category porn you defined in dest is blocked by the expression !porn. You have to add the identifier all after the blocklist or your users will not be able to surf anyway.
The redirect directive is madatory! You must tell SquidGuard which page to display instead of the blocked one.
  2. Choosing more than one category to block

    First you define your categories. Just like you did above for porn. For example:
Defining three categories for blocking
dest adv {
        domainlist      adv/domains
        urllist         adv/urls
dest porn {
        domainlist      porn/domains
        urllist         porn/urls
dest warez {
        domainlist      warez/domains
        urllist         warez/urls

  1. Now your acl looks like that:
acl {
        default {
                pass    !adv !porn !warez all
                redirect http://localhost/block.html
  2. Whitelisting

    Sometimes there is a demand to allow specific URLs and domains although they are part of the blocklists for a good reason. In this case you want to whitelist these domains and URLs.
Defining a whitelist
dest white {
        domainlist      white/domains
        urllist         white/urls
acl {
        default {
                pass    white !adv !porn !warez all
                redirect http://localhost/block.html

  1. In this example we assumed that your whitelists are located in a directory called white whithin the blacklist directory you specified with dbhome.
    Make sure that your white identifier is the first in the row of the pass directive. It must not have an exclamation mark in front (otherwise all entries belonging to white will be blocked, too).
  2. Initializing the blacklists

    Before you start up your squidGuard you should initialize the blacklists i.e. convert them from the textfiles to db files. Using the db format will speed up the checking and blocking.
    The initialization is performed by the following command:
Initializing the b lacklists
squidGuard -C all
chown -R <squiduser> /usr/local/squidGuard/db/*

  1. The second command ensures that your squid is able to access the blacklists. Please for <squiduser> the uid of your squid.
    Depending on the size of your blacklists and the power of your computer this may take a while. If anything is running fine you should see something like the following output in your logfile:
2006-01-29 12:16:14 [31977] squidGuard 1.2.0p2 started (1138533256.959)
2006-01-29 12:16:14 [31977] db update done
2006-01-29 12:16:14 [31977] squidGuard stopped (1138533374.571)

  1. If you look into the directories holding the files domains and urls you see that additional files have been created: domains.db and urls.db. These new files must not be empty!
    Only those files are converted you specified to block or whitelist in your squidGuard.conf file.

Verification of your squidGuard Configuration

Now that you have installed and configured your squidGuard you just check a couple of things before going online.
  1. Permissions
    Ensure that the blacklist and db files belong to your squid user. If squid cannot access (or modify) them blocking will not work.

  1. SquidGuard dry-run
    To verify that your configuration is working run the following command (changed to reflect your configuration):
Dry-run squidGuard
echo " - - GET" | squidGuard -c /tmp/test.cfg -d 

  1. If the redirector works properly you should see the redirection URL for the blocked site. For sites not being part of your blacklists the output should end with:
2007-03-25 16:18:05 [30042] squidGuard ready for requests (1174832285.085)
2007-03-25 16:18:05 [30042] squidGuard stopped (1174832285.089)

  1. Some remarks about the different entries of the echoed line:
    • The first entry is the URL you want to test.
    • The second entry is the client IP address. If you configured access control based on IP addresses make sure to test allowed and not allowed IP addresses to ensure proper working.
    • In the third entry (the first - ) you can specify a username. This is only of importance if you have access control based on user names. Make sure to check different names with different access to verify your configuration.

Finalizing the installation by configuring squid

If everything is working properly add the following line to your squid.conf (assuming that your squidGuard is installed in /usr/local; make sure to change the paths to match your installation accordingly):
 url_rewrite_program /usr/local/bin/squidGuard -c /usr/local/squidGuard/squidGuard.conf


  1. is the worlds leading publisher of native acl
    blacklists tailored specifically for Squid proxy, and alternative formats for all major third party plugins as well as
    many other filtering platforms. Including SquidGuard, DansGuardian, and ufDBGuard, as well as pfSense and more.

    There is room for better blacklists, we intend to fill that gap.

    It would be our pleasure to serve you.


    Benjamin E. Nichols

  2. We specialize in serving intelligent network administrators high quality blacklists for effective, targeted inline web filtering leveraging Squid proxy. We are the worlds leading and ONLY publisher of blacklists tailored specifically for use with Squid Proxy Native ACL. We also publish the worlds LARGEST adult domain blacklist, as well, as the worlds first blasphemy blacklist. Our works are available in several alternative formats for compatibility with multiple other web filter platforms. There is a demand for a better blacklist. And with few alternatives available, we intend to fill that gap. Est. 2012. Owned and maintained by Benjamin E. Nichols & Co. It is an extension of the work I have been doing for years applying filters to my own networks with squid proxy and firewalls. is platform whereby I hope to share the amalgamation of these works with the community, in the hopes that it will serve the greater good, helping to secure networks while providing a useful resource for individuals looking for a reasonable level of control of http traffic on their respective networks using a range of filtering solutions.

    It would be our pleasure to serve you,


    Benjamin E. Nichols