DansGuardian Documentation Wiki

You are here: Main Index » bypassing_dansguardian


Wiki Information

Bypassing DansGuardian

Bypasses are devices that allow some people to dash from point A to point B very fast while other people dash form point B to point A very fast. People living at point C, being a point directly in between, are often given to wonder what's so great about point A that so many people from point B are so keen to get there, and what's so great about point B that so many people from point A are so keen to get there. They often wish that people would just once and for all decide where the hell they wanted to be.
“The Hitchhiker's Guide to the Galaxy”, Douglas Adams

Stated Problem

Commonly asked questions with DansGuardian include:

  • How can I have some users bypass DansGuardian?
  • How can I allow bypass of DansGuardian, but only with a password?
  • Only some of my users should have their web access filtered. How do I serve the rest?
  • I just installed DansGuardian, and my users are now upset. How can I turn it off for some people?
  • This DansGuardian thing is too good! Can I keep it in reserve to use only when it's really necessary?

:!: The usual meaning of “bypassing DansGuardian” is disabling filtering. If instead you mean letting the browser and the server communicate as though DansGuardian wasn't even there, there's no way to do this from inside DansGuardian. If your problem does not result in a DansGuardian “access denied” message, listing the site in 'exceptionsitelist' won't help.

Fleshing Out the Problem Definition

