DansGuardian Documentation Wiki

You are here: Main Index » delivering_block_messages


Wiki Information

Americans will put up with anything provided it doesn't block traffic.
Dan Rather

Behind the Scenes

When a user tries to view a restricted page, instead they see a page that delivers the “blocked” message. DansGuardian provides two different ways of doing this.

You get to choose one method or the other.

Method 1 (of 2): Using an HTML File

The newer method, which is recommended in the vast majority of cases, is to have DansGuardian deliver the “blocked” page in place of the webpage the user requested. When using this method you do not need to deploy dansguardian.pl at all. Choose this option simply by setting reportinglevel = 3.

HTML File Advantages

This method is simple to deploy, partly because it doesn't require running a separate web server (unless you've added images). It's a little faster too (although the times might be too short for a human to notice the difference). And it's adequate for the vast majority of environments.

As a side effect of the way it's implemented, the browser's address bar will display the URL of the webpage the user was trying to visit rather than the URL of the “blocked” message. (In general the browser's address bar is almost impossible to control or fake, but it will be different in this particular case with DansGuardian.)

HTML File Behavior

When the browser requests a webpage, DansGuardian examines that webpage, then delivers something back to the browser. If the webpage wasn't banned, DansGuardian delivers the actual webpage. But if the page was banned, DansGuardian -without notifying the browser in any other way- delivers the “blocked” message page rather than the actual webpage.

DansGuardian can inject quite a bit of variable information into the HTML file, so the message can appear a little differently every time. You can control which injections occur and where by placing a number of special strings within the HTML file.

If you implement any additional processing, it must be done on the client side (i.e. JavaScript), which may entrain browser compatibility problems and be hard to maintain.

HTML File Parameters

The possibly injected variables are noted by the strings -URL-, -REASONGIVEN-, -REASONLOGGED-, -USER-, -IP-, -CATEGORIES-, -HOST-, -BYPASS-, -SERVERIP-, -RAWFILTERGROUP-, and -FILTERGROUP-.

  • -URL- is the original URL, the one of the webpage that was blocked.
  • -REASONGIVEN- and -REASONLOGGED- are DansGuardian's descriptions of why the webpage was blocked. -REASONGIVEN- corresponds to reportinglevel = 1 and -REASONLOGGED- to reportinglevel = 2; -REASONGIVEN- is suitable for presentation to any user, and -REASONLOGGED- is the full reason for the block including the complete pattern that matched and thus possibly displaying a list of proscribed words.
  • -USER- is the username if DansGuardian knows it; in many cases it will simply be blank.
  • -IP- identifies the workstation where the user is and -SERVERIP- identifies the machine DansGuardian is running on; -HOST- is the name of the workstation where the user is if the name as well as the IP address is available.
  • -CATEGORIES- is whatever you entered in #listcategory: "foobar" - often the name of the blacklist directory containing the file that contained the relevant block instruction.
  • -BYPASS- is a combined URL and hash for overriding a block; depending on your environment you may not wish to use it at all. It's presence may be further controlled by the bypass = setting in dansguardianfN.conf.
  • -RAWFILTERGROUP- and -FILTERGROUP- are the number and name respectively of the group DansGuardian associated the request with.
Example of HTML File Use - Password for Bypass

A specific typical use of the HTML File is as part of using "multiple filter groups" to provide password-protected bypass functionality. (Note this is an example of the usefulness of having a different HTML File for each filter group, an option that DansGuardian easily supports.)

Method 2 (of 2): Using a CGI Program

The older method of reporting blocks involves vectoring to a CGI Program running on a separate webserver. This method shouldn't be used indiscriminately.

(The webserver may or may not run on the same machine as DansGuardian in some cases. Note that running a webserver on a firewall itself may be considered an unwarranted security risk.)

A blocked page CGI Program can do more than just deliver the blocked message to the user. The infrastructure for delivering a blocked page message via a CGI Program is also appropriate for taking other immediate actions. (Behaviors that don't require action right this minute –such as delivering a list of suspect URLs to the DansGuardian administrator– may be more appropriately done by a Log File Analysis program.)

CGI Program Advantages

This option is almost infinitely flexible and can handle the weird cases that the HTML File method can't. As the page presented to the user is the result of a program, it can be very different in different cases. And this option provides an easy upgrade path from older versions of DansGuardian.

Computing is done on the server side using a heavier language such as Perl or PHP, rather than on the client side either using a lighter language such as JavaScript or using nothing at all.

CGI Program Behavior

When the browser requests a webpage, DansGuardian examines that webpage, then delivers something back to the browser. If the webpage wasn't banned, DansGuardian delivers the actual webpage. But if the page was banned, DansGuardian -without notifying the browser in any other way- delivers a Location: … HTTP instruction to the browser which tells it where to find the CGI Program that will calculate the answer to its request.

This redirect URL delivered by DansGuardian includes quite a few query parameters. These parameters are accessed using whatever standard method is provided by the host language; for example in the Perl CGI environment the query parameters are contained in the %in hash.

CGI Program Warning: Avoid Loops

With the CGI Program method of delivering “blocked” messages, you must take special care to avoid having the “blocked” page itself go through DansGuardian. Otherwise, horrible looping behavior may occur. The looping behavior may be even worse if either reporting level is set to 2 (full detail) or if Deep URL Analysis is on.

If you see log entries for 'dansguardian.pl', or if you see several log entries each of which seems to contain the previous one and more, this type of loop is probably the cause.

Of course the easiest way to avoid any chance of such loops is to instead use the HTML File method of delivering “blocked” messages.

One way to avoid these loops is to place dansguardian.pl on the same LAN as the end user computers. (You may also need to explicitly turn on a browser option that causes proxy settings to be ignored if the destination address is local.) An alternate way to avoid these loops is to explicitly list the host that provides the “blocked” page as an exception to proxying in each browser's configuration.

Another method is to add the name of the computer that hosts the “blocked” message to the DansGuardian server's 'exceptionsitelist'. [However there's a suspicion this does not work in a few cases (bannediplist? groupmode=0?), so it might not be an alternative after all. Also, some comments suggest (but perhaps wrongly?) you can only use this method if you both a) have a “transparent-intercepting” environment and b) host your “blocked” page on a web server that's not on the same LAN as your end user computers.]

