|
|
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..
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:
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 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, 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, 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 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 }
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.
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.
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.)).
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.
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:
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:
For optimal performance try:
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 } }
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 } }
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
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
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
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.
+ 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 } }
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 } }
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |