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.

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

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.

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

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

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.

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 PerlCGI environment the query parameters are contained in the %in hash.

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

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.

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}).

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.

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.

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.