Tue 26th March 2002 - Draft 4a
Originally by Daniel Barron, modified by GB
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.
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.
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).
option |
description |
default value |
|
bindir |
where the binary gets placed | /usr/sbin/ |
|
sysconfdir |
where the config and data files gets placed | /etc/dansguardian/ |
|
sysvdir |
where the startup script gets placed | /etc/rc.d/init.d/ |
|
cgidir |
where the cgi-bin dir is located | /home/httpd/cgi-bin/ |
|
mandir |
where the man docs get placed | /usr/man/ |
|
logdir |
where the logs get place | /var/log/dansguardian/ |
|
runas_usr |
the system user the daemon runs as | nobody |
|
runas_grp |
the system group the daemon runs as | nobody |
|
piddir |
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.
Here are some examples of options for the configure script for different distributions:
FreeBSD
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/
\
--mandir=/usr/local/man/
OpenBSD
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/
\
--mandir=/usr/share/man/
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/
\
--cgidir=/var/www/cgi-bin/
Mandrake 7.2
./configure
--mandir=/usr/share/man/
Mandrake 8/8.1
./configure
--mandir=/usr/share/man/ \
--cgidir=/var/www/cgi-bin/
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
\
--cgidir=/usr/local/httpd/cgi-bin/
SuSE 7.3
./configure
--runas_grp=nogroup \
--cgidir=/usr/local/httpd/cgi-bin/
\
--sysvdir=/etc/init.d/
Solaris
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/
\
--logdir=/opt/dansguardian/log/
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:
Usernames who will not be filtered (basic authentication or ident must be enabled).
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 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).
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.
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.
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.
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.
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.
You can modify the acl rules so that only localhost has access. In my squid.conf I had the following lines:
# INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS # acl localnet src 192.168.42.0/255.255.255.0 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 192.168.0.2 acl domainusers proxy_auth REQUIRED http_access allow domainusers http_access deny allWhich 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 192.168.0.2 acl domainusers proxy_auth REQUIRED acl linuxserver src 192.168.0.1/255.255.255.255 acl ntserver src 192.168.0.2/255.255.255.255 http_access allow linuxserver http_access allow ntserver http_access allow domainusers localhost http_access allow CONNECT SSL_ports http_access deny allSo 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.
Let's assume you have a Linux server at IP 192.168.0.1 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 192.168.0.1 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 - 192.168.0.1 in this case. If you've got DNS working, you can use the DNS address of your local server. I tend not to.
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.