DansGuardian operation is controlled by several tens of configuration files (largely named …list), only a few of which should be modified for initial installation. Each file contains a different kind of information and serves a different purpose. While a few of the configuration files are heavily used, many others are hardly ever touched.
This guide to initial configuration provides all the details for one step of the Big-Picture Installation Guide, which you should consult for guidance when installing DansGuardian. The default configuration is functional; use it (without modifying it yet) to get to the point where the DansGuardian software is fully operational.
Once the DansGuardian software is operational, modify its configuration to suit your local policies and needs. If it's bewildering to figure out which files your local modifications should go in, just follow this guide. You only need to modify a handful of configuration files; all the rest can remain unchanged.
- In dansguardianf1.conf, change the value of naughtynesslimit = NNN to suit your needs. This one setting has more effect on DansGuardian operation than anything else. The “default” value is probably not suitable; be sure you change it.
- Edit bannedextensionlist. Comment out the lines for types of files that the default would block but which you wish to allow (there may be quite a few). Also un-comment the lines for any types of files that the default would allow but which you wish to block (again there may be quite a few). If you discover a file extension you don't know what to do with, just leave that setting as it is for now.
- For lines that you commented out in 'bannedextensionlist' that correspond to a line in bannedmimetypelist, edit 'bannedmimetypelist' as well and comment out those lines too. Be sure to do this thoroughly: 'bannedextensionlist' and 'bannedmimetypelist' are logically ORed together, and it's assumed there are no inconsistencies between them. (References such as http://www.webmaster-toolkit.com/mime-types.shtml will help you map filename extensions to preferred mimetypes. DansGuardian provides flexibility here because the situation isn't as simple as the references make it appear: sometimes one filename extension really corresponds to more than one mimetype, sometimes “unregistered” mimetypes are in common use as alternates to the preferred one, and sometimes websites use “user-defined” mimetypes.)
- If you wish to force all users to access websites only by their domain name but never by their IP address, edit bannedsitelist and un-comment the two blanket block lines *ip and *ips. (If you're using a blacklist style of operation, it's assumed you already modified 'bannedsitelist' to specify which categories you wish to blacklist.)
- Edit weightedphraselist (this file is particularly important). Un-comment the ”.Include…phraselists…category…” lines for each category you wish to filter out. (If you have problems later, you might then need to comment out some of the lines labelled #ALPHA# or #BETA#.)
Do not simply un-comment all lines in this file; un-commenting everything will almost certainly lead to so many false positives that the system is unusable. Also, try to not un-comment any lines for any language which none of your users can read anyway. Phrase scanning in some other languages is particularly prone to false positives. You can un-comment some such lines later if it becomes clear doing so is necessary.
- Edit urlregexplist. Initially this file contains a lot of commented-out lines that force “safe search” (or “family filter” or whatever it's called) for various search services. If you wish to force “safe search” for a service, un-comment that set of lines. Each un-commented set of lines here may have a measurable impact on performance, so don't un-comment more than you need. (Note although “safe search” has its place, it may not be as important as it first seems, because all result pages will be content-scanned by DansGuardian anyway.)
One of the search services is listed in file 'headerregexplist' instead. Again, edit that file and un-comment that line if you wish to activate it. (Note that it may be possible to get the same effect with another set of lines in 'urlregexplist' instead, but such a set of lines does not exist in the current default configuration.)
For initial installation, you need not make changes to any other ….list files (including those in the 'contentscanners' and 'downloadmanagers' subdirectories).
(The subdirectory /usr/local/etc/dansguardian/lists/blacklists will contain distributed blacklists if you choose to obtain and install them. No files within this subdirectory should be edited. The subdirectory /usr/local/etc/dansguardian/lists/phraselists contains phraselists which are typically distributed along with the DansGuardian software [newer phraselists might be available from http://contentfilter.futuragts.com/phraselists/]. No files within this subdirectory should be edited.)
The question arises how to modify the configuration files. The answer is “it depends”. Specifically, it depends on what distribution you're using, where you obtained DansGuardian, and what additional configuration tools you may have installed. Usually your system will fall into one of these four categories:
Some distributions –SME Server for example– provide their own extensive configuration tools that don't look to you anything like files.
In these cases, you will need to consult instructions for your distribution, as “generic” DansGuardian did not construct the configuration tool and has only the faintest idea how it works or even what it looks like or what terminology it uses.
Some distributions –Ubuntu for example– have their own system-wide recommended way to access and modify application configuration files. These may include a special “administrator” logon, use of the `sudo` command, and so forth. After you get write access to the configuration files, proceed as though you were just using a “raw” distribution.
(The recommended system-wide way to configure applications on these distributions is usually ridiculously easy to circumvent [which doesn't mean you should do so]. In fact, responses from the “generic” DansGuardian mailing list often amount to circumventing the usual restrictions rather than doing it the “right” way …and don't even realize what they're saying. You should consult instructions for your distribution.)
The most common GUI configuration tool for DansGuardian is the Webmin DansGuardian tool from sourceforge.net.
Once it gets down to a specific ….list file, the interface it presents is essentially just editing the plain file. In other words often little or nothing needs to be taken into account even though you're using a GUI configuration tool.
On some systems (CentOS, “generic” DansGuardian, etc.) the main configuration interface is simply directly editing the various configuration files.
All the DansGuardian configuration files are just plain text files, so you can use any text editor program you choose (texted, nano, etc. etc.). Don't look for the editor program that specifically corresponds to these configuration files, as no such thing exists (or even should exist).