
   [1][eto-small.gif] The master version is at
   [2]http://info.ost.eltele.no/freeware/squidGuard/installation.shtml
   This page was last modified on Wednesday, 28-Jul-1999 13:45:32 MET DST
   
   A guide to squidGuard installation [3][squidGuard.gif] 
   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.
   
Contents

     * [4]In general
     * [5]Quick install - For the impatient/experienced:
     * [6]Detailed install - For the less impatient:
     * [7]Copyright
     * [8]Feedback
     * [9]Authors
       
In general

   The good news:
          squidGuard uses Squid's [10]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 [11]Berkeley DB library (if not already
       installed on your system)
    2. [12]./configure
    3. [13]make
    4. [14]make install
    5. Create a [15]squidGuard.conf that suits your needs
    6. Create the [16]domain, [17]url and [18]expression lists you want
    7. Test/simulate
    8. [19]Configure squid to use squidGuard as the redirector and
       specify the number of redirector processes you want
    9. [20]Send Squid a HUP signal
       [21]Voil!
       
  For the less impatient:
  
    1. Besides [22]Squid you need a basic UNIX development environment
       with a [23]make compatible build tool, an ANSI [24]C compiler, a
       [25]yacc compatible parser generator, a [26]lex compatible lexical
       analyzer generator and a [27]regcomp()/regexec() compatible
       regular expression library. You also need [28]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 [29]Berkeley DB library installed on
       your system. If you don't already have it, [30]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 [31]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 [32]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}
    3. [33]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 [34]GNU auto configuration for maximum
       portability and easy compilation setup. For a default environment,
       simply run:
       
        ./configure
                
       If you have [35]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 [36]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.elt
                      ele.no/filter/conf/filter.conf\
                      --with-sg-logdir=/var/spool/www/hosts/proxy.ost.elt
                      ele.no/filter/logs\
                      --with-sg-dbhome=/var/spool/www/hosts/proxy.ost.elt
                      ele.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 [37]configuration file for squidGuard. Start with a
       [38]minimal configuration and extend as your experience and needs
       grow.
    9. Make the [39]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://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.rew
                rite > test.rewrite.out
                prefix/bin/squidGuard -c /your/squidGuard.conf < test.blo
                ck > 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 [40]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.c
                onf
                
       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
       [41]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.
       
Copyright

   squidGuard is covered by the [42]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 [43]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 [44]ElTele st AS; and
       most likely with [45]Sleepycat too for the DB part.
       
   For more copyright details you have to read the [46]GNU General Public
   Licence (GPL).
   
Feedback

   If you find a bug, have a bug fix, a contribution, a question or a
   comment on squidGuard feel free to send it to
   [47]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 [48]very welcome too.. They makes [49]us even more
   enthusiastic!
   
Authors

   squidGuard was designed by [50]Pl Baltzersen and implemented by
   [51]Lars Erik Hland
   at [52]ElTele st AS and made freely available by permission of
   [53]ElTele st AS.
   
   This page is written and maintained by [54]Pl Baltzersen.
   Please [55]report any errors, broken links, missing stuff, typos,
   misspellings, wrong grammar, norwenglish phrases etc. you discover.
   
       [56][gnu-logo.gif] [57][perl-logo.gif] [58][solaris-logo.gif]
                 [59][sun-logo.gif] [60][eltele-logo.gif] 
                                      
      [61][apache-logo.gif] [62][squid-logo.gif] [63][squidGuard.gif] 
                                      
                             [64][identd.gif] 

