DansGuardian Documentation Wiki

You are here: Main Index » filter_groups_configurations


|

Wiki Information

Configuring With Multiple Filter Groups

This document describes various ways to inter-relate the configuration lists for easier maintenance of Multiple Filter Groups. If you wish instead to just let a program do most of the right things, just use the “Set Up Lists&Configs For Multiple Filter Groups” tool in the DansGuardian (Webmin) GUI.
(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].)

This documentation is for the DansGuardian 2.9/2.10 series. Some of the suggested options do not work the same way in the 2.8 series.

Which Configuration Files?

DansGuardian comes with a set of pre-supplied configuration files. This default set is correct and complete for the simple case of no multiple filter groups (only filter group f1, with its configuration list files being the “main” ones). The default configuration will work as is, which may be useful for testing. Of course, near the end of the installation process the configuration should be adjusted to operate usefully in your particular environment.

With multiple filter groups though you will probably need to create some additional configuration files, delete some unused files, modify some of the default content inside some of the files, and move some options from one file to another. Depending on how many filter groups you're setting up and how you choose to share or consolidate configuration files, you may need to handle many tens or hundreds of configuration files.

Create new dansguardianfN.conf files as necessary by copying the existing dansguardianf1.conf. One way to create new configuration list files *listfN is by copying the existing *list files. Some more information on configuring for multiple filter groups is in Group Configuration.

Which Option Where?

Most DansGuardian options can go in either the main configuration file dansguardian.conf or in an individual filter group configuration file dansguardianfN.conf. If an option is given in both places, the value in dansguardianfN.conf takes precedence. So the value in dansguardian.conf can be a sort of “system wide default” which is used by most filter groups yet is overridden by a setting in their dansguardianfN.conf for a few filter groups. In the default configuration, options are apportioned to different configuration files for maximum convenience; the default location of each option reflects where it would most likely go in a “typical” configuration. The default apportionment does not imply a restriction or limitation though.

If you find the same option with the same value repeated over and over in every one of your dansguardianfN.conf files, consider moving that option into dansguardian.conf instead. Add it to dansguardian.conf, and delete all the occurrences in the various dansguardianfN.conf. If you find the same option with the same value repeated over and over in most of your dansguardianfN.conf files, consider if it should be treated as a “system wide default”. If so, add it to dansguardian.conf, and delete the identical occurrences in the various dansguardianfN.conf.

Reusing Configuration Files

When deciding “how many filter groups”, support in DansGuardian (up to 99 filter groups) is not a limiting factor. What is often limiting though is the sheer difficulty of maintaining so many configuration files. With multiple filter groups, the number of configuration lists can easily become very large. For example five filter groups –each with their own completely separate set of configuration lists– will total 135 (!) configuration list files; the chances of changing the wrong file by accident may become a serious maintenance issue.

There are several tricks for consolidating some of the configuration files so the total number of configuration list files is lower than you might expect for the number of filter groups. Several different multiple filter group environments are described below, each illustrating the one trick most closely identified with that environment. Using any of these methods to share or consolidate configuration lists will improve performance by reducing memory requirements. The tricks are not mutually exclusive nor are they restricted to the listed environment. It's common to combine several of these tricks to produce a configuration that's most suited to your environment.

