This document started out as a way for me to document the procedure and required readings for re-creating the deployment of Qmail-Scanner and ClamAV for my employer's email system. I am not a writer, or a programmer. I am a lowly little systems administrator that got frustrated looking online for all of the information to make Qmail-Scanner work with ClamAV. This HOWTO will document the steps that I took to get Qmail-Scanner and ClamAV to work together. Is this the right way to do it? Who knows, it worked for me. There are plenty of snippets of information that I "liberated" from many sources. Please see the Acknowledgments. The most current version of this document can be found at http://stevepeace.no-ip.org.

This document is not a comprehensive source of information for ClamAV, Qmail-Scanner, qmail, daemontools, Linux, Un*x, FreeBSD, Perl, etc. I do not pretend to know everything about everything. Like I said before, this worked for me it may not work for you. If you don't know how to use a particular OS, tool, or piece of software, THIS HOWTO WILL NOT HELP YOU! I am a firm believer in RTFM. So please make sure that you check out Appendix A, and the Disclaimer before following this HOWTO.

I would like to acknowledge the following people and groups:

Copyright (c) 2004 Steven R. Peace.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

This HOWTO is free documentation; you can redistribute it and/or modify it under the terms of the GNU Free Documentation License. This document 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.

I disavow any potential liability for the contents of this document. Use of the concepts, examples, and/or any other information or content of this document is entirely at your own risk.

All copyrights are owned by their owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark.

Naming of particular products or brands should not be seen as endorsements.

You are strongly recommended to take a backup of your system before major installation and backups at regular intervals.

The document home page can be found at http://stevepeace.no-ip.org. Check here for the most current versions.

From the ClamAV website:

"Clam AntiVirus is a GPL anti-virus toolkit for UNIX. The main purpose of this software is the integration with mail servers (attachment scanning). The package provides a flexible and scalable multi-threaded daemon, a command line scanner, and a tool for automatic updating via Internet. The programs are based on a shared library distributed with the Clam AntiVirus package, which you can use with your own software. Most importantly, the virus database is kept up to date."

Download the ClamAV source at http://www.clamav.net. As of the writing of this HOWTO, the latest version is 0.65.

#tar -xvzf clamav-0.65.tar.gz 
#cd clamav-0.65 #groupadd clamav
#useradd clamav -g clamav -c "Clam AntiVirus" -s /nonexistent .
#/configure
#make 
#make install 
#cd ..
			

As long as make and make install have finished without errors, you are now ready to test your installation (If you did experience errors, please review the ClamAV documentation that was included in the tar ball. You may also try the ClamAV website for some helpful tips). To test your installation type:

#clamscan -r -l scan.txt clamav-0.65

Clamscan should find a test virus (This is NOT a real virus) in the clamav-0.65/test directory and log it to the scan.txt log file.

Now you need to configure the ClamAV daemon, clamd, for testing.

#vi /usr/local/etc/clamav.conf

Comment out "Example" line in clamav.conf and save.

#clamdscan -l scan.txt clamav-0.65

This should provide output that is similar to the clamscan command you entered above.

Now we need to update our virus definitions. Clamscan includes a utility, freshclam, to take care of this. Freshclam automatically changes from root to the clamav user that you created during the installation. First, create a log file that freshclam can log to.

#touch /var/log/clam-update.log
#chmod 600 /var/log/clamupdate.log
#chown clamav /var/log/clamupdate.log

Now start freshclam:

#freshclam -d -c 6 -l /var/log/clam-update.log
			

This checks for a new virus definition database six (6) times a day. Check the /var/log/clam-update.log file. It should look something like this:

-----------------------------------------------------------------------------------------------------
ClamAV update process started at Wed Jan 28 17:49:48 2004
main.cvd is up to date (version: 19, sigs: 19987, f-level: 1, builder: ddm)
daily.cvd updated (version: 111, sigs: 597, f-level: 1, builder: tomek)
Database updated (20584 signatures) from database.clamav.net (81.4.91.185).
-----------------------------------------------------------------------------------------------------
			

Now add the freshclam -d -c 6 -l /var/log/clam-update.log to your startup scripts.

You can also setup a cronjob to update the Defs every 6 hours, if you like.

#vi /etc/crontab
			

