=head1 NAME

SquidClamav v6 - HTTP Antivirus for Squid based on ClamAv and the ICAP protocol

=head1 DESCRIPTION

SquidClamav v6 is an antivirus for the Squid proxy based on the ICAP protocol
and the awards-winning ClamAv anti-virus toolkit. Using it will help you
securing your home or enterprise network web traffic. SquidClamav is the most
efficient antivirus tool for HTTP traffic available for free, it is written
in C as a c-icap service and can handle several thousands of connections at once.

SquidClamav v6 only scan the HTTP stream sent by Squid through the ICAP server.
It doesn't make HTTP requests itself so this is a gain of performance and ensures
that the data scanned is the same as the user has requested.

Why use c-icap server? This is the only open source icap server written in C,
it is very fast and stable.

Why writing another clamav c-icap module? Well, to be honest, outside the
survival of SquidClamav, I think that using clamd instead of libclamav to scan
files is speediest and more simple than the srv_clamav module provided with the
c-icap server.

SquidClamav v6 is faster than any other HTTP antivirus and can handle several
thousands of simultaneous users at once, this is what we need.

The other unique feature of SquidClamav is that you can have Clamd failover by
setting up up to 4 clamd server IP addresses. When a clamd server is not reachable
in one second, SquidClamav switches to the next IP address.

If you are using ClamAV above 0.95, SquidClamav will have support for Google
Safe Browsing database. All signatures provided by Google Safe Browsing Database
will be prefixed with the Safebrowsing tag. If ClamAV reports:

	Safebrowsing.<something> FOUND

This will be redirected by squidclamav just like if a virus was found.


=head1 USAGE

=head2 Generic Program Information

SquidClamav v6 has been completely rewritten to be used through the Squid v3.x
ICAP feature allowing "on stream" scanning. It is now built as a c-icap server
service but keeps all features from v5 and is fully compatible with the old
SquidClamav configuration file. The squidclamav configuration file is unchanged
minus some obsolete directives.

This also means that SquidClamav can no more be run into an interactive console
for testing your URL. All debug information will now go to the c-icap logfile.

=head2 Installing Squid

=head2 Setting SquidClamav as Squid Icap service

I want SquidClamav to be installed as a c-icap service, to be configured as
easy as possible and to be compatible with the old configuration file. This 
means that I voluntary omit some capabilities of c-icap server to preserve a 
full compatibility with the old squidclamav.conf file.

=head3 Squid v3.x installation and configuration

To have full and stable icap support with Squid you must use the 3.x branch
and configure squid with the following option:

	--enable-icap-client

I don't know what other options you are using but you have to add this one
to your configure command. If you prefer to use distribution packaging you
may already have it configured like this if you can install the c-icap 
package too.

If you don't know, run the following command an search for the configuration
directive: --enable-icap-client

	/usr/local/squid/sbin/squid -v | grep "enable-icap-client"

If it is not enable you must reinstall Squid with this configuration option or
install the additional packages.

Once you have it enabled, to integrate c-icap and SquidClamav to your squid
cache just edit squid.conf and set the following directives.

=over 4

=item Squid 3.4.x configuration

There are some configuration differences between 3.1.x and 3.4.x Squid version.
Here are the directives I use for Squid 3.4.x:

	icap_enable on
	icap_send_client_ip on
	icap_send_client_username on
	icap_client_username_encode off
	icap_client_username_header X-Authenticated-User
	icap_preview_enable on
	icap_preview_size 1024
	icap_service service_avi_req reqmod_precache
	icap://localhost:1344/squidclamav bypass=off
	adaptation_access service_avi_req allow all
	icap_service service_avi_resp respmod_precache
	icap://localhost:1344/squidclamav bypass=on
	adaptation_access service_avi_resp allow all

If you don't know where to put them in squid.conf, just search for 'icap_.*'
and add those configuration lines at the end of the icap section.

=item Squid 3.1.x configuration

