Web filtering for IPCop using squidGuard


squidGuard describes itself as: "An ultrafast and free filter, redirector and access controller for Squid". In my experience, it is the ideal web filter for use with Smoothwall and IpCop since it is lightweight and easy to set up. I use it on an i486, 33Mhz system with 18Mb of Ram and 500Mb of hard drive - and while there is a minor performance hit, the hit is not significant.

This simple how-to describes the steps I took to install squidGuard on my system - it should work for yours too.


These notes, sample files and tools are supplied free of charge in the hope that they will prove useful. The files are provided under the terms of the GNU General Public License (GPL) and come with no warranty or guarantee what so ever. The author of this note, his employer and the author of the software referenced by it will not be held responsible for any damage inflicted, whether caused directly or indirectly by following (or attempting to follow) the advise given, or using (or attempting to use) the software referenced.

All of which guff means - I think this works, but all of the risk of following these instructions lies firmly in your own court.


These notes were written with reference to ..

  • SmoothWall GPL 1.0 system with patch 4 installed
  • IPCop version 1.3.0 with patch 2 installed.

I am also told (thank you Brian Biggs) that this procedure works for SmoothWall express 2.0.

I have not tried it on a GPL 2.0 system or earlier IPCop systems - but my guess is that it will work on those platforms too. If you are willing to try out this procedure on any of these other platforms and let me know about your progress, I would be delighted to hear from you. I can then publish the results of your efforts for others to benefit from.

Step 1 : Obtain the squidGuard sources or binary

Either: Sources (Recommended)

Download these from http://www.squidguard.org. I used the sources for version 1.2.0, which was the "current" version in May 2003, when I installed this stuff on my own system.

Now, go to step 2 to compile the sources

Or: Pre-compiled binary (For the lazy).

NB: This file is Available under GPL License, and comes with no absolutely warranty at all

If you dont have the facilities, time, knowledge or will to compile these yourself, you can download my compiled version of the file (version 1.2.0) from here. After downloading, please check that "md5sum squidGuard-1.2.0.gz" returns "39a76832a70ae7508f7cd3b0d2fd4a9f".

Note that this file needs to be unzipped (gunzip), renamed to 'squidGuard' and given the "execute" mode before use, like this...

gunzip squidGuard-1.2.0
mv squidGuard-1.2.0 squidGuard
chmod +x squidGuard

If you choose this route, you can now skip step 2 and jump straight to step 3. Also note that this file is supplied under the terms of the GNU General Public License, and comes with no Warranty of any kind.

Step 2 : Extract, Modify and Compile the sources.

  • Place the tarball onto a Linux system with a C compiler (I used a RedHat 7.3 system) and un-tar them, using the command..
tar xvfz squidGuard-1.2.0.tar.gz
  • You will need the "db3" and "db3-devel" rpms installed on your compilation system. If these are missing, obtain them from the RedHat CD or download site, and install onto your compilation system (not the firewall).
  • CD into the directory containing the untarred sources
cd squidGuard-1.2.0
  • Run the "./configure" command and verify that it doesn't report any errors.
  • Edit the files "Makefile" and "src/Makefile" to add the option "-static" to the end of the lines that start with the text "CFLAGS =" and/or "LDFLAGS =". The modified lines then look something like this...
CFLAGS = -g -O2 -I/usr/local/BerkeleyDB/include -static
LDFLAGS = -L/usr/local/BerkeleyDB/lib -static
  • We take this step in order to solve any problems associated with the different versions of the C run time library on your firewall and compilation system. It does mean that the squidGuard binary is larger than it need be, but it saves on other potential headaches.Run the command "make" to build the software and verify that no error messages are displayed.
  • Check that the software really has been built using static libraries by running the command..
ldd src/squidGuard
  • This should display the text: "not a dynamic executable".


Step 3 : Install the compiled software on the firewall box.

  • Copy the file src/squidGuard to /usr/local/bin/squidGuard on your firewall system. You can do this using "sftp" or "scp". The scp command line is..
cd src
scp -P 222 squidGuard root@firewall-ip-address:/usr/local/bin
  • Note: replace "firewall-ip-address" with the IP address of your firewall

Step 4 : Download and install the blacklist files.

  • These are available for download from the squidGuard site.
  • Once downloaded, copy the blacklists.tar.gz file to the /tmp directory of your firewall box using scp ..
scp -P 222 blacklists.tar.gz root@firewall-ip-address:/tmp
  • Log in to your firewall box using ssh, as the "root" user.
ssh -p 222 root@firewall-ip-address
  • Un-tar the blacklist files and copy into place on the firewall, using the following commands (on the firewall box)..
