DansGuardian Documentation Wiki

allowing_a_website

2009-12-11T23:21:54-06:00

"You can't get there from here. "Old Yankee Saying" " Getting There I want to get to website . In some cases I want to go even further, skipping “content filtering” for that website so I always get there without ever seeing “access denied”. How do I do that?

allowing_ip_addresses

2008-11-06T22:19:19-06:00

"‘Tell me not, in mournful numbers, Life is but an empty dream! For the soul is dead that slumbers, and things are not what they seem. ... "“A psalm of life” by Henry Wadsworth Longfellow" " IP Addresses (Rather Than Domain Names) Problematic A few websites use IP addresses rather than DNS names in some of their hyperlinks. (For some reason this is most often seen on webmail websites.)

automatic_proxy_configuration

2009-04-15T22:44:08-06:00

If computers can find and use the web proxy automatically, an "explicit-proxy" configuration can become significantly more convenient. In fact, in some cases there may no longer any reason to use a "transparent-intercepting" configuration. Such a configuration may in fact be possible, using a combination of WPAD and PAC. The first part, WPAD, “Web Proxy Autodiscovery Protocol”, is how the browser locates the proxy configuration. The second part, PAC, “Proxy Auto-Configuration” is what the brow…

big-picture_installation_guide

2010-03-23T22:14:30-06:00

These directions are for installing DansGuardian on a “raw” distribution (such as CentOS) that has no application configuration tools, application preferences, nor default application configurations of its own. Some not-so-raw distributions will have already done some of these steps for you and will combine or hide other steps, making this list appear overlong and irrelevant.

block_messages

2008-11-07T21:47:52-06:00

Banned Site: http://www.website.com The entire website you attempted to visit has been banned. This occurs when the entire website at the domain is known to contain pornography, webmail or another category of blocked sites. http://www.hotmail.com http://www.kazaa.com

bypass_hash_usage

2009-04-29T21:02:31-06:00

:!: DansGuardian's “bypass” functionality works for http: access, but of course not for https: (ssl/tls/443/encrypted) access. Generating and/or processing the hash outboard of DansGuardian doesn't change that; use of CGI reporting is not a way to relax the inability to bypass https: restrictions.

bypassing_dansguardian

2009-10-04T16:35:04-06:00

" 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 w…

capturing_problems

2009-01-06T15:37:01-06:00