There are some configuration differences between 3.1.x and 3.0.x Squid version.
Here are the directives I use for Squid 3.1.x:

	icap_enable on
	icap_send_client_ip on
	icap_send_client_username on
	icap_client_username_encode off
	icap_client_username_header X-Authenticated-User
	icap_preview_enable on
	icap_preview_size 1024
	icap_service service_req reqmod_precache bypass=1 icap://127.0.0.1:1344/squidclamav
	adaptation_access service_req allow all
	icap_service service_resp respmod_precache bypass=1 icap://127.0.0.1:1344/squidclamav
	adaptation_access service_resp allow all

If you don't know where to put them in squid.conf, just search for 'icap_.*'
and add those configuration lines at the end of the icap section.

Here the bypass is set to 1, that means that in case of squidclamav problems
squid will simply ignore the error and continue. This is the equivalent of the
bridge mode in version 5.x of suidclamav.


=item Squid 3.0.x configuration

For squid 3.0.x you must replace 'bypass=1' by '1' or 'bypass=0' by '0' and
the access to the service is defined at a class level. Only the last four
configuration lines change from version 3.1.x.

	icap_enable on
	icap_send_client_ip on
	icap_send_client_username on
	icap_client_username_encode off
	icap_client_username_header X-Authenticated-User
	icap_preview_enable on
	icap_preview_size 1024
	icap_service service_req reqmod_precache 1 icap://127.0.0.1:1344/squidclamav
	icap_service service_resp respmod_precache 1 icap://127.0.0.1:1344/squidclamav
	icap_class class_avreq service_req
	icap_class class_avresp service_resp
	icap_access class_avreq allow all
	icap_access class_avresp allow all

If you don't know where to put them in squid.conf, just search for 'icap_.*'
and add those configuration lines at the end of the icap section.

Here the bypass is set to 1, that means that in case of squidclamav problems
squid will simply ignore the error and continue. This is the equivalent of the
bridge mode in version 5.x of suidclamav.

=back

What do that configuration directives do? They enable Squid's ICAP client and 
tell Squid to send the logged username and client's IP address to the ICAP server. 
They also enable preview for faster SquidClamav work. The last four lines define 
how to call the ICAP server. Here we call the squidclamav service on localhost and
port 1344 (host and port can be changed). The bypass parameter set to 1 means that 
Squid will continue without bothering about ICAP server or SquidClamav failure. This 
is just like the old bridge mode in previous releases of SquidClamAV. I don't want 
users to be bored by a continuously error message if SquidClamav or c-icap produce
errors or if there's an error in the configuration file. Users don't have to know 
about that, they want to surf and don't care about your problems :-) 
If you don't think like me, just set the bypass argument to 0 and Squid will return 
an error message in case of a failure.

=head3 C-icap server installation/configuration

If you don't have package solutions or encounter problems when installing SquidClamav
I recommand you to install the c-icap server from source as following. You can
download it from SourceForge at http://c-icap.sourceforge.net/. Choose version
c-icap-0.3.2 or later versions, then run:

	./configure --prefix=/usr/local/c-icap --enable-large-files
	make
	make install

Then, edit the file /usr/local/c-icap/etc/c-icap.conf. It contains a set of
documented values that configure the c-icap server. To enable the support of
SquidClamav just add the following line to the end of the file:

	Service squidclamav squidclamav.so

Don't care about the srv_clamav.* configuration directives, this will not break
anything. SquidClamav doesn't use them but reads its own directives from the file
/etc/squidclamav.conf.

You can disable the c-icap embedded modules by commenting out these lines:

	#Service url_check_module srv_url_check.so
	#Service antivirus_module srv_clamav.so

This will preserve some resources.

Following your installation you may need to create the /var/run/c-icap/ where
c-icap server is writing pid and socket file.

You may also want to change the user/group owning c-icap's processes. By default
the owner is the user/group who runs the program. I recommand you to change them
to the same user/group running your Squid cache. For example:

	User proxy
	Group proxy

Of course you will need to change the owner of directory /var/run/c-icap/ and
the directory of your server log. See the ServerLog directive to get the path.
For me, I use the following commands to set the good rights on my installation:

	mkdir /var/run/c-icap/
	chown -R proxy:proxy /var/run/c-icap/
	chown -R proxy:proxy /usr/local/c-icap/

After that you can run the c-icap server as explained below.

=head3 SquidClamav installation/configuration

Installing SquidClamav requires that you already have installed the c-icap
as explained above. You must provide the installation path of c-icap to the
configure command as following:

	./configure
	make
	make install

