DansGuardian Documentation Wiki

You are here: Main Index » big-picture_installation_guide


Wiki Information

Big-Picture Installation Guide

These directions are for installing DansGuardian on a “raw” distribution (such as CentOS) that has no application configuration tools, application preferences, nor default application configurations of its own. Some not-so-raw distributions will have already done some of these steps for you and will combine or hide other steps, making this list appear overlong and irrelevant.

Whenever you make any configuration change, be sure to restart the affected software (usually DansGuardian) so the changes are guaranteed to take effect. This applies to so many of the steps below that we don't mention it explicitly over and over. (It can be very confusing –even appearing to not work at all– if you make configuration changes but don't then restart the affected software right away.) Note we're talking about a command something like service dansguardian restart, not about rebooting the whole computer.


Before changing your computer, you should investigate DansGuardian a bit, make a few decisions and collect a little information:

  • Decide how web taffic from browsers should get into DansGuardian. There are two different methods: “transparent-intercepting” and “explicit-proxy”. Each has its own advantages and disadvantage; neither is clearly better in all situations. Make a conscious choice of which configuration family you're going to use.
  • Decide which computer DansGuardian should run on. For filtering a whole network, DansGuardian usually runs as either an additional application on your network firewall computer (just before the ISP modem connection), or by itself on a separate server computer. Often this choice is dictated by whether or not you already have a network firewall computer and by whether or not that computer can absorb yet another significant addition to its load.
  • Decide which web backend (proxy) your DansGuardian will incorporate. The typical choice for systems that filter whole networks is Squid. Typical choices for a single-computer filter are Tinyproxy and Oops!.
  • Identify a test system where you can use a web browser the same way a user would use it. Make sure it can already access the web before doing anything at all with DansGuardian.
     Where DansGuardian is filtering for a whole network, do not attempt to test from a browser running on the same computer as DansGuardian itself. A browser running on the same computer as DansGuardian may behave differently than other user browsers. Worse, it sometimes happens that you'll get a browser running on the same computer as DansGuardian working, but find that browsers on other computers still do not work.
  • Find out what version(s) of DansGuardian (and your chosen web backend: Squid or Tinyproxy or Oops! or etc.) are readily available to you. Look in each of the places listed below, and write down what you find. Then choose which version?, which may dictate where to get it. (In some cases the version your distribution supplies by default may be very old and you will need to replace it with a newer version from the distribution's “test” or “beta” repository or even from an unofficient repository or collection.)
     (Note packages are not available directly from the DansGuardian website. As with most Linux application websites, only source is offered directly there, and source is usually not the most appropriate way to do an installation.) Places to investigate are:
    • already installed on the computer but not yet running
    • the applications were present on distribution media (probably as an “option”) but were not selected for installation initially - they can be added now
    • the distribution's standard repository
    • the distribution's “test” or “beta” repository
    • unofficial repositories and collections such as “Dag Wieers”
  • For use in your tests, identify a “good” website page that can't possibly be objected to, and a “bad” website page that's so egregious it's clear it should be blocked. (Your testing will be much easier if these pages are the “home” or “default” page on their websites.) Always test with these same two webpages; attempting to test with other webpages that you haven't used yet can add complications that you don't need.
     (When testing, always click the browser's “refresh” button so there's no possibility of your viewing something that was already in the browser's cache.)

Start Out

These few steps are all you need to do to get DansGuardian working:

  1. If necessary, locate or fetch packages for DansGuardian (and often also for your chosen web backend: Squid or Tinyproxy or Oops! or …).
  2. Install and activate the packages. If necessary, change squid.conf, dansguardian.conf, and/or dansguardianf1.conf to get it to work. Do not change any of the DansGuardian configuration ….list files yet. Use only the default installed configuration –which is functional– to test that the software is working. Defer all attempts to “tune” the DansGuardian configuration until later. Part of activation is to set up Dansguardian/Squid to restart automatically every reboot.
  3. Make sure traffic from your test browser goes through DansGuardian. Test your “good” page (be sure to click “refresh” so you don't just see what's in the browser's cache) and be sure it displays. Then check that some entries were added to /usr/local/var/log/dansguardian/access.log.
  4. Be sure DansGuardian can block a page. and that when it does so the “access denied” page is diaplayed to the user. Try to browse your “bad” page. Check that the browser displays the “access denied” page to the user. (Do not attempt to customize the “access denied” page yet.)
  5. Implement either a “blacklist”, a “nolist”, or a “whitelist” style of operation.
    • blacklist:
      * Fetch a sample blacklist and install it (see Downloadable Blacklists).
      * Go through file /usr/local/etc/dansguardian/lists/bannedsitelist and un-comment (delete the first column containing an octothorpe '#') the ”.Include…blacklist…category…” lines for each category you want to block outright unconditionally (but of course not all, nor even “most”, categories).
      * Also un-comment each corresponding line in /usr/local/etc/dansguardian/lists/bannedurllist (it's up to you to keep the “blacklist categories” in 'bannedsitelist' and 'bannedurllist' the same) if the line exists.
    • nolist:
      To implement a content-scanning-only mode of operation, you don't need to do anything at all at this point in time.
    • whitelist:
      * In /usr/local/etc/dansguardian/lists/bannedsitelist, un-comment (delete the first column containing an octothorpe '#') the four blanket block lines **, **s, *ip, and *ips.
      * Add at least your “good” test website (your whole list of allowable websites if you have it) to /usr/local/etc/dansguardian/lists/greysitelist.
  6. Minimally tune your “access denied” page. In particular add your contact information, and consider making the reference to DansGuardian just text rather than a hyperlink, so users aren't confused into thinking the DansGuardian website is where they should go for help.
  7. Tune the DansGuardian configuration to your policies and wishes by customizing its Initial Configuration. (This process of changing as necessary all the DansGuardian configuration ….list files and the dansguardianf1.conf may be substantial. That's why it's covered in detail in a separate document.)


Now that DansGuardian is installed and working, you may wish to undertake some of these steps too:

  • Finish tuning your “access denied” page. You may wish to display to users either more or less information about why a page was blocked. And you may wish to change the color scheme.
     See Template Customization for additional help. In any case, keep it real simple. Do not attempt to add any sort of server-side [ex: PHP] or client-side {ex: JavaScript] scripting. And unless you're already very familiar with HTML and websites, do not even attempt to add any pictures (ex: <img…).
  • In some locations, you may need to extend the DansGuardian configuration for a language the default phraselists don't already cover. Preferably simply get a copy of suggested configuration extensions from some other network administrator in your locale. While it's possible, configuring an additional language from scratch yourself (as described in Language and Encoding Effects on Phrase Matching) can be a complex process.
  • If some users on your network use particular applications or websites that cannot easily be made to work right with content filtering, arrange for those accesses to go directly to the web/Internet rather than through DansGuardian. (Getting the DansGuardian configuration exactly right so it works even with such special applications can be quite difficult or even impossible; there's no good reason to expend so much effort for so little payback. For example, any application that uses WebDAV [if you don't know what WebDAV is you don't have it:-] should not go through DansGuardian.)
  • If you want DansGuardian to treat different users differently, investigate setting up multiple filter groups. Among other things, doing this involves setting up some “auth” method to identify users or computers, and partially sharing configuration files. For partially sharing configuration files, you may find configuring with multiple filter groups helpful, or you may wish to obtain the lastest Webmin DansGuardian module from sourceforge.net and have it set up configuration files for multiple filter groups.
  • Lock down use of DansGuardian by extending your system configuration to Preventing Skipping Around. (Do not attempt to do this earlier, especially not as part of your initial DansGuardian installation.)
  • If you're using a “blacklist” style of operation, decide on a mechanism for handling your “local overrides” to the distributed blacklists. It need not be complex. Often simply listing sites you think are okay even though they are blacklisted in 'greysitelist' is a sufficient mechanism.
     Blacklists are typically extremely large (many hundreds of thousands of entries). And there will always be legitimate disagreements over whether certain sites should be blacklisted or not. So trying to get a distributed blacklist to be exactly the way you think it should be is a fool's errand. In most cases, choose some “local override” mechanism other than planning to manually edit the blacklists directly, so your local overrides don't simply get overwritten and lost the next time your blacklists are updated.
  • If you plan to update your blacklists at least once a month, automate the blacklist updating operation so it starts and proceeds unattended and simply notifies you of its results.
  • Implement anti-virus scanning of some files in DansGuardian. Modify the four files in /usr/local/etc/dansguardian/lists/contentscanners/* to control which files are checked for viruses (which is usually different from which files are filtered by content). (DansGuardian 2.10 can anti-virus scan any web content you wish, without having linked-in dependencies on any particular version of any anti-virus tool or requiring any “patch” or special version. See for example references to “ClamAV” in the FAQ.)
  • Implement web file download restrictions in DansGuardian. For relatively simple restrictions such as those described in Configuring Download Managers, just edit 'dansguardianf1.conf' and the two configuration list files /usr/local/etc/dansguardian/lists/{exceptionfilesitelist,exceptionfileurllist}.
     For complex operations and restrictions, you may wish to activate a “downloadmanager” and configure it with the files in /usr/local/etc/dansguardian/lists/downloadmanagers/*. In order to complete configuration for more complex cases, you may need to understand How Download Managers Work.
  • Re-tune your DansGuardian configuration if necessary. For example, after using DansGuardian for a few days, you may find that the list of weighted phrase categories you enabled isn't quite right, and you will have to comment or un-comment a few additional categories. (Sometimes this amounts to nothing more than re-doing your initial configuration now that you understand things better.)
  • If web browser responses are sluggish, or if the additional load generated by DansGuardian turns out to be less acceptable than you had estimated, look into Performance Tuning. Such problems are usually easily resolved.
  • Frequently make ongoing tweaks to the DansGuardian configuration. In some cases a low level of routine maintenance of the DansGuardian configuration will go on forever: for example, you may find a need to modify your 'bannedsitelist' slightly every few days.
  • In a few special cases (not usually, and only if you're a hardcore computer geek), rather than simply commenting or un-commenting whole groups of existing phrase entries, construct your own weighted phrases per phraselist configuration and editing. (Then contribute your work back to the standard phraselists so it can be incorporated in future distributions.)