Help Configuring Dansguardian (Cop+ 3)
The IPCop GUI page for Dansguardian is under the Services - Content Filter menu.
There are 3 basic layers to Dansguardian filtering.
- The first layer is the Blacklists. If a URL is in the blacklists, it isn't retrieved, and the user gets a blocked page. If it's not in the blacklists, Dansguardian asks squid to get it, and then it is inspected by Dansguardian.
- Second, Dansguardian checks the PICs ratings if any are embedded in the web page. There are several different PICs rating systems, which some websites will use to voluntarily rate themselves; I find PICs ratings more annoying than helpful and turn PICs off.
- Lastly, the word filter looks for banned words or phrases in the text on the page and weighted words and phrases. If Dansguardian doesn't find too many bad words or phrases in the page, it is passed on to the user. Banned words will block it immediately, weighted words add or subtract points. If the points for a page add up to more than the "Naughtiness Limit" the page will be blocked.
Understanding the Cop+ GUI
Cop+ is preconfigured to block pornography, adult sites, virus infected, and proxy sites for everyone on your Green and Blue networks. The one thing you should do is download some blacklists using the form at the bottom of the GUI page. Cop+ no longer includes blacklists, and Dansguardian actually does a good job of blocking porn without them, but it's better to have some. If you do nothing, Cop+ will automatically download lists from http://squidguard.mesd.k12.or.us every Monday morning. I recomend you pay for and download the extensive blacklists offered by urlblacklist.com
The copplus setup program gives you a head start on setting up dansguardian with three filter groups. By default only one group is used, but configuration files are included for a second group "ExpandedAccess" and a third group "LimitedAccess."
To enable these extra groups you need to do two things:
1) Set the number of filter groups to 3 (On the dansguardian config page)
2) Edit the filtergroupslist to put some people in group 2 and group 3. Anybody not specifically put in another group defaults to group 1.
The easiest way to assign users to groups is to configure the DHCP server to hand out a fixed lease to a particular machine. This will always give the same IP number to a machine based upon it's MAC address. You can then assign that IP number to filter group 2 or 3 by putting a line in the filtergroupslist like this:
Be aware that in the Dansguardian Config files, any line that starts with a pound sign (#) is a comment, and completely ignored by Dansguardian.
You can also assign a whole subnet to a particular filter group. Suppose you're using your Blue network for guests to get virus updates and MS Windows updates but you don't want to allow regular web browsing from Blue. Assuming my Blue network is IP numberss 192.168.100.1-255, edit the filtergroups list like this:
Enable 3 filtergroups, and make sure your virus updatesites etc. are in the whitelists for group 3, and restart Dansguardian.
For more complicated networks, you can install the advanced proxy addon, and enable one of the "authentication methods." Except for the rather insecure "ident" method, this requires you to turn off the transparent proxy setting, and configure all your client computers to use a proxy server at IPCop's Green IP number, port 8080. Then you can require users to login with a name and password, and dansguardian can sniff the username and assign people to groups based on username, not IP number:
The dansguardianf1.conf file determines access limits for filter group1 (the Default group). dansguardianf2.conf is for group 2, dansguardianf3.conf for group3. Filter group 2 "ExpandedAccess" is configured to block only porn and virusinfected sites, plus it is configured with a different "blocked" page which will allow the users bypass the blocking if they want to. This is intended for people you trust to behave themselves.
Filter group 3 "LimitedAccess" is configured with a "blanket block." Users are blocked from everything except sites you explicitly put in the greysitelist3 or exceptionsitelist list.
Filter groups 2 and 3 have their own bannedsitelists and greylists but they use the same whitelists and phraselists as the default group1. If this is more complexity than you need, you can, for instance, configure them to use the same greylists as group 1. This will save RAM in your IPCop and simplify maintenance for you, the administrator.
If this setup doesn't suit your needs, you have complete control over the configuration of each group by clicking on this icon to edit the main group configuration file.
Use caution,as misconfigurations such as refering to a file that doesn't exist will keep Dansguardian from starting up.
To help get you started, the settings I edited to make groups 2 and 3 different were:
- groupname = ...
- bannedsitelist = ...
- greysitelist = ...
- bannedurllist = ...
- greyurllist = ...
- naughtynesslimit = ...
- bypass = ...
- htmltemplate = ...
The GUI doesn't support it, but you can create more than 3 groups if you manually copy and edit files with WinSCP. Be aware you'll need more RAM in your IPCop box to support more groups. The main config files are in /etc/dansguardian. Make a copy of dansguardianf1.conf and name it dansguardianf4.conf to create a 4th group. All the other config files are in /etc/dansguardian/lists. If you need to, you can make a slightly different replica of any of these files and refer to them in dansguardianf4.conf etc. The possibilities are endless.
More helpful information on Dansguardian Filter Group setup is here:
In fact there's lots of other great help on the Dansguardian wiki:
You can get the Advance Proxy IPCop addon here:
The blacklists are downloaded and overwritten every week and include lots of separate lists for different categories, but not all the categories are blocked. Each filter group has two "master control" blacklist files which tell dansguardian which blacklists to use. One lists "domains," the other specific URLs. These are kept permanently on IPCop and don't get overwritten each week. You can edit them by clicking on one of the black face icons.
By editing these two files, you control which blacklists are actually used. Remove the "#" from the beginning of one of the ".Include..." lines to include the list category it refers to. The default installation blocks sites in the "adult," "porn," "redirector," "proxy" and "virus infected" lists. (Redirector and proxy sites are blocked since they could be used to bypass Dansguardian's filtering.) If you add a url directly to either of these files, it's permanently blacklisted.
Note that none of the lists referred to actually exist when you first install Cop+. This is a problem because if you refer to a list that doesn't exist, dansguardian silently refuses to start. The GUI attempts to create an empty list if one you refer to isn't there, but I suppose it's not completely foolproof. Even after you've downloaded some blacklists, some of the categories in the config files may not exist, depending on who supplies your lists. If you get your blacklists from urlblacklist.com, they all will be there.
All this to say, if Dansguardian refuses to start, try undoing any edits you've made to these ".Include" lines.
Greylists are your primary way of unblocking a site or domain.
Sometimes a site or whole domain appears in the blacklists that you want to allow access to. For instance myspace.com is in there. If you edit it out of the blacklists, it'll just come back next week when you get new blacklists. What you want to do is add it to one of the greylists. This has the affect of permanently removing the site or url from the blacklists, BUT the word filter still applies. On my home network I've put myspace.com in the "Grey site (domain) list file". You could alternately put only certain subsections of myspace.com into the "Grey URL list file"
Ideally, what you'd like to do in cases like this is strip myspace.com from the domain blacklist, but leave specific "bad" sections of myspace in the url blacklist. (Cop+ 3 gives you the ability to do this by editing the "noblacklist" file. Put myspace.com in the noblacklist file and wait till the next time you download blacklists. The downloader script will strip myspace.com from all the "domain" blacklists. After that you won't need myspace.com from the domain greylist anymore.)
There are some words that are outright banned. If they appear even once, the page is blocked. These words are in the "Banned phrase list file" and the "Banned regular expression list file".
There are other words and phrases that are allowed occasionally. They are given a number and a tally is kept for the page. If the tally for a page exceeds the "naughtyness limit" number, the page is blocked. There are even "good words" which have a negative value so they offset the bad words. This helps Dansguardian to distinguish between a medical site and a porn site. It sort-of works, sometimes. All this is controlled by the "Weighted phrase list file", the "Exception Phrase list file" and the "Naughtyness limit" You can enable the lists for languages other than english if that is appropriate you your location. You can also add to or modify these lists if you're adventurous, but I never touch them.
Whitelists are your sledgehammer for unblocking a site.
Put a domain in the "Exception site (domain) list file" if you're sure you want to allow anything inside that domain through. For instance, we've got symantec.com whitelisted. Less risky is putting a subsite in the "Exception URL list file". To allow me to read the dansguardian yahoo group mail, I had to put in tech.groups.yahoo.com/group/dansguardian/
Although the GUI has six hyperlinks for configuring the whitelists, they all point back to the same two files, which is probably what most people will want. If you actually DO want to maintain a different set of whitelists for filter group 3, edit the filter group 3 config file, and change the following two lines:
exceptionsitelist = '/etc/dansguardian/lists/exceptionsitelist' exceptionurllist = '/etc/dansguardian/lists/exceptionurllist'
exceptionsitelist = '/etc/dansguardian/lists/exceptionsitelist3' exceptionurllist = '/etc/dansguardian/lists/exceptionurllist3'
After that the Group 3 Whitelist links will point to these new files, and you can edit them to make them different than Group 1
People get pretty emotional about blocked pages; reassure them you're there to help and the computer sometimes makes mistakes. Figuring out why it was blocked will help you to unblock it. You can change the wording on the blocked page if you want. Follow the "Edit the blocked page template" link. You should put in the real name and phone number of the content filter administrator (you) and/or your e-mail address so folks know who to contact to get a page unblocked.
Both the blocked page put up by Dansguardian and the Dansguardian log file will tell you why a page was blocked. If a site is blocked because it's in a blacklist, it will say "Banned Site: blabla.com". If the PICs rating isn't allowed it says something like "PICs labeling exceeded" If the word filter blocks a page they'll get a blocked page saying something like "weighted phrase limit exceeded". In this last case greylisting won't help, you'll have to whitelist the site to let it through.
Rarely you might see something like "Banned regular expression URL" which means there was a bad word in the URL itself, so Dansguardian didn't even try and get the page.
Other possibilities are "banned file extension" or "banned MIME type." These are off by default, but you can block downloading of, for instance, mp3 files, or other audio or video file types to conserve bandwidth.
If you think Cop+ is interfering with some application, your first step should be to look in the dansguardian logs for *denied* requests when you run your application. Dansguardian only gets involved if your application is using port 80, (also port 443 if transparent proxy is turned off).
Dansguardian logs everything it's blocking except sites that are in the ads blacklists, to prevent filling up the logs. You can enable the logging of ad blocks in the content filter "Advanced Configuration Options" page.
Some applications don't work correctly when going through a transparent proxy. It might help to configure your application to use a proxy server at IPCop's IP number, port 8080. You can do this with any web browser or web app, whether or not "transparent" is set on the IPCop services - proxy GUI page.
Denied means the page was not delivered to the user, EXCEPTION means dansguardian would have denied a page, but it didn't (it delivered it) because you, the admin, had configured an exception. Either:
You have whitelisted a site that would have been blocked. i.e. you put the site in the Exception site (domain) list file or the Exception URL list file.
It means you have put the user's machine's ip number in the Exception IP list file or the Exception user list fileand that user went to a site that would have normally been banned. (This is a feature that allows you to configure a particular machine on your network to get past dansguardian for administrative reasons. Like checking up on if a blocked page really should be allowed.)