DansGuardian Documentation Wiki

You are here: Main Index » initial_configuration


Wiki Information

Table of Contents

Initial Configuration

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.


  1. 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.
  2. 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.
  3. 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.)
  4. 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.)
  5. 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.
  6. 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.)
  7. Edit exceptionregexpurllist. Choose what you want to do with each of Cascading Style Sheet and JavaScript files (either “allow them but only after content scanning”, or “allow them regardless”), and either leave commented or un-comment the corresponding line. Web browser operation via DansGuardian is rather sensitive to both these lines: leaving a line commented out (especially CSS) may cause some web page displays to be garbled; on the other hand un-commenting that line (especially JavaScript) may make some hack attempts easier. (Note that some JavaScript files will escape phrase scanning anyway no matter what you do here, because they use a mimetype such as 'application/javascript' rather than now-officially-obsolete 'text/javascript'.)
  8. You could enable some of the various web content changes that appear as commented out lines in contentregexplist (often nothing in this file is used though). Some of the modifications replace occasional profanities so they never ever appear on displayed webpages, which may be particularly useful with audiences of very young children. Many of the other modifications are either very version specific or extremely conservative, and will break even routine website operation (or at least cause JavaScript to throw bizarre errors). And it's fairly easy to erroneously apply these content modifications to archive files too (.tar, .tar.gz .gzip, .zip, .rar, etc.); such erroneous changes will of course appear as “downloaded file corruption”.

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:

Alternative 1/4: distribution provides fancy application configuration tools

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.

Alternative 2/4: distribution controls access to application configuration files

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.)

Alternative 3/4: a DansGuardian-specific GUI configuration tool

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.

Alternative 4/4: direct manual editing of plain files

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).