Installing squidGuard
squidGuard is an ultrafast and free filter, redirector and access controller for Squid By Pål Baltzersen and Lars Erik Håland Copyright © 1999-2000, Tele Danmark InterNordia Visitors: (Since 2002-01-08 19:54:05)

This page was last modified 2002-01-08

## Installation instructions

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:

### For the impatient/experienced:

1. Install version 2.X of the Berkeley DB library (if not already installed on your system)
2. `./configure`
3. `make`
4. `make install`
5. Create a `squidGuard.conf` that suits your needs
6. Create the domain, url and expression lists you want
7. Test/simulate
8. Configure squid to use squidGuard as the redirector and specify the number of redirector processes you want
9. Send Squid a `HUP` signal
   Voilà!

### For the less impatient:

1. 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.
2. 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 Tele Danmark we use:
     `

         #!/bin/sh -
            cd build_unix
            CC=gcc \
            CXX=g++ \
            CFLAGS="-O3 -D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64" \
            CXXFLAGS="-O3 -D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64" \
            ../dist/configure \
              --verbose \
              --target=sparc-sun-solaris \
              --enable-dynamic \
              --enable-compat185 \
              --enable-rpc \
              --prefix=/local

     `
   By default the more recent versions of the Berkeley DB library installs itself under `/usr/local/BerkeleyDB/{lib,include,bin,docs}`
3. 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``
4. 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 Tele Danmark we use:
     `

         #!/bin/sh -
            CC="gcc" \
            CFLAGS="-O3 -Wall" \
            LIBS="-R/local/lib -lnls" \
            ./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.teledanmark.no/filter/conf/filter.conf \
            --with-sg-logdir=/var/spool/www/hosts/proxy.teledanmark.no/filter/logs \
            --with-sg-dbhome=/var/spool/www/hosts/proxy.teledanmark.no/filter/db

     `
5. 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.
6. To test the newly built squidGuard run:
     `make test`
7. 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`.
8. Make a configuration file for squidGuard. Start with a minimal configuration and extend as your experience and needs grow.
9. Make the destination lists (databases) you want (if any at all).
10. 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://freeware.teledanmark.no/squidGuard/ 10.1.2.3/pc123.teledanmark.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.
11. 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.
12. 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.
13. Send Squid a `HUP` signal:
      `kill -HUP `cat /somewhere/squid.pid``
    or
      `squid -k reconfigure`
14. Test with a browser.