0 6 * * * root /usr/local/bin/clamscan
			

Edit /etc/clamd.conf and make the following changes.

#vi /etc/clamd.conf

Create the clamav directory.

#mkdir -p /usr/local/clamav/bin

Now create a startup/shutdown script for clamd. Copy and paste the script shown below. This script was written by Jesse D. Guardiani.

     
#vi /usr/local/clamav/bin/clamdctl

#!/bin/sh

# For Red Hat chkconfig
# chkconfig: - 80 30
# description: the ClamAV clamd daemon

PATH=/usr/local/clamav/bin:/bin:/usr/bin:/usr/local/bin:/usr/local/sbin
export PATH

case "$1" in
  start)
    echo "Starting clamd"
    if svok /service/clamd ; then
      svc -u /service/clamd
    else
      echo clamd supervise not running
    fi  
    if [ -d /var/lock/subsys ]; then
      touch /var/lock/subsys/clamd
    fi
    ;;
  stop)
    echo "Stopping clamd..."
    echo "  clamd"
    svc -d /service/clamd
    if [ -f /var/lock/subsys/clamd ]; then
      rm /var/lock/subsys/clamd
    fi
    ;;
  stat)
    svstat /service/clamd
    svstat /service/clamd/log
    ;;
  restart)
    echo "Restarting clamd:"
    echo "* Stopping clamd."
    svc -d /service/clamd
    echo "* Sending clamd SIGTERM and restarting."
    svc -t /service/clamd
    echo "* Restarting clamd."
    svc -u /service/clamd
    ;;
  hup)
    echo "Sending HUP signal to clamd."
    svc -h /service/clamd
    ;;
  help)
    cat <<HELP
   stop -- stops clamd service (smtp connections refused, nothing goes out)
  start -- starts clamd service (smtp connection accepted, mail can go out)
   stat -- displays status of clamd service
restart -- stops and restarts the clamd service
    hup -- same as reload
HELP
    ;;
  *)
    echo "Usage: $0 {start|stop|stat|restart|hup|help}"
    exit 1
    ;;
esac

exit 0


			

Make clamdctl an executable and link to path:

#chmod 755 /usr/local/clamav/bin/clamdctl

#chown clamav /usr/local/clamav/bin/clamdctl

#ln -s /usr/local/clamav/bin/clamdctl /usr/local/bin

Create the supervise directories for the clamd service:

#mkdir -p /usr/local/clamav/supervise/clamd/log

Now you must create the /usr/local/clamav/supervise/clamd/run file, or just copy and paste the script shown below. This script was also created by Jesse D. Guardiani:

vi /usr/local/clamav/supervise/clamd/run

#!/bin/sh
#
# --------------------------------------------------
# run
#
# Purpose     - Start the clamd daemon/service.
#                               
# Author      - Jesse D. Guardiani
# Created     - 09/10/03
# Modified    - 09/25/03
# --------------------------------------------------
# This script is designed to be run under DJB's
# daemontools package.
#         
#  ChangeLog
#  ---------
#
#  09/25/03 - JDG
#  --------------
#  - Changed clamd user to qscand in compliance with
#    the change to qmail-scanner-1.20rc3
#
#  09/10/03 - JDG
#  --------------
#  - Created
# --------------------------------------------------
# Copyright (C) 2003 WingNET Internet Services
# Contact: Jesse D. Guardiani (jesse at wingnet dot net)
# --------------------------------------------------

lockfile="/tmp/clamd"   # Location of clamd lock file
path_to_clamd="/usr/local/sbin/clamd"
                        # Location of the clamd binary
BAD_EXIT_CODE=1         # The exit code we use to announce that something bad has happened

# The following pipeline is designed to return the pid of each
# clamd process currently running.
get_clam_pids_pipeline=`ps -ax | grep -E "${path_to_clamd}\$" | grep -v grep | awk '{print $1}'`


# --------------------------------------------------
# Generic helper functions
# --------------------------------------------------

# Basic return code error message function
die_rcode() {
	EXIT_CODE=$1
	ERROR_MSG=$2

	if [ $EXIT_CODE -ne '0' ]; then
		echo "$ERROR_MSG" 1>&2
		echo "Exiting!" 1>&2
		exit "$BAD_EXIT_CODE"
	fi
}