This will install the squidclamav.so library into the c-icap modules/services
repository.

Note that if the c-icap installation does not save the c-icap-config program in
a directory that can be found in your default path you will need to give the
path to this program to squidclamav at configure time:

	./configure --with-c-icap=/usr/local/c-icap/
	make && make install


=head3 Running c-icap server

Finally, you can run the c-icap server as root user:

	/usr/local/c-icap/bin/c-icap

or any other path to the binary. If you want to display debugging information
on the terminal, the previous command should be executed with the following
arguments:

	/usr/local/c-icap/bin/c-icap -N -D -d 10

The first argument -N prevents the c-icap server from forking into the background,
the second argument -D enables the printing of messages to standard output, and
the third argument -d 10 enables the printing of full debugging information.

=head3 Reloading configuration without restarting the c-icap server

To force SquidClamav to reread its configuration file after changes you can
send the following command to the c-icap server

	echo -n "squidclamav:cfgreload" > /var/run/c-icap/c-icap.ctl

It will reread all its configuration directives and restart pipes to squidGuard.
So if you make changes to squidGuard you must execute this command to activate
them in SquidClamav.

Or to be sure that everything is really initialized or that you have made change 
to the c-icap configuration file you can run the following command:

	echo -n "reconfigure" > /var/run/c-icap/c-icap.ctl

The service will reread the config file without the need for stopping and restarting
the c-icap server. The service will just be reinitialized.

=head1 CONFIGURATION

By default, the configuration file must be /etc/squidclamav.conf, you may not
use an other path unless you change it in the source code (see src/squidclamav.h).

SquidClamav installation will create a default file with the maximum security
level. If you have low resources on your server there's some predefined pattern
optimized for speed. Feel free to modify it to match your desired security level.

The format of the configuration file consists in always lower case configuration
directive names followed by a value. The name and the value must be separated by
a single space character. Comments are lines starting with a '#' character.

=head2 Global configuration

=head3 Log file and debug

In version 6.x the directives 'logfile', 'debug' and 'stat' are obsolete as
logging and debug are now handled by the c-icap server. You can control them
using the following c-icap.conf directives:

	ServerLog /usr/local/c-icap/var/log/server.log
	DebugLevel 0

Debug information is disable by default, do not enable it on production
systems as it costs a lot of performance. The debug level can be set
from 1 up to 3 for SquidClamav but can be up to 10 for c-icap.

=head3 Clamd daemon

SquidClamav needs to know where to contact clamd, the ClamAV daemon, for on
stream virus scanning.

	clamd_local /tmp/clamd
	#clamd_ip 192.168.1.5
	#clamd_port 3310

By default SquidClamav will contact clamd locally on the /tmp/clamd unix socket
(clamd_local). If your clamd daemon uses INET socket or stays in a remote server,
you have to set the IP address and the port with clamd_ip and clamd_port.

If you use INET socket the 'clamd_local' directive must be commented, or
SquidClamav will always use the clamd_local directive.

=head3 Clamd failover

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
comma. Do not insert space characters in this list or it will break all. For example:

	clamd_ip 192.168.1.5,192.168.1.13,192.168.1.9
	clamd_port 3310
	timeout 1

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

SquidClamav will always connect to the first IP address available. If this fails
it will try the next defined IP address after 1 second. When a connect
can be established SquidClamav will reuse this last "working" IP address first to
not slow down process the next time.

If you think 1 second is a low value, you can change the connect timeout by
editing file squidclamav.conf and set the 'timeout' directive to a higher value. For example :

	timeout 2

Value must be set in seconds. Do not set it too high (< 5) or you can slow down
everything.

=head3 Redirection

=head4 URL redirect

When a virus is detected SquidClamav needs to redirect the client to a warning
page. The SquidClamav distribution contains a set of Perl CGI scripts
with different languages that you can use. To specify this redirection you have
to have to specify a redirect URL to the 'redirect' directive as follow:

	redirect http://proxy.samse.fr/cgi-bin/clwarn.cgi

Take a look in the cgi-bin directory to see all translations of this cgi script.

