DansGuardian 2.2.x Detailed Installation Guide

Tue 26th March 2002 - Draft 4a

Originally by Daniel Barron, modified by GB




This is not a HOWTO. This document is an attempt at detailed installation instructions for DansGuardian 2.2.x. If you just want to get DansGuardian up and running as quickly as possible, you might want to read the brief installation guide.



You must already be running a fairly recent distribution of Linux, FreeBSD, OpenBSD, Solaris or SuSE. You also need to have squid running and configured on port 3128.

DansGuardian is a filtering pass-through that sits between the client browser and the Squid proxy. It listens on port 8080 and connects to squid on port 3128. So you must have no other daemon running already using port 8080.

You will need a web server. Apache (httpd) that comes with RedHat 6.2 is absolutely perfect and you would be hard pushed to find a better web server. The server is used to display a cgi perl script that gives the user notification of an 'Access Denied'.

You will need the standard development tools installed such as glibc, autoconf, gcc and make. Debian users will also require zlib1g-dev. The default Redhat 6.2 installation and most others come with these installed so you don't need to worry about them.

Most of the time during this work you will need to be logged on as root. A more experienced user will be able to determine when, however for most people - stay logged on as root for the entirety.

Make sure you have all of the above installed and working before you continue.


Collecting what you need

Obviously, you need DansGuardian. You can download it from here: DansGuardian, or from the US mirror site.

It is recommended that you download and install from the source as this is always the most up to date.  However, packages are available for some distributions. For the purpose of these instructions, we shall be installing from the source.


Installation and compilation

If you just want to quickly get on with the installation and avoid all this detail, don't forget you can simply follow the brief installation guide.

1. Download DansGuardian-2.2.*.source.tar.gz into a temporary area, and untar with a tar -zxpf.  This will create the subdirectory DansGuardian-2.2.*.

DansGuardian uses gnu autoconf, auto-generating the Makefile with the "configure" script.

2. cd into this new directory. Run the configure script with the help option (./configure --help) to see the user selectable settings (see table below).



default value


where the binary gets placed /usr/sbin/


where the config and data files gets placed /etc/dansguardian/


where the startup script gets placed /etc/rc.d/init.d/


where the cgi-bin dir is located /home/httpd/cgi-bin/


where the man docs get placed /usr/man/


 where the logs get place /var/log/dansguardian/


the system user the daemon runs as nobody


the system group the daemon runs as nobody


where the pid file gets placed /var/run/

3. Run configure with the appropriate options. For examples, see section  Example Configure Scripts below.

RedHat 6.2 and 7.0 users can run configure with the default settings. RedHat 7.1 and 7.2 will have to change their cgidir option. Solaris, OpenBSD and FreeBSD will have to set just about all settings.

4. Edit the Makefile and verify that all the settings are correct. If not, re-run the configure script. If you don't understand Makefiles, skip this step.

5. Run make to build DansGuardian (gmake for Solaris).

6. Run make install to create the directory structure, install all the files in the chosen paths and set permissions as appropriate.

7. Doing a make clean will remove the now un-needed binaries etc.

8. When a page is denied, DansGuardian redirects to a cgi perl script on your web server to report to the user. This makes it easy to customise the message. This server does not need to be the same machine as the DansGuardian filter server, however if it is not local you will need to amend or comment out the perl script copying line in the Makefile.

To configure the address of your web server that will display the access denied perl script, edit the accessdeniedaddress within dansguardian.conf (see sysconfdir above).  For further configuration options, see the Options section.

9. The last thing that we need to do is configure the log rotation. Log rotation ensures that the filesystem does not fill up with a huge log file. Most daemons that log such as httpd and squid rotate their logs once a week. With DansGuardian, there are five log files: access.log, access.log.1, access.log.2 ... and so on up to 4.  Once a week, the oldest of the five log files is deleted, and the remaining logs' names are incremented by one, and a new access.log is created. The Makefile copies a log rotation script to the configuration directory. We need to schedule this script to run once a week, so (as root) do a crontab -e and enter the following:

59 23 * * sat /etc/dansguardian/logrotation

Then save. This will schedule it for 23:59 every Saturday. Of course you can schedule the log rotation differently or edit the script to your own liking.

