DansGuardian Documentation Wiki

You are here: Main Index » group_configuration


Wiki Information

Setting Up 'Multiple Filter Groups'

DansGuardian can easily be configured to have multiple filter configurations to provide varying degrees of web filtering to different groups of users. (It's like having lots of DansGuardians in parallel, with each user being intelligently connected to the right one.) For example, this allows you to have one set of filter settings for students and a less strict set of settings for staff.

This document describes how Multiple Filter Groups works and shows you how to configure it step by step. You may find it simpler to just let the “Set Up Lists&Configs For Multiple Filter Groups” tool in the DansGuardian (Webmin) GUI do most of the work.
 (To get the GUI for DansGuardian, first install the Webmin framework, then install the DansGuardian Module. If your distribution doesn't provide packages, you can obtain Webmin from http://www.webmin.com/download.html and the DansGuardian Module from http://sourceforge.net/projects/dgwebminmodule/ [get version 0.7.or later - here the words “devel”, “stable”, “alpha”, and “beta” have different meanings than usual].)

If you just want your user individuals to be identified in your logs, but don't want a full “Multiple Filter Groups” configuration, you can do that too by performing only a few of the steps described below and skipping most things. For further information see Setting Up Identity Logging.

From some older release notes:

As of version, DansGuardian supports up to 99 different filter groups.
Added filter group support so different filtering settings can be used for different groups of users. Added inteligent list managing so that if different filter groups use the same file they will share one copy of it. It also means it does not need to read in two copies.

:!: This document includes quite a few sections about various special cases (guest computers, kiosk computers, Windows AD groups, etc.). As a result, it can appear longer and more complex than it really is. Just ignore all the sections that aren't relevant to your situation.

:!: Almost all of this document applies to 2.8 as well as 2.10. The few parts that are 2.10-only are specifically noted within those sections, and directions for equivalent 2.8 configurations are given in each case.

Concise Description

Basically all you need to do is the following:

  1. modify the filtergroups setting in dansguardian.conf to reflect how many groups you have
  2. duplicate the dansguardianf1.conf file to dansguardianf2.conf etc for the different groups you're creating (if necessary use chown/chgrp/chmod to give the newly copied files the same owership and permissions as the existing dansguardianf1.conf)
  3. Adjust the settings in the subsequent dansguardianf(x).conf files to reflect the settings each group should have
  4. Add your usernames to the filtergroupslist file (or your IP addresses to the authplugins/ipgroups file)

Configuring the number of filter groups

You configure the number of filter groups in the dansguardian.conf file as you can see below. Keep in mind that the more filter groups you have running, the more memory and processing resources DansGuardian will require.

Here is the excerpt from the dansguardian.conf file

# Filter groups options
# filtergroups sets the number of filter groups. A filter group is a set of content
# filtering options you can apply to a group of users.  The value must be 1 or more.
# DansGuardian will automatically look for dansguardianfN.conf where N is the filter
# group.  To assign users to groups use the filtergroupslist option.  All users default
# to filter group 1.  You must have some sort of authentication to be able to map users
# to a group.  The more filter groups the more copies of the lists will be in RAM so
# use as few as possible.
filtergroups = 2
filtergroupslist = '/etc/dansguardian/filtergroupslist'

The default configuration of DansGuardian is without multiple filtergroups. filtergroups is set to only 1, all users are effectively members of group #1, and only the group configuration file dansguardianf1.conf is consulted.

Probably Squid Proxy

DansGuardian is frequently paired with either Tinyproxy or Oops! for use on a single computer or by single users. But for installations that are large enough to use “multiple filter groups”, Squid is usually more appropriate. So as a rule of thumb (but not a hard and fast rule), if you're setting up “multiple filter groups”, consider switching to Squid.

Tinyproxy (and probably other lightweight proxies) cannot request auth credentials. As a result, the three of five potential DansGuardian auth methods that require assistance from the proxy cannot be used. (These same three auth methods can only be used in an “explicit-proxy” environment –not a “transparent-intercepting' environment– even with Squid.)

The remaining two auth methods (Ident and IP) can still be used, but only in environments where each IP address can be traced to only one person at a time (i.e. not multiuser systems and not LTSP).

It's also possible that lightweight proxies will not provide adequate performance for more than a few simultaneous users.

Typically Set Default Group (f1) To No Web Access At All

Don't carry the advice of using fewer groups too far by trying to make the default/f1 filter group do double duty. (The warning about multiple filter groups consuming lots of memory is less true since several filter groups learned how to share a single copy of a file in version 2.7.5.) Filter group …f1… is where DansGuardian dumps all the requests that it can't identify. Don't confuse things by putting something else in here too, inextricably intermixing two separate things.

Often you'll want this default/f1 filter group where unidentified web requests go to have no web access at all (for 2.10 simply groupmode=0 in dansguardianf1.conf - see the directions later in this document for 2.8).

Setting the group filtering settings

Every group must have an appropriate dansguardianfN.conf file assigned to it where N is the number of the specific group. This is where you set the filter settings for each group, ie. the naughtynesslimit setting, which exceptionsitelist file is referenced by the group etc.

Keep in mind the following:

  • Filtergroups can share configuration files to simplify management and reduce resource use
  • You can include the exceptionsitelist file from the filtergroup1 group in the exceptionsitelist file for filtergroup2 by putting an include line in the exceptionsitelist file referenced in the dansguardianf2.conf file like this:
  • One way to keep track of which list file belongs to which filtergroup is to name the list files accordingly. E.g. for the filtergroup2, the conf file is named dansguardianf2.conf and the exceptionsitelist file could be called exceptionsitelistf2.

The main limit on the complexity of a multiple filter groups configuration is your imagination; in fact it's pretty easy to unintentionally create a spaghetti mess. For further guidance on sharing and consolidating multiple filter group configuration files, see Filter Groups Configurations.

Identifying Filter Groups In The Log

Knowing which filter group a request was assigned to can be invaluable during debugging. The filter group name of each request will be included in the log …if it's available.

To be sure it's available, fill in a unique string for groupname='...' in each dansguardianfN.conf configuration file.

The default value is the empty string, which shows up as nothing in the log, which makes debugging more difficult than it need be.

Although multi-word filter group names containing white space are supported, using them might not be a good idea. The white space can make parsing the fields of the log file later more difficult. It may be preferable to jam all the words together with no intervening spaces (or to replace blanks with underscores).

Here's an example with a value filled in for the group name.

# Filter group name
# Used to fill in the -FILTERGROUP- placeholder in the HTML template file and to
# name the group in the access logs
# Defaults to empty string
groupname = 'anonymous'

Sample Filter Group Configuration File

Here is a sample of the most relevant portions of a dansguardianfN.conf file:

# Content filtering files location
bannedphraselist = '/etc/dansguardian/bannedphraselist'
weightedphraselist = '/etc/dansguardian/weightedphraselist'
exceptionphraselist = '/etc/dansguardian/exceptionphraselist'
bannedsitelist = '/etc/dansguardian/bannedsitelist'
greysitelist = '/etc/dansguardian/greysitelist'
exceptionsitelist = '/etc/dansguardian/exceptionsitelist'
bannedurllist = '/etc/dansguardian/bannedurllist'
greyurllist = '/etc/dansguardian/greyurllist'
exceptionurllist = '/etc/dansguardian/exceptionurllist'
bannedregexpurllist = '/etc/dansguardian/bannedregexpurllist'
bannedextensionlist = '/etc/dansguardian/bannedextensionlist'
bannedmimetypelist = '/etc/dansguardian/bannedmimetypelist'
picsfile = /etc/dansguardian/pics.disabled
contentregexplist = '/etc/dansguardian/contentregexplist'
anonregexplist = '/etc/dansguardian/anonregexplist'
exceptionregexpurllist = '/etc/dansguardian/exceptionregexpurllist'
greyregexpurllist = '/etc/dansguardian/greyregexpurllist'

# Filter group name
# Used to fill in the -FILTERGROUP- placeholder in the HTML template file and to
# name the group in the access logs
# Defaults to empty string
groupname = 'GiantKillers'

# Naughtyness limit
# This the limit over which the page will be blocked.  Each weighted phrase is given
# a value either positive or negative and the values added up.  Phrases to do with
# good subjects will have negative values, and bad subjects will have positive
# values.  See the weightedphraselist file for examples.
# As a guide:
# 50 is for young children,  100 for old children,  160 for young adults.
naughtynesslimit = 50

# Temporary Denied Page Bypass
# It provides a link on the denied page to bypass the ban for a few minutes.  To be
# secure it uses a random hashed secret generated at daemon startup.  You define the
# number of seconds the bypass will function for before the deny will appear again.
# 300 = 5 minutes
# 0 = disable ( defaults to 0 )
bypass = 0

# Temporary Denied Page Bypass Secret Key
# Rather than generating a random key you can specify one.  It must be more than 8 chars.
# '' = generate a random one (recommended and default)
# 'Mary had a little lamb.' = an example
# '76b42abc1cd0fdcaf6e943dcbc93b826' = an example
bypasskey = ''

Adding users to specific filter groups

After you have configured the number of filter groups, you need to configure which users are assigned to which filter group configuration.

Keep in mind the following:

  • All users not explicitly listed default to filter1
  • Either usernames or unchanging (probably static) IP addresses can be assigned to groups
  • IP address ranges or subnet masks are only supported in release and beyond; they cannot be used with earlier releases

Here is the excerpt from the filtergroupslist file

# Filter Groups List file for DansGuardian
# Format is <user>=filter<1-n> where 1-n are the groups
# Eg:
# daniel=filter2
# This file is only of use if you have more than 1 filter group

Identifying Users By Username

If you use usernames to sort users into different filter groups, DansGuardian must somehow reliably determine which user is where. DansGuardian generally refers to this information as “authentication” (even though you may think of it more as “identification”).

DansGuardian can obtain this information a variety of different ways depending on its configuration. In general terms, the information is usually obtained by the local proxy, inserted into the HTTP headers, then “sniffed” by DansGuardian. In other words in many cases DansGuardian looks for and uses the information, but does not actually initiate its capture or modify the exchange between the browser and the local proxy.

Earlier it was often necessary to run a sandwich configuration with Squid1↔DansGuardian↔Squid2 to get this information. This is no longer necessary with recent releases of DansGuardian.

This process does not happen by default. You will need to explicitly set up some way for DansGuardian to determine usernames, perhaps Using IDENT for User Identification or Using NTLM for User Identification. (In some cases you may wish to determine computers rather than users, perhaps with something like Using IP Addresses For User Identification.) Most often this involves two things:

  1. Configure the proxy (probably Squid) as necessary to obtain and then check the information (this can be very different for different types of auth, may involve tricky issues because checking passwords is so security conscious, and often requires complex configuration and testing - follow the test procedures recommended by Squid, which usually don't involve DansGuardian or even the all of Squid)
  2. Specify the proper “auth method” lines in dansguardian.conf. (i.e. uncomment one [or occasionally more] of the lines below)
# Auth plugins
# These replace the usernameidmethod* options in previous versions. They
# handle the extraction of client usernames from various sources, such as
# Proxy-Authorisation headers and ident servers, enabling requests to be
# handled according to the settings of the user's filter group.
# Multiple plugins can be specified, and will be queried in order until one
# of them either finds a username or throws an error. For example, if Squid
# is configured with both NTLM and Basic auth enabled, and both the 'proxy-basic
# and 'proxy-ntlm' auth plugins are enabled here, then clients which do not support
# NTLM can fall back to Basic without sacrificing access rights.
# If you do not use multiple filter groups, you need not specify this option.
#authplugin = '/etc/dansguardian/authplugins/proxy-basic.conf'
#authplugin = '/etc/dansguardian/authplugins/proxy-digest.conf'
#authplugin = '/etc/dansguardian/authplugins/proxy-ntlm.conf'
#authplugin = '/etc/dansguardian/authplugins/ident.conf'
#authplugin = '/etc/dansguardian/authplugins/ip.conf'

Identifying Users By Groupname

Remember that in this section we're talking about User Groups (as in Windows AD) as well as filter groups. It's unfortunate that the same word “groups” is used for both things.

A common question, particularly with NTLM authentication or in AD environments, is if it's possible to use the groupname rather than the username to assign each request to the appropriate filter group.

You should extract the user/group/permission information from your authentication system, transform it a little bit, and inject it into DansGuardian very frequently. Make the transformation logic handle your groups, for example “if this user is a member of group X then assign it to filter group f2”. With your group information being automatically injected into DansGuardian like this so frequently, it becomes irrelevant whether DansGuardian uses the groupname directly or indirectly.


The adjunct program that transforms information from your authentication system into DansGuardian is pretty simple. It's typically either a Linux shell script or a Perl script and may be specifically constructed for each site. A sample shell script (which may work for you with little or no modification) is at http://dansguardian.org/downloads/chrisnighswonger/usermap. This sample shell script gets its information either via the net command (which is not part of core Linux; it's usually part of the Samba suite), or from local files. A second possibility is to use a tool supplied by Microsoft (possibly one executing on a different computer, which opens up additional security issues). A third possibility if the information is stored in LDAP is to use ldapsearch. A fourth possibility is to use standard Linux commands such as getent or id, which get their information from any of a variety of places depending on how your /etc/nsswitch is configured.

In all cases -after transforming the information as necessary- the script should write the new information to a new version of /etc/dansguardian/lists/filtergroupslist (save the old version of the file first). Then the script should issue the command dansguardian -g so the new information will take effect.

Once you have such a script, you can schedule it to be executed as often as you like to keep your authentication information closely synchronized. Use the Linux 'cron' facility to schedule automatic frequent execution of the script (every day? every daytime hour? every ten minutes? every five minutes?).

Why Not Direct Groupname?

The NTLM exchange determines the username but not (any of) the groupname(s). Squid copies the available information into HTTP headers, then DansGuardian copies it again out of those same HTTP headers.

This limitation is understandable. It's a little unclear which group membership or how many group memberships NTLM should try to put in the HTTP headers, especially if your end user computers don't all use the same OS (it may not even clear if there's any groupname at all for a particular user). NTLM -like other web auth schemes- has resolved the ambiguity by simply not dealing with any group information at all. And since NTLM doesn't have it, there's no way DansGuardian can copy it.

Direct Groupname Patch

There was a patch to version to directly use groupnames fetched from LDAP. It's not clear either that this patch is applicable to the 2.9/2.10 series or that it's really needed since indirect groupname→username→filtergroup seems to work and to perform quite adequately.

Unfiltered or Noaccess Groups

You may want one (or more) of your groups to be unfiltered (or to have no web access at all). By far the easiest way to do this is to simply set groupmode = 2 in the relevant dansguardianfN.conf file (or groupmode = 0 for no web access at all).

Remember that when DansGuardian can't figure out which group to associate a request with, it defaults that request to group …f1… So if you have a filtered and an unfiltered group, you probably want the filtered group to be …f1… and the unfiltered group to be …f2…, as if the groups were the other way around a new user (or a program error) would dump requests into the unfiltered group (probably not what you want).

Unfiltered Or Noaccess Groups In The 2.8 Series

The groupmode= setting in dansguardianfN.conf is available in the 2.10 series but not in the 2.8 series of DansGuardian. With the 2.8 series, configuration of unfiltered or noaccess groups is less convenient (although still straightforward). To configure a group with “no” access in the 2.8 series, turn on blanket block (**) in bannedsitelist for the group, and ensure all the exception...list files for the group are empty (probably simply by setting each of them to /dev/null). To configure a group with “all” access in the 2.8 series, add a line that says simply .* into exceptionregexpurllist, and ensure all the banned...list files for the group are empty (probably simply by setting each of them to /dev/null).

Common Problems - "auth" no longer failing outright, but...

Until “auth” is completely working, enable the display of -FILTERGROUP- and -RAWFILTERGROUP- in your HTML Template File.

It's common for everything to seem to work, yet all requests always get thrown into the default filter group f1. As filter group f1 often has no web access at all, it's common for everything you try to do to be denied, which can be puzzling and frustrating.

What's really happening is that -despite appearances- “auth” is never actually succeeding. The browser asks you for credentials, you type what you think are valid credentials, there's no error message, but the credentials aren't actually accepted and your request is denied.

This most often happens because of an incomplete Squid configuration (especially for Basic, Digest, or NTLM “auth”). Temporarily abandon any web browser and DansGuardian. Go directly to the Squid test procedures for the type of auth you are using. Usually these will involve executing only the Squid “helper” program rather than all of Squid, and usually they will emit enough debugging information to easily identify the problem. Only after you get the Squid “auth” working right, return to the full complement of sofware (Squid and DansGuardian and browser).

Minimizing Authentication Hassles

There are a few situations where you might not want users to have to type a username/password.

  • A few important yet highly non-technical users (for example a CEO)
  • Access to a few preselected websites (for example internal websites)
  • Important computers in a few special (and physically secure) locations

What NOT To Do

It may seem easy to jump from “don't type a username/password” to “don't authenticate at all”. The Squid configuration can be manipulated to just never request credentials in the first place in these situations. This is not a solution however; the alternative of completely skipping authentication of users from some source computers has several drawbacks, including:

  • Users who skip auth are dumped into filter group f1 just the same as unknown or unprivileged users. Giving special users and unknown users the same treatment is probably not what you want.
  • Operating with a mixture of authenticated and unauthenticated users might uncover some uncommon oddities in DansGuardian.
  • The usernames in the DansGuardian log and on the “access denied” page will sometimes be meaningful but sometimes they'll just be ”-”.
  • Using IPs to identify computers doesn't work reliably in a DHCP environment, and isn't especially secure in any environment. (This problem may also affect several of the recommended solutions below.)

Ways To Minimize Authentication

In general your goal should be to “hide” authentication rather than simply skip it entirely. Once unobvious –or even fake– authentications are made, you can use them to to assign users to different filter groups appropriately.

The choice of which way(s) to minimize authentication is highly dependent on the particulars of the environment, so no general recommendation can be made. Here are some options:

  1. In an all-Windows environment where every user has a login (even if they never use it), use NTLM authentication. When browsers get the request for credentials, they just pass it along to the OS, which answers with the credentials the user used to login with. (This also works with autologin, so you can avoid ever having a user type their username/password at all.)
     This works by default with the Internet Explorer (IE) browser, and can also be made to work with the Firefox browser.
  2. If you have a mixed environment and so can't use NTLM authentication, use Ident authentication instead. It works in mixed environments. On the other hand it's significantly less secure than NTLM and should only be used with caution if you're worried about internal crackers.
  3. Use IP authentication (at least for the computers that should be treated specially even if not for everyone).
  4. Use an add-on for Mozilla and Firefox that remembers and automatically supplies usernames and passwords, such as the Magic Password Generator.

Kiosk Computers

In the common situation of kiosk computers, users will never have a username/password on the network. There are several ways you can fake DansGuardian authentication for them anyway:

  • If all the guest/kiosk users always use the same userid, add that userid to your domain as a “generic” user. When asked for credentials, the browsers will always supply this same userid, which will always be accepted since it's on your list.
  • If you can identify these computers by their IP address (for example all IP addresses in a particular subnet are “guest/kiosk” machines), use a special configuration that uses IP authentication among other things to treat them specially. Enable both NTLM and IP auth in DansGuardian, but use Squid ACLs to request NTLM authentication only from regular computers, and configure the DansGuardian IP auth to allow authentication only to special computers.
  • Modify the Squid authentication helper code to handle these computers. Make the helper always accept whatever username/password is supplied by these computers. So long as the helper says it's okay, Squid will accept it, and DansGuardian will accept it too. The user will appear to be fully authenticated to the web filter, even if the username/password isn't really valid anywhere else.

Guest Computers

Another common situation arises with local logons to guest computers that are not members of your domain, as the local usernames may not correspond to the name you know users by in your domain. You can handle this situation a couple different ways:

  • If all users have a username/password on your domain (only the computer is a guest, not the person), one option is to just let the initial NTLM auto-response fail so a popup appears asking the user to type in their credentials. Then the user should just type their usual username and password on your domain. They will be authenticated using the username your domain knows them by, and everything will then work just as though they were using a computer that was a member of your domain rather than a “guest” computer.
  • Another option –as above– is to modify the Squid NTLM authentication helper program a little bit to okay rather than reject all authentication requests for usernames in domains it doesn't know about. Modify the source code and rebuild the helper program. This will allow all users who use “guest” computers to be known to DansGuardian/Squid by their username on the “guest” computer. If that username doesn't appear anywhere in your configuration, the user will be assigned to default filter group f1.
     (Note this convenience is wildly insecure. If you are significantly concerned about the possibility of a user forcing their assignment to a different filter group and thus gaining illicit privileges, do not do this.)