Squidclamav will pass the following parameters to this CGI:

	url=ORIGNAL_HTTP_REQUEST
	virus=NAME_OF_THE_VIRUS
	source=DOWNLOADER_IP_ADDRESS
	user=DOWNLOADER_IDENT

If this directive is disabled squidclamav will use c-icap error templates
 to report issues. See below.

=head4 Using c-icap template instead of redirect scripts

If the redirect directive is not set, SquidClamav will attempt to load a template
up from disk and send this back to the user. By default this template is found at
the following path:

	/usr/share/c_icap/templates/squidclamav/en/MALWARE_FOUND

Available format tokens are all of those available to the LogFormat directive
of c-icap, plus an additional token:

	%mn - formatted name of the malware, as given by ClamAV.

=head4 Notice redirection into log file

To log every redirection enable the 'logredir' configuration directive:

	logredir 1

By default it is disabled as you can also log this information with the
cgi-script or send an email.


=head3 Chained Url Checker

The squidguard directive is preserved for backward compatibility but you
must remove it from your configuration file as it could result in many
squidclamav crashes.

Please use the 'url_rewrite_program' squid.conf directive instead to call
squidGuard.

	url_rewrite_program /usr/bin/squidGuard
	url_rewrite_children 15
	url_rewrite_access allow all

If you still want to use it, SquidClamav allows you to chain the SquidGuard
program to check the URL requested against blocklists using the 'squidguard'
directive. You just have to give the path to the program.

	squidguard /usr/local/squidGuard/bin/squidGuard

The chained program is called before the virus scan and any other SquidClamav
operations. The call to this program can be disabled with the 'whitelist',
'trustuser' and 'trustclient' directives. See SquidClamav Patterns for more
information.

To log every chained program redirection enable the 'logredir' configuration
directive as following:

	logredir 1

By default it is disabled as you can also log this information with squidguard.

=head3 Maxsize

This directive allows to disable virus scan completely for files bigger than the
value in bytes. Default is 0, no size limit as you may want to control download
size into squid.conf or clamd.

	maxsize 2000000

If you want to abort virus scan after a certain amount of data you must take a
look at the clamd configuration directive 'StreamMaxLength' that will close a
stream when the given size is reached.

=head2 Controlling SquidClamav behaviour

As in SquidClamav v5.x, v6.0 will scan all downloaded files by default.
You have five directives to control the way things must work.

All these directives used extended regex pattern matching and are case
insensitive.

=head3 Control both chained program and virus scan

There are 3 configuration directives that allow you to disable virus scan and
call to chained redirector like SquidGuard. Those pattern matchings are searched
as soon as a Squid entry is received.

=over 4

=item whitelist

The 'whitelist' configuration directive allows you to disable chained program
and virus scan at URL level. When the given pattern matches the URL, SquidClamav
falls back to Squid instantly.

For example:

	whitelist \.clamav\.net

will deliver any files from hosts on clamav.net domain directly.

You can alse use a file containing all regex that might be whitelisted and
provide the file name to the whitelist dorective. Suppose that you have a
file named /usr/local/c-icap/etc/sc_whitelist with the following content:

	\.clamav\.net
	\.darold\.net

then you just have to set whitelist in squidclamav.conf as follow:

	whitelist /usr/local/c-icap/etc/sc_whitelist

the file must contain only one regex per line and no extra character.

=item trustuser

The 'trustuser' directive allows you to disable chained program and virus scan
when an ident matches the search pattern. On regex found SquidClamav falls back to
Squid instantly. Of course you must have Squid authentication helper enabled.

For example:

	trustuser administrator

will let user logged as administrator to not be bored by chained program and
virus scan.

=item trustclient

The 'trustclient' directive allows you to disable chained program and virus scan
if the client source IP address or DNS name match the search pattern. The source
IP address can be a single IP address or an address range following the given regex pattern.

For example:

	trustclient ^192\.168\.1\.1$
	trustclient ^192\.168\.1\..*$
	trustclient ^mypc\.domain\.dom$

The first and the last entry will disable chained program and virus scan for a
single computer and the second will do for en entire class C network.

=item dnslookup

Enable / disable DNS lookup of client IP address. Default is enabled '1' to
preserve backward compatibility but you must deactivate this feature if you
don't use trustclient with hostname in the regexp or if you don't have a DNS
on your network. Disabling it will also speed up squidclamav.

