Installing qscanq

Preliminaries

Like most free software, qscanq comes with NO WARRANTY of any kind, except for the qscanq security guarantee. For questions relating to installation, configuration, etc., please write to the qscanq mailing list.

Before installing qscanq, you need to install and configure ripmime, which is used to extract MIME attachments from email messages for scanning. Don't skip this step! The most common cause of installation problems is failure to install ripmime first!

You will also need to install a virus scanner. By default, qscanq uses clamav. See clamscan notes for important instructions if you plan to use clamav.

Instead of clamav, you can install antivir, which is not open-source. See antivir notes for important instructions. In fact you can use any scanner you prefer.

What scanner do I recommend? More and more, I lean toward clamdscan. Because it has maturity issues, mission critical systems would probably do well to choose something else--but I'm rooting for clamdscan, because it's exactly the right idea.

Before installing qscanq, you must also have installed Dan Bernstein's daemontools software. In particular, /package and /service must exist, and svscan must run at boot time in /service.

If you want a log entry for each rejected email (recommended), then you'll need to configure qmail-smtpd to log rejections. You should get logging working to your satisfaction before proceding to install qscanq.

Steps not affecting qmail

Everyone should follow these steps, whether they use an unpatched qmail or a version built with Bruce Guenter's QMAILQUEUE patch.

Download qscanq. The current version is qscanq-0.43.tar.gz (Changelog)

Unpack the source into /package:

gunzip -v qscanq-VER.tar.gz
cd /package
tar -xvf PATH/qscanq-VER.tar.gz
cd mail/qscanq-VER

Verify the settings in the src/conf-* files. Most of these should not need to be changed. You must edit conf-scancmd to use the correct scanner, or qscanq will not build. You must also make sure that conf-scan-stdin is correct for your chosen scanner. If your scanner doesn't read email files automatically, you will need to edit conf-ripmime and specify a MIME unpacking utility. Finally, if you use QMAILQUEUE, you should also edit conf-qmailq so that it points to the directory where qmail-queue is installed.
Create users named Gqscanq and Gqscanlog (or whatever is in conf-users), and a group named Gqscanq (or whatever is in conf-groups). The users should NOT belong to the Gqscanq group. You can set the users' login shells to /bin/true, disable their passwords, and refrain from creating a home directory for them. Their home directories can be set to / or else to /var/qmail/avscan and /var/qmail/avscan/log, respectively (i.e., the directory named in conf-spool and its log subdirectory).

Note to RedHat users: your adduser command may reject user names having a capital letter. There is no good reason for this behavior. I suggest creating the users with all-lowercase names, and then editing /etc/passwd and capitalizing the first letter. Don't forget to edit /etc/shadow.
Build and install the software:
```
./package/install
```
Run some automated tests:
```
./package/rts
```

Steps Affecting qmail

If all of the preceding steps went smoothly, it's time to wrap qmail-queue and try sending email. If you wish, you can disable qmail-smtpd as a precaution while running this test; that will cause delivery attempts to your machine to be deferred during your test.

If you are using unpatched qmail, or are using QMAILQUEUE but want qscanq to scan local as well as incoming email, replace qmail-queue with qscanq:
```
./command/install-wrap
```
If you are using QMAILQUEUE and you wish to leave qmail-queue in its default location, then instruct qmail-smtpd to run /package/mail/qscanq/command/qscanq instead of qmail-queue. An example tcprules file that accomplishes that is:
```
192.168.1.:allow,RELAYCLIENT=""
127.:allow,RELAYCLIENT=""
:allow,QMAILQUEUE="/package/mail/qscanq/command/qscanq"
```
Try sending an email with a fake virus attachment:
```
DEBUG=1 /var/qmail/bin/qmail-inject -a root < src/TEST-BAD
echo $?
```
The response from qmail-inject should say, "mail server permanently rejected message" and nothing else. The exit code should equal 100. If there is a problem, then a diagnostic message should be printed instead. (Note: this test will fail if you are using QMAILQUEUE.)
Try sending an email with no virus:
```
DEBUG=1 /var/qmail/bin/qmail-inject -a root < src/TEST-GOOD
echo $?
```
There should be no message from qmail-inject, and $? should equal 0. The message should show up in the mailbox for the alias user, or wherever you have configured root's email to end up. If some problem occurs, then diagnostic output will be printed to stderr. (Note: this test is irrelevant if you are using QMAILQUEUE.)

Test an SMTP submission from the command line:

# setuidgid qmaild /usr/local/bin/fixcrio /var/qmail/bin/qmail-smtpd
220 localhost.localdomain ESMTP
helo _
250 localhost.localdomain
mail from:<root>
250 ok
rcpt to:<root@localhost>
250 ok
data
354 go ahead
From: Root
To: Root
Subject: Test

test
.
250 ok 1066016729 qp 2503
quit
221 localhost.localdomain

The message should show up in the mailbox for the alias user, or wherever you have configured root's email to end up. (Note: this and the remaining tests should work with QMAILQUEUE or with an unpatched qmail.)

Telnet to port 25 and attempt to send an email, using the same SMTP conversation as in the previous test. It should be accepted for delivery and arrive wherever root's email ends up (usually, the mailbox for the alias user).
With your usual mail client, attempt to send a message with src/eicar_com.zip attached. The message should be accepted by qmail-smtpd.

Finally, extract eicar.com from the zip file (where you virus scanner won't intercept it!) and attempt to send it as an attachment using your email client. It should be rejected by qmail-smtpd. If it appears to be accepted, you may have one of those mailers that doesn't check return codes; look in the log for qmail-smtpd to see the actual disposition of the file. You should see a message like the following:
```
@400000003f8af70524cfed64 29588 > 554 mail server permanently rejected message (#5.3.0)
```

At this point, you can either leave qscanq installed, or you can uninstall it. If you use QMAILQUEUE, remove the reference to qscanq from your tcprules file. Otherwise, uninstall qscanq as follows:

/package/mail/qscanq/command/install-unwrap

That's it!

If you love qscanq, consider contributing.