DansGuardian Documentation Wiki

You are here: Main Index » using_a_debug_version


|

Wiki Information

Using "debug" DansGuardian

What's A "debug" Version Good For?

Occasionally a “debug” version of DansGuardian is a necessary diagnostic. Other troubleshooting methods are preferred because they are simpler and easier, but sometimes none of them do the job. The last resort is a “debug” version.

A “debug” version is useful for example for:

  • Unexplained frequent crashes when not even a stack backtrace identifies a resolution.
  • Identifying all the contributors to a weighted phrase score, especially negatively scored “goodphrases” which can be difficult to identify any other way if the total didn't exceed 'naughtynesslimit'.

What Does A "debug" Version Provide?

The output of a “debug” version is very large and not very organized. It's a series of detailed messages about what DansGuardian is doing at each moment. (It does not contain many diagnostic messages nor any explicit identification of a problem.) It will usually give an expert enough information to identify a problem. To use debug output profitably, users will typically have several of:

  • a Computer Science background
  • experience with multitasking
  • familiarity with searching and matching algorithms
  • understanding of how the world wide web uses the HTTP protocol
  • ability to read and follow source code
  • prior experience writing code
  • familiarity with C++
  • fluency with *nix commands such as `grep` and `find`

To others the debug output may just appear to be impenetrable gobbledygook that doesn't help at all. It's quite common that the debug output is of no use to even one person associated with a DansGuardian environment.

Because the debug output is so heavily dependent on context, it's usually only of use to the same person who recreated the problem. It will often not make any sense to anyone else, particularly without a very detailed description of exactly what steps were taken to recreate the problem. Although the output of a “debug” version may very occasionally be requested as an attachment to private email, it's too large and amorphous to be of much use as part of a posting to the mailing list.

Not With Users

If at all possible, a “debug” version should be used either in an isolated testbed or off-hours when a network is completely idle.

Why?

  • A “debug” version often has significantly degraded performance and so may not provide an acceptable level of service to production users.
  • The output of a “debug” version is quite large even in the best of circumstances. If production users use the system at the same time you're testing, the output may become unwieldly.
  • The output of a “debug” version can be rather mysterious even in the best of circumstances. If production users use the system at the same time you're testing, the multiple requests may be so intermixed in the output that you can't even figure out what's going on, let alone identify a problem.

Creating A "debug" Version

To create a “debug” version you must be able to complete a build of DansGuardian. (Some applications have a provision for enabling their debug mode without rebuilding, but DansGuardian is not among them.)

(There's nothing to prevent distributions from offering two DansGuardian packages, one for production and the other [maybe “dansguardian-debug”] containing a pre-built debug executable [or alternatively two verions of the DansGuardian executable in a single package]. But such a thing does not appear to exist at this time. So the only alternative is to build your own.)

What's desired is a version that's exactly the same as the production DansGuardian, differing only in the inclusion of the debug mode. Constructing such a thing only when you need to use it can be frustrating. It makes more sense to create it in advance and keep it ready at hand so you can use it whenever you need to.

Here's a script that creates a debug version that's exactly the same as your production version. Copy this script from here and paste it into a new file named “buildexec.debug” in the DansGuardian source tree in the same directory where “configure” resides.

#!/bin/bash

eval `dansguardian -v | grep 'Built with:' | sed -e 's/Built with:/.\/configure --with-dgdebug/'`
make
# We intentionally do NOT execute `make install`
# Rather we just explicitly copy the executable out of the build tree
DEST=`which dansguardian`
DESTBASE=`basename $DEST`
DESTDIR=`echo $DEST | sed -e "s/$DESTBASE//"`
cp src/dansguardian $DESTDIR/dansguardian.debug

(The mixture of single quotes, double quotes, back quotes, and backslashes [along with pipes and shell variables and an `eval`] may be daunting. And if any of them are off even a little, the script won't work right. To avoid the problems that retyping would inevitably lead to, just copy&paste the script literally.)

Once the script is in place, execute it something like this:

prompt#   # go to wherever your build source directory is, for example
prompt# cd /usr/local/src/dansguardian.1.2.3.4
prompt#   # building may take three or four minutes
prompt#   # and may display several screenfuls of messages 
prompt# ./buildexec.debug

Do not execute make install, neither inside nor outside the script. All you want is building of an executable. You do not want to trigger any sort of configuration operation.

Using The "debug" Version

If at all possible, test either in an isolated testbed or when there's no other activity on the network.

Use: Step One

Stop any production DansGuardian process.

Use: Step Two

Change into a directory that can store a large volume of debug output and that won't interfere in any way with production usage. For example prompt# cd /home/dansguardian.

Use: Step Three

Run the debug version and capture its output in a file. For example prompt# dansguardian.debug >debuglog 2>&1.

Use: Step Four

Go to an end user or test computer (not the computer DansGuardian is running on or a firewall or gateway), and recreate the problem in as few steps as possible.

Use: Step Five

Go back to the computer where DansGuardian is running and stop it by keying “control-C”.

Use: Step Six

Enter the file full of debug output with your favorite text editor (for example prompt# nano debuglog. Use the text editor to

  • display a full screen of the file
  • scroll around in the file
  • scroll to the beginning and the end
  • search for and find things