cd /tmp
tar xvfz blacklists.tar.gz
cd /usr/local
mkdir -p squidGuard/db/dest
mkdir -p squidGuard/log
cd squidGuard/db/dest
cp -a /tmp/blacklists/* .

Step 5 : Set up the "blocked" notification script.

  • This the CGI script that creates the page that is displayed when a user browses to a URL or domain that is "blocked" by your firewall's squidGuard.
  • Create the perl CGI script in /home/httpd/cgi-bin/blocked to report (and log) accessed to blocked web pages. You are welcome to take a copy of the one I use from here. This is available under the terms of the GPL license, and comes with no warranty or support.
  • If you are using my "blocked" script (downloaded above), then you should do the following to install it..Copy it to /home/httpd/cgi-bin/blocked on the firewall box using these commands on the download/development system
dos2unix < blocked.txt > blocked
chmod +x blocked
scp -P 222 blocked root@firewall-ip-address:/home/httpd/cgi-bin/blocked
  • Make it "executable" using the command on the firewall box..
chmod 755 /home/httpd/cgi-bin/blocked
  • On an IPCop system you must now edit the file /etc/httpd/conf/httpd.conf to allow the blocked script to be run without the need to enter a password. To make this change, modify the following section by adding the lines shown in red..
<Directory /home/httpd/cgi-bin>
    AllowOverride None
    Options None
    AuthName "Restricted"
    AuthType Basic
    AuthUserFile /var/ipcop/auth/users
    Require user admin
    <Files index.cgi>
        Satisfy Any
        Allow from All
    <Files dial.cgi>
         Require user admin dial
    <Files blocked>
         Satisfy Any

This change will take effect after a reboot (which we will do at the end of the procedure).

Step 6 : Set up 'log file rotation'

  • Download the log file rotation script from here, and install it as /etc/logrotate.d/squidGuard on your firewall system. This file instructs the system to 'rotate' the log file /var/log/squid/blocked.log once a week, and to compress it using gzip in the process. A maximum of 5 backdated copies of the file are retained - meaning that you have 5 weeks of history kept for review. Edit this file if you want something different from this.
dos2unix < logrotate-squidGuard.txt > logrotate-squidGuard
chmod +x logroate-squidGuard
scp -P 222 logrotate-squidGuard root@firewall-ip-address:/etc/logrotate.d/squidGuard
  • Ensure that the ownership and modes of the file are correct by entering the following commands (on the firewall box)
cd /etc/logrotate.d
chown root.root squidGuard
chmod 644 squidGuard
  • Create the initial (zero length) log file using the commands..
touch /var/log/squid/blocked.log
chown nobody.nobody /var/log/squid/blocked.log

Step 7 : Configure squidGuard

  • Create the squidGuard configuration file /usr/local/squidGuard/squidGuard.conf. You can download an example one that will work with the system as we have installed it so far from here (but note the comments it contains about the edit you must make to it for it to work). Refer to the squidGuard web site's documentation pages to discover how to change the configuration to meet your needs.
  • The sample configuration file is written to work with the sample 'blocked' script that you may have used in step 5. If you know enough about what you are doing, and have supplied your own 'blocked' script then you may need to change the config file to match.
  • Build the blacklist databases from the source files by running the following commands on the firewall box (the 2nd of these can take a reasonably long time [2 1/2 minutes on my i486DX2/66 system], so be patient).
chmod +x /usr/local/bin/squidGuard
/usr/local/bin/squidGuard -C all -d
  • Verify that this runs without errors.
  • Change the ownership of all the files in the squidGuard tree to belong to the user 'squid', using the commands..
cd /usr/local
chown -R squid.squid squidGuard


Step 8 : Configure squid

  • Patch the squid configuration to arrange for it to invoke the squidGuard plug-in when it starts. To do this, edit the file /var/smoothwall/proxy/acl (or /var/ipcop/proxy/acl) and add the following lines to the end of the file..
# Install squidGuard plug-in - Manual edit [put date here]
redirect_program /usr/local/bin/squidGuard
  • Use the web management interface for your firewall to turn web proxying on. You do this by ..
    • browse to the "services" section, "web proxy" page
    • set the "enabled" flag to "on" (checked)
    • set the "transparent" flag to "on" (on IPCop)
    • Click the "save" button.
    • On a SmoothWall system...
      • Once the 'save' action has completed, verify that the squid proxy is actually running - for some reason, it doesnt always start first time and may require you to click the 'start' button a second time (but dont do this unless the first attempt failed). To verify whether squid is running, use the firewall web management interface as follows..
        • Browse to the 'info' page, and the 'status' sub-page (which is the usual default).
        • Verify that the 'web proxy' is shown as being in the 'RUNNING' state. If it isnt, then revist the "services/web proxy" page and click 'start' again - then recheck.
      • On an IPCop system...
        • I have found that the 'save' button doesnt actually start, restart or stop the squid and squidGuard software, but that a reboot is required. So - reboot the machine now and then verify that the web proxy service is running using the "info" page of the web management interface.This is not a problem with the squidGuard installation described here, but seems to be a fault with IPCop 1.3.0 - please dont mail me about this issue. Thanks.

Finished! - But note ..

Well, that should be that - squidGuard is (well: should be) now running, and your web browsing should be filtered by the squidGuard rules. From experience, there are a few points that it is worth making at this stage...

  • SquidGuard's filtering isnt perfect - it filters on the basis of the strings contained in the web page URLs that you access, not on the basis of the content of the pages. This has the possitive benefit that it doesnt slow your web browsing down too much, and can be run on fairly low-power machines. But it has it's negative side too - any pages that dont have recognisably 'bad' URLs wont be filtered. This means that the (fictional) web page http://www.angels.com/pictures.html will probably 'get through' (since it looks like a religious site) even if it actually contains pictures that you would rather not show your kids or mother in law.
  • You are free to "improve" the filtering by watching log files of web pages accessed (/var/log/squid/access.log) and the pages that have been blocked (/var/log/squid/blocked.log), and changing the filtering rules to meet your personal requirements.
  • Read the squidGuard on-line documentation. Adding your own rules is quite nice and easy, but the author of this note will not get involved in answering questions about rule writing.
  • Aim to place your own filtering rules in different rule sets than the ones delivered with the blacklists files - this means that you can regularly download the latest blacklists without losing your own edits.
  • Be aware of the fact that we have editted files that are part of the standard software release - the /var/smoothwall/proxy/acl (or /var/ipcop/proxy/acl) file and /etc/httpd/conf/httpd.conf if you are working with IPCop. It is always possible that a future patch will replace these file, meaning that the changes will be lost. For this reason, you should check the files after installing patches, and re-enter the new lines if they have vanished.

Finally - let the me know about your experiences using this advise. If you have problems, I cant promise to solve them, but I am interested to hear about them - so that I can address problems that are commonly encountered.

Scroll to Top