CGI Program Parameters

The full redirection URL delivered by DansGuardian, including query parameters, is (really all one long line, shown broken here for readability)
   accessdeniedaddress?DENIEDURL=...&REASON=...&USER=...&IP=...     &CATEGORIES=...&HOST=...&GBYPASS=...&GIBYPASS=...&HASH=...

   (accessdeniedaddress is typically set to something like   http://yourhost.yourdomain/cgi-bin/dansguardian.pl)

  • DENIEDURL is the URL of the original webpage that was blocked.
  • REASON is the reason DansGuardian blocked the webpage, and may be either suitable for display anywhere if reportinglevel = 1 or may contain the full reason including the banned pattern -thus possibly including a list of proscribed words- if reportinglevel = 2.
  • USER is the user's ID if DansGuardian knows it, but may often be blank.
  • IP is the address of the user's computer that the request originally came from.
  • CATEGORIES is the information from the most relevant #listcategory: "foobar" instruction.
  • HOST may be the name corresponding to the IP of the user's computer, but may not be present if the name is not known.
  • GBYPASS may be the URL for overriding a block, and is often not present.
  • GIBYPASS may be the URL for overriding the result of a failed anti-virus scan, and is often not present.
  • HASH may be extra information to make GBYPASS or GIBYPASS work in a way that can't just be trivially hacked, or may simply be some flags of little relevance.

Comparison of the 2 Methods

The CGI Program supplies the bypass hash as a separate variable, whereas with the HTML File it's integrated into the bypass URL.

Changing whether you wish to display the full or a sanitized reason for the blockage just involves using a different variable (-REASONGIVEN- or -REASONLOGGED-) with the HTML File option, but requires changing a config file setting (reportinglevel =) with the CGI Program option.

The CGI Program option can directly handle bypassing anti-virus results along with everything else. The HTML File option on the other hand cannot handle bypassing anti-virus results and requires switching to the CGI Program option. This is probably because the need for (and wisdom of) overriding the results of anti-virus scanning is uncommon. Several of the variables provided by DansGuardian have slightly different names or contents with the HTML File option and with the CGI Program option. -URL- is the same as DENIEDURL. -REASONGIVEN- is the same as REASON when reportinglevel = 1 and -REASONLOGGED- is the same as REASON when reportinglevel = 2. -BYPASS- is a combination of GBYPASS and HASH. The information in GIBYPASS is only available to the CGI Program option, and the information in -RAWFILTERGROUP- and -FILTERGROUP- is only available to the HTML File option. (If your CGI programs need to know the “group”, simply use a different accessdeniedaddress for each group and infer the group according to which CGI Program was invoked.) The information in -SERVERIP- is initially available to the CGI Program option as an environment variable (probably SERVER_ADDR) rather than a query parameter (with the sample dansguardian.pl it will ultimately appear as something like $in{SERVER_ADDR}).

Special Issues


Including an image on the “blocked” page -even just a logo- is done the same way you'd include any graphic in any other webpage: the final HTML will include an <img src="http://yourwebserver/..."> tag. The src= attribute must point to a real webserver (not to any function inside of DansGuardian), and to do so must be absolute (not relative).

For CGI Programs this is easy, as you can simply reuse the webserver that provided the CGI Program. For HTML Files though you'll now need to provide your own webserver where you didn't need one before. Adding images to the HTML File "blocked" message page is straightforward. (The src= attribute could instead point to a local file://yourlocalimagelocation, if that file exists on every end user computer.)

In summary, graphics on a webpage are always possible, regardless of whether you've chosen the HTML File option or the CGI Program option. But with the HTML File option this simple-sounding enhancement might have a significant cost.

Multiple Groups

If DansGuardian is configured with multiple groups (…f1…, …f2…, etc.), each group can have its own “blocked” message.

More Than One HTML File

In the typical case, all DansGuardian groups use the same “blocked” message file (<configdir>/<languagedir>/<language>/template.html). That one file is used by all the groups (as though it had been repeated).

Using just one “blocked” message for all groups isn't required though. If you want a group to have their own “blocked” message file, set htmltemplate=otherlocation in their dansguardianfN.conf. Copy the template.html file to the other location, and customize it as desired for that group.

Mixing HTML File and CGI Program

In really complicated scenarios, you can even have some groups use a HTML File while other groups use a CGI Program. For those groups that you want to use an HTML File, set recordinglevel = 3 (and maybe also htmltemplate=…) in their dansguardianfN.conf files. For those groups that you want to use a CGI Program, set recordinglevel = 1or2 and accessdeniedaddress= in their dansguardianfN.conf files.