DansGuardian Documentation Wiki

You are here: Main Index » general_troubleshooting_strategies


Wiki Information

General Troubleshooting

Make sure of the following:

  • that your proxy server is running and that you can access the web through it properly.
  • that your dansguardian.conf file is pointed at the correct port for your proxy configuration.


Before you post messages to the mailing list, please make sure you have researched the available documentation. Especially understand which documentation is current and which refers to an old release, and which presents solutions (or at least options) as opposed to just documenting a problem.

After you understand and have resolved your issue, please consider contributing to this DansGuardian Wiki for the benefit of others with a similar issue.


Tip: Use The Log Fully

As your very first troubleshooting step look at the log! (probably either /usr/local/var/log/dansguardian/access.log or /var/log/dansguardian/access.log, skip over any similarly named Squid stub log). The log includes a wealth of information; it will tell you exactly what happened and why.

If you post a query to the mailing list, if at all possible include a few relevant lines from the log, and please include the exact version of DansGuardian (and probably Squid) you are using too.

The log will tell you things like exactly why a particular page was banned (often for a different reason than you think), what filter group the request was actually associated with (much better than guessing, especially when the problem may involve an incorrect filter group), what the complete URLs looked like (not just which site they referenced), and the names of other sites that are hidden but required by this site (something that happens frequently). There's no need to either “guess” or rely on the mailing list for any of this information.

Avoid these common pitfalls:

  • just one entry -the right one- is the only one that's relevant (actually a sequence of several entries may be relevant)
  • only entries for the sitename I typed in the browser address bar are relevant (actually lots of websites reference other websites under the covers without the user ever knowing it)
  • only DENIED entries are relevant (actually the clue to the problem is sometimes in a previous log entry for a request that seemed to work okay)

Extracting the relevant entries from the log is straightforward. Here's a general description of isolating troubleshooting activity from your logs, with detailed descriptions of four different methods.

