This guide is a quick step-by-step guide to how I implement DansGuardian on Ubuntu systems. This one is all command-line with no hand-holding. For that, try some of my earlier tutorials. I may yet do another GUI-oriented, in-depth tutorial, if I get time.
Below are my local install notes for putting together a DansGuardian filtering system on Ubuntu Lucid, including multiple filtering profiles and statistics. You'll need to be pretty comfortable with Linux and the command line to replicate this. But it's really nothing too complicated. Basic steps needing no explanation are omitted.
$ sudo passwd root $ su # mv /etc/securetty /etc/securetty.bak # touch /etc/securetty # mv /etc/sudoers /etc/sudoers.bak
/etc/ntp.conf to add us.pool.ntp.org to the top of the list of servers./etc/ssh/sshd_config. Disable root login, disable X11Forwarding, and uncomment Banner./etc/issue.net to be:*******************************************************************************
NOTICE TO USERS
This computer system is the property of the Branch District Library. It is
for authorized use only. Users (authorized or unauthorized) have no explicit
or implicit expectation of privacy.
Any or all uses of this system and all files on this system may be intercepted,
monitored, recorded, copied, audited, inspected, and disclosed to authorized
officials of law enforcement and government agencies.
By using this system, the user consents to such interception, monitoring,
recording, auditing, inspection, and disclosure at the discretion of the Branch
District Library or other authorized officials of law enforcement or government
agencies.
Unauthorized or improper use of this system may result in civil and criminal
penalties and administrative or disciplinary action, as appropriate. By
continuing to use this system you indicate your awareness of and consent to
these terms and conditions of use. LOG OFF IMMEDIATELY if you do not agree to
the conditions stated in this notice.
*******************************************************************************
/etc/network/interfaces. Leave the entry for eth0, add the following for eth1:auto eth1 iface eth1 inet static address 192.168.1.1 netmask 255.255.255.0 network 192.168.1.0 broadcast 192.168.1.255 gateway [gateway from eth0]
# mv /etc/dhcp3/dhcpd.conf /etc/dhcp3/dhcpd.conf.bak
/etc/dhcp3/dhcpd.conf as needed with static address assignments. If you don't want to count your library computers in the statistics (we'll cover that later), make sure all library computers are defined in this file. The top of the file should look something like this:authoritative;
default-lease-time 3600;
max-lease-time 3600;
ddns-update-style none;
log-facility local7;
option routers 192.168.1.1;
option domain-name-servers [your-DNS-1,yourDNS-2];
subnet [IP address of eth0] netmask 255.255.255.0
{
}
subnet 192.168.1.1 netmask 255.255.255.0
{
range 192.168.1.100 192.168.1.254; # desired public service IP address range
host [host name here] # host names for static IP assignment
{
hardware ethernet [MAC address];
fixed-address [IP address];
}
}
# cp /usr/share/doc/shorewall/default-config/* /etc/shorewall/
/etc/shorewall/shorewall.conf. Find the line that reads IP_FORWARDING=Keep and change that to IP_FORWARDING=On./etc/shorewall/interfaces:#ZONE INTERFACE BROADCAST OPTIONS net eth0 detect loc eth1 detect dhcp
/etc/shorewall/masq:eth0 192.168.1.0/24 eth0 192.168.40.0/24
/etc/shorewall/policy:loc all REJECT fw all REJECT net all DROP all all REJECT
/etc/shorewall/rules. At minimum, have the following rules. More likely, use the huge ruleset we normally use.# Accept SSH connections for administration
ACCEPT loc fw tcp 22
ACCEPT net fw tcp 22
# Accept HTTP for the wifi stats
ACCEPT loc fw tcp 80
ACCEPT net fw tcp 80
# All pinging the web filter
ACCEPT loc net icmp
# Allow DNS requests
ACCEPT loc net tcp 53
ACCEPT loc net udp 53
# Allow POP3 email
ACCEPT loc net tcp 110
# Allow NTP (Network Time Protocol)
ACCEPT loc net udp 123
# Allow IMAP email
ACCEPT loc net tcp 143
# Allow secure web sites
ACCEPT loc net tcp 443
# Secure SMTP
ACCEPT loc net tcp 465
# Allow DHCP requests
ACCEPT loc fw tcp 546,547
ACCEPT loc fw udp 67,68
# smtp submission
ACCEPT loc net tcp 587
# Allow Secure IMAP email
ACCEPT loc net tcp 993
# Allow Secure POP3 email
ACCEPT loc net tcp 995
# Allow both sides of the firewall to access the filter
ACCEPT net fw tcp 8080
# Route all HTTP traffic from patron laptops to the passive filter
REDIRECT loc 8080 tcp 80,8000,8001,8080
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE
/etc/shorewall/zones:fw firewall net ipv4 loc ipv4
/etc/default/shorewall. Change startup=0 to startup=1. Restart shorewall.# shorewall restart
/etc/squid/squid.conf, search for http_port 3128. Change this to http_port 127.0.0.1:3128 transparent. Change access_log to none, change cache_store_log to none. Add lines like this to the end of the file to throttle HTTP traffic as needed (adjust to match your bandwidth and needs):########Squid Delay Pools######### # a simple global throttle, users sharing 5 Mbit/s delay_pools 1 delay_class 1 1 # 5 Mbit/s fill rate, 6 Mbit/s reserve delay_parameters 1 655360/786432 acl All src 0/0 delay_access 1 allow All
dansguardian.conf and dansguardianf1.conf to fine-tune our instances. Symlink the binaries, make additional directories for configuration and log files, and copy and symlink to the orginal configuration files (for your copy & paste pleasure, a one-line command of all of the below comes after the list):# ln -s /usr/sbin/dansguardian /usr/sbin/dansguardian1 # ln -s /usr/sbin/dansguardian /usr/sbin/dansguardian2 # ln -s /usr/sbin/dansguardian /usr/sbin/dansguardian3 # mkdir /etc/dansguardian1 # mkdir /etc/dansguardian2 # mkdir /etc/dansguardian3 # mkdir /var/log/dansguardian1 # mkdir /var/log/dansguardian2 # mkdir /var/log/dansguardian3 # chown dansguardian:dansguardian /etc/dansguardian1 # chown dansguardian:dansguardian /etc/dansguardian2 # chown dansguardian:dansguardian /etc/dansguardian3 # chown dansguardian:dansguardian /var/log/dansguardian1 # chown dansguardian:dansguardian /var/log/dansguardian2 # chown dansguardian:dansguardian /var/log/dansguardian3 # cp /etc/dansguardian/dansguardian.conf /etc/dansguardian1/ # cp /etc/dansguardian/dansguardian.conf /etc/dansguardian2/ # cp /etc/dansguardian/dansguardian.conf /etc/dansguardian3/ # cp /etc/dansguardian/dansguardianf1.conf /etc/dansguardian1/ # cp /etc/dansguardian/dansguardianf1.conf /etc/dansguardian2/ # cp /etc/dansguardian/dansguardianf1.conf /etc/dansguardian3/ # ln -s /etc/dansguardian/authplugins /etc/dansguardian1/authplugins # ln -s /etc/dansguardian/authplugins /etc/dansguardian2/authplugins # ln -s /etc/dansguardian/authplugins /etc/dansguardian3/authplugins # ln -s /etc/dansguardian/contentscanners /etc/dansguardian1/contentscanners # ln -s /etc/dansguardian/contentscanners /etc/dansguardian2/contentscanners # ln -s /etc/dansguardian/contentscanners /etc/dansguardian3/contentscanners # ln -s /etc/dansguardian/downloadmanagers /etc/dansguardian1/downloadmanagers # ln -s /etc/dansguardian/downloadmanagers /etc/dansguardian2/downloadmanagers # ln -s /etc/dansguardian/downloadmanagers /etc/dansguardian3/downloadmanagers # ln -s /etc/dansguardian/languages /etc/dansguardian1/languages # ln -s /etc/dansguardian/languages /etc/dansguardian2/languages # ln -s /etc/dansguardian/languages /etc/dansguardian3/languages # ln -s /etc/dansguardian/lists /etc/dansguardian1/lists # ln -s /etc/dansguardian/lists /etc/dansguardian2/lists # ln -s /etc/dansguardian/lists /etc/dansguardian3/lists
# ln -s /usr/sbin/dansguardian /usr/sbin/dansguardian1; ln -s /usr/sbin/dansguardian /usr/sbin/dansguardian2; ln -s /usr/sbin/dansguardian /usr/sbin/dansguardian3; mkdir /etc/dansguardian1; mkdir /etc/dansguardian2; mkdir /etc/dansguardian3; mkdir /var/log/dansguardian1; mkdir /var/log/dansguardian2; mkdir /var/log/dansguardian3; chown dansguardian:dansguardian /etc/dansguardian1; chown dansguardian:dansguardian /etc/dansguardian2; chown dansguardian:dansguardian /etc/dansguardian3; chown dansguardian:dansguardian /var/log/dansguardian1; chown dansguardian:dansguardian /var/log/dansguardian2; chown dansguardian:dansguardian /var/log/dansguardian3; cp /etc/dansguardian/dansguardian.conf /etc/dansguardian1/; cp /etc/dansguardian/dansguardian.conf /etc/dansguardian2/; cp /etc/dansguardian/dansguardian.conf /etc/dansguardian3/; cp /etc/dansguardian/dansguardianf1.conf /etc/dansguardian1/; cp /etc/dansguardian/dansguardianf1.conf /etc/dansguardian2/; cp /etc/dansguardian/dansguardianf1.conf /etc/dansguardian3/; ln -s /etc/dansguardian/authplugins /etc/dansguardian1/authplugins; ln -s /etc/dansguardian/authplugins /etc/dansguardian2/authplugins; ln -s /etc/dansguardian/authplugins /etc/dansguardian3/authplugins; ln -s /etc/dansguardian/contentscanners /etc/dansguardian1/contentscanners; ln -s /etc/dansguardian/contentscanners /etc/dansguardian2/contentscanners; ln -s /etc/dansguardian/contentscanners /etc/dansguardian3/contentscanners; ln -s /etc/dansguardian/downloadmanagers /etc/dansguardian1/downloadmanagers; ln -s /etc/dansguardian/downloadmanagers /etc/dansguardian2/downloadmanagers; ln -s /etc/dansguardian/downloadmanagers /etc/dansguardian3/downloadmanagers; ln -s /etc/dansguardian/languages /etc/dansguardian1/languages; ln -s /etc/dansguardian/languages /etc/dansguardian2/languages; ln -s /etc/dansguardian/languages /etc/dansguardian3/languages; ln -s /etc/dansguardian/lists /etc/dansguardian1/lists; ln -s /etc/dansguardian/lists /etc/dansguardian2/lists; ln -s /etc/dansguardian/lists /etc/dansguardian3/lists;
/etc/dansguardian/lists/bannedextensionlist. Comment out any file extension that you want to allow through the filter. Since we are not locking things down tightly like a corporate environment might, you'll probably want to comment out every line here. If you think you'll never want to block specific file types, you could just select everything then delete the content of the file to save time. /etc/dansguardian/lists/bannedmimetypelist is similar, you'll probably want to comment out, or delete, all the lines. Now open /etc/dansguardian/lists/bannedregexpurllist. For a library, the directives in this file have a tendency to over-block, so comment out or delete all lines./etc/dansguardian/lists/bannedsitelist is one of the more important files. This is where you can force an entire web site to be blocked. You can also use this file to make your filter a whitelist. That is, all sites will be blocked that you don't explicitly allow. Finally, you also have the option to use some built-in blacklists. You likely won't need to edit this file now, but later you might. The comments in the file explain how to enable the various options. One thing you will want to do for a library environment is comment out the advertisement blocking about halfway down through the file./etc/dansguardian/lists/bannedurllist works in a similar fashion, though only for individual pages within a larger web site, while leaving the rest of the web site alone. Like the last file, you probably don't need to edit it now, except for commenting out the ad blocking./etc/dansguardian/lists/bannedregexpurlist: comment it all out.exceptionsitelist—work similar to the banned* ones above, only they apply to things you don't want blocked. Edit them as you see fit. At BDL we add all the major web mail providers to exceptionsitelist so that emails would never get blocked, for example. Also, add .edu, .gov, .mi.us, etc.
/etc/dansguardian/lists/weightedphraselist contains pointers to the various categories of phraselists that DansGuardian uses in evaluating web pages. There's a nice description at the top of the file that describes how the term weighting works. Edit the file as you see fit, commenting out lines for things you don't want to be blocked. For our example we'll leave the weighted phrase lists only for good phrases and pornography, and comment out the rest./etc/dansguardian/languages/ukenglish/template.html as desired.dansguardian.conf and dansguardianf1.conf in the directories /etc/dansguardian1, /etc/dansguardian2, and /etc/dansguardian3. You'll need to change all references in each of these files as needed for filter ports, and for filesystem locatons for configuration directories, and log files. For example, our DansGuardian3 profile will listen on port 8083, will write logs to /var/log/dansguardian3, and so on.dansguardian.conf files, comment out the line near the top of the file that reads "UNCONFIGURED". Find loglevel = 2 and change the "2" to a "1".dansguardianf1.conf files, change the value for naughtynesslimit. We use 100 for children, 200 for adults, and 250 for our public wireless network.# cd /etc/init.d/ # mv dansguardian dansguardian.orig # update-rc.d dansguardian remove
/etc/init.d/dansguardian1. Edit as appropriate for /etc/init.d/dansguardian2 and /etc/init.d/dansguardian3.#! /bin/sh
# Startup script for dansguardian
#
# description: A web content filtering plugin for web \
# proxies, developed to filter using lists of \
# banned phrases, MIME types, filename \
# extensions and PICS labling.
# processname: dansguardian1
# pidfile: /var/run/dansguardian1.pid
# config: /etc/dansguardian1/dansguardian.conf
CONFFILELOCATION=/etc/dansguardian1/
BINARYLOCATION=/usr/sbin/
PIDDIR=/var/run/
# See how we were called
case "$1" in
start)
if [ -f ${BINARYLOCATION}dansguardian1 ] &&
[ -f ${CONFFILELOCATION}dansguardian.conf ]; then
echo " * Starting dansguardian1..."
if ${BINARYLOCATION}dansguardian1 -c /etc/dansguardian1/dansguardian.conf 2> /dev/null; then
echo " [ ok ]"
touch /var/lock/dansguardian1
else
echo " [ FAILED ]"
fi
fi
;;
stop)
echo " * Shutting down dansguardian1..."
if ${BINARYLOCATION}dansguardian1 -c /etc/dansguardian1/dansguardian.conf -q 2> /dev/null; then
echo " [ ok ]"
/bin/rm -f ${PIDDIR}dansguardian1.pid
/bin/rm -f /tmp/.dguardian1ipc
/bin/rm -f /var/lock/dansguardian1
else
echo " [ FAILED ]"
fi
;;
reload|restart)
$0 stop
sleep 3
$0 start
;;
status)
if [ -f ${BINARYLOCATION}dansguardian1 ]; then ${BINARYLOCATION}dansguardian1 -c /etc/dansguardian1/dansguardian.conf -s
fi
;;
*)
echo "Usage: {start|stop|restart|status}" >&2
;;
esac
exit 0
# cd /etc/init.d/ # chmod +x dansguardian* # update-rc.d dansguardian1 defaults 50 19 # update-rc.d dansguardian2 defaults 50 19 # update-rc.d dansguardian3 defaults 50 19
# /etc/init.d/dansguardian1 start # /etc/init.d/dansguardian2 start # /etc/init.d/dansguardian3 start
# mysql -u root -p mysql> CREATE DATABASE IF NOT EXISTS `wifi_stats` DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;quit;
# mysql -u root -p wifi_stats < old_exported_wifi_stats.sql
wifi_stats.sql (right-click to download, remove the .txt) schema and use it to create an empty database:# mysql -u root -p wifi_stats < wifi_stats.sql
wifi_stats.php (right-click to download, remove the .txt), edit to enter your own login credentials, and copy to /var/www/. Download DHCPd-parse.php (right-click to download, remove the .txt) and also copy to /var/www/. You can look at your collected stats at http://YOUR-SERVER-IP-ADDRESS-OR-URL/wifi_stats.phpreportdhcp.pl (right-click to download, remove the .txt) to /usr/lib/cgi-bin/. This program isn't actually used for any of the stats collection, but it can be useful in troubleshooting. Access it from http://YOUR-SERVER-IP-ADDRESS-OR-URL/cgi-bin/reportdhcp.pl.1 * * * * wget http://localhost/DHCPd-parse.php -O /dev/null > /dev/null 2>&1 1 * * * * /etc/init.d/dansguardian1 restart 1 * * * * /etc/init.d/dansguardian2 restart 1 * * * * /etc/init.d/dansguardian3 restart
/etc/default/apcupsd and change "no" to "yes".# mv /etc/apcupsd/apcupsd.conf /etc/apcupsd/apcupsd.conf.bak
/etc/apcupsd/apcupsd.conf with the following content (this is for our UPSes, yours is probably different):UPSCABLE usb UPSTYPE usb DEVICE LOCKFILE /var/lock SCRIPTDIR /etc/apcupsd PWRFAILDIR /etc/apcupsd NOLOGINDIR /etc ONBATTERYDELAY 6 BATTERYLEVEL 5 MINUTES 3 TIMEOUT 60 ANNOY 0 ANNOYDELAY 10 NOLOGON disable KILLDELAY 0 NETSERVER on NISIP 127.0.0.1 NISPORT 3551 EVENTSFILE /var/log/apcupsd.events EVENTSFILEMAX 10 UPSCLASS standalone UPSMODE disable STATTIME 0 STATFILE /var/log/apcupsd.status LOGSTATS off DATATIME 0
And that is all! Reboot and make sure everything comes back up the way it should.