Is DansGuardian failing, but you don't know why? And worse, you don't know what information to capture so others can help (or don't know which commands to use to capture it)? Or the system is administered by a helper or a coworker who knows almost nothing about Linux?

command_line_usage

2010-03-17T23:36:56-06:00

DansGuardian usually runs as a system service (daemon), and uses the same standard method of starting, stopping, and restarting as any other system service. Controlling System Services (including DansGuardian) On some Linux distributions the standard method of starting and stopping services is via the command service:

common_problems

2010-05-25T22:26:10-06:00

Common Problems and their Solutions Check the entire documentation portion of this wiki, especially the Filter Usage and Tips section. Also check the Wiki FAQ Allow Traffic Through Firewall/Router A common problem is blocked communications: end user workstations can't communicate with DansGuardian, or DansGuardian can't communicate with its backend proxy (probably Squid), or the DansGuardian filter system can't communicate with the Internet.

configuration_examples

2008-11-06T14:30:20-06:00

Here are some special configurations that have come up in the mailing list. They are preserved here so that hopefully people can make use of them. Grant users access only to sites you explicity allow If you want to have users whitelisted for a few sites, but then block them from everything else you should use the Blanket Block feature. (Whitelisting is often understood to be what “reverse polarity” means, although there are other interpretations of that phrase too.)

configuring_download_managers

2009-06-12T20:54:47-06:00

Configuring Download Managers This document suggests what to configure in some typical cases, but without explaining why. If you want to understand in detail what's happening, or want to configure for a situation that isn't covered here, read How Download Managers Work.

dansguardian_2.9.x

2008-10-25T21:55:39-06:00

This is a test

dansguardian_mailing_list

2009-06-03T22:45:24-06:00

Getting the Most from the DansGuardian Mailing List Why Any Mailing List? Whatever you send to the mailing list address is repeated to every member of the mailing list. You don't have to keep track of who's a member and who's not, and you don't have to deal with lots of email addresses. All you need to do is post one copy of your message to one address (the address of the mailing list). If you look closely at received messages, you can tell they came via an email list. But if you don't look c…

delivering_block_messages

2009-04-10T00:39:53-06:00

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

dg_2.4_detailed_install

2008-12-03T21:17:38-06:00

:!: DansGuardian 2.4.2 Detailed Installation Guide Fri 29th March 2002 - Draft 3 Originally by Daniel Barron, modified by GB Overview This is not a HOWTO. This document is an attempt at detailed installation instructions for DansGuardian 2.4.1. If you just want to get DansGuardian up and running as quickly as possible, you might want to read the brief installation guide.

download_managers

2009-07-08T12:24:00-06:00

Download Managers See * Configuring Download Managers * How Download Managers Work

downloadable_blacklists

2010-03-17T23:54:44-06:00

Introduction One filtering method used by DansGuardian is to check whether the web site being visited is listed in categorized blacklists. These are lists that are generated either automatically by computer programs (robots or spiders) or by humans. Below you'll see a number of lists that are compatible with DansGuardian.

editing

2008-11-03T15:04:07-06:00

While not everyone may be technically inclined and able to assist with programming the DansGuardian software, most would be able to write up or improve documentation. If you are interested in helping maintain this Wiki, please do the following: Send an e-mail to fernand {at} futuragts [dot] com with the following content:

faq

2010-10-22T16:50:30-06:00

The original of this document is stored at http://contentfilter.futuragts.com/wiki/doku.php?id=faq * * * * * (part of DansGuardian installation package typically /usr/local/share/doc/dansguardian/FAQ) :!: These DansGuardian Wiki FAQs were updated in December 2009. They apply to the current 2.10.x.x versions of DansGuardian, which will probably be the only available version for the foreseeable future. …

filter_groups_configurations

2009-06-13T13:30:24-06:00

If you wish instead to just let a program do most of the right things, just use the “Set Up Lists&Configs For Multiple Filter Groups” tool in the DansGuardian (Webmin) GUI. GUI“”“”“”“”

general_troubleshooting_strategies

2009-12-11T16:25:47-06:00

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 leas…

grey...list_or_exception...list

2009-07-09T22:41:15-06:00

"Well, art is art, isn't it? Still, on the other hand, water is water! And east is east and west is west and if you take cranberries and stew them like applesauce they taste much more like prunes than rhubarb does. Now, uh... Now you tell me what you know. "Groucho Marx (1890 - 1977) "

group_configuration

2010-03-23T22:22:07-06:00

You may find it simpler to just let the “Set Up Lists&Configs For Multiple Filter Groups” tool in the DansGuardian (Webmin) GUI do most of the work. GUI“”“”“”“”

how_download_managers_work

2010-03-23T22:16:18-06:00

This document explains in some detail several of the interesting mysteries of how Download Managers operate. In some areas its coverage is quite thorough, yet other areas aren't covered at all. If you want instead to simply configure your system in one of the typical ways, consult Configuring Download Managers instead of this document.

identity_logging

2009-12-17T00:21:05-06:00

Setting Up Identity Logging One part of setting up Multiple Filter Groups is identification of individuals in the logs. Occasionally this identification of individuals in the logs is all you want; you don't need or want Multiple Filter Groups. If this is all you want (assuming you've configured ):

initial_configuration

2010-03-23T22:13:56-06:00

DansGuardian operation is controlled by several tens of configuration files (largely named ...list), only a few of which should be modified for initial installation. Each file contains a different kind of information and serves a different purpose. While a few of the configuration files are heavily used, many others are hardly ever touched.

language_and_encoding_effects_on_phrase_matching

2010-03-23T22:22:52-06:00

"Words calculated to catch everyone may catch no one. "Adlai E. Stevenson Jr." " :!: This describes DansGuardian as it actually is (not necessarily as it could be). After reading this, you might conclude that: * DansGuardian and its defaults and phraselists tend to focus on the Roman alphabet, on very regularly spelled languages such as English, and on simple 8-bit Latin1-style character encodings * nevertheless DansGuardian can also be made to work with virtually any alphabet and …

log_file_analysis

2010-03-17T15:37:47-06:00

Purpose Analyzing the extensive activity log produced by DansGuardian is often very useful. Choosing the “best” log analyzer depends on your purpose. You may want to * produce summaries of your network's activity, or * summmarize the activity of DansGuardian/Squid, or * zero in on the activities of a particular individual at a particular time.

main_index

2010-03-17T00:14:06-06:00

DansGuardian is an active web content filter that filters web sites based on a number of criteria. These include the website URL, words and phrases included in the page, file type, mime type and more. Below you will find an unofficial collection of documentation, FAQs and HowTos that will help in installing, configuring and managing DansGuardian.

more_than_one_auth_method

