Fri 17th August 2001 - Draft 7
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 and make. 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.
And also, of course, you need DansGuardian! You can download it from here: DansGuardian
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.
tar -zxpf nb++-0.6.0.tar.gz. This will create a subdirectory nb++-0.6.0. cd into this subdirectory and run ./configure, make, then make check, then make install, and if desired a make clean.
If you have problems or want more detailed instructions, read the INSTALL file within the nb++-0.6.0 directory.
tar -zxpf dansguardian-*.tar.gz. This will create a subdirectory DansGuardian-*.*.*.
cd into this new directory. You may need to edit the Makefile. Infact pull it up into your favourite editor now so you know what we are talking about. The Makefile compiles all the components of DansGuardian and produces a binary file. It then copies all the files needed to where they need to be. I.e. the dansguardian binary, the configuration files, the SysV script and the perl script used for reporting denied pages. The final thing that it does is create and permission a log directory.
The binary file is copied into /usr/sbin/
The perl file is copied into /home/httpd/cgi-bin/
The configuration files are copied into /etc/dansguardian
The SysV script (the thing to allow you to stop and start the service in NT speak) is copied into /etc/rc.d/init.d/
The log directory is /var/log/dansguardian
If you really don't know or care about the Makefile settings then don't worry - just leave it as is - especially if you are using a Redhat 6.2 or better distribution.
If you know what you are doing then edit the Makefile to your liking. The installation structure uses a RedHat style which you may not like. However keep in mind the extra complications such as editing the SysV script to point to the new binary location etc.
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.
Now do a make, make install and optional make clean. This will have installed DansGuardian, but you need to configure the server to start the daemon at bootup. To do this use your favourite SysV Init Editor such as linuxconf or the one that comes with KDE and Gnome. You ought to put it some number higher than squid and httpd but not much higher.
We need to configure the address of your web server that will display the access denied perl script. Pull /etc/dansguardian/dansguardian.conf into your favourite editor and edit the accessdeniedaddress. For more information see the Options section.
The last thing that we need to do is configure the log rotation. The idea of log rotation is to make sure that the filesystem does not get filled eventually with a huge log file. Most daemons that log such as httpd and squid rotate their logs once a week; the oldest log file is deleted and the 2nd oldest is renamed to log.4. The current log is renamed to log.1. The rest you can guess. The Makefile copies a log rotation script to the configuration directory. We need to run it once a week, so (as root) do a crontab -e and enter the following:
59 23 * * sun /etc/dansguardian/logrotation
Then save. This will schedule it for 23:59 every Sunday. Or configure as pleases you. You can edit the logrotation file if you want.
As linux is so stable, you are unlikely to ever need to reboot it (I have several with uptime since last millennium) and so DansGuardian will never be started. You can start and stop it manually by doing a: /etc/rc.d/init.d/dansguardian start (or stop).
DansGuardian is now installed and ready to go with the default settings. However you may wish to change some of these default settings...
After you have modified any configuration file, to apply the changes you will need to restart DansGuardian. To do this type the following in a terminal:
/etc/rc.d/init.d/dansguardian restart
There is one main configuration file, several banned lists and an exception list. These are all explained below:
As of DansGuardian 0.8.7 you can also have combinations of phrases as well, which if they are all found in a page, it is blocked.
The only setting that is vitally important that you configure in the dansguardian.conf file is the accessdeniedaddress setting. You should set this to the address 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.
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 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.
But when I installed DansGuardian I needed to allow SSL through without going through DansGuardian. I also needed to disallow people to bypass DansGuardian. 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.
Lets assume you have a lovely Linux server at ip 192.168.0.1 which is a proxy to the Internet 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 Daniel.