DansGuardian Documentation Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== 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.
==== Documentation ====
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 [[Editing|contributing]] to this DansGuardian Wiki for the benefit of others with a similar issue. 
==== Tips ====

== 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 access.log Files#Log Fields|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 [[Allowing A Website#Figuring Out The Subsidiaries: Isolating Activity|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
[[Allowing A Website#Figuring Out Subsidiaries: Using Anonymized Logs|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|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\  <color #351>dmesg</color>\  command. (Or to capture the messages to your own debug file, maybe on a different disk, execute something like\  <color #351>dmesg\ >\ dmesg.out</color>.)

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

<color #666>(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 __un__filtered web access.)</color>

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 <html><span style="font-family: Courier">service&nbsp;dansguardian&nbsp;restart</span></html>
or <html><span style="font-family: Courier">/etc/init.d/dansguardian&nbsp;restart</span></html>.

(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 
<html><span style="font-family: Courier">prompt#&nbsp;service&nbsp;dansguardian&nbsp;start</span></html> 
or <html><span style="font-family: Courier">prompt#&nbsp;/etc/init.d/dansguardian&nbsp;start</span></html>) 
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 <color green>OK</color> or <color red>Failed</color>. 
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 <html><span style="font-family: Courier">prompt#&nbsp;dansguardian</span></html>, 
then examine the detailed messages. 

== Tip: Which Filter Group? ==
One of the very useful things the log can tell you is
[[Group Configuration#Identifying Groups In The Log|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 <html><span style="font-family: Courier">groupname='...'</span></html>
in each <html><span style="font-family: Courier">dansguardianf<i>N</i>.conf</span></html> 
configuration file.
You may for example wish to specify
something like
<html><span style="font-family: Courier">groupname&nbsp;=&nbsp;'anonymous'</span></html>
in dansguardianf1.conf,
and some other unique group name in each of your other
<html><span style="font-family: Courier">dansguardianf<i>N</i>.conf</span></html> files.

== Tip: Don't Anonymize Logs When Troubleshooting ==
Set <html><span style="font-family: Courier">anonymizelogs=off</span></html> 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 
[[Allowing A Website#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 [[Preventing Skipping Around|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 [[#TipWhich Half?|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.

==== Tools ====

== 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 [[Scan Config|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, [[Capturing Problems|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 [[Using A Debug Version|use a "debug" version of DansGuardian]] to track down a problem.
DansGuardian Documentation Wiki

Index

FAQ

Key Topics

Wiki Information