# --------------------------------------------------
# Main
# --------------------------------------------------

ps_clamd=""
ps_clamd="$get_clam_pids_pipeline"

if [ -n "$ps_clamd" ]; then
	pid_count="0"
	for pid in $ps_clamd
	do
		pid_count=`expr $pid_count + 1`
	done
	
	die_rcode $BAD_EXIT_CODE "Error: $pid_count clamd process(es) already running!"

fi

if [ -e "$lockfile" ]; then
	rm "$lockfile"
	exit_code="$?"
	die_rcode $exit_code "Error: 'rm $lockfile' call failed."
fi

exec /usr/local/bin/setuidgid qscand $path_to_clamd

# --
# END /usr/local/clamav/supervise/clamd/run file.
# --

Create the /usr/local/clamav/supervise/clamd/log/run file:

#vi /usr/local/clamav/supervise/clamd/log/run

#!/bin/sh
exec /usr/local/bin/setuidgid qscand /usr/local/bin/multilog t /var/log/clamd
			

Make the run files executable:

#chmod 755 /usr/local/clamav/supervise/clamd/run

#chmod 755 /usr/local/clamav/supervise/clamd/log/run

Now set up the log directories:

#mkdir -p /var/log/clamd

chown qscand /var/log/clamd

Finally, link the supervise directory into /service:

#ln -s /usr/local/clamav/supervise/clamd /service

* Note: The clamd script will start automatically shortly after these links are created. If you don't want it running, do the following:

#clamdctl stop

To start clamd backup, do the following

#clamdctl start

From the Qmail-Scanner website: "Qmail-Scanner is an addon that enables a qmail email server to scan all gateway-ed email for certain characteristics (i.e. a content scanner). It is typically used for its anti-virus protection functions, in which case it is used in conjunction with commercial virus scanners, but also enables a site (at a server/site level) to react to email that contains specific strings in particular headers, or particular attachment filenames or types (e.g. *.VBS attachments). It also can be used as an archiving tool for auditing or backup purposes. Qmail-Scanner is integrated into the mail server at a lower level than some other Unix-based virus scanners, resulting in better performance. It is capable of scanning not only locally sent/received email, but also email that crosses the server in a relay capacity."

We are now ready to install Qmail-Scanner. Download the latest source of Qmail-Scanner. As of the writing of this HOWTO, it is 1.20.

Create a user for Qmail-Scanner to run as.

#groupadd qscand

#useradd qscand -g qscand -c "qmail scanner" -s /nonexistent

Unpack the tar ball and change to the Qmail-Scanner directory.

#tar -zxvf qmail-scanner-1.20.tar.gz

#cd qmail-scanner-1.20

Run Configure to autodetect what software is installed on your system. Review the output to make sure it is correct. It should look similar to this:

#./configure

This script will search your system for the virus scanners it knows
about, and will ensure that all external programs
qmail-scanner-queue.pl uses are explicitly pathed for performance
reasons.

It will then generate qmail-scanner-queue.pl - it is up to you to install it
correctly.

Continue? ([Y]/N) <PRESS ENTER>

Found tnef on your system! That means we'll be able to decode stupid
M$ attachments :-)


The following binaries and scanners were found on your system:

mimeunpacker=/usr/local/bin/reformime
unzip=/usr/bin/unzip
tnef=/usr/local/bin/tnef

Content/Virus Scanners installed on your System

