| 
 | 
 | 
 The configuration file
   The configuration file
  The default path for the squidGuard configuration file is "/usr/local/squidGuard/squidGuard.conf" but another default can be set at compile time, and can be changed at runtime. From here we'll use squidGuard.conf for short.
Note: The number of configuration options and the flexibility may look overwhelming. Don't panic! Concentrate on the options that suits your needs. Start with a simple working configuration and extend as your needs and experience grows. Don't try to solve everything in your first attempt..
 In general
   In general
  The recommended structure for squidGuard.conf is:
| Path declarations | (i.e. logdir and dbhome) | (optional) | 
| Time space declarations | (i.e. time zones) | (optional) | 
| Source group declarations | (i.e. clients) | (optional) | 
| Destination group declarations | (i.e. URLs) | (optional) | 
| Rewrite rule group declarations | (optional) | |
| Access control rule declarations | (required) | 
Note: No forward references are allowed! Within this strong limitation you may actually chose any structure you prefer.
The following words are reserved in squidGuard.conf and should be avoided in declaration names:
       acl             fri             outside         sun             urllist 
       anonymous       friday          pass            sunday          user 
       date            fridays         redirect        sundays         userlist 
       dbhome          ip              rew             thu             wed 
       dest            log             rewrite         thursday        wednesday 
       destination     logdir          sat             thursdays       wednesdays 
       domain          logfile         saturday        time            weekly 
       domainlist      mon             saturdays       tue             within 
       else            monday          source          tuesday         
       expressionlist  mondays         src             tuesdays        
    
   
  
  | # | used to start a comment. Everything from the # to the end of line is ignored. | 
|---|---|
| { } | used to delimit the start and end of a group declaration. | 
| - | often used to declare a range (i.e. "from-to" or "from - to"). | 
Declaration names/lables have the same limitations as domainnames except _ is allowed too (i.e. [-_.a-z0-9]+). Reserved words should be avoided as they may cause unpredictable results.
Generally you may break a (long) line by repeating the leading keyword. Repeated lines of the same type within a class will bee joined when the rule trees are built. So:
 Path declarations
   Path declarations
  | logdir | defines the diretory for the standard logfiles "squidGuard.error" and "squidGuard.log", and the base for relative logfilenames in log rules. The default is "/usr/local/squidGuard/logs" but another default can be set at compile time. | 
|---|---|
| dbhome | defines the base for relative list filenames. The default is "/usr/local/squidGuard/db" but another default can be set at compile time. | 
Although the defaults can be used silently it is recommended to declare these explicitly for clarity. For instance:
     logdir /usr/local/squidGuard/logs
     dbhome /usr/local/squidGuard/db
   
  
   Time space declarations
   Time space declarations
  Time spaces, or zones if you prefer, are declared by:
where specification can be any reasonable combination of:
   Note1: The numeric formats are strict (I.e. 08:00 not 8:00
   for HH:MM etc).
   
   Note2: Overlaps are OK, and the result is the union.
  
Thus for instance a Norwegian time space definition for leisure time including holidays and short days could look something like:
     time leisure-time {
	  weekly   * 00:00-08:00  	      # night
	  weekly   * 17:00-24:00  	      # evening
	  weekly   fridays 16:00-17:00	      # weekend
	  weekly   saturdays sundays	      # weekend
	  date	   *.01.01		      # New Year's Day
	  date	   *.05.01		      # Labour Day
	  date	   *.05.17		      # National Day
	  date	   *.12.24 12:00-24:00	      # Christmas Eve
	  date	   *.12.25		      # Christmas Day
	  date	   *.12.26		      # Boxing Day
	  date	   1999.03.31 12:00.24:00     # Ash Wednesday
	  date	   1999.04.01-1999.04.05      # Easter
	  date	   1999.05.13 1999.05.24      # Ascension Day and Whitsun
	  date	   2000.04.19 12:00.24:00     # Ash Wednesday y2000
	  date	   2000.04.20-2000.04.24      # Easter y2000
	  date	   2000.06.01 2000.06.12      # Ascension Day and Whitsun y2000
     }
   
  
   Source group declarations
   Source group declarations
  Source group, or client groups if you prefer, are declared by:
where:
Time constraints on clientgroups can be used to make these clients unknown (i.e. use the default rule) within or outside a given time space. Or it can be used to define a usergroup that is expected to move between two locations at given times (like office/home)
Specification can be any reasonable combination of:
   
    
     *) The use of domain match for clientsgroups requires Squid
     is set up to do revese lookups on clients.
 **) The use
     of username match for clientsgroups requires Squid is set up to
     do ident/RFC-931 lookups.
    
   
  
   Note1: Overlaps are OK, and the groups are matched in the
   order they are defined.
 Note2: The logical operator
   between different types within a group (ip/domain/user) is AND. The
   default is any. Thus one of each defined type
   must match but undefined types are ignored.
  
Thus an administrator client group could look something like:
     src admin within leisure-time {
	  ip	   10.11.12.13 10.11.12.26    # The administrators home WS/PCs
	  domain   ras.teledanmark.no	      # The RAS domain
	  user	   root administrator foo bar # The administrators login names
     } else {
	  ip	   10.1.1.15 10.1.2.17        # The administrators office WS/PCs
	  domain   lan.teledanmark.no	      # The LAN domain
	  user	   root administrator foo bar # The administrators login names
     }
   
  
   Destination group declarations
   Destination group declarations
  Destination group, or target groups if you prefer, are declared by:
where:
Time constraints on destinationgroups can be used to make these groups void (i.e. ignored) within or outside a given time space.
Specification can be any combination of zero or one of each of:
   Note1: Overlaps are OK, and the groups are matched in the
   order they are listed in the pass declaration in for the
   actual clientgroup.
 Note2: The logical operator between
   different types (domainlist/urllist/expressionlist) is OR. The
   default is void. Thus the destinationgroup is matched if
   one of the defined types match. Within a destination group
   the test order is domainlist, urllist, and expressionlist.
  
Thus an entertainment destination group declaration could look something like:
     dest not-business-related outside leisure-time {
	  domainlist	 entertainment/domains
	  urllist	 entertainment/urls
	  expressionlist entertainment/expressions
     }
   
  
   Rewrite rule group declarations
   Rewrite rule group declarations
  Rewrite rule groups, or rewrite rule sets if you prefer, are declared by:
where:
Time constraints on rewritegroups can be used to make these groups functional within or outside a given time space only; Like redirect to local copies within peek business hours.
Substitution is sed style (multiple):
   Note1: Sed style substitutions uses regular expressions and
   thus slows down squidGuard more than B-tree lookups.
   Note2: Suport for visible redirects (i.e. 302: URL
   prefix) is broken in some versions of Squid.
  
A rewrite rule set declaration could look something like:
     rew get-local {
	  s@.*/cb32e46.exe$@http://ftp/pub/www/client/windows/cb32e46.exe@r
	  s@.*/cc32e46.exe$@http://ftp/pub/www/client/windows/cc32e46.exe@r
	  s@.*/cp32e46.exe$@http://ftp/pub/www/client/windows/cp32e46.exe@r
     }
   
  
   Access Control Lists
   Access Control Lists
  The Access Control List, ACL, combies the previous definitions into distinct rulesets for each clientgroup:
Note: There may be no more than one acl block.
The default section defines fallbacks for all acl rulesets. Thus if you define a rewrite rule here it will be used in acls where there are no rewrite rules defined. (i.e. the other acls inherits the definitions in the default acl optionally overruled by own definitions). The default rule set is used for all clients that match no clientgroup and for clientgroups with no acls declared.
   The pass rules declares destination groups that should
   pass for the actual client group. "!" is the
   NOT operator and indicates a destination group that should
   not pass (i.e. be redirected to the actual redirect URL).
   
   Note: Pass rules ends with an implicit "all". It is good
   practice to allways en the pass rules with either "all" or "none"
   to make them clear. Ie. use:
   
     pass good none
   
   or
   
     pass good !bad all
   
   Note: If there is a !group there must also
   be a redirect definition for eiter that destination group, the
   actual acl or the default acl. If you want some rules for unknown
   clients that should not apply to the other acls you should define a
   last clientgroup named "unknown" and with an IP range 0.0.0.0/0
   (i.e. any), and put those rules in the "unknown" acl.
  