References

   1. http://www.ost.eltele.no/
   2. http://info.ost.eltele.no/freeware/squidGuard/
   3. http://ftp.ost.eltele.no/pub/www/proxy/squidGuard/
   4. http://info.ost.eltele.no/freeware/squidGuard/installation.shtml#General
   5. http://info.ost.eltele.no/freeware/squidGuard/installation.shtml#Quick_install
   6. http://info.ost.eltele.no/freeware/squidGuard/installation.shtml#Detailed_install
   7. http://info.ost.eltele.no/freeware/squidGuard/installation.shtml#Copyright
   8. http://info.ost.eltele.no/freeware/squidGuard/installation.shtml#Feedback
   9. http://info.ost.eltele.no/freeware/squidGuard/installation.shtml#Authors
  10. http://squid.nlanr.net/Squid/1.1/Release-Notes-1.1.txt
  11. http://info.ost.eltele.no/freeware/squidGuard/installation.shtml#Detailed_install_2
  12. http://info.ost.eltele.no/freeware/squidGuard/installation.shtml#Detailed_install_4
  13. http://info.ost.eltele.no/freeware/squidGuard/installation.shtml#Detailed_install_5
  14. http://info.ost.eltele.no/freeware/squidGuard/installation.shtml#Detailed_install_7
  15. http://info.ost.eltele.no/freeware/squidGuard/configuration.shtml
  16. http://info.ost.eltele.no/freeware/squidGuard/configuration.shtml#Domainlists
  17. http://info.ost.eltele.no/freeware/squidGuard/configuration.shtml#URLlists
  18. http://info.ost.eltele.no/freeware/squidGuard/configuration.shtml#Expressionlists
  19. http://info.ost.eltele.no/freeware/squidGuard/installation.shtml#Detailed_install_12
  20. http://info.ost.eltele.no/freeware/squidGuard/installation.shtml#Detailed_install_13
  21. http://info.ost.eltele.no/freeware/squidGuard/installation.shtml#Detailed_install_14
  22. http://info.ost.eltele.no/freeware/squidGuard/#Squid
  23. http://info.ost.eltele.no/freeware/squidGuard/#Gmake
  24. http://info.ost.eltele.no/freeware/squidGuard/#Gcc
  25. http://info.ost.eltele.no/freeware/squidGuard/#Bison
  26. http://info.ost.eltele.no/freeware/squidGuard/#Flex
  27. http://info.ost.eltele.no/freeware/squidGuard/#Regex
  28. http://info.ost.eltele.no/freeware/squidGuard/#Gzip
  29. http://info.ost.eltele.no/freeware/squidGuard/#DB
  30. http://info.ost.eltele.no/freeware/squidGuard/#DB
  31. mailto:squidguard@ost.eltele.no
  32. http://ftp.ost.eltele.no/pub/db/db.local.diff
  33. http://info.ost.eltele.no/freeware/squidGuard/#Downloading
  34. http://www.gnu.org/software/autoconf/
  35. http://info.ost.eltele.no/freeware/squidGuard/#Gcc
  36. http://www.ost.eltele.no/
  37. http://info.ost.eltele.no/freeware/squidGuard/configuration.shtml
  38. http://info.ost.eltele.no/freeware/squidGuard/configuration.shtml#Minimal
  39. http://info.ost.eltele.no/freeware/squidGuard/configuration.shtml#Lists
  40. http://info.ost.eltele.no/freeware/squidGuard/#Apache
  41. http://info.ost.eltele.no/freeware/squidGuard/installation.shtml#Defaultconfigfile
  42. http://www.gnu.org/copyleft/gpl.html
  43. http://www.ost.eltele.no/
  44. mailto:squidguard@ost.eltele.no?subject=squidGuard%20licensing
  45. http://www.sleepycat.com/db/licensing.html
  46. http://www.gnu.org/copyleft/gpl.html
  47. mailto:squidguard@ost.eltele.no
  48. mailto:squidguard@ost.eltele.no?subject=SquidGuard%20success%20report
  49. mailto:squidguard@ost.eltele.no
  50. mailto:pal.baltzersen@ost.eltele.no
  51. mailto:leh@nimrod.no
  52. http://www.ost.eltele.no/
  53. mailto:info@ost.eltele.no
  54. mailto:pal.baltzersen@ost.eltele.no
  55. mailto:squidguard@ost.eltele.no
  56. http://www.gnu.org/
  57. http://www.perl.com/
  58. http://www.sun.com/solaris/
  59. http://www.sun.com/servers/
  60. http://www.ost.eltele.no/
  61. http://www.apache.org/httpd.html
  62. http://squid.nlanr.net/
  63. http://info.ost.eltele.no/freeware/squidGuard/
  64. http://info.ost.eltele.no/freeware/identd/