DansGuardian is now ready to go. You can start it by just running the binary (ie just type dansguardian and hit return). You can stop it with a dansguardian -q. Or you can use the SysV(-like) script provided. Run a dansguardian -h to see other command line options available.

Example Configure Scripts

Here are some examples of options for the configure script for different distributions:

A standard configure script that should work, provided you have installed FreeBSD and the associated programs in their default locations.

./configure --cgidir=/usr/local/www/cgi-bin/ \
--sysconfdir=/usr/local/etc/dansguardian/ \
--sysvdir=/usr/local/etc/rc.d/ \
--bindir=/usr/local/sbin/ \

A standard configure script that should work, provided you have installed OpenBSD and the associated programs in their default locations.

./configure --cgidir=/var/www/cgi-bin/ \
--sysconfdir=/usr/local/etc/dansguardian/ \
--sysvdir=/usr/local/etc/rc.d/ \
--bindir=/usr/sbin/ \

RedHat 6.2/7.0
It is safe to run the configure (./configure) script with the defaults.

RedHat 7.1/7.2
./configure --sysconfdir=/usr/local/etc/dansguardian/ \
--sysvdir=/etc/rc.d/init.d/ \

Mandrake 7.2
./configure --mandir=/usr/share/man/

Mandrake 8/8.1
./configure --mandir=/usr/share/man/ \

The system user 'squid' might be also appropriate rather than 'nobody' when configuring your system's "runas" option.

SuSE 7.2
./configure --runas_grp=nogroup \

SuSE 7.3
./configure --runas_grp=nogroup \
--cgidir=/usr/local/httpd/cgi-bin/ \

Only Solaris 8 (7/01) has been tested. DansGuardian requires the GNU version of make (gmake), and GCC version 2.95.3 (3.01 may work but is as yet untested and not recommended).

Both gmake and GCC 2.95.3 are included with the OS on the "Companion CD", and are usually installed in /opt/sfw/bin. To ensure these are in your path, simply do (in csh; bash syntax is different):

setenv PATH /opt/sfw/bin\:$PATH

To configure and compile, do:
./configure --bindir=/opt/dansguardian/sbin/ \
--sysconfdir=/opt/dansguardian/etc/ \
--sysvdir=/etc/init.d/ \
--cgidir=/var/apache/cgi-bin/ \
--mandir=/opt/dansguardian/man/ \

Further customisation - configuration options

DansGuardian is highly configurable. The source code is provided so you have the ultimate in configurability, although most people will be content with modifying the configuration files. If you do modify the source code please send what you've done to Daniel.

After you have modified any configuration file, to apply the changes you will need to restart DansGuardian. To do this run the sysv script with the restart option.  For example, for RedHat type the following in a terminal:

/etc/rc.d/init.d/dansguardian restart

or for OpenBSD:

/usr/local/etc/rc.d/dansguardian.sh restart

Alternatively, run a dansguardian -q followed by a dansguardian.

There is one main configuration file, several banned lists and an exception list. These are all explained below:


This contains a list of domain endings that if found in the requested URL, DansGuardian will not filter the page. Note that you should not put the httpd:// or the www. at the beginning of the entries.


This contains a list of client IPs who you want to bypass the filtering. For example, the network administrator's computer's IP.


Usernames who will not be filtered (basic authentication or ident must be enabled).


This contains a list of banned phrases. The phrases must be enclosed between < and >. DansGuardian is supplied with an example list. You can not use phrases such as <sex> as this will block sites such as Middlesex University. The phrases can contain spaces. Use them to your advantage. This is the most useful part of DansGuardian and will catch more pages than PICS and URL filtering put together.

Combinations of phrases can also be used, which if they are all found in a page, it is blocked.