The rewrite rules declares the substitution rulsets that applies to the actual acl.
   The redirect rules declares the altenative URL to be used
   for blocked destination groups (!groups) for the actual
   acl.
 Note: Inside an acl, this is a fallback used when
   there is no special redirect declared for the actual destination
   group, and the default redirect is the last resort.
  
squidGuard can do runtime string substitutions in the redirectors. Therefor the character "%" has special meaning in the redirector URLs:
| %a | is replaced with IP address of the client. | 
|---|---|
| %n | is replaced with the domainname of the client or "unknown" if not available. | 
| %i | is replaced with the user ID (RFC931) or "unknown" if not available. | 
| %s | is replaced with the matched source group (client group) or "unknown" if no groups were matched. | 
| %t | is replaced with the matched destination group (target group) or "unknown" if no groups were matched. | 
| %u | is replaced with the requested URL. | 
| %p | is replaced with the REQUEST_URI, i.e. the path and the optional query string of %u, but note for convenience without the leading "/". | 
| %% | is replaced with a single "%". | 
Thus you can pass usefull information to a more or less intelligent CGI page:
     http://proxy/cgi/squidGuard?clientaddr=%a&clientname=%n&clientident=%i&clientgroup=%s&destinationgroup=%t&url=%u
   
  
  For a start, there is a sample of such a script in samples/squidGuard.cgi in the source tree.
 The database
   The database
  squidGuard uses a database that can be devided into an unlimited number of distinct categories like "local", "customers", "vendors", "banners", "banned" etc. Each category may consist of separate unlimited lists of domains, URLs and/or regular expressions. For easy revision the lists are stored in separate plain text files that. The lists are for efficiency stored in in-memory-only B-trees at startup.
Note: All URLs are converted to lowercase before match search. So the lists should not contain uppercase leters.
 Domainlists
   Domainlists
  The domainlist file format is simply domainnames/zonenames separated by a newline. The length of these lists have neglectable influence on the performance.
For instance a start for a financial category:
     amex.com
     asx.com.au
     bourse-de-paris.fr
     exchange.de
     londonstockex.co.uk
     nasdaq.com
     nyse.com
     ose.no
     tse.or.jp
     xsse.se
   
  
  Note: squidGuard will match any URL with the domainname itself an any subdomains and hosts (i.e. amex.com, www.amex.com, whatever.amex.com and www.what.ever.amex.com but not .*[^.]amex.com (i.e. aamex.com etc.)).
 URLlists
   URLlists
  
   The urllist file format is simply URLs separated by newline but
   with the "proto://((www|web|ftp)[0-9]*)?" and
   "(:port)?" parts and normally also the ending
   "(/|/[^/]+\.[^/]+)$" part (i.e. ending "/" or
   "/filename") choped off. (i.e. "http://www3.foo.bar.com:8080/what/ever/index.html" =>
   "foo.bar.com/what/ever")
  
For instance a category for banned sites:
     foo.com/~badguy
     bar.com/whatever/suspect
   
  
  Note: The removed parts above are ignored by squidGuard in URL matching. Thus all these URLs will match the above urllist:
     http://foo.com/~badguy
     http://foo.com/~badguy/whatever
     ftp://foo.com/~badguy/whatever
     wais://foo.com/~badguy/whatever
     http://www2.foo.com/~badguy/whatever
     http://web56.foo.com/~badguy/whatever
   
  
  but not:
     http://barfoo.com/~badguy
     http://bar.foo.com/~badguy
     http://foo.com/~goodguy
   
  
  New in 1.0.0 is the ability to do 1-1 redirects on url basis with "key new_url". Thus as an alternative to using rewrites to redirect to local distributions you can have a destination group with an urllist like:
     netscape.com/pub/communicator/4.51/english/windows/windows95_or_nt/complete_install/cc32e451.exe http://ftp.teledanmark.no/pub/www/client/windows/cc32e451.exe
     netscape.com/pub/communicator/4.51/english/windows/windows95_or_nt/base_install/cb32e451.exe http://ftp.teledanmark.no/pub/www/client/windows/cb32e451.exe
   
  
  and an acl with pass ... !download .... This may be a faster alternative than using lots of s@from@to@ rewrites for 1-1 mapping since it will be faster to search the B-tree than perform a bunch of string edits.
 Expressionlists
   Expressionlists
  The expressionlist file format is lines with regular expressions as described in regex(5). Of most interrest is:
Thus a start to block possible sexual material by expression match could look like:
 Prebuilt databases
   Prebuilt databases
  To convert a domainlist or urllist from plain text file to a prebuilt database use:
To add and remove entries from a prebuilt database in runtime put the changes in a diff file (file.diff for file.db) with the following simple format:
 Tuning hints
   Tuning hints
  For optimal performance try:
 Working configuration examples
   Working configuration examples
   Example 0 - The
   absolutely minimal do nothing config:
   Example 0 - The
   absolutely minimal do nothing config:
  The absolutely minimal config file is an emty but existing file (i.e. squidGuard -c /dev/null) which is equivalent to:
     acl {
	  default {
	       pass all
	  }
     }
   
  
   Example 1 - The recommended minimal do nothing
   config:
   Example 1 - The recommended minimal do nothing
   config:
  We do recommend, for clarity, to say explicitly what squidGuard is expected to do (makes things less magic for a new operator):
     logdir /usr/local/squidGuard/log
     acl {
	 default {
	     pass all
	 }
     }
   
  
   Example 2 -
   Limiting the access to one destination group only:
   Example 2 -
   Limiting the access to one destination group only:
  
     logdir /usr/local/squidGuard/log
     dbhome /usr/local/squidGuard/db
     dest local {
	 domainlist local/domains
     }
     acl {
	 default {
	     pass local none
	     redirect http://localhost/cgi/blocked?clientaddr=%a&clientname=%n&clientuser=%i&clientgroup=%s&url=%u
	 }
     }
   
  
  This implies there must be a domain list file "/usr/local/squidGuard/db/local/domains" that may simply look like:
     teledanmark.no
   
  
   Example 3 -
   Blocking the access for unknown or unprivileged clients:
   Example 3 -
   Blocking the access for unknown or unprivileged clients:
  
     logdir /usr/local/squidGuard/log
     dbhome /usr/local/squidGuard/db
     src privileged {
	 ip	10.0.0.1 10.0.0.73 10.0.0.233	# ONE OF single clients
	 ip	10.0.0.10-10.0.0.20		# OR WITHIN range 10.0.0.10 - 10.0.0.20
	 ip	10.0.1.32/27			# OR WITHIN range 10.0.1.32 - 10.0.1.63
	 ip	10.0.2.0/255.255.255.0		# OR WITHIN range 10.0.2.0  - 10.0.2.255
						# AND
	 domain foo.bar				# MATCH foo.bar. OR *.foo.bar.
     }
     acl {
	 privileged {
	     pass all
	 }
	 default {
	     pass none
	     redirect http://info.foo.bar/cgi/blocked?clientaddr=%a&clientname=%n&clientuser=%i&clientgroup=%s&url=%u
	 }
     }
   
  
  Using client domainname match implies reverse lookup is enabled (log_fqdn on) in squid.conf.
     teledanmark.no
   
  
   Example 4 -
   Blocking inappropriate sites:
   Example 4 -
   Blocking inappropriate sites:
  
     logdir /usr/local/squidGuard/log
     dbhome /usr/local/squidGuard/db
     dest porn {
	 domainlist porn/domains
	 urllist    porn/urls
     }
     acl {
	 default {
	     pass !porn all
	     redirect http://localhost/cgi/blocked?clientaddr=%a&clientname=%n&clientuser=%i&clientgroup=%s&url=%u
	 }
     }
   
  
  This implies there must be a domain list file "/usr/local/squidGuard/db/porn/domains" and a domain list file "/usr/local/squidGuard/db/porn/urls". The domain list file may have a zillion lines like:
     porn.com
     sex.com
   
  
  The "url list file may have an other zillion lines like:
     foo.com/~porn
     bar.com/img/sex
   
  
   Example 5 -
   Blocking inappropriate sites for some users and blocking unknown
   clients:
   Example 5 -
   Blocking inappropriate sites for some users and blocking unknown
   clients:
  
     logdir /usr/local/squidGuard/log
     dbhome /usr/local/squidGuard/db
     src grownups {
	 ip	   10.0.0.0/24	  # range 10.0.0.0  - 10.0.0.255
			       # AND
	 user   foo bar	  # ident foo or bar
     }
     src kids {
	 ip	   10.0.0.0/22	  # range 10.0.0.0 - 10.0.3.255
     }
     dest porn {
	 domainlist porn/domains
	 urllist    porn/urls
     }
     acl {
	 grownups {
	     pass all
	 }
	 kids {
	     pass !porn all
	 }
	 default {
	     pass none
	     redirect http://info.foo.bar/cgi/blocked?clientaddr=%a&clientname=%n&clientuser=%i&clientgroup=%s&targetgroup=%t&url=%u
	 }
     }
   
  
  Using userident match implies RFC931/ident lookup is enabled in squid.conf, optionally only for the actual client groups, and that foo and bar's workstations must support RFC931.
 Example 6 -
   Blocking inappropriate sites partially with regex:
   Example 6 -
   Blocking inappropriate sites partially with regex:
  
    + ensuring local and good sites are passed
   even if they would match a blocking regex:
   
    + limiting the usage of IP-address URLs:
  
     logdir /usr/local/squidGuard/log
     dbhome /usr/local/squidGuard/db
     dest local {
	 domainlist     local/domains
     }
     dest good {
	 domainlist     local/domains
     }
     dest porn {
	 domainlist     porn/domains
	 urllist        porn/urls
	 expressionlist porn/expressions
     }
     acl {
	 default {
	     pass local good !in-addr !porn all
	     redirect http://localhost/cgi/blocked?clientaddr=%a&clientname=%n&clientuser=%i&clientgroup=%s&url=%u
	 }
     }
   
  
   Example 7 -
   Blocking inappropriate sites within business hours only:
   Example 7 -
   Blocking inappropriate sites within business hours only:
  
     logdir /usr/local/squidGuard/log
     dbhome /usr/local/squidGuard/db
     time leisure-time {
	 weekly * 00:00-08:00 17:00-24:00	# night and evening
	 weekly fridays 16:00-17:00		# weekend
	 weekly saturdays sundays		# weekend
	 date	*.01.01				# New Year's Day
	 date	*.05.01				# Labour Day
	 date	*.05.17				# National Day
	 date	*.12.24 12:00-24:00		# Christmas Eve
	 date	*.12.25				# Christmas Day
	 date	*.12.26				# Boxing Day
	 date	1999.03.31 12:00.24:00		# Ash Wednesday
	 date	1999.04.01-1999.04.05		# Easter
	 date	1999.05.13 1999.05.24		# Ascension Day and Whitsun
	 date	2000.04.19 12:00.24:00		# Ash Wednesday y2000
	 date	2000.04.20-2000.04.24		# Easter y2000
	 date	2000.06.01 2000.06.12		# Ascension Day and Whitsun y2000
     }
     src grownups {
	 ip	10.0.0.0/24			# range 10.0.0.0  - 10.0.0.255
						# AND
	 user	foo bar				# ident foo or bar
     }
     src kids {
	 ip	10.0.0.0/22			# range 10.0.0.0 - 10.0.3.255
     }
     dest porn {
	 domainlist	porn/domains		# file listing domains	(clear text)
	 urllist	porn/urls		# file listing URLs	(clear text)
	 expressionlist porn/expressions	# file with expressions (clear text regex)
	 redirect       302:http://info.foo.bar/images/blocked.gif
						# redirect matches to this URL
	 log anonymous  porn.log		# log redirects anonymized to logdir/porn.log
     }
     acl {
	 grownups within leisure-time {
	     pass all				# don't censor peoples leisure-time
	 } else {
	     pass !in-addr !porn all		# restrict access during business hours
	 }
	 kids {
	     pass !porn all			# protect the kids 24h anyway
	 }
	 default {
	     pass none				# reject unknown clients
	     redirect http://info.foo.bar/cgi/blocked?clientaddr=%a&clientname=%n&clientuser=%i&clientgroup=%s&targetgroup=%t&url=%u
	 }
     }
   
  
  |   |   | 
|   |   | 
|   |