SquidClamav Configuration


This page is related to SquidClamav version 6.x and 5.x configuration.

By default, since 6.12 the configuration file squidclamav.conf is created under the c-icap configuration directory. It should be found at the same place as c-icap.conf. Older versions used to saved squidclamav.conf under /etc/squidclamav.conf

For v5.x branch, the configuration file is located by default at: /etc/squidclamav.conf. If you need an other path just set the path in command line argument as follow:

	/usr/local/bin/squidclamav --config /usr/local/etc/squidclamav.conf

SquidClamav installation will create a default file optimized for speed. Feel free to modify it to match your security level. If you want maximum security edit the file and comment all abort/abortcontent lines. The format of the configuration file consists in always lower case configuration directives name followed by a value. The name and the value must be separated by a single space character. Comments are lines starting with a '#' character.

Global configuration

Squid ip address and port (obsolete/unused in v6.x)

With SquidClamav v6.x you don't have to connect to Squid. This is Squid that is sending HTTP stream to the ICAP server. So just omit these configurations directives.

SquidClamav v5.x use Squid to download files, you have to set the ip address and port where SquidClamav can contact Squid. Here are the default values for these directives.

	squid_ip 127.0.0.1
	squid_port 3128

'squid_ip' may always be the localhost ip address as they run in the same host.

Log file and debug (obsolete/unused in v6.x)

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

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

Debug informations are disable by default, do not enable it on production server as it cost a lot of system performance. The debug level can be set from 1 up to 3 for SquidClamav but can be up to 10 for c-icap.

SquidClamav v5.x log file by default stay at /var/log/squid/squidclamav.log as directory '/var/log/squid/' may already be writable by squid running user. SquidClamav is executed by this user.

	logfile /var/log/squid/squidclamav.log
	debug 0
	stat 0

Debug and statistic informations are disable by default, do not enable it on production server as it cost a lot of system performance. The debug level can be set from 1 up to 3. At level 3 SquidClamav will dump HTTP headers of files it download.

You also have the 'stat' directive that logs time performance statistics of SquidClamav. Set it to 1 to see SquidClamav performance and analyze where SquidClamav waste its time.

Clamd daemon

SquidClamav need 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 use INET socket or stay 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 else SquidClamav will always used the clamd_local directive.

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 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
	timeout 1

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

SquidClamav will always connect to the firt available ip address. If it can not connect after 1 second it will try the next defined ip address. When a connect can be establish 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 second. Do not set it too high (< 5) or you can slow down everything.

Redirection

When a virus is detected SquidClamav need to redirect the client to a warning page. You can find in the SquidClamav distribution a set of perl CGI scripts with different language that you can use. To specify this redirection you have to use the 'redirect' directive as follow:

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

Squidclamav will pass to this CGI the following parameters:

	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.

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.

Chained redirector (obsolete/unused in v6.x)

The 'squidguard' configuration directive is preserved for bacward compatibility but you must remove it from your configuration file as it could result in many squidclamav crash. 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 allow you to chain an other redirector with the 'squidguard' directive. You just have to give the path to the program. It is named squidguard but can be any other redirector.

	squidguard /usr/local/squidGuard/bin/squidGuard

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

For SquidClamav 6.x, see chapter on chained url checker below.

Chained Url Checker (version 6.x only)

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.

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.

Override User Agent (obsolete/unused in v6.x)

With SquidClamav v6.x this directive is obsolete as it no more have to download files by itself.

With version 5.x some uggly sites require IE like client browser. You can force these sites to accept you by using the 'useragent' directive. The default setting should be enough. Without that SquidClamav will comes with the LibCurl user agent.

	useragent Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)

Site redirection (obsolete/unused in v6.x)

In version 6.x we follow Squid stream so this directive is obsolete.

When SquidClamav is downloading a file with libCurl it will not follow infinitly the site redirections. By default it allow 30 'maxredir' from a single file.

	maxredir 30

Download timeout (obsolete/unused in v6.x)

The entire process of file download and virus scan may end before the client internal timeout. Most of them have a timeout of 1 minute before displaying an error message to the client. The 'timeout' directive is done for that.

	timeout 60

Trust your cache (obsolete/unused in v6.x)