(You will have some additional difficulties if your configuration includes anonymizelogs=on. Any one of several techniques can be applied to the problem of using anonymized logs. One of those techiques is simply, when recreating the problem, temporarily set anonymizelogs=off in dansguardian.conf. While logs may need to be anonymized in some production environments, doing so can makesanalyzing problems needlessly difficult; it may work best to temporarily pull back the stricter setting during debugging.

Unblocking sites that reference other sites under the covers is a common problem; but what are the subsidiary sites? The log will tell you. You may wish to refer to Allowing A Website - Figuring Out the Subsidiaries.

Tip: Use The OS's "dmesg" Command

The system/kernel log messages can be quite useful. When DansGuardian either won't start or stops unexpectedly and abruptly, there's probably no message by DansGuardian that explains the situation. But there are often system/kernel messages about DansGuardian that do enlighten.

If an application fails but the kernel and hardware keep working, all the system/kernel messages will be written to disk normally. But when the kernel itself partially fails or the disk has a problem, the messages of interest may not be able to get to the disk and so remain stuck in memory.

Fortunately you can see the system/kernel messages anyway. To see the last group of messages –regardless of whether or not they've been written to disk– execute the  dmesg  command. (Or to capture the messages to your own debug file, maybe on a different disk, execute something like  dmesg > dmesg.out.)

Tip: Separate Distribution from Application

If you rely on your distribution's configuration utilities, you should generally get support for the sorts of questions listed below from your distribution's support channels.

  • upgrading DansGuardian
  • system configuration of DansGuardian
  • interaction between DansGuardian and other applications

The DansGuardian community may not be able to help very much with distribution-specific configuration. In fact, they may not even understand your question. Many configuration utilities are written and maintained by the distributions, and the DansGuardian application community has little knowledge about them (even though they say “DansGuardian” in their title).

Tip: Begin With Working User Web Access

Before installing DansGuardian, make sure every end user system can already surf the web unfiltered. Have all IPtables rules for communication policies, Network Address Translation (NAT), Domain Name System (DNS), Internet connectivity, and non-web services in place and working before you do anything with DansGuardian.

(Although this may seem painfully obvious to some, prudence dictates stating it explicitly. Surprisingly many “DansGuardian” problems have turned out to have nothing at all to do with web filtering, instead just manifesting a problem with unfiltered web access.)

If you start with end user systems that can't reliably surf the web and add a web filter such as DansGuardian, you'll end up with systems that can't reliably surf the web. The difference? Problems will now be much more difficult to analyze and fix.

If DansGuardian doesn't work, and you're not sure that your end user systems reliably surfed the web before you started, back up. Remove DansGuardian from the data path (perhaps undo browser proxy settings, perhaps undo Shorewall/IPtables additions, etc.).

Get unfiltered web access working reliably for every end user system. Lay out a robust network topology (both physical and logical). Provide good name service (DNS) to every system. Make sure all combinations of `ping` and `traceroute` (spelled `tracert` on Windows) work. Every browser should display external web pages (and not from its cache).

Only then add back in DansGuardian web filtering. Deal simply with unfiltered vs. filtered, knowing that your end user systems can otherwise surf the web.

Tip: Restart DansGuardian Often

Whenever you make a change to any configuration file (such as dansguardian.conf), you must restart DansGuardian. Otherwise DansGuardian will continue to run with the old configuration and results will be puzzling and confusing.

When you think about it, this requirement makes sense and isn't different from most other Linux software. However it's very easy -and common- to forget it in the heat of battle troubleshooting a new installation.

Depending on which distribution you're using, either service dansguardian restart or /etc/init.d/dansguardian restart.

(There's another way to do this using a facility inside of DansGuardian itself that may be a little quicker and may seem a little simpler. But while you're troubleshooting and not yet sure that DansGuardian is working right, stick to using the OS's standard capabilities.)

Tip: Pinpoint Startup Problems

DansGuardian emits messages that may be quite helpful when it starts up. When there's a problem, these messages are often your best troubleshooting tool. For example these messages will tell you exactly which config file line has a problem.

However the typical Linux daemon(service) startup (usually either prompt# service dansguardian start or prompt# /etc/init.d/dansguardian start) gobbles up these messages and you never see them. The typical Linux daemon startup captures all the detailed DansGuardian messages and boils them down to simply OK or Failed. This behavior is the right thing to do for production, but it often makes troubleshooting DansGuardian needlessly difficult. It can leave you unnecessarily “guessing” what the problem is.

When troubleshooting the DansGuardian service/daemon failure to start, at a root command prompt execute simply prompt# dansguardian, then examine the detailed messages.

Tip: Which Filter Group?

One of the very useful things the log can tell you is what filter group each request was actually associated with. But the easy availability of this information depends on your configuration. If your filter groups don't have names, then DansGuardian log will so obscure this information you may not be able to find it at all.

The default value for each filter group's name is the empty string, which shows up as nothing in the log, which makes debugging more difficult than it need be, leading to needless and inaccurate guessing.

To be sure filter group information is easily available, fill in a unique string for groupname='...' in each dansguardianfN.conf configuration file. You may for example wish to specify something like groupname = 'anonymous' in dansguardianf1.conf, and some other unique group name in each of your other dansguardianfN.conf files.

Tip: Don't Anonymize Logs When Troubleshooting

Set anonymizelogs=off in “dansguardian.conf” while you're troubleshooting, including while analyzing access to a particular website long after the initial DansGuardian installation has been completed. Even though removing all personally identifying information from the logs might be the appropriate thing to do in production in your environment, it greatly interferes with troubleshooting and so isn't appropriate for non-production environments.

(This is described in more detail in Figuring Out the Subsidiaries.)

Tip: Which Half?

A DansGuardian system is constructed of two quite separate pieces: DansGuardian itself, and a web proxy (likely Squid). During debugging, access the system in the middle where DansGuardian joins the proxy. By doing so you easily split the potential problem area in half and usually find out which half is causing your problem.

(In oder to prevent skipping around, Dansguardian production systems are generally configured so the joint between DansGuardian and its proxy is not accessible to end users. For debugging you may need to temporarily disable or remove your security measure.)

Tip: Don't Lockdown Until It Works

Some of the configurations and strategies recommended for production use make troubleshooting needlessly difficult. Disable lockdown measures while troubleshooting, re-enable them only when you're done.

Tip: Don't Prevent Skipping Around Until It Works

In production you want to prevent users from skipping around the DansGuardian web filter, as described in Preventing Skipping Around. However these measures interfere considerably with troubleshooting a new DansGuardian installation that doesn't yet work right. For example, measures to prevent skipping around prevent your use of the very useful troubleshooting technique of isolating a problem to either one half or the other half of a DansGuardian system .

Get DansGuardian working first, and only then implement measures to prevent skipping around it.


Tool: Checking Configuration Very Carefully

There are quite a few subtle configuration errors which will cause DansGuardian to misbehave, yet will not cause it to emit an error message or refuse to start up. So use this computerized tool to go through your configuration carefully and in detail and inform you of possible problems. Using this tool is somewhat analogous to “use strict” in Perl; it automatically points to and filters out all the simple problems, leaving only the “hard” problems.

Tool: Getting Expert Help

To get someone else to help with a problem, it's often helpful to accurately describe the problem in excruciating detail. Even if you don't know anything about how either DansGuardian or your OS work, this capture tool will make it easy to capture every bit of helpful information in a standardized format. If you can send this description to a person who's trying to help solve your problem it may be very useful. (You might even consider posting the whole captured problem description to the DansGuardian mailing list.)

Tool: Detailed Operation Tracking

Sometimes the only way to track down a really obscure problem is to find out exactly what DansGuardian is doing at a very detailed (almost line by line) level. Once in a while it will be necessary to use a "debug" version of DansGuardian to track down a problem.