This contains a list of banned MIME-types. If a URL request returns a MIME-type that is in this list, DansGuardian will block it. DansGuardian comes with some example MIME-types to deny. This is a good way of blocking inappropriate movies for example. It is obviously unwise to ban the MIME-types text/html or image/*.


This contains a list of banned file extensions. If a URL ends in an extension that is in this list, DansGuardian will block it. DansGuardian comes with some example file extensions to deny. This is a good way of blocking kiddies from downloading those lovely screen savers and hacking tools. You are a fool if you ban the file extension .html, or .jpg etc.


This contains a list of banned regular expression URLs.  For more information on regular expressions, click here.


This file contains a list of banned sites.  Entering a domain name here bans the entire site.  For banning specific parts of a site, see bannedurllist. Also, you can have a blanket ban all sites except those specifically excluded in exceptionsitelist. You can also block sites specified only as an IP address, and include a stock squidGuard blacklists collection. To enable these blacklists, download them from the extras section here. Simply put them somewhere appropriate, un-comment the squidGuard blacklists collection lines at the bottom of the bannedsitelist file, and check the paths are correct. For URL blacklists, edit the bannedurllist in a similar way.


This allows you to block specific parts of a site rather than the whole site.  To block an entire site, see bannedsitelist. To enable squidGuard blacklists for URLs, you will need to download the blacklists and edit the squidGuard blacklists collection section at the bottom (as for bannedsitelist above).


This file allows you to finely tune the PICS filtering. Each PICS section comes with a description of the allowed settings and what they represent. The default settings with DansGuardian are set for youngish children, for example mild profanities and artistic nudity are allowed.

For more detailed information on PICS ratings, click here.


The ICRA section is fairly self-explanatory.  A value of 0 means nothing of that category is allowed, whereas a value of 1 allows it. For example,

ICRAnudityartistic = 1

allows nude art. For more in-depth information see here.


RSAC is an older version of ICRA. The values here range from 0 meaning none allowed, through 2 (the default value), to 4, which allows wanton and gratuitous amounts of the given category. For more in-depth information see here.


evaluWEB rating uses a system similar to the British Film classification system:

0 = U (Universal, ie. suitable for even the youngest viewer)

1 = PG (Parental Guidance recommended)

2 = 18 (Only suitable for viewers aged 18 and over)


Similar to RSAC, but containing a larger range of categories with the range from 0 = full filtering to 9 = wanton and gratuitous. For more in-depth information, see here.


See evaluWEB. For more in-depth information, see here.

Vancouver Webpages

This is yet another ratings scheme.  See here for more information.



The only setting that is vital for you to configure in the dansguardian.conf file is the accessdeniedaddress setting. You should set this to the address (not the file path) of your Apache server with the perl access denied reporting script. For most people this will be the same server as squid and DansGuardian. If you really want you can change this address to a normal html static page on any server.

Reporting Level

You can change the reporting level for when a page gets denied. It can say just 'Access Denied', or report why, or report why and what the denied phrase is. The latter may be more useful for testing, but the middler would be more useful in a school environment. Stealth mode logs what would be denied but doesn't do any blocking.

Logging Settings

This setting lets you configure the logging level. You can log nothing, just denied pages, text based and all requests. HTTPS requests only get logged when the logging is set to 3 - all requests.

Network Settings

These allow you to modify the IP address that DansGuardian is listening on, the port DansGuardian listens on, the IP address of the server running squid as well as the squid port. It is possible to configure the Access Denied reporting page here also.

Content Filtering Settings

Here you can modify the location of the list files. Adjusting these locations is not recommended.

Reverse Lookups for Banned Sites and URLs

If set to on, DansGuardian will look up the forward DNS for an IP URL address and search for both in the banned site and URL lists. This would prevent a user from simply entering the IP for a banned address. It will reduce searching speed somewhat so unless you have a local caching DNS server, leave it off and use the Blanket IP Block option in the bannedsitelist file instead.

Build bannedsitelist and bannedurllist Cache Files

This will compare the date stamp of the list file with the date stamp of the cache file and will recreate as needed. If a bsl or bul .processed file exists, then that will be used instead. It will increase process start speed by 300%. On slow computers this will be significant. Fast computers do not need this option.

POST protection (web upload and forms)

This is for blocking or limiting uploads, not for blocking forms without any file upload. The value is given in kilobytes after MIME encoding and header information.

Username identification methods (used in logging)

The proxyauth option is for when basic proxy authentication is used (obviously no good for transparent proxying). The ntlm option is for when the proxy supports the MS NTLM authentication.  This only works with IE5.5 sp1 and later, and has not been implemented yet. The ident option causes DansGuardian to try to connect to an identd server on the computer originating the request.

Forwarded For

This option adds an X-Forwarded-For: <clientIP> to the HTTP request header. This may help solve some problem sites that need to know the source IP.

Max Children

This sets the maximum number of processes to spawn to handle the incoming connections. This will prevent DoS attacks killing the server with too many spawned processes. On large sites you might want to double or triple this number.

Log Connection Handling Errors

This option logs some debug info regarding fork()ing and accept()ing which can usually be ignored. These are logged by syslog. It is safe to leave
this setting on or off.


Squid configuration

There is none that is required as DansGuardian appears to squid just as a normal web browser. However...

We need to make sure that squid will not allow client browsers to bypass DansGuardian. This is a non trivial problem. What I will assume is that you have already blocked open web access (via firewall IP tables and IP chains) and the only way to access the web is through squid and hence DansGuardian. This goal is achievable in a number of ways.

squid.conf method

You can modify the acl rules so that only localhost has access. In my squid.conf I had the following lines:

acl localnet src
http_access allow localnet
http_access allow localhost
http_access deny all

So I remmed out both the localnet lines with a #. I believe that the default configuration of squid is to only have localhost allowed so you probably don't even have to do this.

With proxy authentication things get a little bit more complex. With no DansGuardian in my squid.conf I have:

authenticate_program /usr/bin/smb_auth -W DOMAIN -U
acl domainusers proxy_auth REQUIRED
http_access allow domainusers
http_access deny all
Which allows authenticated users to access the proxy from anywhere.

However, it makes sense to let SSL through without going through DansGuardian, yet at the same time still prevent bypassing DansGuardian on other ports. So the same section became:

authenticate_program /usr/bin/smb_auth -W DOMAIN -U
acl domainusers proxy_auth REQUIRED
acl linuxserver src
acl ntserver src
http_access allow linuxserver
http_access allow ntserver
http_access allow domainusers localhost
http_access allow CONNECT SSL_ports
http_access deny all
So for all web access (SSL or not) the user is required to be authenticated, but SSL is allowed to bypass DansGuardian. I also allow the NT and Linux servers to bypass the filtering and access squid directly.

ipchains method 1

You could redirect incoming requests on port 3128 from the local net to port 8080 while still allowing incoming from the localhost to access 3128. More specific detail is currently beyond the scope of these instructions.

ipchains method 2 - sneaky method

A really sneaky method would be to configure squid to work as a transparent proxy and redirect all port 80 traffic to port 8080. You would want to include method 1 as well. More specific detail is currently beyond the scope of these instructions. There are HOWTOs that cover this.


Client Configuration

Simple config

Let's assume you have a Linux server at IP which is a caching web proxy and intranet web server. On this server you have DansGuardian installed listening on port 8080.

You need to configure the client browser for http proxy with port 8080. You can configure ftp the same as http - it is reported to work. That's it. But for efficiency you might want to set the 'no proxy on' to your local Apache server address - in this case. If you've got DNS working, you can use the DNS address of your local server. I tend not to.

Sneaky Config

If you've used the sneaky method to configure squid then there should be no configuration required. Configure your browser for no proxy and maybe set the 'no proxy on' to your local Apache server address - in this case.

Beebug(Daniel's) Config

This could be known as super sneaky I suppose. The problem with the simple config method is that you have to configure by hand every browser. This is a pain and is why the sneaky method is really quite good.
The way Beebug solve this is by using a custom in-house Visual Basic application that loads upon login and modifies the needed Windows registry and various files so that IE and Netscape (including email) are configured automatically. It's so good, you can just stick a copy of Netscape on a server in a share and run this program at login and it automatically just works on all the PCs. No installation and a central copy so it's easy to update.
It also has other features such as removing unwanted bits such as web folders, GMT/BST auto switching (already done by login script), app data, and other fixes.
Unless I persuade the directors to release it open source you can't use this method without paying or writing your own. And guess who wrote this - yes - the DansGuardian author!


For all support issues, join the mailing list and post your question or comment there.

If you feel your message is not suitable for public viewing and is private (for example asking for pricing or other commercial issues) then email me direct. My address is daniel at jadeb dot com.

You can also get further help from the DansGuardian web site dansguardian.org.

Any comments about this document, email gb at dansguardian dot org.