clamuko=/usr/local/bin/clamdscan (which means clamscan won't be used as clamdscan is better)

Qmail-Scanner details.

log-details=0
fix-mime=1
debug=1
notify=sender,admin
redundant-scanning=no
virus-admin=root@mail  --substitute you domain here
local-domains='mail' --substitute your domain here
silent-viruses='klez','bugbear','hybris','yaha','braid','nimda','tanatos','sobig','winevar','palyh','fizzer','gibe','
cailont','lovelorn','swen','dumaru','sober','hawaii','holar-i'
scanners="clamuko_scanner"

If that looks correct, I will now generate qmail-scanner-queue.pl
for your system...
Continue? ([Y]/N)<PRESS ENTER>

			

Now type:

# ./configure ?install

This installs qmail-scanner-queue.pl and creates the necessary directory structures. You should see similar messages as before. Once again, read the output of the script to make sure everything is correct. If it is press ENTER to install Qmail-scanner.

If qmail has been installed successfully, qmail-scanner-queue.pl should now be installed. You should see qmail-scanner-queue.pl in /var/qmail/bin.

#ls /var/qmail/bin

/var/qmail/bin/qmail-scanner-queue.pl

If you do not see qmail-scanner-queue.pl in /var/qmail/bin, then execute the configure script again. Please pay attention to the output of the script and verify that all of the settings are correct. You can also visit the Qmail-scanner mail-archives at http://lists.sourceforge.net/mailman/listinfo/qmail-scanner-general .

In order for Qmail-Scanner to be able to use ClamAV, some of the ClamAV ownerships must be changed. If you recall, we made a clamav user to run ClamAV, and then changed the permissions so only the clamav user could run it. Now we need to provide the qscand user privledges to use ClamAV First, change the ownership of the clamd supervise directories.

#chown -R qscand /usr/local/clamav/supervise

Now change the ownership of the ClamAV log file:

#chown -R qscand /var/log/clamd

Now test Qmail-Scanner:

#./contrib./test_instaltion.sh -doit

Sending standard test message - no viruses...done!

Sending eicar test virus - should be caught by perlscanner module...
				done!

Sending eicar test virus with altered filename - should only be caught
				by commercial anti-virus modules (if you have any)...

Sending bad spam message for anti-spam testing - In case you are using
				SpamAssassin... Done!

Now check the e-mail for your postmaster alias account.

You should now have 4 email messages in your postmaster?s mailbox

If you do not have the 4 messages in the postmaster's mailbox, then: Verify that you are checking the proper mailbox.

Re-execute the configure script for qmail-scanner-queue.pl. Verify that the 'virus-admin' from the script output is the same as your qmail postmaster alias.

Check qmail to see if the messages are in the queue. If they are try issuing a 'qmailctl' flush command to force delivery.

If all else fails check the Qmail-Scanner mailing list archives at http://lists.sourceforge.net/mailman/listinfo/qmail-scanner-general.

Once everything is installed, configured, and successfully tested, configure qmail to utilize Qmail-Scanner and ClamAV. If you have followed the instructions found in Dave Sills Life With qmail (see Appendix A: Reading Resources), you should have a tcp.smtp file in your /etc directory. You must edit tcp.smtp file to include the QMAILQUEUE variable.

	
#vi /etc/tcp.smtp

127.:allow,RELAYCLIENT="",QMAILQUEUE="/var/qmail/bin/qmail-queue"
10.:allow,RELAYCLIENT="",QMAILQUEUE="/var/qmail/bin/qmail-scanner-queue.pl"
:allow.QMAILQUEUE="/var/qmail/bin/qmail-scanner-queue.pl"
			

As you can see, we use qmail-queue for all local deliveries by setting the QMAILQUEUE variable to be the original qmail-queue. We then changed the local subnet mail deliveries to use qmail-scanner-queue.pl. This causes all local subnet SMTP traffic to be scanned by Qmail-Scanner and ClamAV. The last line of this file scans all inbound emails.

After adding the QMAILQUEUE variables, you must rebuild the cdb file for Qmail.

#qmailctl cdb

If you try to send an email message, you will most likely receive an error from your client. The error message will say something that includes this:

451 qq temporary problem (#4.3.0)

If you followed Life with qmail, you then have a memory limit set in the /var/qmail/supervise/qmail-smtpd/run file. Look for the line that contains softlimit. It should look similar to this:

exec /usr/local/bin/softlimit -m 2000000 \

This example sets the memory limit for qmail-smtpd to 2M. After all of your changes qmail-smtpd is now running the entire Perl interpreter, and ClamAV. 2M will never be enough.

Each system is different, and has different requirements. It will take some experimenting on your part to find the correct value for your system's softlimit. Do not set softlimit to some high value! You are asking for trouble if you do this. To find the minimal value for your system, I recommend the following steps:

Once you have found the minimum, I recommend increasing that by 1.5M, just for times that your email server has a heavy load.

After that just create a daily cronjob that runs /var/qmail/bin/qmail-scan-queue.pl -z to cleanup any dropped SMTP sessions that may be lying around in /var/spool/qmailscan.