Difference between revisions of "Dansguardian"

From SME Server
Jump to navigationJump to search
m (Category:Contrib as smeserver-dansguardian is a contrib)
 
(74 intermediate revisions by 14 users not shown)
Line 1: Line 1:
 +
{{Languages}}
 +
== Dansguardian web content filtering ==
 +
{{Level|Medium}}
  
== Dansguardian web content filtering HOWTO install & configure on sme 7.x ==
+
{{Warning box| Dansguardian is deprecated and not available on Koozali SME v10.
 +
There is a fork called e2guardian http://e2guardian.org/cms/index.php and https://github.com/e2guardian }}
  
'''Author: Ray Mitchell - mitchellcpa_AT_yahoo_dot_com_dot_au'''
+
=== Version ===
 +
{{ #smeversion: dansguardian}}
 +
{{ #smeversion: smeserver-dansguardian}}
  
'''Howto Release Date & Version: 11 July 2007 - v7.3'''
+
Also see:
 +
https://wiki.koozali.org/index.php?title=Dansguardian-panel
 +
{{ #smeversion: smeserver-dansguardian-panel}}
  
'''sme server version supported: 7.1.3'''
+
=== Description ===
  
+
Dansguardian is a web content filter, which analyses the actual content of web pages based on many criteria including phrase matching, PICS filtering, URL filtering and lists of banned sites. Each content type is given a score, and when the threshold score is exceeded, access to the web site is blocked. For additional information see http://dansguardian.org
  
==='''Contributors'''===
+
This HOWTO requires command line control to edit configuration files & restart the dansguardian service after configuration changes.
  
Thanks to Stephen Noble at dungog.net for providing rpms & information generally. This HOWTO requires command line control to edit configuration files & restart the dansguardian service after configuration changes.
+
There is a commercial implementation of Dansguardian for sme server which adds a server manager panel to allow GUI control of all Dansguardian functionality & settings, see http://dungog.net/wiki/Dungog-dansguardian
  
Dungog.net sells a commercial implementation of Dansguardian for sme server which adds a server manager panel to allow GUI control of all Dansguardian functionality & settings.
 
  
  
==='''Information'''===
+
===Information===
  
 
To have a proper understanding of how Dansguardian works and the importance of certain configuration settings you should read the detailed installation notes and Manual at the Dansguardian web site http://dansguardian.org
 
To have a proper understanding of how Dansguardian works and the importance of certain configuration settings you should read the detailed installation notes and Manual at the Dansguardian web site http://dansguardian.org
Line 29: Line 36:
 
Mailing list is here: http://tech.groups.yahoo.com/group/dansguardian/
 
Mailing list is here: http://tech.groups.yahoo.com/group/dansguardian/
  
The information on the Dansguardian website is of a generic nature and some of it is NOT applicable to sme server installations, refer to the instructions in this HOWTO in preference.
+
The information on the Dansguardian website and other websites referred to, is of a generic nature and some of it is NOT applicable to sme server installations, refer to the instructions in this HOWTO in preference.
  
==='''Installation instructions'''===
+
===Installation instructions===
  
{{Warning box|Do not upgrade dansguardian v2.9 over previous v2.8 (or earlier) installations as there are substantial changes. (The recommendation from Dansguardian is to edit the new configuration files/lists rather than try to edit your old ones)}}
+
Install dansguardian and it's dependencies from the smecontribs repository
 +
yum --enablerepo=smecontribs install smeserver-dansguardian
  
{{Note box|Please check the dungog.net web site for later versions http://sme.dungog.net/packages/smeserver/7.0/i386/html/index_dungog.html}}
+
Optional, download and install a set of blacklists from http://urlblacklist.com/
 +
alternatively you can choose ftp://ftp.ut-capitole.fr/pub/reseau/cache/squidguard_contrib/blacklists.tar.gz from http://dsi.ut-capitole.fr/blacklists/
  
 +
{{Note box|It is not sufficient to simply install the package, the appropriate manual configuration is an integral part of getting Dansguardian working on your system. A minimal installation requires all the configuration steps listed below to be carried out, ie from the "Modifying Firewall and Proxy" section up to "Filter Groups and Auth login". Filter Group configuration is only required if you wish to control access on a per user basis.}}
 +
 +
{{Tip box|If you would like to have a graphical and web based overview of what dansguardian has analyzed then take a look at http://wiki.contribs.org/Dansguardian-stats}}
  
Download the required rpms into an empty folder on your sme server using the Linux wget command
+
====Upgrading====
 
+
There are substantial changes between dansguardian v2.9 over previous v2.8 (or earlier) installations. The recommendation from dansguardian.org is to edit the new configuration files/lists rather than try to edit your old ones.
wget <nowiki>http://mirror.contribs.org/smeserver/contribs/rmitchell/smeserver/contribs/dansguardian/rpms/2.9.8-2/dansguardian-2.9.8-2.noarch.rpm</nowiki>
 
 
 
wget <nowiki>http://mirror.contribs.org/smeserver/contribs/rmitchell/smeserver/contribs/dansguardian/rpms/2.9.8-2/smeserver-dansguardian-2.9-3.el4.sme.noarch.rpm</nowiki>
 
 
 
wget <nowiki>http://mirror.contribs.org/smeserver/contribs/rmitchell/smeserver/contribs/dansguardian/rpms/2.8.0.6/dungog-blacklists-1.0-20061002.noarch.rpm</nowiki>
 
 
 
Install the rpms
 
 
 
yum localinstall *.rpm
 
 
 
 
 
 
 
Alternatively you can add the dungog repository
 
{{Repository|Dungog}}
 
 
 
yum --enablerepo=dungog install smeserver-dansguardian dungog-blacklists
 
 
 
To view available updates
 
yum --enablerepo=dungog list updates
 
 
 
==='''Modifying Dansguardian configuration'''===
 
 
 
You need to manually modify configuration files  /etc/dansguardian/dansguardian.conf  and  /etc/dansguardian/dansguardianf1.conf  and  /etc/dansguardian/dansguardianf2.conf  and  /etc/dansguardian/dansguardianf3.conf  and so on depending on the number of filter groups you wish to have.
 
 
 
pico -w /etc/dansguardian/dansguardian.conf
 
 
 
You will initially need to change:
 
 
 
accessdeniedaddress = 'http://YOURSERVER.YOURDOMAIN/cgi-bin/dansguardian.pl'
 
 
 
for example to
 
 
 
accessdeniedaddress = 'http://www.mydomain.com/cgi-bin/dansguardian.pl'
 
 
 
Make any other required changes to suit your situation by carefully reviewing the other setting possibilities
 
 
 
Ctrl o (to save)
 
 
 
Ctrl x (to exit)
 
 
 
pico -w /etc/dansguardian/dansguardianf1.conf
 
 
 
You may initially need to change (to suit adult level of protection)
 
 
 
naughtynesslimit = 50
 
 
 
to
 
 
 
naughtynesslimit = 160 (or even 250 or 300 depending on your sensitivity/tolerance requirements)
 
 
 
Make any other required changes to suit your situation by carefully reviewing the other setting possibilities
 
 
 
Ctrl o and Ctrl x
 
 
 
If you wish to use additional filter groups then edit further configuration files.
 
 
 
pico -w /etc/dansguardian/dansguardianf2.conf
 
 
 
Make any required changes to suit your situation by carefully reviewing all the setting possibilities
 
 
 
Ctrl o and Ctrl x
 
 
 
pico -w /etc/dansguardian/dansguardianf3.conf
 
 
 
Make any required changes to suit your situation by carefully reviewing all the setting possibilities
 
 
 
Ctrl o and Ctrl x
 
  
 +
Upgrading from 2.9 versions creates .rpmnew config files under /etc/dansguardian. This preserves your existing config files, but there is a chance that dansguardian won't start if parameters in the config file have changed.
  
==='''Modifying other Dansguardian configuration files'''===
+
Clamav libraries can cause problems when updating. If while updating you see something like
 +
Error: Missing Dependency: libclamav.so.3 is needed by package dansguardian
 +
Update with
 +
yum update --enablerepo=smecontribs dansguardian clamav
 +
then
 +
yum update
  
You will need to change other config files to suit your site requirements:
+
===Modifying Firewall and Proxy===
  
You can read information in the beginning of each config file that explains usage & syntax
+
====Configuring your system to force Dansguardian usage & prevent bypassing====
  
These are located in /etc/dansguardian/lists...  /etc/dansguardian/lists/f1/...  /etc/dansguardian/lists/f2/... & so on and subfolders
+
These instructions assume that the sme server is running in server gateway mode and acting as the gateway for your network, and the squid proxy is running on the same machine that Dansguardian is running on.
  
eg
+
If your server is configured in server only mode, then you will need to point your browser at that machine to find the squid proxy rather than the default gateway.
  
pico -w /etc/dansguardian/lists/f1/bannedextensionlist
+
Dansguardian uses port 8080 for web proxy requests. If your browser does not use port 8080 then Dansguardian filtering will be bypassed. To force this usage & prevent users bypassing filtering you should do ALL the following steps:
  
make the required changes
+
'''1) Configure your SME Server to use Transparent Proxy port 8080 and to block direct access to the squid proxy port 3128 & redirect port 80 to port 8080'''
  
Ctrl o and Ctrl x
+
Note the functionality to create the required custom firewall rules using iptables is built in to the smeserver-dansguardian and is configured with the following commands. The Transparent proxy must also be enabled (which is the sme default) to prevent users bypassing Dansguardian filtering.
 
 
Most users will need to change these 4 files as a minimum
 
 
 
bannedextensionlist
 
 
 
bannedsitelist
 
 
 
bannedurllist
 
 
 
exceptionsitelist
 
 
 
You should review ALL the dansguardian config files in /etc/dansguardian/lists and subfolders  as part of your initial Dansguardian setup.
 
 
 
Some of the default settings in these files will prevent access to certain web sites and file types, which may conflict with your site requirements. See details in the "Further customisation" section at the end of this Howto or at http://dansguardian.org
 
 
 
 
 
==='''Modifying the default html error message page'''===
 
 
 
You may also want to tailor the html template for the error message displayed when Dansguardian blocks a site, see
 
 
 
/etc/dansguardian/languages/(languagename)/template.html
 
 
 
eg
 
 
 
pico -w /etc/dansguardian/languages/ukenglish/template.html
 
 
 
 
 
==='''Starting Dansguardian'''===
 
 
 
After install & initial configuration you must manually start Dansguardian to enable web content filtering
 
 
 
(Note that suitable links to start Dansguardian at startup/reboot are setup when the rpm is installed)
 
 
 
/etc/init.d/dansguardian start
 
 
 
'''Stopping Dansguardian'''
 
 
 
If you need to stop Dansguardian (ie to disable filtering or test your system without Dansguardian running)
 
 
 
/etc/init.d/dansguardian stop
 
 
 
'''Restarting Dansguardian'''
 
 
 
You will need to restart Dansguardian after making any configuration changes (so they can take effect)
 
 
 
/etc/init.d/dansguardian restart
 
 
 
'''Status check of Dansguardian'''
 
 
 
If you need to check that Dansguardian is running
 
 
 
/etc/init.d/dansguardian status
 
 
 
 
 
==='''Configuring your system to force Dansguardian usage & prevent bypassing'''===
 
 
 
Dansguardian uses port 8080 for web proxy requests. If your browser does not use port 8080 then Dansguardian filtering will be bypassed. To force this usage & prevent users bypassing filtering you should do the following steps:
 
 
 
'''1) Configure your sme server to use Transparent Proxy port 8080 and to block direct access to the squid proxy port 3128 & redirect port 80 to port 8080'''
 
 
 
Note the functionality to create custom firewall rules using iptables is built in to the rpms provided by http://www.dungog.net
 
  
 
  config setprop squid TransparentPort 8080
 
  config setprop squid TransparentPort 8080
 +
config setprop squid Transparent yes
 
  config setprop dansguardian portblocking yes
 
  config setprop dansguardian portblocking yes
  signal-event post-upgrade; signal-event-reboot  
+
  signal-event post-upgrade; signal-event reboot
  
To return Transparent Proxy port to default value and to disable portblocking
+
To return Transparent Proxy port to default value and to disable portblocking and to enable the Transparent proxy (which is the sme default)
  
  config delprop squid TransparentPort 3128
+
  config setprop squid TransparentPort 3128
 +
config setprop squid Transparent yes
 
  config delprop dansguardian portblocking
 
  config delprop dansguardian portblocking
  signal-event post-upgrade; signal-event-reboot  
+
  signal-event post-upgrade; signal-event reboot  
 +
 
 +
{{Note box|If you disable the Transparent Proxy feature of SME Server, Dansguardian can be bypassed at will by your users. You should keep the Transparent Proxy enabled (configured as above) for filtering to work.}}
 
   
 
   
 
'''2) Configure your workstation web browser to auto detect proxy port'''
 
'''2) Configure your workstation web browser to auto detect proxy port'''
Line 206: Line 100:
 
Or alternatively use the server IP 192.168.1.1 (or whatever yours is) and use a port of 8080
 
Or alternatively use the server IP 192.168.1.1 (or whatever yours is) and use a port of 8080
  
 +
====Bypass Proxy====
 +
Allow individual PC's or selected sites to bypass the proxy (and dansguardian) entirely see [[Firewall#Bypass_Proxy]].
  
==='''Configuring Dansguardian to use Auth login'''===
+
====Workstation IP allocation====
 +
Control of workstation access to the web (when using dansguardian), is implemented by nominating the workstation IP in the various dansguardian configuration files (ie the local LAN IP address). To apply consistent filtering rules or allow proxy bypass (see section above), the workstation IP must remain the same throughout restarts & DHCP IP refreshes or allocations. Configuring your workstations to have a consistent IP is a fundamental & important step when configuring your whole computer system.
  
This functionality is built in to the rpms provided by http://www.dungog.net & requires enabling with a db command
+
This can be achieved by manually specifying a fixed IP address when each workstation is configured, but requires every workstation to be setup individually. Alternatively the workstation can be configured for auto allocation of an IP, and the Hostnames and Addresses panel in server manager can then be used to force the allocation of a specified IP by the SME DHCP server, based on the workstation NIC mac address. See the SME Manual for further details at http://wiki.contribs.org/SME_Server:Documentation:Administration_Manual:Chapter13#Reserving_IP_Addresses_Through_DHCP
 +
The basic steps are to determine the mac address of your workstation NIC and then create a hostname eg station5 and enter the mac address and the required "forced or fixed" IP eg 192.168.1.5
  
Dansguardian supports different types of auth login ie nsca, pam & ident
+
Any reference to the filtering of station5 then uses the IP 192.168.1.5, which will always stay the same, unless the NIC is changed. Remember to re-enter the mac address details into server manager, in the event the workstation NIC or motherboard is changed.
  
Depending on your requirements, enable using the appropriate command. Most users of sme will probably use pam auth as that will authorise access against sme users and passwords.
+
====Configuring Proxy to use Auth login====
  
For details regarding the various auth login methods & other configuration requirements, see http://dansguardian.org or Google, select one
+
Dansguardian supports different types of auth login ie ncsa, pam & ident, and allows control of web site access based on user name. For more details regarding the various auth login methods & other configuration requirements, see http://dansguardian.org or Google.
  
 +
Enable this functionality using the appropriate command, depending on your requirements. Most users of sme will probably use pam auth as that will authorise access against sme users and passwords.
 +
 +
Choose one of the following
 
  config setprop squid RequireAuth pam
 
  config setprop squid RequireAuth pam
  config setprop squid RequireAuth nsca
+
  config setprop squid RequireAuth ncsa
 
  config setprop squid RequireAuth ident
 
  config setprop squid RequireAuth ident
  
 
To disable Auth login
 
To disable Auth login
 
 
  config delprop squid RequireAuth
 
  config delprop squid RequireAuth
  
To enable any of the above setting changes you must follow the command with:
+
To enable any of the above setting changes you must follow the command with
 
 
 
  expand-template /etc/squid/squid.conf
 
  expand-template /etc/squid/squid.conf
 
  sv t /service/squid
 
  sv t /service/squid
  
If you are using nsca auth, create the user & password authentication list (you don't require users to be valid sme users)
+
====Using NCSA Auth login====
 +
If you are using ncsa auth, create the user & password authentication list (you don't require users to be valid sme users)
  
  touch /home/e-smith/db/proxyusers
+
  touch /etc/proxyusers
  
 
Enter user names & password combinations one by one using this command
 
Enter user names & password combinations one by one using this command
  
htpasswd -b /home/e-smith/db/proxyusers username password
+
htpasswd -b /etc/proxyusers username password
  
 
You can test the authentication list using the following command
 
You can test the authentication list using the following command
  
/usr/lib/squid/ncsa_auth /home/e-smith/db/proxyusers
+
/usr/lib/squid/ncsa_auth /etc/proxyusers
  
 
Then enter the username & password when asked
 
Then enter the username & password when asked
Line 246: Line 146:
 
You will see a ERR or OK response
 
You will see a ERR or OK response
  
If you are using ident auth, you will require a ident client/server on your workstation. One windows ident client is available from:
+
====Using Ident login====
 +
If you are using ident auth, you will require a ident client on your workstation. One windows ident client is available from:
  
 
https://sourceforge.net/projects/retinascan
 
https://sourceforge.net/projects/retinascan
  
 +
In some cases, the Windows firewall blocks access to the ident client and you will have to add an exception in your firewall rules as follows:
  
==='''Groups and Auth login'''===
+
'''Control Panel''' >> '''Windows Firewall''' >> '''Exceptions''' >> '''Add Port'''
  
See http:/dansguardian.org re Group configuration functionality in relation to Auth login (ie filtering users access rights based on group membership)
+
* Name: '''auth'''
 +
* Port number: '''113'''
 +
* '''TCP'''
  
The Group filter files are located in:
+
===Modifying Dansguardian Configuration Files===
  
/etc/dansguardian/lists/f1/...
+
====Modifying Dansguardian dansguardian.conf & dansguardianf1.conf files====
  
/etc/dansguardian/lists/f2/...
+
You need to manually modify various configuration files.
 +
As a minimum the following basic changes need to be made:
  
/etc/dansguardian/lists/f3/...
+
pico -w /etc/dansguardian/dansguardian.conf
  
and so on depending on the number of groups you set up
+
You will initially need to change:
 +
accessdeniedaddress = 'http://YOURSERVER.YOURDOMAIN/cgi-bin/dansguardian.pl'
 +
for example to
 +
accessdeniedaddress = 'http://www.mydomain.com/cgi-bin/dansguardian.pl'
  
Edit these to suit your site requirements
+
Make any other required changes to suit your situation by carefully reviewing the other setting possibilities
  
 +
To save & exit
 +
Ctrl o
 +
Ctrl x
  
<nowiki>*********************************************************************************************</nowiki>
 
  
 +
pico -w /etc/dansguardian/dansguardianf1.conf
  
The following are rough notes re creating additional files & configuration steps needed for multiple filter groups.
+
You may initially need to change (to suit adult level of protection)
 +
naughtynesslimit = 50
 +
to
 +
naughtynesslimit = 160
 +
(or even 250 or 300 depending on your sensitivity/tolerance requirements)
  
This section is a work in progress & will be tidied up later.
+
Make any other required changes to suit your situation by carefully reviewing the other setting possibilities
  
Do not literally use/copy these steps as if they are sme commands as they are not, they are procedural steps to give a brief indication of what is involved.
+
Save & exit
 +
Ctrl o
 +
Ctrl x
  
 +
Additional Options can be found here, http://wiki.contribs.org/Dansguardian/ConfigFiles under the topic dansguardian.conf & dansguardianf1.conf
  
configure pam auth using the db command from howto
+
If you have additional filter groups, then additional configuration files will need to be created and modified. See section on "Filter Groups and Auth login" below.
  
copy /etc/dansguardian/dansguardianf1.conf to /etc/dansguardian/dansguardianf2.conf
+
====Modifying other Dansguardian configuration files====
  
and to a f3 version if required also
+
You will need to change other config files to suit your site requirements:
  
 +
You can read information in the beginning of each config file that explains usage & syntax
  
Copy /etc/dansguardian/list/f1 to /etc/dansguardian/list/f2 including all subfolders and files
+
These are located in
 +
/etc/dansguardian/lists... 
 +
/etc/dansguardian/lists/f2/... 
 +
& so on and subfolders  
  
edit /etc/dansguardian/dansguardianf2.conf and change all instances of f1 to f2 in filename locations
+
eg
 +
pico -w /etc/dansguardian/lists/f2/bannedextensionlist
 +
make the required changes
 +
Ctrl o
 +
Ctrl x
  
 +
Most users will need to change these 4 files as a minimum
 +
bannedextensionlist
 +
bannedsitelist
 +
bannedurllist
 +
exceptionsitelist
  
edit /etc/dansguardian/dansguardian.conf
+
You should review ALL the dansguardian config files in /etc/dansguardian/lists and subfolders  as part of your initial Dansguardian setup.  
  
Filter group options
+
Some of the default settings in these files will prevent access to certain web sites and file types, which may conflict with your site requirements.
  
filtergroups = 2
+
For many more details and descriptions on the configuration files see [[:Dansguardian/ConfigFiles]]  page of this Howto or at http://dansguardian.org
  
or however many filter groups you want to have
+
====Modifying the default html error message page====
  
 +
You may also want to tailor the html template for the error message displayed when Dansguardian blocks a site, see
 +
/etc/dansguardian/languages/(languagename)/template.html
 +
or in some newer versions
 +
/usr/share/dansguardian/languages/(languagename)/template.html
  
Auth plugins
+
e.g.
 +
pico -w /etc/dansguardian/languages/ukenglish/template.html
 +
After you make any changes to the template.html you will need to run the command,
 +
/etc/init.d/dansguardian restart
 +
for the changes to take effect.
  
remove # from in front of
+
====Filter Groups and Auth login====
  
authplugin = '/etc/dansguardian/authplugins/proxy-basic.conf'
+
Dansguardian supports filter groups, which allow web access control of users based on filter group membership. Different users can have different access rights, and to achieve this each filter groups configuration files are configured with different access rights. Users are made members of the required filter group by editing /etc/dansguardian/lists/filtergroupslist
  
leave other possibilities with # at start of line
+
When you open a web browser you get asked to login with a username & password.
 +
Depending on the users group membership they get filtered or unfiltered access.
  
 +
For additional information on filtering users access rights based on group membership (in conjunction with Auth login), see http:/dansguardian.org
  
edit /etc/dansguardian/dansguardianf1.conf
+
In order to use filter groups, you must be using one of the Auth login methods.
  
change Filter group mode
+
If you wish to authenticate users when opening a browser using pam auth method, then you will need to disable Transparent Proxy as it is not compatible with this method.
  
leave this unchanged as this group will be the filtered standard users group
+
Issue the following command
 +
config setprop squid Transparent no
 +
expand-template /etc/squid/squid.conf
 +
sv t /service/squid
 +
 
 +
Doing the above will also require you to manually specify the proxy settings in your browser, so you will need to add the server IP eg 192.168.1.1 and port 8080 for the proxy setting
 +
 
 +
You cannot have pam auth enabled and Transparent Proxy set to yes.
 +
 
 +
Issue one of the following commands to enable the type of Auth login required, which will then permit the configuration & use of Filter Groups
 +
config setprop squid RequireAuth pam
 +
config setprop squid RequireAuth ncsa
 +
config setprop squid RequireAuth ident
 +
 
 +
To enable any of the above settings do
 +
expand-template /etc/squid/squid.conf
 +
sv t /service/squid
  
groupmode = 1
 
  
 +
When using Filter Groups, a typical situation may have:
 +
Filter Group 1 - blocked users (no access) - See [http://contentfilter.futuragts.com/wiki/index.php?title=Group_Configuration#Typically_Set_Default_Group_.28f1.29_To_No_Web_Access_At_All]
 +
Filter Group 2 - standard users (standard access rights)
 +
Filter Group 3 - guest users (limited access rights)
 +
Filter Group 4 - power users (more generous access & file download rights)
 +
Filter Group 5 - admin users (unlimited access)
  
Filter group name
 
  
remove # from front of groupname = ''
+
To create the additional filter group configuration files and folders do
 +
cp /etc/dansguardian/dansguardianf1.conf /etc/dansguardian/dansguardianf2.conf
 +
cp /etc/dansguardian/dansguardianf1.conf /etc/dansguardian/dansguardianf3.conf
 +
cp /etc/dansguardian/dansguardianf1.conf /etc/dansguardian/dansguardianf4.conf
 +
cp /etc/dansguardian/dansguardianf1.conf /etc/dansguardian/dansguardianf5.conf
  
change to  
+
Because the Filter Group 1 (default) uses the configuration files located at the root of "/lists" directory, it is only necessary to create the rest of the directories f2, f3, f4 and f5 to host the configuration files for each Filter Group.
  
groupname = 'Standard Users'
+
Each filter directory (f2, f3, etc.) will house all the configuration files located at the root of "/lists" directory unless filtergroupslist, bannediplist and exceptioniplist, because they are not used for filtering because only they are called (logically) from the general configuration file dansguardian.conf.
  
 +
Because the configuration files are modified, is a smart idea to create a "virgin" copy of the files and then use it to create new filters directory. This directory will named "virgin" or something similar.
  
edit /etc/dansguardian/dansguardianf2.conf
+
mkdir -p /etc/dansguardian/lists/virgin
 +
cp /etc/dansguardian/lists/* /etc/dansguardian/lists/virgin
 +
rm -f /etc/dansguardian/lists/virgin/filtergroupslist
 +
rm -f /etc/dansguardian/lists/virgin/bannediplist
 +
rm -f /etc/dansguardian/lists/virgin/exceptioniplist
 +
cp -R /etc/dansguardian/lists/virgin /etc/dansguardian/lists/f2
 +
cp -R /etc/dansguardian/lists/virgin /etc/dansguardian/lists/f3
 +
cp -R /etc/dansguardian/lists/virgin /etc/dansguardian/lists/f4
 +
cp -R /etc/dansguardian/lists/virgin /etc/dansguardian/lists/f5
 +
(which will include all subfolders and files)
  
change Filter group mode
+
Then edit & save the various main configuration files
 +
pico -w /etc/dansguardian/dansguardianf2.conf
 +
and change all instances of /lists/ to /lists/f2/ in filename locations
  
change this as this group will be the unfiltered Admin Users group
 
  
groupmode = 2
+
pico -w /etc/dansguardian/dansguardianf3.conf
 +
and change all instances of /lists/ to /lists/f3/ in filename locations
  
  
Filter group name
+
pico -w /etc/dansguardian/dansguardianf4.conf
 +
and change all instances of /lists/ to /lists/f4/ in filename locations
  
remove # from front of groupname = ''
 
  
change to  
+
pico -w /etc/dansguardian/dansguardianf5.conf
 +
and change all instances of /lists/ to /lists/f5/ in filename locations
  
groupname = 'Admin Users'
 
  
 +
Edit & save the main dansguardian configuration file to setup filter groups
 +
pico -w /etc/dansguardian/dansguardian.conf
  
Content filtering files location
+
Configure the following settings as shown
 +
#Filter group options
 +
filtergroups = 5
 +
(or however many filter groups you want to have)
  
change all these to show f2 in the location path
+
#Auth plugins
 +
authplugin = '/etc/dansguardian/authplugins/proxy-basic.conf'
 +
(leave other possibilities with # at start of line)
  
change all other occurrences of f1 to f2 in file paths
 
  
 +
Edit Filter Group 1 main configuration file
 +
pico -w /etc/dansguardian/dansguardianf1.conf
  
edit /etc/dansguardian/lists/filtergroupslist
+
Configure the following settings as shown
 +
#Filter group mode
 +
groupmode = 0
  
add entries for users who are members of filter group2
+
#Filter group name
 +
groupname = 'Blocked Users'
  
use this format
 
  
username=filtergroupnumber
+
Edit & save Filter Group 2 main configuration file
 +
pico -w /etc/dansguardian/dansguardianf2.conf
  
eg
+
Configure the following settings as shown 
 +
#Filter group mode
 +
groupmode = 1
  
ray=filter2
+
#Filter group name
 +
groupname = 'Standard Users'
  
  
It's not necessary to add all users who are in filter group 1 as everyone is automatically a member of group 1 by default.  
+
Edit & save Filter Group 3 main configuration file
 +
pico -w /etc/dansguardian/dansguardianf3.conf
  
Filter group 2 settings override filter group 1  
+
Configure the following settings as shown
 +
#Filter group mode
 +
groupmode = 1
  
restart dansguardian for changes to take effect
+
#Filter group name
 +
groupname = 'Guest Users'
  
/etc/init.d/dansguardian restart
 
  
You can create as many groups as you want, using similar steps as above.  
+
Edit & save Filter Group 4 main configuration file
 +
pico -w /etc/dansguardian/dansguardianf4.conf
  
Each group can have different levels of filtering eg different exceptionlists and naughtyness limits etc etc etc.
+
Configure the following settings as shown
 +
#Filter group mode
 +
groupmode = 1
  
 +
#Filter group name
 +
groupname = 'Power Users'
  
edit the exception and banned lists in
 
  
/etc/dansguardian/lists/f3/exceptionsitelist etc etc etc
+
Edit & save Filter Group 5 main configuration file
 +
pico -w /etc/dansguardian/dansguardianf5.conf
  
and in each other group list structure eg f1 & f2
+
Configure the following settings as shown
 +
#Filter group mode
 +
groupmode = 2
  
obviously if f2 is a unfiltered group then setting changes to exception & other lists will have no effect
+
#Filter group name
 +
groupname = 'Admin Users'
  
  
In practice you get asked for a login user & password when you access a web site.  
+
Edit & save the Filter Groups List file to add details of users and their group membership
 +
All users are automatically members of Filter Group 1, so you only need to add details of users who are in other groups.
 +
pico -w /etc/dansguardian/lists/filtergroupslist
 +
add entries for users who are members of other filter groups, use this format
 +
username=filtergroupnumber
 +
for example
 +
ray=filter2
 +
george=filter3
 +
mary=filter4
 +
peter=filter5
 +
and so on.
  
Depending on your group membership you get filtered or unfiltered access.
+
Filter group 2,3,4 & 5 settings override filter group 1 settings.
  
==='''Testing access'''===
+
Restart dansguardian for changes to take effect
 +
/etc/init.d/dansguardian restart
  
From a workstation web browser go to the site of www.sex.com or www.sex.com.au
+
You can create as many groups as you want, using similar steps as above.
 +
 
 +
Each group can have different levels of filtering eg different exceptionlists and naughtyness limits etc.
 +
 
 +
 
 +
edit the exception and banned lists in
 +
pico -w /etc/dansguardian/lists/f2/exceptionsitelist
 +
etc etc
 +
 
 +
and in each other group list structure eg f3, f4 & f5
  
You should receive a message advising the site is blocked. Try browsing to other sites with inappropriate content or a site on your banned site list and you should receive a site blocked message.
+
Where f2 is a blocked group then setting changes to exception & other lists for that group will have no effect.
 +
Where f5 is a unfiltered group then setting changes to exception & other lists for that group will have no effect.
  
Remember that access to sites is controlled by settings in the config files.
+
====ClamAV support====
  
   
+
If you want to use DansGuardian with SME antivirus, edit /etc/dansguardian/dansguardian.conf and uncomment following line:
 +
  contentscanner = '/etc/dansguardian/contentscanners/clamdscan.conf'
 +
Now at the end of the file, add following lines:
 +
# OPTION: virusscanexceptions
 +
# If off, antivirus scanner will ignore exception sites and urls.
 +
virusscanexceptions = on
  
==='''General information re Blacklists'''===
+
also edit /etc/dansguardian/contentscanners/clamdscan.conf and uncomment
 +
+ clamdudsfile = '/var/clamav/clamd.socket'
 +
- #clamdudsfile = '/var/run/clamav/clamd.socket'
  
You can install blacklists from mesd.k12.or.us or alternatively use the commercial blacklist from URLBlacklist.com
+
If you also want to be warned each time a bad page is blocked, edit /etc/dansguardian/dansguardianf1.conf and modify default settings:
 +
usesmtp = on
 +
mailfrom = 'dansguardian'
 +
avadmin = 'admin'
 +
contentadmin = 'admin'
 +
notifyav = on      <= virus mail alert
 +
notifycontent = on <= content mail alert
  
If you choose to use or trial the lists from blacklist .com, download the tgz file, uncompress and move to the
+
Restart dansguardian and try to [http://securite-informatique.info/virus/eicar/download/eicar.zip download eicar test virus ]
  
/etc/dansguardian/blacklists directory. There is also a blacklist from dungog.net that was installed at the beginning of this HOWTO.
+
DansGuardian should block the download!
  
+
=====ClamAV & Dansguardian on SME 9+=====
 +
The path to clamd.socket changed with SME 9, and [https://forums.contribs.org/index.php/topic,52519.msg269937.html#msg269937 users report] file access rights issues between dansguardian and clamav.
  
==='''Further customisation - configuration options'''===
+
After installing DansGuardian and completing the clamav setup instructions above, there are 3 extra steps to take on SME9:
  
DansGuardian is highly configurable. The source code is available so you have the ultimate in configurability, although most people will be content with modifying the configuration files.  
+
1. The path to clamd.socket must match the path given in /etc/clamd.conf
 +
* edit <span style="color:blue;">/etc/dansguardian/contentscanners/clamdscan.conf</span> and set clamdudsfile to:
 +
  clamdudsfile = '/var/clamav/clamd.socket'
  
After you have modified any configuration file, to apply the changes you will need to restart DansGuardian.
+
2. Dansguardian and Clamav must run as the same user for clamav scanning to work.  Set Dansguardian to run as 'clamav' as follows:
 +
* edit <span style="color:blue;">/etc/dansguardian/dansguardian.conf</span>
 +
** uncomment 'daemonuser' and 'daemongroup'
 +
** set 'daemonuser' to 'clamav':
 +
  daemonuser = 'clamav'
 +
  daemongroup = 'dansguardian
  
There are two main configuration files, several banned lists and exception lists. These are all explained below:
+
3. Correct the ownership on existing files and folders that belong to the original dansguardian user account.
 +
* Execute the commands below
 +
  chown clamav /var/log/dansguardian/access.log
 +
  'rm' -rf /tmp/.dguardianipc
 +
  'rm' -rf /tmp/.dguardianurlipc
  
===='''exceptionsitelist'''====
 
This contains a list of domain endings that if found in the requested URL, DansGuardian will not filter the page. Note that you should not put the http:// or the www. at the beginning of the entries.
 
  
===='''exceptioniplist'''====
+
Restart dansguardian and test
This contains a list of client IPs who you want to bypass the filtering. For example, the network administrator's computer's IP.  
+
  /etc/init.d/dansguardian restart
  
===='''exceptionuserlist'''====
+
====Other Dansguardian Config Files====
Usernames who will not be filtered (basic authentication or ident must be enabled).
 
  
===='''exceptionphraselist'''====
+
There are many other config files, including but not limited to the ones in this appendix
If any of the phrases listed here appear in a web page then the filtering is bypassed. Care should be taken adding phrases to this file as they can easily stop many pages from being blocked. It would be better to put a negative value in the weightedphraselist.
 
  
===='''exceptionurllist'''====
+
See [[:Dansguardian/ConfigFiles]]
URLs in here are for parts of sites that filtering should be switched off for.
 
  
===='''bannediplist'''====
+
===Starting Dansguardian===
IP addresses of client machines to disallow web access to. Only put IP addresses here, not host names.
 
  
===='''bannedphraselist'''====
+
After install & initial configuration you must manually start Dansguardian to enable web content filtering
This contains a list of banned phrases. The phrases must be enclosed between < and >. DansGuardian is supplied with an example list. You can not use phrases such as <sex> as this will block sites such as Middlesex University. The phrases can contain spaces. Use them to your advantage. This is the most useful part of DansGuardian and will catch more pages than PICS and URL filtering put together.
 
  
Combinations of phrases can also be used, which if they are all found in a page, it is blocked. Exception phrases are no longer listed in this file - see exceptionphraselist.
+
(Note that suitable links to start Dansguardian at startup/reboot are setup when the rpm is installed)
  
===='''banneduserlist'''====
+
/etc/init.d/dansguardian start
Users names, who, if basic proxy authentication is enabled, will automatically be denied web access.  
 
  
===='''bannedmimetypelist'''====
+
'''Stopping Dansguardian'''
This contains a list of banned MIME-types. If a URL request returns a MIME-type that is in this list, DansGuardian will block it. DansGuardian comes with some example MIME-types to deny. This is a good way of blocking inappropriate movies for example. It is obviously unwise to ban the MIME-types text/html or image/*.
 
  
===='''bannedextensionlist'''====
+
If you need to stop Dansguardian (ie to disable filtering or test your system without Dansguardian running)
This contains a list of banned file extensions. If a URL ends in an extension that is in this list, DansGuardian will block it. DansGuardian comes with some example file extensions to deny. This is a good way of blocking kiddies from downloading those lovely screen savers and hacking tools. You are a fool if you ban the file extension .html, or .jpg etc.
 
  
===='''bannedregexpurllist'''====
+
/etc/init.d/dansguardian stop
This contains a list of banned regular expression URLs. For more information on regular expressions, see http://www.opengroup.org/onlinepubs/7908799/xbd/re.html
 
  
Regular expressions are a very powerful pattern matching system. This file allows you to match URLs using this method.
+
'''Restarting Dansguardian'''
  
===='''bannedsitelist'''====
+
You will need to restart Dansguardian after making any configuration changes (so they can take effect)
This file contains a list of banned sites. Entering a domain name here bans the entire site. For banning specific parts of a site, see bannedurllist. Also, you can have a blanket ban all sites except those specifically excluded in exceptionsitelist. You can also block sites specified only as an IP address, and include a stock squidGuard blacklists collection. To enable these blacklists, download them from the extras section http://dansguardian.org/?page=extras
 
  
Simply put them somewhere appropriate, un-comment the squidGuard blacklists collection lines at the bottom of the bannedsitelist file, and check the paths are correct. For URL blacklists, edit the bannedurllist in a similar way.  
+
/etc/init.d/dansguardian restart
  
===='''bannedurllist'''====
+
'''Status check of Dansguardian'''
This allows you to block specific parts of a site rather than the whole site. To block an entire site, see bannedsitelist. To enable squidGuard blacklists for URLs, you will need to download the blacklists and edit the squidGuard blacklists collection section at the bottom (as for bannedsitelist above).
 
  
===='''weightedphraselist'''====
+
If you need to check that Dansguardian is running
Each phrase is given a value either positive or negative and the values are added up. Phrases to do with good subjects will have negative values, and bad subjects will have positive values. Once the naughtyness limit is reached (within dansguardian.conf), the page is blocked. See the Naughtyness Limit description within the dansguardian.conf section below.
 
  
===='''pics'''====
+
/etc/init.d/dansguardian status
This file allows you to finely tune the PICS filtering. Each PICS section comes with a description of the allowed settings and what they represent. The default settings with DansGuardian are set for youngish children, for example mild profanities and artistic nudity are allowed. PICS filtering can also be totally disabled / enabled using the enablePICS = on | off option.
 
  
For more detailed information on PICS ratings, see http://www.w3.org/PICS/
 
 
===='''contentregexplist'''====
 
  
  
===='''ICRA'''====
+
===Testing access===
The ICRA section is fairly self-explanatory. A value of 0 means nothing of that category is allowed, whereas a value of 1 allows it. For example,
 
  
ICRAnudityartistic = 1
+
From a workstation web browser go to the site of www.sex.com or www.sex.com.au
  
allows nude art. For more in-depth information see http://www.rsac.org/
+
You should receive a message advising the site is blocked. Try browsing to other sites with inappropriate content or a site on your banned site list and you should receive a site blocked message.
  
===='''RSAC'''====
+
Remember that access to sites is controlled by settings in the config files.
RSAC is an older version of ICRA. The values here range from 0 meaning none allowed, through 2 (the default value), to 4, which allows wanton and gratuitous amounts of the given category. For more in-depth information see http://www.rsac.org/
 
  
===='''evaluWEB'''====
+
=== Using Group Policy Editor to force proxy port setting on workstations ===
evaluWEB rating uses a system similar to the British Film classification system:
 
  
0 = U (Universal, ie. suitable for even the youngest viewer)
+
If you are using Windows & Internet Explorer you can use Group Policy Editor (gpedit.msc) to configure your workstation settings, to force all users of the workstation to use preset proxy port settings.
  
1 = PG (Parental Guidance recommended)
+
Refer to this forum thread for additional details
  
2 = 18 (Only suitable for viewers aged 18 and over)
+
http://forums.contribs.org/index.php?topic=38284.0
  
===='''SafeSurf'''====
+
Some users report that this method does not seem to work for them.
Similar to RSAC, but containing a larger range of categories with the range from 0 = full filtering to 9 = wanton and gratuitous. For more in-depth information, see http://www.safesurf.com
 
  
===='''Weburbia'''====
+
An alternative approach (which is known to work OK), is to use gpedit.msc to remove the IE menu option for changing connection settings. Do this using the following brief steps.
See evaluWEB. For more in-depth information, see http://www.weburbia.com/safe/index.shtml
 
  
===='''Vancouver Webpages'''====
+
Run gpedit.msc
This is yet another ratings scheme. See http://vancouver-webpages.com/VWP1.0/
 
  
for more information.
+
Select Local Computer Policy
  
+
Select User Configuration
  
==='''dansguardian.conf & dansguardianf1.conf'''===
+
Select Administrative Templates
The only setting that is vital for you to configure in the dansguardian.conf file is the accessdeniedaddress setting. You should set this to the address (not the file path) of your Apache server with the perl access denied reporting script. For most people this will be the same server as squid and DansGuardian. If you really want you can change this address to a normal html static page on any server.
 
  
===='''Reporting Level'''====
+
Select Windows Components
You can change the reporting level for when a page gets denied. It can say just 'Access Denied', or report why, or report why and what the denied phrase is. The latter may be more useful for testing, but the middler would be more useful in a school environment. Stealth mode logs what would be denied but doesn't do any blocking.
 
  
===='''Logging Settings'''====
+
Select Internet Explorer
This setting lets you configure the logging level. You can log nothing, just denied pages, text based and all requests. HTTPS requests only get logged when the logging is set to 3 - all requests.
 
  
===='''Log Exception Hits'''====
+
Select Disable changing connection settings
Log if an exception (user, ip, URL, or phrase) is matched and so the page gets let through. This can be useful for diagnosing why a site gets through the filter.
 
  
===='''Log File Format'''====
+
Select Enabled then click OK
This setting alters the format of the DansGuardian log file. Please note option 3 (standard log format) is not yet unimplemented.
 
  
===='''Network Settings'''====
+
This will disable the Internet Explorer menu Tools/Internet Options/Connections, so ensure you have made the correct desired settings first.
These allow you to modify the IP address that DansGuardian is listening on, the port DansGuardian listens on, the IP address of the server running squid as well as the squid port. It is possible to configure the Access Denied reporting page here also.  
 
  
===='''Content Filtering Settings'''====
 
Here you can modify the location of the list files. Adjusting these locations is not recommended.
 
  
===='''Naughtyness limit'''====
+
Note that if TransparentPort = 8080 and portblocking = yes and you are not using Group Filtering, workstations can be set to "Auto detect proxy port" and will be forced to use Dansguardian.
This setting refers to the weighted phrase limit over which the page will be blocked. Each weighted phrase is given a value either positive or negative and the values added up. Phrases to do with good subjects will have negative values, and bad subjects will have positive values. See the weightedphraselist file for examples. As a rough guide, a value of 50 is for young children, 100 for older children, 160 for young adults.  
 
  
===='''Show weighted phrases found'''====
+
Note that if Transparent = no and you are using Group Filtering with user login authentication, then your browsers proxy port will need to be set to port 8080 (for all users). If you are using Windows & Internet Explorer, then using gpedit.msc can simplify configuration for all users of workstations.
If enabled then the phrases found that made up the total which exceeds the naughtyness limit will be logged and, if the reporting level is high enough, reported.  
 
  
===='''Reverse Lookups for Banned Sites and URLs'''====
+
=== Bugs ===
If set to on, DansGuardian will look up the forward DNS for an IP URL address and search for both in the banned site and URL lists. This would prevent a user from simply entering the IP for a banned address. It will reduce searching speed somewhat so unless you have a local caching DNS server, leave it off and use the Blanket IP Block option in the bannedsitelist file instead.  
+
Please raise bugs under the SME-Contribs section in {{BugzillaFileBug|product=|component=|title=bugzilla}}and select the smeserver-dansguardian component or use {{BugzillaFileBug|product=SME%20Contribs|component=smeserver-dansguardian|title=this link}}.
  
===='''Build bannedsitelist and bannedurllist Cache Files'''====
+
{{#bugzilla:columns=id,product,version,status,summary |sort=id |order=desc |component=smeserver-dansguardian|noresultsmessage="No open bugs found."}}
This will compare the date stamp of the list file with the date stamp of the cache file and will recreate as needed. If a bsl or bul .processed file exists, then that will be used instead. It will increase process start speed by 300%. On slow computers this will be significant. Fast computers do not need this option.  
 
  
===='''POST protection (web upload and forms)'''====
 
This is for blocking or limiting uploads, not for blocking forms without any file upload. The value is given in kilobytes after MIME encoding and header information.
 
  
===='''Username identification methods (used in logging)'''====
+
===Changelog===
The proxyauth option is for when basic proxy authentication is used (obviously no good for transparent proxying). The ntlm option is for when the proxy supports the MS NTLM authentication. This only works with IE5.5 sp1 and later, and has not been implemented yet. The ident option causes DansGuardian to try to connect to an identd server on the computer originating the request.  
+
Only versions released in smecontrib are listed here.
  
===='''Forwarded For'''====
+
{{ #smechangelog: smeserver-dansguardian}}
This option adds an X-Forwarded-For: <clientIP> to the HTTP request header. This may help solve some problem sites that need to know the source IP.
 
  
===='''Max Children'''====
 
This sets the maximum number of processes to spawn to handle the incoming connections. This will prevent DoS attacks killing the server with too many spawned processes. On large sites you might want to double or triple this number.
 
  
===='''Log Connection Handling Errors'''====
 
This option logs some debug info regarding fork()ing and accept()ing which can usually be ignored. These are logged by syslog. It is safe to leave this setting on or off.
 
  
 +
----
 
[[Category:Contrib]]
 
[[Category:Contrib]]
 
[[Category:Dungog]]
 
[[Category:Dungog]]
 +
[[Category:Administration:Content Spam Virus Blocking]]
 +
[[Category:Security]]
 +
[[Category:Contrib:webfiltering]]

Latest revision as of 09:46, 19 September 2023


Dansguardian web content filtering

PythonIcon.png Skill level: Medium
The instructions on this page require a basic knowledge of linux.



Warning.png Warning:
Dansguardian is deprecated and not available on Koozali SME v10.

There is a fork called e2guardian http://e2guardian.org/cms/index.php and https://github.com/e2guardian


Version

Contrib 9:
dansguardian
The latest version of dansguardian is available in the SME repository, click on the version number(s) for more information.


Contrib 9:
smeserver-dansguardian
The latest version of smeserver-dansguardian is available in the SME repository, click on the version number(s) for more information.


Also see: https://wiki.koozali.org/index.php?title=Dansguardian-panel

Devel 9:
smeserver-dansguardian-panel
The latest version of smeserver-dansguardian-panel is available in the SME repository, click on the version number(s) for more information.


Description

Dansguardian is a web content filter, which analyses the actual content of web pages based on many criteria including phrase matching, PICS filtering, URL filtering and lists of banned sites. Each content type is given a score, and when the threshold score is exceeded, access to the web site is blocked. For additional information see http://dansguardian.org

This HOWTO requires command line control to edit configuration files & restart the dansguardian service after configuration changes.

There is a commercial implementation of Dansguardian for sme server which adds a server manager panel to allow GUI control of all Dansguardian functionality & settings, see http://dungog.net/wiki/Dungog-dansguardian


Information

To have a proper understanding of how Dansguardian works and the importance of certain configuration settings you should read the detailed installation notes and Manual at the Dansguardian web site http://dansguardian.org

An old version 2.4 installation notes are here: http://dansguardian.org/downloads/detailedinstallation2.4.html#further

The FAQ is here: http://sourceforge.net/docman/display_doc.php?docid=27215&group_id=131757

Information about group configuration is here: http://contentfilter.futuragts.com/wiki/index.php?title=Group_Configuration

Mailing list is here: http://tech.groups.yahoo.com/group/dansguardian/

The information on the Dansguardian website and other websites referred to, is of a generic nature and some of it is NOT applicable to sme server installations, refer to the instructions in this HOWTO in preference.

Installation instructions

Install dansguardian and it's dependencies from the smecontribs repository

yum --enablerepo=smecontribs install smeserver-dansguardian 

Optional, download and install a set of blacklists from http://urlblacklist.com/ alternatively you can choose ftp://ftp.ut-capitole.fr/pub/reseau/cache/squidguard_contrib/blacklists.tar.gz from http://dsi.ut-capitole.fr/blacklists/


Important.png Note:
It is not sufficient to simply install the package, the appropriate manual configuration is an integral part of getting Dansguardian working on your system. A minimal installation requires all the configuration steps listed below to be carried out, ie from the "Modifying Firewall and Proxy" section up to "Filter Groups and Auth login". Filter Group configuration is only required if you wish to control access on a per user basis.



Information.png Tip:
If you would like to have a graphical and web based overview of what dansguardian has analyzed then take a look at http://wiki.contribs.org/Dansguardian-stats


Upgrading

There are substantial changes between dansguardian v2.9 over previous v2.8 (or earlier) installations. The recommendation from dansguardian.org is to edit the new configuration files/lists rather than try to edit your old ones.

Upgrading from 2.9 versions creates .rpmnew config files under /etc/dansguardian. This preserves your existing config files, but there is a chance that dansguardian won't start if parameters in the config file have changed.

Clamav libraries can cause problems when updating. If while updating you see something like

Error: Missing Dependency: libclamav.so.3 is needed by package dansguardian

Update with

yum update --enablerepo=smecontribs dansguardian clamav 

then

yum update

Modifying Firewall and Proxy

Configuring your system to force Dansguardian usage & prevent bypassing

These instructions assume that the sme server is running in server gateway mode and acting as the gateway for your network, and the squid proxy is running on the same machine that Dansguardian is running on.

If your server is configured in server only mode, then you will need to point your browser at that machine to find the squid proxy rather than the default gateway.

Dansguardian uses port 8080 for web proxy requests. If your browser does not use port 8080 then Dansguardian filtering will be bypassed. To force this usage & prevent users bypassing filtering you should do ALL the following steps:

1) Configure your SME Server to use Transparent Proxy port 8080 and to block direct access to the squid proxy port 3128 & redirect port 80 to port 8080

Note the functionality to create the required custom firewall rules using iptables is built in to the smeserver-dansguardian and is configured with the following commands. The Transparent proxy must also be enabled (which is the sme default) to prevent users bypassing Dansguardian filtering.

config setprop squid TransparentPort 8080
config setprop squid Transparent yes
config setprop dansguardian portblocking yes
signal-event post-upgrade; signal-event reboot

To return Transparent Proxy port to default value and to disable portblocking and to enable the Transparent proxy (which is the sme default)

config setprop squid TransparentPort 3128
config setprop squid Transparent yes 
config delprop dansguardian portblocking
signal-event post-upgrade; signal-event reboot 


Important.png Note:
If you disable the Transparent Proxy feature of SME Server, Dansguardian can be bypassed at will by your users. You should keep the Transparent Proxy enabled (configured as above) for filtering to work.


2) Configure your workstation web browser to auto detect proxy port

Go to your workstation and open your browser eg Internet Explorer or Firefox or your preferred browser

Change the settings for Connections to LAN

Select Auto detect proxy

Or alternatively use the server IP 192.168.1.1 (or whatever yours is) and use a port of 8080

Bypass Proxy

Allow individual PC's or selected sites to bypass the proxy (and dansguardian) entirely see Firewall#Bypass_Proxy.

Workstation IP allocation

Control of workstation access to the web (when using dansguardian), is implemented by nominating the workstation IP in the various dansguardian configuration files (ie the local LAN IP address). To apply consistent filtering rules or allow proxy bypass (see section above), the workstation IP must remain the same throughout restarts & DHCP IP refreshes or allocations. Configuring your workstations to have a consistent IP is a fundamental & important step when configuring your whole computer system.

This can be achieved by manually specifying a fixed IP address when each workstation is configured, but requires every workstation to be setup individually. Alternatively the workstation can be configured for auto allocation of an IP, and the Hostnames and Addresses panel in server manager can then be used to force the allocation of a specified IP by the SME DHCP server, based on the workstation NIC mac address. See the SME Manual for further details at http://wiki.contribs.org/SME_Server:Documentation:Administration_Manual:Chapter13#Reserving_IP_Addresses_Through_DHCP The basic steps are to determine the mac address of your workstation NIC and then create a hostname eg station5 and enter the mac address and the required "forced or fixed" IP eg 192.168.1.5

Any reference to the filtering of station5 then uses the IP 192.168.1.5, which will always stay the same, unless the NIC is changed. Remember to re-enter the mac address details into server manager, in the event the workstation NIC or motherboard is changed.

Configuring Proxy to use Auth login

Dansguardian supports different types of auth login ie ncsa, pam & ident, and allows control of web site access based on user name. For more details regarding the various auth login methods & other configuration requirements, see http://dansguardian.org or Google.

Enable this functionality using the appropriate command, depending on your requirements. Most users of sme will probably use pam auth as that will authorise access against sme users and passwords.

Choose one of the following

config setprop squid RequireAuth pam
config setprop squid RequireAuth ncsa
config setprop squid RequireAuth ident

To disable Auth login

config delprop squid RequireAuth

To enable any of the above setting changes you must follow the command with

expand-template /etc/squid/squid.conf
sv t /service/squid

Using NCSA Auth login

If you are using ncsa auth, create the user & password authentication list (you don't require users to be valid sme users)

touch /etc/proxyusers

Enter user names & password combinations one by one using this command

htpasswd -b /etc/proxyusers username password

You can test the authentication list using the following command

/usr/lib/squid/ncsa_auth /etc/proxyusers

Then enter the username & password when asked

You will see a ERR or OK response

Using Ident login

If you are using ident auth, you will require a ident client on your workstation. One windows ident client is available from:

https://sourceforge.net/projects/retinascan

In some cases, the Windows firewall blocks access to the ident client and you will have to add an exception in your firewall rules as follows:

Control Panel >> Windows Firewall >> Exceptions >> Add Port

  • Name: auth
  • Port number: 113
  • TCP

Modifying Dansguardian Configuration Files

Modifying Dansguardian dansguardian.conf & dansguardianf1.conf files

You need to manually modify various configuration files. As a minimum the following basic changes need to be made:

pico -w /etc/dansguardian/dansguardian.conf

You will initially need to change:

accessdeniedaddress = 'http://YOURSERVER.YOURDOMAIN/cgi-bin/dansguardian.pl'

for example to

accessdeniedaddress = 'http://www.mydomain.com/cgi-bin/dansguardian.pl'

Make any other required changes to suit your situation by carefully reviewing the other setting possibilities

To save & exit

Ctrl o
Ctrl x


pico -w /etc/dansguardian/dansguardianf1.conf

You may initially need to change (to suit adult level of protection)

naughtynesslimit = 50

to

naughtynesslimit = 160 

(or even 250 or 300 depending on your sensitivity/tolerance requirements)

Make any other required changes to suit your situation by carefully reviewing the other setting possibilities

Save & exit

Ctrl o
Ctrl x

Additional Options can be found here, http://wiki.contribs.org/Dansguardian/ConfigFiles under the topic dansguardian.conf & dansguardianf1.conf

If you have additional filter groups, then additional configuration files will need to be created and modified. See section on "Filter Groups and Auth login" below.

Modifying other Dansguardian configuration files

You will need to change other config files to suit your site requirements:

You can read information in the beginning of each config file that explains usage & syntax

These are located in

/etc/dansguardian/lists...  
/etc/dansguardian/lists/f2/...  

& so on and subfolders

eg

pico -w /etc/dansguardian/lists/f2/bannedextensionlist

make the required changes

Ctrl o
Ctrl x

Most users will need to change these 4 files as a minimum

bannedextensionlist
bannedsitelist
bannedurllist
exceptionsitelist

You should review ALL the dansguardian config files in /etc/dansguardian/lists and subfolders as part of your initial Dansguardian setup.

Some of the default settings in these files will prevent access to certain web sites and file types, which may conflict with your site requirements.

For many more details and descriptions on the configuration files see Dansguardian/ConfigFiles page of this Howto or at http://dansguardian.org

Modifying the default html error message page

You may also want to tailor the html template for the error message displayed when Dansguardian blocks a site, see

/etc/dansguardian/languages/(languagename)/template.html

or in some newer versions

/usr/share/dansguardian/languages/(languagename)/template.html

e.g.

pico -w /etc/dansguardian/languages/ukenglish/template.html

After you make any changes to the template.html you will need to run the command,

/etc/init.d/dansguardian restart 

for the changes to take effect.

Filter Groups and Auth login

Dansguardian supports filter groups, which allow web access control of users based on filter group membership. Different users can have different access rights, and to achieve this each filter groups configuration files are configured with different access rights. Users are made members of the required filter group by editing /etc/dansguardian/lists/filtergroupslist

When you open a web browser you get asked to login with a username & password. Depending on the users group membership they get filtered or unfiltered access.

For additional information on filtering users access rights based on group membership (in conjunction with Auth login), see http:/dansguardian.org

In order to use filter groups, you must be using one of the Auth login methods.

If you wish to authenticate users when opening a browser using pam auth method, then you will need to disable Transparent Proxy as it is not compatible with this method.

Issue the following command

config setprop squid Transparent no 
expand-template /etc/squid/squid.conf
sv t /service/squid

Doing the above will also require you to manually specify the proxy settings in your browser, so you will need to add the server IP eg 192.168.1.1 and port 8080 for the proxy setting

You cannot have pam auth enabled and Transparent Proxy set to yes.

Issue one of the following commands to enable the type of Auth login required, which will then permit the configuration & use of Filter Groups

config setprop squid RequireAuth pam
config setprop squid RequireAuth ncsa
config setprop squid RequireAuth ident

To enable any of the above settings do

expand-template /etc/squid/squid.conf
sv t /service/squid


When using Filter Groups, a typical situation may have:

Filter Group 1 - blocked users (no access) - See [1]
Filter Group 2 - standard users (standard access rights)
Filter Group 3 - guest users (limited access rights)
Filter Group 4 - power users (more generous access & file download rights)
Filter Group 5 - admin users (unlimited access)


To create the additional filter group configuration files and folders do

cp /etc/dansguardian/dansguardianf1.conf /etc/dansguardian/dansguardianf2.conf
cp /etc/dansguardian/dansguardianf1.conf /etc/dansguardian/dansguardianf3.conf
cp /etc/dansguardian/dansguardianf1.conf /etc/dansguardian/dansguardianf4.conf
cp /etc/dansguardian/dansguardianf1.conf /etc/dansguardian/dansguardianf5.conf

Because the Filter Group 1 (default) uses the configuration files located at the root of "/lists" directory, it is only necessary to create the rest of the directories f2, f3, f4 and f5 to host the configuration files for each Filter Group.

Each filter directory (f2, f3, etc.) will house all the configuration files located at the root of "/lists" directory unless filtergroupslist, bannediplist and exceptioniplist, because they are not used for filtering because only they are called (logically) from the general configuration file dansguardian.conf.

Because the configuration files are modified, is a smart idea to create a "virgin" copy of the files and then use it to create new filters directory. This directory will named "virgin" or something similar.

mkdir -p /etc/dansguardian/lists/virgin
cp /etc/dansguardian/lists/* /etc/dansguardian/lists/virgin
rm -f /etc/dansguardian/lists/virgin/filtergroupslist
rm -f /etc/dansguardian/lists/virgin/bannediplist
rm -f /etc/dansguardian/lists/virgin/exceptioniplist
cp -R /etc/dansguardian/lists/virgin /etc/dansguardian/lists/f2
cp -R /etc/dansguardian/lists/virgin /etc/dansguardian/lists/f3
cp -R /etc/dansguardian/lists/virgin /etc/dansguardian/lists/f4
cp -R /etc/dansguardian/lists/virgin /etc/dansguardian/lists/f5

(which will include all subfolders and files)

Then edit & save the various main configuration files

pico -w /etc/dansguardian/dansguardianf2.conf

and change all instances of /lists/ to /lists/f2/ in filename locations


pico -w /etc/dansguardian/dansguardianf3.conf

and change all instances of /lists/ to /lists/f3/ in filename locations


pico -w /etc/dansguardian/dansguardianf4.conf

and change all instances of /lists/ to /lists/f4/ in filename locations


pico -w /etc/dansguardian/dansguardianf5.conf

and change all instances of /lists/ to /lists/f5/ in filename locations


Edit & save the main dansguardian configuration file to setup filter groups

pico -w /etc/dansguardian/dansguardian.conf

Configure the following settings as shown

#Filter group options
filtergroups = 5

(or however many filter groups you want to have)

#Auth plugins
authplugin = '/etc/dansguardian/authplugins/proxy-basic.conf'

(leave other possibilities with # at start of line)


Edit Filter Group 1 main configuration file

pico -w /etc/dansguardian/dansguardianf1.conf

Configure the following settings as shown

#Filter group mode
groupmode = 0
#Filter group name
groupname = 'Blocked Users'


Edit & save Filter Group 2 main configuration file

pico -w /etc/dansguardian/dansguardianf2.conf

Configure the following settings as shown

#Filter group mode
groupmode = 1
#Filter group name
groupname = 'Standard Users'


Edit & save Filter Group 3 main configuration file

pico -w /etc/dansguardian/dansguardianf3.conf

Configure the following settings as shown

#Filter group mode
groupmode = 1
#Filter group name
groupname = 'Guest Users'


Edit & save Filter Group 4 main configuration file

pico -w /etc/dansguardian/dansguardianf4.conf

Configure the following settings as shown

#Filter group mode
groupmode = 1
#Filter group name
groupname = 'Power Users'


Edit & save Filter Group 5 main configuration file

pico -w /etc/dansguardian/dansguardianf5.conf

Configure the following settings as shown

#Filter group mode
groupmode = 2
#Filter group name
groupname = 'Admin Users'


Edit & save the Filter Groups List file to add details of users and their group membership All users are automatically members of Filter Group 1, so you only need to add details of users who are in other groups.

pico -w /etc/dansguardian/lists/filtergroupslist

add entries for users who are members of other filter groups, use this format

username=filtergroupnumber

for example

ray=filter2
george=filter3
mary=filter4
peter=filter5

and so on.

Filter group 2,3,4 & 5 settings override filter group 1 settings.

Restart dansguardian for changes to take effect

/etc/init.d/dansguardian restart

You can create as many groups as you want, using similar steps as above.

Each group can have different levels of filtering eg different exceptionlists and naughtyness limits etc.


edit the exception and banned lists in

pico -w /etc/dansguardian/lists/f2/exceptionsitelist

etc etc

and in each other group list structure eg f3, f4 & f5

Where f2 is a blocked group then setting changes to exception & other lists for that group will have no effect. Where f5 is a unfiltered group then setting changes to exception & other lists for that group will have no effect.

ClamAV support

If you want to use DansGuardian with SME antivirus, edit /etc/dansguardian/dansguardian.conf and uncomment following line:

contentscanner = '/etc/dansguardian/contentscanners/clamdscan.conf'

Now at the end of the file, add following lines:

# OPTION: virusscanexceptions
# If off, antivirus scanner will ignore exception sites and urls.
virusscanexceptions = on

also edit /etc/dansguardian/contentscanners/clamdscan.conf and uncomment

+ clamdudsfile = '/var/clamav/clamd.socket'
- #clamdudsfile = '/var/run/clamav/clamd.socket'

If you also want to be warned each time a bad page is blocked, edit /etc/dansguardian/dansguardianf1.conf and modify default settings:

usesmtp = on
mailfrom = 'dansguardian'
avadmin = 'admin'
contentadmin = 'admin'
notifyav = on      <= virus mail alert
notifycontent = on <= content mail alert

Restart dansguardian and try to download eicar test virus

DansGuardian should block the download!

ClamAV & Dansguardian on SME 9+

The path to clamd.socket changed with SME 9, and users report file access rights issues between dansguardian and clamav.

After installing DansGuardian and completing the clamav setup instructions above, there are 3 extra steps to take on SME9:

1. The path to clamd.socket must match the path given in /etc/clamd.conf

  • edit /etc/dansguardian/contentscanners/clamdscan.conf and set clamdudsfile to:
 clamdudsfile = '/var/clamav/clamd.socket'

2. Dansguardian and Clamav must run as the same user for clamav scanning to work. Set Dansguardian to run as 'clamav' as follows:

  • edit /etc/dansguardian/dansguardian.conf
    • uncomment 'daemonuser' and 'daemongroup'
    • set 'daemonuser' to 'clamav':
 daemonuser = 'clamav'
 daemongroup = 'dansguardian

3. Correct the ownership on existing files and folders that belong to the original dansguardian user account.

  • Execute the commands below
 chown clamav /var/log/dansguardian/access.log
 'rm' -rf /tmp/.dguardianipc
 'rm' -rf /tmp/.dguardianurlipc


Restart dansguardian and test

 /etc/init.d/dansguardian restart

Other Dansguardian Config Files

There are many other config files, including but not limited to the ones in this appendix

See Dansguardian/ConfigFiles

Starting Dansguardian

After install & initial configuration you must manually start Dansguardian to enable web content filtering

(Note that suitable links to start Dansguardian at startup/reboot are setup when the rpm is installed)

/etc/init.d/dansguardian start

Stopping Dansguardian

If you need to stop Dansguardian (ie to disable filtering or test your system without Dansguardian running)

/etc/init.d/dansguardian stop

Restarting Dansguardian

You will need to restart Dansguardian after making any configuration changes (so they can take effect)

/etc/init.d/dansguardian restart

Status check of Dansguardian

If you need to check that Dansguardian is running

/etc/init.d/dansguardian status


Testing access

From a workstation web browser go to the site of www.sex.com or www.sex.com.au

You should receive a message advising the site is blocked. Try browsing to other sites with inappropriate content or a site on your banned site list and you should receive a site blocked message.

Remember that access to sites is controlled by settings in the config files.

Using Group Policy Editor to force proxy port setting on workstations

If you are using Windows & Internet Explorer you can use Group Policy Editor (gpedit.msc) to configure your workstation settings, to force all users of the workstation to use preset proxy port settings.

Refer to this forum thread for additional details

http://forums.contribs.org/index.php?topic=38284.0

Some users report that this method does not seem to work for them.

An alternative approach (which is known to work OK), is to use gpedit.msc to remove the IE menu option for changing connection settings. Do this using the following brief steps.

Run gpedit.msc

Select Local Computer Policy

Select User Configuration

Select Administrative Templates

Select Windows Components

Select Internet Explorer

Select Disable changing connection settings

Select Enabled then click OK

This will disable the Internet Explorer menu Tools/Internet Options/Connections, so ensure you have made the correct desired settings first.


Note that if TransparentPort = 8080 and portblocking = yes and you are not using Group Filtering, workstations can be set to "Auto detect proxy port" and will be forced to use Dansguardian.

Note that if Transparent = no and you are using Group Filtering with user login authentication, then your browsers proxy port will need to be set to port 8080 (for all users). If you are using Windows & Internet Explorer, then using gpedit.msc can simplify configuration for all users of workstations.

Bugs

Please raise bugs under the SME-Contribs section in bugzilla and select the smeserver-dansguardian component or use this link .

IDProductVersionStatusSummary (5 tasks)
12002SME Contribs10.0CONFIRMEDadd contrib to backup list [smeserver-dansguardian]
10898SME Contribs10alphaIN_PROGRESSsmeserver-dansguardian: dansguardian-2.10.1.1-2.el6.sme.x86_64 fails to install
10743SME Contribs9.2CONFIRMEDdansguardian running while disabled
9459SME Contribs9.0CONFIRMEDUpgrade dansguardian to dansguardian-2.12.0.3
4820SME Contribs7.4CONFIRMEDDansguardian can be bypassed


Changelog

Only versions released in smecontrib are listed here.