README file for SquidClamav Version 5.3

SquidClamav - A Clamav Antivirus Redirector for Squid -
	(http://squidclamav.darold.net/)

REQUIREMENT:
------------

You need libcurl 7.12.1 at least and a standard install of regex. Those should
already be installed in modern distro.


INSTALLATION:
-------------

Please see INSTALL file for installation instructions, for express install
just do the following :

	./configure
	make
	make install

and edit /etc/squidclamav.conf to match you needs. Base install directory,
you can change it with the --prefix cnofiguration option like follow:

	./configure --prefix=/usr



SQUID 2.5 CONFIGURATION:
------------------------

To integrate squidclamav to your squid cache just edit the squid.conf
file and set the following:

on ACL definition you should have declared:

        acl localhost src 127.0.0.1/255.255.255.255
        acl to_localhost dst 127.0.0.0/8
	acl purge method PURGE

on http_acces definition you should declared the following :

        http_access deny to_localhost
        http_access allow localhost
	http_access allow purge localhost
	http_access deny purge
        redirector_access deny localhost

and on the redirect section the following:

        redirect_program /usr/local/bin/squidclamav
        redirect_children 15

If you have huge access and enough memory set the redirect_children to
upper value.

Note that the purge acl is only required if you enable trust_cache option.


SQUID 2.6 / 2.7 / 3.0 CONFIGURATION:
------------------------------------

As 2.6 has signifiant change in the configuration file regarding
redirector, to integrate squidclamav to your squid cache just edit
the squid.conf file and set the following:

on ACL definition you should have declared:

        acl localhost src 127.0.0.1/255.255.255.255
        acl to_localhost dst 127.0.0.0/8
	acl purge method PURGE

on http_acces definition you should declared the follwing :

        http_access deny to_localhost
        http_access allow localhost
	http_access allow purge localhost
	http_access deny purge
        url_rewrite_access deny localhost

and on the redirect section the following:

        url_rewrite_program /usr/local/bin/squidclamav
        url_rewrite_children 15

If you have huge access and enough memory set the url_rewrite_children to
upper value.

Note that the purge acl is only required if you enable trust_cache option.


CONFIGURING CLAMD CONNECTION:
-----------------------------

You have 3 configuration option to set the connection to clamd daemon.

If you use unix local socket, just set clamd_local to the socket path
as follow:

	clamd_local /tmp/clamd

If you use TCP socket set the clamd_ip and clamd_port as follow:

	clamd_ip 192.168.1.5
	clamd_port 3310

DO NOT set the clamd_local if you want to use TCP socket !!!

If you have multiple ClamAv servers, SquidClamav is able to do failover between
them. You just have to set 'clamd_ip' to a list of ip adresses separated by a
coma. Do not insert space character in this list it will break all. For example:

        clamd_ip 192.168.1.5,192.168.1.13,192.168.1.9
	clamd_port 3310

You can set up to 5 clamd server. The clamd port must be the same for all these
servers as 'clamd_port' only accept one value.


SIGNALS
-------

To force SquidClamav to reread his configuration file you have to reconfigure Squid,
to do that just send the 'reconfigure' signal to Squid: "squid -k reconfigure"
Squid will reread his configuration file and restart all redirectors.


SQUICLAMAV CONFIGURATION:
-------------------------

See doc/README


IMPROVING SPEED
---------------

See doc/README


TESTING SQUIDCLAMAV:
--------------------

Once you have installed+configured squidclamav and modified Squid configuration
the best way to see if squidclamav is well working is to test it. If you want
to see detailled output set the debug option to 1 in squidclamav.conf file.
If you want more debug trace set debug option to 2.

Open a terminal onto your proxy server and run squidclamav, this will give you
this kind of output:

	root@theproxy# squidclamav 
	SquidClamav running as UID 0: writing logs to stderr
	Thu ... 2008 LOG Reading configuration from /etc/squidclamav.conf
	Thu ... 2008 LOG Chaining with /usr/local/squidGuard/bin/squidGuard
	Thu ... 2008 LOG SquidClamav (PID 7012) started
	Thu ... 2008 bidirectional pipe to squidGuard childs ready...

At this point squidclamav is waiting for squid input. The input line consists
of four fields:

	URL ip-address/fqdn ident method

For example, let's check slashdot:

	http://www.slashdot.org/ 192.168.1.3 mylog GET

As this site doesn't contains any virus :-) squidclamav simply return an empty
line. Now to test clamav antivir let's type the following entry:

	http://www.eicar.org/download/eicar.com 192.168.1.3 mylog GET

The result must be a redirection the clwarn.cgi as follow:

	Thu ... 2008 LOG Redirecting URL to: http://theproxy.com/cgi-bin/clwarn.cgi?url=http://www.eicar.org/download/eicar.com&source=192.168.1.3&user=mylog&virus=stream:+Eicar-Test-Signature+FOUND
	http://theproxy.com/cgi-bin/clwarn.cgi?url=http://www.eicar.org/download/eicar.com&source=192.168.1.3&user=mylog&virus=stream:+Eicar-Test-Signature+FOUND 192.168.1.3 mylog GET

This last line is the request returned to squid.
Type Ctrl+C to quit.


FEEDBACK:
---------

If you find it useful, I'd like to know - please send email
to gilles AT darold DOT net

ACKNOWLEDGEMENT:
----------------

I must thanks a lot all the great contributors:

	- Leonardo Humberto Liporati from www.ig.com.br
	- Dale Laushman from The Uptime Group
	- Rainer schoepf from Proteosys.com

and all others who help me to build a usefull and reliable product.


COPYRIGHT:
----------

This project is a modified version of the excellent Squirm Redirector for Squid
Maintained by Chris Foote, and copyrighted as follow :

        Copyright (C) 1998 Chris Foote & Wayne Piekarski

The original Squirm version used was squirm-1.0betaB. Some other parts are
cut and paste from the ex1.c program given in the ClamAv distribution and
are copyrighted: Copyright (C) 2002 - 2004 Tomasz Kojm

All other code: Copyright (C) 2005-2010 Gilles Darold


LICENSE:
--------

Copyright (C) 2005-2010 Gilles Darold

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Please see the file COPYING in this directory for full copyright
information.