Clam AntiVirus (clamav) includes the freshclam utility to download new virus definitions. This page documents the configuration and troubleshooting of freshclam under clamav 0.80.
$ clamscan --version
ClamAV 0.80/646/Thu Dec 30 11:42:35 2004
freshclam obtains updates via the HyperText Transfer Protocol (HTTP), and saves them to the local filesystem. Configuration of freshclam is done via the freshclam.conf configuration file, though the location of this file will vary between different systems.
Virus definition updates are not available for older versions of clamav. Upgrade clamav to a current version to fix this problem.
Some sites may want to review definition changes before updating local systems, though the alarming rate of new malware for Windows makes such an approach impractical. Use the sigtool utility to inspect the contents of the virus definition files.
The freshclam utility can be run as a daemon, or called periodically from a scheduler. Due to the infrequent need for updates, I recommend against running freshclam as a daemon. If using a vendor supplied clamav package, check whether it already includes some means to run freshclam, for example via cron(8).
$ rpm -ql clamav | grep cron
Critical network servers should run freshclam directly against the clamav mirrors. Critical systems include mail servers, file servers, and intrusion detection systems that can block new outbreaks from reaching vulnerable Windows systems. Less vulnerable Unix client systems should download new definitions less frequently, perhaps from a local cache.
- cron(8) on Unix
The following shows how to run freshclam twice daily on FreeBSD, Linux, or Mac OS X. CFEngine has many benefits over one-off cron jobs, such as automatic SplayTime to spread out operations, and the ease with which new operating systems can be added with a new control entry for freshclam.
freshclam = ( /sw/bin/freshclam )
freshclam = ( /usr/local/bin/freshclam )
freshclam = ( /usr/bin/freshclam )
Under cfengine, a single system could download definition updates, and a copy statement be used to keep other systems updated. This would reduce traffic to the clamav servers, though would prevent updates from reaching clients should cfengine or the download system fail.
The clamd daemon should be notified after virus definitions are updated. There are several methods available to ensure clamd has loaded the most recent definitions.
- Set SelfCheck in clamd.conf.
- Setup NotifyClamd in freshclam.conf.
- Manually notify clamd.
The SelfCheck option configures clamd to periodically check for definitions changes. A safe option to set, in the event other notification methods fail.
freshclam will need write permissions to the clamd socket file.
The following perl command shows how to manually notify the clamd daemon listening to the /var/run/clamd.sock socket file. The location of the socket file will vary; check clamd.conf or use lsof to find the exact location.
# perl -MIO::Socket::UNIX -we \
'$s = IO::Socket::UNIX->new(shift); \
$s->print("RELOAD"); print $s->getline; $s->close' \
The clamd daemon should return the string RELOADING in response to the RELOAD request. A Nagios plugin could send PING to the socket and expect PONG as part of a clamd monitoring script.
freshclam uses HTTP to download new definitions. Misconfigured web proxies or ad-blocking software may block updates, along with firewalls that reach into the HTTP layer. Tools such as tcpflow may be needed to watch the web traffic generated by freshclam for errors.
$ sudo tcpflow -c port 80
Unix Debugging Tips covers tcpflow and other tools in more detail.
freshclam errors like the following indicate some sort of HTTP problem, such as Websense mangling the definition updates.
# freshclam --debug
ClamAV update process started at Thu Mar 10 11:27:10 2005
main.cvd is up to date (version: 30, sigs: 31086, f-level: 4, builder: tkojm)
Downloading daily.cvd [*]
LibClamAV debug: Can't read CVD head from stream
ERROR: Verification: Broken or not a CVD file
Even if run by the superuser, freshclam will setuid to the clamav user. The freshclam utility requires write permissions to the DatabaseDirectory to save local copies of the virus definitions. If any permissions or ownerships are wrong, freshclam will fail.
$ sudo freshclam
ClamAV update process started at Mon Jun 21 14:22:01 2004
Reading CVD header (main.cvd): OK
main.cvd is up to date (version: 23, sigs: 21096, f-level: 2, builder: ddm)
Reading CVD header (daily.cvd): OK
ERROR: Can't open new file ./clamav-37e017e7f9e9df66 to write
open: Permission denied
Decide which user will update the virus definitions files (typically clamav), then fix all the permissions, ownerships, and configuration settings to agree on the user.
- Set directory and definitions file permissions.
- Ensure the correct user is set in freshclam.conf.
- Fix other permissions.
In this example, the definitions directory is /var/lib/clamav, and the clamav user used by freshclam. The clamav user must have write permissions to the DatabaseDirectory.
$ ls -al /var/lib/clamav
drwxr-xr-x 4 clamav clamav 136 21 Jun 10:22 .
drwxr-xr-x 9 root wheel 306 19 Mar 08:16 ..
-rw-r--r-- 1 clamav clamav 88226 21 Jun 10:22 daily.cvd
-rw-r--r-- 1 clamav clamav 1034725 11 May 22:01 main.cvd
The DatabaseOwner option can be used to specify which user freshclam will setuid to.
# By default when freshclam is started by root it drops privileges and
# switches to the "clamav" user. You can change this behavior here.
freshclam and clamd may use custom log files, and lack the permission to write to them.
$ sudo freshclam
ERROR: Can't open /var/log/freshclam.log in append mode.
ERROR: Problem with internal logger.
For freshclam, find the UpdateLogFile option, and fix the permissions to that file.
$ grep -i updatelogfile /etc/freshclam.conf
$ ls -l /var/log/freshclam.log
ls: /var/log/freshclam.log: No such file or directory
$ sudo touch /var/log/freshclam.log
$ sudo chown clamav:clamav /var/log/freshclam.log
I recommend against custom log files, and use LogSyslog in clamd.conf and freshclam.conf to send logs via syslog(3). System Logging documents centralized logging setup on Unix systems.
# Path to the log file (make sure it has proper permissions)
If problems persist, run freshclam under tracing tools such as ktrace or strace. Unix Debugging Tips covers these tools in more detail.