To advise on the problem, it's useful to know a little more about it. (You might even think of this as “refining” the problem description.)

  1. Do you really want differing degrees of filtering for various classes of users? Or do you really just want “all” filtering vs. “no” filtering?
  2. Do you want to make future expansion of DansGuardian easier? Or is your only concern resolving the current issue?
  3. In your environment is it sufficient to identify computers (by static IP address)? Or do you need to identify individual people (by username)?
  4. Is your configuration of the “transparent-intercepting” family, or of the “explicit-proxy” family? (If you don't understand this question, see Two Configuration Families.)
  5. Are you trying to solve a technical problem? Or do you really have a political problem (and a technical solution is just your preferred hammer)?
  6. Will you not worry too much if there are potential holes for skipping around your filter (maybe you have “cooperative” or “honorable” users, or maybe a bit of cheating doesn't matter very much)? Or do you need to plug all holes so nobody can skip around your filter no matter what?


Political Issues

If your users were accustomed to a previously unfiltered environment, and you introduced DansGuardian abruptly, your users may be very upset. Figure out clearly what problem you're trying to solve, and communicate upper level management fiats (or at least support) to your users. Communicate with your users voluminously and well in advance. If you still have issues, try reading a psychology book or talking to a bartender; this document focuses on technical problems and solutions and doesn't provide more detailed political advice even though that may be what you really need.

Be warned though that attempting technical solutions to political problems has a very mixed record.

Different Kinds of "Bypassing"

One definition of “bypassing DansGuardian” is to eliminate filtering. That's the definition this document uses. That's what listing the site in 'exceptionsitelist' does.

A different definition of “bypassing DansGuardian” is to pass packets between the web browser and the remote web server as though DansGuardian weren't even there. There is no way to do this from inside DansGuardian. This is not what listing the site in 'exceptionsitelist' does. Completely circumventing DansGuardian can only be done with some other tool such as IPtables. These methods of circumventing DansGuardian entirely of course also have the effect of eliminating filtering.

Technical Solutions That Don't Work

“usernames” is just one part of the 'multiple filter groups' feature. Attempting to use “usernames” for any purpose in DansGuardian without fully setting up 'multiple filter groups' won't help. If you're lucky it won't do anything at all; if you're unlucky it might create an additional problem.

Technical Solutions That Do Work

(Often there are additional technical solutions outside DansGuardian that also can work. Usually these involve either IPtables/Shorewall or browser proxy settings. Such techniques allow a session to completely circumvent DansGuardian, not just to eliminate filtering. So long as your goal is simply to eliminate filtering, these methods don't provide significant additional functionality beyond what the simpler methods inside DansGuardian provide. So they're not discussed further here.)

Option 1 (of 3) - Quick and Dirty Solution

You can only do this if the details of your problem description allow you to provide access to computers rather than to people and if your end user computer IP Addresses don't change. (This is probably true if each end user computer has a static IP Address and you can clearly say whether it should be 'filtered' or 'unfiltered'.)

Just add the IP Addresses of the computers that should bypass filtering to the DansGuardian configuration file 'exceptioniplist' (and restart DansGuardian to make the change take effect).

The above quick and dirty solution will make it more difficult to move to “some filtering” later. This use of exceptioniplist is incompatible with multiple filter groups. When you later move to multiple filter groups, you will need to undo this.

Option 2 (of 3) - Clean Solution

Do only a minimal setup of the DansGuardian 'multiple filter groups' feature. Have only two filter groups; make f1 filtered and f2 unfiltered. (This way any unknown users will default to filtered web access until you update your configuration as necessary.)

Use the simplest "auth" method you can: Ident if you're not overly concerned about hacker users “cheating”, IP if addresses are unchanging. Using either of these “auth” methods will make setup simpler as they do not require any assistance from the local proxy (probably Squid).

Option 3 (of 3) - Thorough Solution

If any of the items below apply, you should proceed to fully set up the DansGuardian 'multiple filter groups' feature. (Attempting some sort of “shortcut” to “bypass” DansGuardian web filtering is likely to just cause more problems.) Any one of these indications suggests a need to fully implement 'multiple filter groups':

  • You have realized while refining your problem description that you really want different levels of filtering for different classes of users, not just 'totally filtered' and 'completely unfiltered' web access.
  • Although just 'filtered' and 'unfiltered' access is all you really need right now, you can reasonably expect additional levels of filtering to be useful in the future.
  • Control of levels of web filtering must be by the individual person, access control by computer isn't good enough.
  • You can't use either Ident or IP authentication, partly because the IP addresses of computers may change as they're not “static”.

Requiring Password For Bypass - Details

A common question is how to set up DansGuardian so that it's possible to “bypass” the filter, but only for one (or a few) webpage(s) at a time for each user and protected by a password. In earlier versions the recommended strategy involved a CGI script. But that method, although the best available at the time, had significant drawbacks, including:

  • Users had to respond to the password mechanism every time they wanted to visit a denied page, rather than just once when their web session began.
  • Implementation typically required some programming skills, as both a web server and a CGI script had to be set up, often including customization to the local environment.

The CGI solution almost always specified just one password for everyone, which brought many additional drawbacks:

  • As inadvertent disclosure is quite likely when lots of people use the same password, undesired access is typically rampant.
  • Misbehavior of just one user (for example “posting” the password) affects all users, including all those that played by the rules.
  • Revoking bypass privileges is very difficult, as it doesn't work very well to command a user to “forget the password”.
  • One way to address many problems is with frequent changes of the password. But then users often forget the most recent password and the support mechanism becomes clogged with “the password doesn't work”.

A newer strategy based on “multiple filter groups” does a better job of handling password-protected bypass access (and does not in any way involve any CGI script). This significantly different methodology answers the same goals; it's equivalent or better. At the time of “bypass”, nothing more than a “click to acknowledge” is required, even though the newer method is overall more secure. And rather than relying on some users not knowing a password, with this strategy users who aren't allowed to bypass never even see the option. As setup involves a few more steps besides just the generic setup of multiple filter groups, we'll outline all the steps here.

Initially set up multiple filter groups, using whichever one of DansGuardian's "auth" mechanisms best identifies individuals in your environment. Choose any number of filter groups to satisfy your other needs too; at minimum just for this purpose you probably want something like f1=unknown, f2=filtered, and f3=withbypass. Usually choose an auth method that identifies people rather than machines, perhaps even one that works invisibly like NTLM. So far the net effect will be that every user always identifies themselves with their personal username and password (usually different for each user) when they start a web session. Note well that each individual user has already been identified and has already provided a password, so there's no need to enter a password every single time access to a webpage is denied.

Configure a different “access denied” template for each filter group. In each dansguardianfN.conf, set htmltemplate to a unique value (for example /etc/dansguardian/languages/ukenglish/fN/template.html if in dansguardian.conf languagedir=/etc/dansguardian/languages and language=ukenglish). And create the referenced files, for example (again supposing languagedir=/etc/dansguardian/languages and language=ukenglish in dansguardian.conf):

prompt# cd /etc/dansguardian/languages/ukenglish
prompt# for n in 1 2 3	  #or however many filter groups you've created
prompt#   do
prompt#     mkdir f$n
prompt#     cp template.html f$n/template.html
prompt#   done

In the “access denied” HTML template for the filter group that should be able to bypass filtering (but not for the other filter groups), enable the -BYPASS- option. If you're not familiar with editing HTML you may wish to simply add a paragraph like this after “deemed inappropriate.<br><br>”. (This is one specific example of Template Customization.)

<a href="-BYPASS-">Proceed to view the denied material anyway.</a>. 
(Clicking here will bypass filtering of this material for a few minutes,
but will not affect the filtering of any other user or of other material.)

In the dansguardianfN.conf of the filter group that can bypass, set option bypass=time each bypass remains valid, typically 300 seconds for five minutes. And make sure the default value bypasskey='' is still present.

Finally stop and restart DansGuardian (a soft ”-g” reload is not sufficient).