|
A guide to squidGuard installation
|
|
|
A free filter, redirector and access controller for Squid
|
Note: this page is primarily written for
squidGuard-1.0.x. Though most of it still applies to
squidGuard-0.9.x.
-
The good news:
-
squidGuard uses Squid's standard
redirector interface so no patching of Squid is
needed!
-
and the not so good news:
-
Currently we don't distribute precompiled versions of
squidGuard.
Though following these few steps should bring you
up and going with squidGuard within a few minutes, provided you
have the basic tools:
-
Install version 2.X of the Berkeley
DB library (if not already installed on your system)
-
./configure
-
make
-
make install
-
Create a squidGuard.conf that
suits your needs
-
Create the domain, url and expression lists you want
-
Test/simulate
-
Configure squid to use
squidGuard as the redirector and specify the number of
redirector processes you want
-
Send Squid a HUP
signal
Voilà!
-
Besides Squid you need a basic UNIX development
environment with a make compatible
build tool, an ANSI C compiler, a yacc compatible parser generator, a
lex compatible lexical analyzer
generator and a regcomp()/regexec() compatible
regular expression library. You also need gzip to unpack the
distribution. Don't despair: If you managed to install Squid
you most likely have all this! If not the links here points
you to all the free sources you need.
-
You need a version 2.X of the Berkeley DB library installed on your system. If
you don't already have it, download and
install the latest 2.X version. It should compile and install
right out of the box. (squidGuard is developed with Berkeley DB
version 2.x in mind, but it might work with Berkeley DB versions
1.85 and 1.86 too. If you have success linking and running with
versions 1.85 or 1.86 please report!)
Here is a
quick installation guide for the Berkeley DB library:
-
mkdir -p /local/src (or wherever you like)
cd /local/src
gzip -dc /wherever/db-2.y.z.tar.gz | tar xvf -
cd db-2.y.z/dist
./configure (optionally add the environment and flags you prefer) *)
make
make install
make clean (optional)
*) At Eltele Øst AS we apply this little
patch and use:
-
tcsh# (setenv CC "gcc";setenv CFLAGS "-O3 -Wall";\
./configure --verbose --target=sparc-sun-solaris\
-
--prefix=/local\
)
By default the more recent versions of the Berkeley DB library
installs itself under
/usr/local/BerkeleyDB/{lib,include,bin,docs}
-
Download squidGuard and unpack the
distribution with:
-
mkdir -p /local/src (or wherever you like)
cd /local/src
gzip -dc /wherever/squidGuard-x.y.z.tar.gz | tar xvf -
cd squidGuard-x.y.z
-
squidGuard now comes with GNU auto
configuration for maximum portability and easy compilation
setup. For a default environment, simply run:
-
./configure
If you have gcc you may want to force the use
of gcc and optimize more:
-
csh|tcsh# (setenv CC "gcc"; setenv CFLAGS "-O3";
./configure)
or
-
sh|bash|ksh# CC="gcc" CFLAGS="-O3" ./configure
depending on your shell. This will prepare Makefiles to compile
and optionally install the squidGuard executable as
/usr/local/bin/squidGuard. If you prefer to
install squidGuard as for instance
/local/squid/bin/squidGuard, use the option:
-
./configure --prefix=/local/squid
To avoid the need of runing
squidGuard with the command line option
"-c /wherever/filter.conf"*), you may want to
change the default to the actual location of the configuration
file at compile time by adding:
-
./configure --with-sg-config=/wherever/filter.conf
*)Note: squid-2.2.x up to STABLE2are broken and ignores the
argument list silently without passing it to the
redirector. Therefor with squid-2.2.x up to STABLE2 you
must specify the correct config file location with
--with-sg-config=... at compile time. Versions up to
2.1.PATCH2 do not have this problem.
To see the full list of
build configuration options run:
-
./configure --help
At ElTele Øst AS we build with
this setup:
-
tcsh# (setenv CC "gcc";setenv CFLAGS "-O3 -Wall";\
./configure --verbose --target=sparc-sun-solaris\
-
--prefix=/local/squid\
--with-db-lib=/local/lib\
--with-db-inc=/local/include\
--with-sg-config=/var/spool/www/hosts/proxy.ost.eltele.no/filter/conf/filter.conf\
--with-sg-logdir=/var/spool/www/hosts/proxy.ost.eltele.no/filter/logs\
--with-sg-dbhome=/var/spool/www/hosts/proxy.ost.eltele.no/filter/db\
)
-
Now simply run:
-
make
This should compile squidGuard without errors. If you compile with
gcc -Wall you may safely ignore warnings for the machine
generated code y.tab.{c,h} (from sg.y) and
lex.yy.c (from sg.l). You should probably
investigate other warnings and errors.
-
To test the newly built
squidGuard run:
-
make test
-
If all is OK run:
-
make install
This will install the squidGuard executable in
prefix/bin/squidGuard where prefix
is /usr/local unless you changed it with
--prefix=/some/where/else.
-
Make a configuration file for squidGuard. Start
with a minimal configuration
and extend as your experience and needs grow.
-
Make the destination lists (databases) you
want (if any at all).
-
Test your configuration
isolated. Put some sample requests in three files named something
like test.pass, test.rewrite and
test.block. (Omit test.rewrite if you don't have
rewrite rules.) The format of these files is:
-
URL ip-address/fqdn ident method
For instance:
-
http://info.ost.eltele.no/freeware/squidGuard/ 10.1.2.3/pc123.ost.eltele.no fdgh GET
http://bad.site.com/dirty/stuff/foo.htm 10.3.2.1/- - GET
The ip-address is mandatory, the fqdn and ident fields may be "-"
depending of how you have configured Squid with respect to reverce
DNS lookups and indent lookups. The request method is
GET, POST, etc.
Put some sample
requests that should pass transparently, be rewritten/redirected
and blocked in test.pass, test.rewrite and
test.block respectively. Now you are ready to simulate
real requests. Run the three simulations:
-
prefix/bin/squidGuard -c /your/squidGuard.conf < test.pass > test.pass.out
prefix/bin/squidGuard -c /your/squidGuard.conf < test.rewrite > test.rewrite.out
prefix/bin/squidGuard -c /your/squidGuard.conf < test.block > test.block.out
Check the pass output:
-
wc -l test.pass
wc -l test.pass.out
wc -w test.pass.out
The numerical results should be identical for the first two tests
and 0 for the last.
Check the rewrite/redirect output
(Omit if you don't have rewrite rules.):
-
wc -l test.rewrite
wc -l test.rewrite.out
diff test.rewrite test.rewrite.out | egrep -ic '^> ..* [0-9.]+/..* ..* [a-z]+$'
more test.rewrite.out
The numerical results should be identical for the first three
tests. Visually ensure the new URLs are as expected with the
more command.
Check the block output:
-
wc -l test.block
wc -l test.block.out
diff test.block test.block.out | egrep -ic '^> ..* [0-9.]+/..* ..* [a-z]+$'
more test.block.out
The numerical results should be identical for the first three
tests. Visually ensure the new URLs are as expected with the
more command.
-
Install the empty image,
stopsign image, dummy access denied page, the more or
less intelligent CGI page or whatever your redirectors points to,
on a web server that Squid can access; typically on the proxy
server or a nearby server. If you don't have a web server we
strongly recommend Apache although any
stable web server of your choice can be used.
-
Tell
Squid to use squidGuard as the redirector by uncommenting and
changing the following tags in squid.conf to:
-
redirect_program /prefix/bin/squidGuard
or if squidGuard's config file is somewhere else than set at
compile time*):
-
redirect_program /prefix/bin/squidGuard -c /wherever/squidGuard.conf
where prefix is /usr/local unless you
changed it with
--prefix=/some/where/else.
*)Note: squid-2.2.x up to STABLE2 are broken and ignores
the argument list silently without passing it to the
redirector. Therefor with squid-2.2.x up to STABLE2 you
must specify the correct config file location with
--with-sg-config=... at compile time. Versions up to
2.1.PATCH2 do not have this problem.
Also configuere the number of redirector processes you think you
want:
-
redirect_children 4
I really don't know why one should have more than one squidGuard
process on a single CPU system cince squidGuard never blocks
indefinitly like the cache_dns_program and
optional authenticate_program are more likely to
do. Of course with more redirectors there is a chance a request
that matches the first client group, rule and destination group
could sneak out before a request that matches the last rule. But
on the other hand more redirectors also slows down the system by
added overhead and memory usage. Anyway 4 seems like a fine number
to start with. We haven't done any benchmarking to find the best
value and it may vary with the actual configuration.
-
Send Squid a HUP
signal:
-
kill -HUP `cat /somewhere/squid.pid`
or
-
squid -k reconfigure
-
Test with a browser.
squidGuard is covered by the GNU General Public
Licence (GPL). The copyright boils down to:
-
You may use squidGuard in both free and commercial services
without fee or registration to ElTele Øst AS.
-
You may freely redistribute unchanged free copies of squidGuard;
precompiled or in source form.
-
There is no warranty for squidGuard.
-
You may not change the copyright.
-
You may not sell or use squidGuard in a commercial software
package without a written agreement with ElTele
Øst AS; and most likely with Sleepycat
too for the DB part.
For more copyright details you have to read the GNU General Public
Licence (GPL).
If you find a bug, have a bug fix, a contribution, a question or a
comment on squidGuard feel free to send it to squidguard@ost.eltele.no
-
The preferred bug fix format is context diff:
-
diff -c origfile fixedfile
-
or
-
diff -cr origdir fixeddir
-
Please explain what problem your diff fixes.
Success reports are very
welcome too.. They makes us even more
enthusiastic!
squidGuard was designed by Pål Baltzersen and
implemented by Lars Erik
Håland
at ElTele Øst
AS and made freely available by permission of ElTele Øst AS.
This page is written and maintained by Pål Baltzersen.
Please report any
errors, broken links, missing stuff, typos, misspellings, wrong
grammar, norwenglish phrases etc. you discover.