simscan Troubleshooting

A lot of people seem to have problems getting simscan up and running the first time. In most cases these problems revolve around the different programs involved (simscan, clamd, etc.) running as different userids. I've seen and heard of people who resort to things as insecure as making clamd run as root, or forcing all of the programs to run as the vpopmail user, in order to "make it work". The problem is not limited to simscan- the same issue affects qmail-scanner, and for many people (especially users of the "qmailrocks" guide) it affects how the SMTP "AUTH" command is validated as well.

The various programs involved (simscan, clamd, vpopmail, etc.) are all specifically DESIGNED to run as different userids, for security reasons. This is to limit the amount of damage that an attacker using some currently unknown bug (aka "zero day" vulnerability, because you'll have zero days' notice before a real attack starts happening on the open internet) will be able to do.

For example, if somebody were to find a bug in clamd and build a message which caused clamd to do something bad when scanning the message, all they would have to do is send that message to a user on your server and your clamd would be doing something on their behalf, without your knowledge or authorization. If clamd is running as root, you will have just allowed this attacker to do whatever they want on your server.

Even if it's not running as root... if everything is running as the vpopmail user, they could go through all of your users' mailboxes and harvest email addresses for a spammer, they could grab a list of all of your users and their passwords (you ARE encrypting your users' passwords, right?) and use your server as a spam relay by using one or all of your users' passwords withan AUTH command, they could be targeting one specific user and be able to read all of that user's mail without their knowledge or consent, or they could just be malicious and DELETE all of your users' mailboxes.

Issues with clamav 0.90 and higher

Two of the most common problems involve clamav version 0.90 or higher. One is the error message "configure: error: Unable to find your clamav databases, specify --enable-clamavdb-path." when running the "./configure" command. The other is that if you have upgraded clamav from an earlier version to version 0.90 or higher, the virus database numbers in the email headers suddenly stop working (or the versions which appear in the simversions.cdb file no longer appear, and you just see something like "0.90/m:" in there instead.)

These issues are both caused by the same problem.

When clamav version 0.90 was released, they changed the location and format of the virus definition files. The "simscanmk" program needs to know where to find these files in order to read the versions and build the simversion.cdb file.

I have written a patch which fixes this issue. Note that after applying this patch, you need to run the "autoconf" command to re-generate the "configure" script.

Issues with User IDs and permissions

The simscan and clamav programs are both designed to run as their own dedicated non-root user, in order to limit the amount of damage which can be done by a bug in either program. The design is that the "simscan" user will expand the incoming message into a set of files stored in a temporary directory, and the "clamav" user will need to READ those files in order to scan them for viruses.

In order for this to happen safely, ALL of the following conditions must be true:

• The /var/qmail/bin/simscan executable must be owned by the "simscan" user, group not important (but is usually "root"), and have permissions 4711 ("-rws--x--x"). This is normally done for you, by the "make install" or "make install-strip" step when you install simscan.

  # ls -la /var/qmail/bin/simscan
  -rws--x--x 1 simscan root 22000 Aug 7 19:27 /var/qmail/bin/simscan
  
  If you need to fix anything...
  # chown simscan /var/qmail/bin/simscan
  # chmod 4711 /var/qmail/bin/simscan

• The /var/qmail/simscan directory must be owned by the "simscan" user and the "simscan" group, and have permissions 2750 ("drwxr-s---"). Simscan's "make install" does part of this for you, but it doesn't set the correct permissions or group.

  # ls -lad /var/qmail/simscan
  drwxr-s--- 2 simscan simscan 4096 Aug 9 06:42 /var/qmail/simscan
  
  If you need to fix anything...
  # chown simscan:simscan /var/qmail/simscan
  # chmod 2750 /var/qmail/simscan

  Note that running "make install" for simscan will reset the permissions on the directory, so if you need to re-install simscan, you will need to run the "chmod" command again.

• The "clamav" user needs to be a member of the "simscan" group. This is half of allowing the "clamd" process to read the temporary files created by simscan when it expands the message's MIME structure. (The other half involves telling clamd to actually use the "group" permissions it may not otherwise try to use, and is covered below.)

  # groups clamav
  clamav : clamav simscan
  
  If you need to add the clamav user to the simscan group...
  # usermod -a -G simscan clamav
  Note that this command works for most versions of Linux, other systems should have a similar command. Note that you don't want to change the "login group" of the clamav user, you want to add simscan as an "extra" or "supplementary" group.

• The temporary files need to have "group read" permissions. When simscan expands the message into the temporary directory, it needs to create the directory and its contents with "group read" (and in the case of the directory itself, "group execute") permissions. Normally simscan specifies 0755 for the temporary directory, and doesn't specify any specific permissions for the files (which results in 0666.)

  However, both of these values are filtered through a system-level setting called the "umask", which specifies which permissions should NOT be set for new files. Most OS distributions set this to a value like "022" (i.e. "group write" and "other write" will be disabled) when the system boots, and unless some other process explicitly changes it, this value is inherited by simscan and used in order to set the permissions on the temporary directory and files that it creates before calling clamdscan.

  Some people, myself included, normally set the "umask" value to a more restrictive setting, like 077 (which means that "group" and "other" will have no permissions to access any new files.) The result of this is that the temporary directories and files will not have "group read" permissions, which prevents clamd from being able to read them.

  There are two ways to handle this issue. You should do at least one of them, although it won't hurt anything if you do both.

  • I have written a patch to make simscan explicitly set the umask value to 027 before creating any temporary files. This will hopefully become part of the next release of simscan.

  • You can add the line "umask 027" in the "run" script for your qmail-smtpd service(s), somewhere before the final "exec tcpserver" line, and then restart the service(s) using a "svc -t" command. Doing this will cause simscan to inherit this umask value from its parent processes.

• You must tell clamd to use the extra "group" permissions that it gains by virtue of the "clamav" user being part of the "simscan" group. To do this, edit your clamd.conf file and make sure you have the following setting in place:

  # Initialize supplementary group access (clamd must be started by root).
  # Default: no
  AllowSupplementaryGroups yes

• The clamd process needs to run as the "clamav" user. To do this, edit your clamd.conf file and make sure you have the following setting in place:

  # Run as another user (clamd must be started by root to make this option
  # working).
  # Default: don't drop privileges
  User clamav

  If you had to make any changes to the clamd.conf file, make sure to restart the clamd process so it sees and uses the new settings.

Extra debugging information

You may also wish to install the debug patch I wrote for simscan 1.3.1. This patch enables two different types of "extra debugging".

The first change is, if you set SIMSCAN_DEBUG=3, simscan will log the actual text returned by clamdscan. This may show you more information about why clamdscan and clamd are having problems scanning the files created by simscan.

The other change is, if you set SIMSCAN_DEBUG_FILES=1, simscan will NOT delete the temporary directory it creates for each messages, or the files within that directory, when clamdscan returns an error. This allows you to see exactly what simscan did or did not do. If you set SIMSCAN_DEBUG_FILES=2, simscan will not delete these temporary files for ANY messages.

I've sent the patch to the simcan developers, if they add it to a future version then there won't be any need for a patch, and you can just follow these directions to see the extra information.

Copyright 1995-2024 John M. Simpson KG4ZOW (email) (PGP key)
Last updated 2008-08-08 03:43:26 +0000