One of the main configuration directive for performance improvement is 'trust_cache'. SquidClamav detect if the file to download is already stored in Squid cache. If you activate 'trust_cache', SquidClamav will not scan a file comming from Squid cache as it may have already been scanned during the first download. If trust_cache is disabled, no matter if the file is stored in the cache, SquidClamav will rescan the same file at each client request. I really recommand you to activate this directive.

	trust_cache 0

Trusted cache is disable by default as you may want to start with a fresh cache.

Maxsize

This directive allow to completely disable virus scan for files bigger than the value in bytes. Default is 0, no size limit.

	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 stream when the given size is reach.

Controlling SquidClamav behaviour

As we says SquidClamav scans 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.

Control both chained program and virus scan

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

whitelist

The 'whitelist' configuration directive allow you to disable chained program and virus scan at URL level. When the given pattern match the URL SquidClamav fallback to Squid instantly.

For example:

	whitelist \.clamav\.net

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

trustuser

The 'trustuser' directive allow you to disable chained program and virus scan when an ident match the search pattern. On regex found SquidClamav fallback 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.

trustclient

The 'trustclient' directive allow 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 or a network 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.

dnslookup

Enable / disable DNS lookup of client ip address. Default is enabled '1' to preserve backward compatibility but you must desactivate 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.

Control virus scan

There's 2 configuration directives that allow you to disable virus scan for downloaded files.

abort

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

For example:

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

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

abortcontent

The 'abortcontent' directive allow you to exclude from virus scanning any file whose Content-Type match the regex pattern. This directive cost more time because SquidClamav need to download the HTTP header for a file with a HEAD request.

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.

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 installations and should be enabled with extreme care.

All signatures provided by Google Safe Browsing Database will be prefixed with the Safebrowsing tag. If ClamAV reports Safebrowsing.<something> FOUND, it means that the advisory was provided by Google and not by ClamAV Virus database.

Please note that such reports do NOT necessarily mean that the data scanned contains some malware. You should treat such data as a potential risk, that is a suspicious source of malware.

If you want to know more about the potentially dangerous data matched by the signature, you should visit http://www.antiphishing.org/ (for phishing warnings) or http://www.stopbadware.org/ (for malware warnings).

In order to enable this feature, you must 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.

Configuration file example for v6.x

Here is the configuration file use for 1500 Internet users per day.

	clamd_ip 192.168.1.5,192.168.1.6
	clamd_port 3310
	maxsize 10000000
	redirect http://proxy.mydom.dom/cgi-bin/clwarn.cgi
	squidguard /usr/local/squidGuard/bin/squidGuard

Configuration file example for v5.x

Here is the configuration file use for 1500 Internet users per day with speed in mind.

	squid_ip 127.0.0.1
	squid_port 3128
	logfile /var/log/squid/squidclamav.log
	debug 0
	stat 0
	clamd_local /tmp/clamd
	#clamd_ip 192.168.1.5
	#clamd_port 3310
	maxsize 5000000
	redirect http://proxy.mydom.dom/cgi-bin/clwarn.cgi
	squidguard /usr/local/squidGuard/bin/squidGuard
	maxredir 30
	timeout 60
	useragent Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)
	trust_cache 1

	# Do not scan standard HTTP images
	abort ^.*\.(ico|gif|png|jpg)$
	abortcontent ^image\/.*$
	# Do not scan text and javascript files
	abort ^.*\.(css|xml|xsl|js|html|jsp)$
	abortcontent ^text\/.*$
	abortcontent ^application\/x-javascript$
	# Do not scan streaming videos
	abortcontent ^video\/mp4$
	abortcontent ^video\/x-flv$
	# Do not scan pdf and flash
	#abort ^.*\.(pdf|swf)$

	# Do not scan sequence of framed Microsoft Media Server (MMS) data packets
	abortcontent ^.*application\/x-mms-framed.*$

Testing SquidClamav V6.x

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 fine and set DebugLevel to 3 and enable ServerLog. Then check for line with squidclamav string into the log file defined with ServerLog.

Testing SquidClamav V5.x

Once you have installed+configured squidclamav and modified Squid configuration the best way to see if squidclamav is working well 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/mypc.domain.dom 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.

Free and Open Source...
but worth more! Consider
a Donation