=back

=head3 Safebrowsing

ClamAV 0.95 introduced support for Google Safe Browsing database.  The database
is packed inside a CVD file and distributed through our mirror network as
safebrowsing.cvd. This feature is disabled by default on all clamav installations.

In order to enable this feature, you must first add “SafeBrowsing Yes” to freshclam.conf.
There is no option in clamd.conf. If the engine finds Google Safe Browsing files in the
database directory, ClamAV will enable safe browsing. To turn it off you need to update
freshclam.conf and remove the safebrowsing files from the database directory before
restarting clamd.

Then to enable this feature into SquidClamav you have to enable the following
configuration directive.

=over 4

=item safebrowsing

Enable / Disable Clamav Safe Browsing feature. You mus have enabled the
corresponding behavior in clamd by enabling SafeBrowsing into freshclam.conf
Enabling it will first make a safe browsing request to clamd and then the
virus scan request. 

=back

=head3 Control virus scan

There are 3 configuration directives that allow you to disable virus scan for
downloaded files.

=over 4

=item abort

The 'abort' directive will let you disable virus scanning at URL level (not
chained program). When the URL matches the regex pattern, SquidClamav falls back to
Squid immediately after the call to the chained program, if one is defined there.

For example:

	abort \.squid-cache\.org
	abort .*\.(png|gif|jpg)$

The first regexp will exclude any file hosted on domain squid-cache.org from virus scanning, 
the last one will exclude all PNG, GIF and JPEG image from scanning.

=item abortcontent

The 'abortcontent' directive allows you to exclude any file from virus scanning,
whose Content-Type matches the regex pattern. This directive costs more time
because SquidClamav needs to download the HTTP header for a file with a HEAD
request. Note that some sites do not answer to HEAD requests so the content type
will not be able to be retrieved so they will be scanned.

Example:

	abortcontent ^image\/.*$
	abortcontent ^video\/x-flv$

The first directive will complete the "abort .*\.(png|gif|jpg)$" previous
directive to match dynamic image or with parameters at end. The second will
allow your users to view streamed video instantly.

=item maxsize

As said above, the 'maxsize' directive allows you not to scan a file when the
content-length of the file is bigger than the defined value. By default there's
no size limit.

=back

=head2 Testing SquidClamav

As SquidClamav v6.0 is now a c-icap service, it can no more be run at console
in interactive mode. To check what is going wrong, you must edit c-icap.conf
file, set DebugLevel to 3 and enable ServerLog. Then check for lines with
squidclamav string in the log file which is defined with ServerLog in squidclamav's config.

=head2 Performance

With SquidClamav v6.x the way to tune your service is to tune c-icap server and
clamd daemon. On heavy http access, putting the clamd daemon on a dedicated
server with multiple CPU will really help.

If you experience Squid "ICAP protocol error" (with bypass enabled) please
consider increasing the following c-icp parameters: StartServers, MaxServers,
MinSpareThreads, MaxSpareThreads, ThreadsPerChild. Increasing MaxThreads parameter
in clamd.conf may also help.

=head1 BUGS

Please report any bugs, patches, discussion, etc. to <gilles AT darold DOT net>.

=head1 FEATURE REQUESTS

If you need new features let me know at <gilles AT darold DOT net>. This helps
a lot to develop a better/useful tool.

=head1 HOW TO CONTRIBUTE ?

Any contribution to build a better tool is welcome, you just have to send me
your ideas, features requests or patches and they will be applied.

=head1 AUTHOR

Gilles Darold <gilles AT darold DOT net>

=head1 ACKNOWLEDGEMENT

Thanks to Squid-cache.org, Clamav.net and c-icap.sf.net for their great
software.

Special thanks to Christos Tsantilas for his implementation of the
c-icap server. Lots of SquidClamav v6 source code has been learned
or simply cut and pasted from the source code of his clamav service.

I must also thank all the great contributors:

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

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

=head1 LICENSE

Copyright (c) 2005-2016 Gilles Darold - All rights reserved.

Some code is Copyright (C) 2004-2008 Christos Tsantilas

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 3 of the License, or
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, see < http://www.gnu.org/licenses/ >.