2010-03-23T22:17:04-06:00

Typical Use Typically only one “auth” method (plugin) should be enabled in DansGuardian. More than one auth plugin can be enabled and the results will be determinate/replicable. But the behavior nay not be what you expect; in fact it might not even be what a human would consider “reasonable”.

network_billboard

2008-12-14T16:29:14-06:00

The Problem Imagine a non-technical kid that gets a new iPhone for Christmas, takes it to school, then starts up the web browser and accesses the web. With a "transparent-intercepting" configuration, web access is likely to work, and even if it doesn't at least a message can be displayed easily. But with a plain old "explicit-proxy" configuration, the web browser may be totally unresponsive, and the kid will have no idea why or what to do about it.

operation_under_netbsd_freebsd_openbsd

2009-12-14T22:26:58-06:00

Operation Under NetBSD/FreeBSD/OpenBSD If your DansGuardian runs under NetBSD/FreeBSD/OpenBSD and operation seems less reliable than it should be, here's some possible fixes. For years there has been a low level but naggingly persistent series of reports that DansGuardian doesn't run as reliably under BSD-derived kernels (NetBSD/FreeBSD/OpenBSD) as it does under Linux. Most users never see any problem at all …but a few unlucky ones do. Occasional failure of a DansGuardian child process may …

other_help_resources

2011-03-09T14:06:08-06:00

Here is a listing of various places you can look for help with DansGuardian implementations. Official DansGuardian * DansGuardian Website * DansGuardian Support Mailing List * FAQ * Documentation * DansGuardian Filtering Process Flow * Alternate Documentation

patches_and_hacks

2010-03-23T22:13:20-06:00

:!: for the 2.8 series :!:source code patchescannot be applied directly to the 2.10 series Introduction There are several community-contributed patches that can be applied to the DansGuardian source prior to compiling the software. These patches add functionality to the current version and if regarded as stable and useful will generally be added to the main DansGuardian distribution in a future release.

pattern_matching

2008-11-07T15:48:22-06:00