(We'll assume throughout that if two filter groups can be “compared”, the more restrictive one will always have the lower number. This convention is consistent with the default filter group f1 being the lowest number and sometimes being used for a group that has no web access at all.)

Reuse Environment 1 (of 5): Nested Filter Groups

Sometimes each filter group is simply a superset of the previous filter group. For example suppose group f1 is students, group f2 is teachers which can see everything students can see plus more, and group f3 is admins which can see everything teachers can see plus more. In this example f2 is a superset of f1, and f3 is a superset of f2. The configuration list files can be set up to capture and take advantage of the superset relationships, so the relationships between the filter groups will always stay correct no matter what.

All the “banned…” (and “urlregexp…” and “weighted…”) files should .Include the corresponding file for the next higher filter group number. And all the “exception…” (and “grey…”) files should .Include the corresponding file for the next lower filter group number.

Although it's in fact very sensible, this trick can present you with several very similar files without giving many hints toward remembering which file is really what. And some versions of Webmin –if used– won't be much help either. So put some comments at the very top of each file that will clearly remind you of which file is really what.

Here's an example of the references to and contents of the “exceptionsitelist…” and “bannedsitelist…” files:

#     dansguardianf1.conf
 ...
groupname = 'Students'
 ...
exceptionsitelist = '/etc/dansguardian/lists/f1/exceptionsitelistf1'
 ...
bannedsitelist = '/etc/dansguardian/lists/f1/bannedsitelistf1'
 ...
#     dansguardianf2.conf
 ...
groupname = 'Teachers'
 ...
exceptionsitelist = '/etc/dansguardian/lists/f2/exceptionsitelistf2'
 ...
bannedsitelist = '/etc/dansguardian/lists/f2/bannedsitelistf2'
 ...
#     dansguardianf3.conf
 ...
groupname = 'Admins'
 ...
exceptionsitelist = '/etc/dansguardian/lists/f3/exceptionsitelistf3'
 ...
bannedsitelist = '/etc/dansguardian/lists/f3/bannedsitelistf3'
 ...
#     exceptionsitelistf1
#
# Exception sites for everybody
# (Exception sites for f1 and higher)
 ...
#     exceptionsitelistf2
#
# Exception sites delta between f2 and f1
# (Exception sites for f2 and higher, but not for f1)
 ...
.Include</etc/dansguardian/lists/f1/exceptionsitelistf1>
 ...
#     exceptionsitelistf3
#
# Exception sites delta between f3 and f2
# (Exception sites for f3, but not for f2 and lower)
 ...
.Include</etc/dansguardian/lists/f2/exceptionsitelistf2>
 ...
#     bannedsitelistf1
#
# Banned sites delta between f2 and f1
# (Exception sites for f1, but not for f2 and higher)
 ...
.Include</etc/dansguardian/lists/f2/bannedsitelistf2>
 ...
#     bannedsitelistf2
#
# Banned sites delta between f3 and f2
# (Banned sites for f2 and lower, but not for f3)
 ...
.Include</etc/dansguardian/lists/f3/bannedsitelistf3>
 ...
#     bannedsitelistf3
#
# Banned sites for everybody
# (Banned sites for f3 and lower)
 ...

Reuse Environment 2 (of 5): Closely Related Filter Groups

Sometimes the filter groups are closely related. In this case it makes sense for all of them to include the same base, then each expand on that base a little differently. For example suppose group f1 is workers, group f2 is managers, and group f3 is executives. They're all part of the same company organization, so it makes sense for all of them to be variants off the same base.

Each individual filter group configuration list should .Include the base. The base is the main configuration lists, so any edit of the main configuration lists changes the base and so shows up in all the individual filter groups.

Here's an example of the references to and contents of the “exceptionsitelist…” files:

#     dansguardian.conf
#
# the "main" or "base" configuration
 ...
# value below is overridden in every individual filter group 
# (all of which in turn .Include this file)
exceptionsitelist = '/etc/dansguardian/lists/exceptionsitelist'
 ...
#     dansguardianf1.conf
 ...
groupname = 'Workers'
 ...
exceptionsitelist = '/etc/dansguardian/lists/f1/exceptionsitelistf1'
 ...
#     dansguardianf2.conf
 ...
groupname = 'Managers'
 ...
exceptionsitelist = '/etc/dansguardian/lists/f2/exceptionsitelistf2'
 ...
#     dansguardianf3.conf
 ...
groupname = 'Executives'
 ...
exceptionsitelist = '/etc/dansguardian/lists/f3/exceptionsitelistf3'
 ...
#     exceptionsitelist
#
# Universal base (or main) included by all filter groups
 ...
#     exceptionsitelistf1
#
# Variations for f1 from shared base
 ...
.Include</etc/dansguardian/lists/exceptionsitelist>
 ...
#     exceptionsitelistf2
#
# Variations for f2 from shared base
 ...
.Include</etc/dansguardian/lists/exceptionsitelist>
 ...
#     exceptionsitelistf3
#
# Variations for f3 from shared base
 ...
.Include</etc/dansguardian/lists/exceptionsitelist>
 ...

Reuse Environment 3 (of 5): Distantly Related Filter Groups

Sometimes the filter groups are only distantly related. It may make sense for each to have their own separate configuration file in some cases, yet all share the same configuration file in other cases. For example suppose group f1 is goths, group f2 is jocks, and group f3 is geeks. For excepted sites they don't have much commonality, so each has their own configuration list file. But they do all share the same URL regular expression list.

Here's an example of the references to and contents of the (example unique) “exceptionsitelist…” files and the (example common) “urlregexplist…” files:

#     dansguardian.conf
 ...
# each filter group has their own of these configurations
#exceptionsitelist = per filtergroup
 ...
# common configurations shared by all filter groups
urlregexplist = '/etc/dansguardian/lists/urlregexplist'
 ...
#     dansguardianf1.conf
 ...
groupname = 'Goths'
 ...
exceptionsitelist = '/etc/dansguardian/lists/f1/exceptionsitelistf1'
 ...
#urlregexplist = common
 ...
#     dansguardianf2.conf
 ...
groupname = 'Jocks'
 ...
exceptionsitelist = '/etc/dansguardian/lists/f2/exceptionsitelistf2'
 ...
#urlregexplist = common
 ...
#     dansguardianf3.conf
 ...
groupname = 'Geeks'
 ...
exceptionsitelist = '/etc/dansguardian/lists/f3/exceptionsitelistf3'
 ...
#urlregexplist = common
 ...
#     urlregexplist
#
# Common list shared by all filter groups
 ...
#     exceptionsitelistf1
#
# Site exceptions for f1
 ...
#     exceptionsitelistf2
#
# Site exceptions for f2
 ...
#     exceptionsitelistf3
#
# Site exceptions for f3 ...
 ...

Reuse Environment 4 (of 5): Forbidden Default Filter Group

It may be desired to have one filter group with no web access at all. If so, use the default group f1 for this purpose so new users will have no web access at all until the system is told about them. For example suppose there are two real groups in addition to the group with no web access at all, so group f1 is unknownAndForbidden, group f2 is children, and group f3 is adults. The easiest way to specify a filter group having no web access at all is with groupmode (rather than arranging particular configuration lists a certain way). (For configuring groups with either “all” or “no” web access with 2.8, see Unfiltered Or Noaccess Groups In The 2.8 Series.)

Here's an example of the references to and contents of the “exceptionsitelist…” files:

#     dansguardianf1.conf
 ...
groupname = 'UnknownAndForbidden'
 ...
groupmode = 0
 ...
#     dansguardianf2.conf
 ...
groupname = 'Children'
 ...
exceptionsitelist = '/etc/dansguardian/lists/f2/exceptionsitelistf2'
 ...
#     dansguardianf3.conf
 ...
groupname = 'Adults'
 ...
exceptionsitelist = '/etc/dansguardian/lists/f3/exceptionsitelistf3'
 ...
#     exceptionsitelistf2
#
# Site exceptions for f2
 ...
#     exceptionsitelistf3
#
# Site exceptions for f3 ...
 ...

Reuse Environment 5 (of 5): Unrelated Filter Groups

Sometimes the filter groups are completely unrelated. For example suppose group f1 is librarians, group f2 is firemen, and group f3 is assessors. (You might think of this as like running multiple copies of DansGuardian that share only your blacklist subscription, and having each user intelligently connected to the right one.)

In this situation it's unavoidable that each filter group will have their own configuration lists, with no sharing or consolidation of configuration files being possible.

Here's an example of the references to and contents of the “exceptionsitelist…” files:

#     dansguardianf1.conf
 ...
groupname = 'Librarians'
 ...
exceptionsitelist = '/etc/dansguardian/lists/f1/exceptionsitelistf1'
 ...
#     dansguardianf2.conf
 ...
groupname = 'Firemen'
 ...
exceptionsitelist = '/etc/dansguardian/lists/f2/exceptionsitelistf2'
 ...
#     dansguardianf3.conf
 ...
groupname = 'Assessors'
 ...
exceptionsitelist = '/etc/dansguardian/lists/f3/exceptionsitelistf3'
 ...
#     exceptionsitelistf1
#
# Site exceptions for f1
 ...
#     exceptionsitelistf2
#
# Site exceptions for f2

 ...
#     exceptionsitelistf3
#
# Site exceptions for f3
 ...

Webmin Configuration

Webmin automatically adjusts for all these configuration variations (although it doesn't “understand” nested configuration files). It reads the same configuration files as DansGuardian itself, so any changes you make for DansGuardian also affect Webmin. To construct a list of files that might be edited, Webmin simply starts at the top (dansguardian.conf for main, or the appropriate dansguardianfN.conf for each filter group) and follows all the uncommented = '/…' and .Include statements.

It's sometimes possible to take advantage of this Webmin behavior by adding configuration lines that modify the behavior of Webmin without modifying the behavior of DansGuardian itself. For example suppose that a grey URL list file applies to filter group f2, but you'd like Webmin to show it as a candidate for editing not only for filter group f2 but also for the main configuration (without changing the behavior of DansGuardian). You can do so simply by adding a line to dansguardian.conf like this:

#     dansguardian.conf
 ...
# following just for Webmin, overridden in each dansguardianfN.conf for DansGuardian 
greyurllist = 'foobarf2'
 ...
#     dansguardianf2.conf
 ...
greyurllist = 'foobarf2'
 ...

(The Webmin DansGuardian Module is changing especially rapidly in the areas of a] multiple filter groups, b] setting the same option in both dansguardian.conf and dansguardianfN.conf, and c] specifying extra lists. A workaround used with a particular version of the Webmin DansGuardian Module may not only fail to work but not even be needed with a different version.)