What Are Regular Expressions? “Regular expressions” originated in the field of neurophysiology and were originally mathematically codified as “regular sets”. But that interesting factoid is disjoint from the actual computer use of “regular expressions” (in fact most computer “regular expressions” don't even meet the mathematical requirements of “regular sets” any more). Linux (and hence DansGuardian) “regular expressions” are simply an extremely compact (some would say cryptic:-) pattern matchi…

performance_tuning

2010-03-17T23:45:14-06:00

"The hurrier I go, the behinder I get." The performance of a DansGuardian system can be so good the filtering isn't even detectable by users. There's no good reason to put up with much less. Unfortunately the performance of DansGuardian/Squid when first installed may not be anywhere near optimal, so some tuning will often be in order. This document attempts to answer the question: When “tuning” is required, where should one look?

phraselists

2010-02-13T20:17:17-06:00

Phraselists are very easy to edit. Just open the phrase list files in your favourite editor and follow the examples below. (Note though that creating phrase lists for foreign languages can be somewhat arcane. Before attempting to create phrase lists for foreign languages, you should thoroughly understand the material in Language and Encoding Effects on Phrase Matching.)

preventing_skipping_around

2010-04-19T22:45:41-06:00

Both configuration families of DansGuardian (“transparent-intercepting” and “explicit-proxy”) can easily be set up so it's impossible for users to skip around them. But eliminating skipping may not be automatic in either case, and some instructions are a little misleading about configuring a DansGuardian system so it can't be skipped.

products_that_include_dansguardian

2011-03-09T13:54:06-06:00

Commercial These are products that include support of some kind or other. Usually they include DansGuardian within some type of firewall software package to be installed on a PC or they come bundled as part of a security appliance. Software Packages Smoothwall Products website This product is the “day job” of the DansGuardian developer and is the only commercial software using DansGuardian technology that is officially endorsed.

scan_config

2009-05-27T21:54:07-06:00

Scan Config The Squid part of DansGuardian/Squid has an option () to parse or check the configuration without actually doing anything. But there's nothing similar built in to the DansGuardian part. When you attempt to start DansGuardian, some configuration errors will cause it to emit an error message and not start. But many other configuration errors --including misspelled options-- are never detected.

start

2008-11-16T00:11:19-06:00

system_requirements

2008-11-06T15:22:25-06:00

What will you require to run DansGuardian? See below. System Requirements You must already be running a fairly recent distribution of Linux, FreeBSD, OpenBSD, OS-X or Solaris. You also need to have squid running and configured on port 3128. Note that DansGuardian should be able to be compiled to run on any distribution of an *nix operating system.

technology_overview

2010-03-23T22:19:42-06:00

" DSDF (Different Strokes for Different Folks) " -Common Idiom" " DansGuardian is an award winning web content filtering proxy for Linux, FreeBSD/OpenBSD/NetBSD, Mac OS X, HP-UX, and Solaris that uses a web proxy such as Squid to do all the fetching. It uses multiple methods to filter incoming content (not outgoing content).

template_customization

2009-12-05T22:37:46-06:00

The HTML Template File is the most common way of delivering a blocked page message to a user. It delivers a blocked page message quickly and cleanly to all web browsers, and does almost nothing else. It's just regular HTML; there's no special syntax. You can edit it with any text editor.

the_access.log_files

2010-01-30T23:11:44-06:00

The DansGuardian access.log Files What Are Logs Good For? The “access.log” written by DansGuardian contains a wealth of information. There's usually a separate entry for every single request (whether allowed or denied). It includes lots of information about the request, including a detailed explanation of why it was handled the way it was.

two_configuration_families

2010-03-23T22:30:38-06:00

"Two roads diverged in a yellow wood, And sorry I could not travel both And be one traveler, long I stood And looked down one as far as I could ... And that has made all the difference. "“The Road Not Taken” by Robert Frost" " Two Roads Diverged There are two distinct families of DansGuardian configurations: transparent-intercepting, and explicit-proxy. Right up front you need to choose carefully which one you'll use, as there are significant ramifications both now and in the future, and …

user_identification_methods

2010-03-23T23:00:41-06:00

"If you wake up at a different time, in a different place, could you wake up as a different person? "Chuck Palahniuk" " At DansGuardian's core is the idea of treating different people differently. Its umbrella name for this facility is ””.

user_identification_to_ad

2009-06-12T23:13:34-06:00

User Identification To An Active-Directory-Like System NTLM or Kerberos? The Squid NTLM Helper Program has options to allow both the previous NTLM scheme and the newer Kerberos-like scheme, and can switch easily to using either one. However you cannot use Kerberos-like authentication within the NTLM scheme with DansGuardian/Squid. It can work with Squid and the browser so the credentials will be validated, however it cannot be made to work with DansGuardians “Multiple Filter Groups”. …

using_a_debug_version

2009-05-12T17:41:01-06:00

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.

using_blocked_message_delivery_for_other_purposes_too

2009-12-05T22:39:44-06:00

Using Blocked Message Delivery for Other Purposes Too A CGI program that's invoked whenever a page is blocked can do more than just deliver the message to the user. It can also send email, permanently deny web access to users that exceed their daily allotment of page blocks, and so forth. Using additional CGI Program behaviors is most appropriate where some immediate action is required. Where action can wait until the end of the day (for example notify the administrator of a list of susp…

using_ident_for_user_identification

2010-08-31T23:40:22-06:00

Introduction You can use Ident to identify your users based on log in name. This simplifies management so you don't have to go around matching IP addresses to computers. Of course it also allows you to add users to groups based on their username.

using_ip_addresses_for_user_identification

2010-10-14T14:43:34-06:00

Introduction You can use IP Addresses to identify your users and match them to a filtergroup configuration. This is a simple way to quickly authenticate computers without having to set up a complex authentication system. Note that there are some disadvantages to this system:

using_ntlm_for_user_identification

2010-04-04T17:17:14-06:00

Using NTLM for User Identification If you wish to authenticate your users to an NT/Active Directory domain (implemented either with Microsoft products or with OSS replacements such as Samba) using NTLM, here is some detailed information and some instructions that may help you. (You might also wish to authenticate your users to an Active Directory domain using LDAP or Kerberos but not NTLM.)

virus_filtering

2008-11-06T14:28:12-06:00

FIXME

where_to_get_it

2010-10-22T16:24:38-06:00

There are several places to obtain DansGuardian, usually from your distribution's official and unofficial repositories. :!:Make sure you read and agree with the License and Copyright before you download the software. If you are charging for software installation or using this software commercially, then you should pay for a license!

which_version

2010-03-23T22:05:29-06:00

"Time ripens all things... "Miguel de Cervantes" " :!: This article is time sensitive and was last updated near the beginning of 2010. Which Version? DansGuardian follows the convention that versions 2.oddnum.x.x are “development/beta” while 2.evennum.x.x are “stable”. So when 2.9.x.x development “crystallized”, the tip was simply re-christened 2.10 (2.10 is not based on different code and is not discontinuous from 2.9 in some way). Development series are released frequently, typicall…