Installing and configuring simscan

June 30, 2025 by Roberto Puzzanghera 89 comments

github
Changelog
John Simpson's simscan page (patch and a lot of info)
README
Old combined patch used (Sep 13, 2023)
Version: simscan-1.4.6.2

Simscan is a simple program that enables the qmail smtpd service to reject viruses, spam, and block attachments during the SMTP conversation so the processing load on the email system is kept to a minimum.

Version 1.4.6 details

As you can see, for convenience I moved the simscan sources to my github space. Nonetheless, all information about simscan will continue to be posted here, and this page remains the place to seek support if needed.

Version 1.4.6 is a fork of the 1.4.1 version, which updates the original simscan by Inter7.

In 1.4.1 version the sources have been polished and modernized a bit and contain a number of bug fixes and patches, including almost all the patches by jms (the only missing one is the "debug" patch which we will apply below) and the bug fix by Gustavo Castro that I had in my previous bundle of patches. Therefore the new 1.4.2 version simply adds the following:

the jms "debug" patch, to improve the debugging of simscan on qmail-smtpd log;
a bug fix by Bob Greco where a received message with multiple 'local' recipients executes spamc as null user and not as the user extracted from the first local recipient.
my attachments-size-limit feature which allows you to overcome a limitation where simscan doesn't pass messages over 250k to spamassassin. This feature let the administrator set the attachments' size limit in bytes by setting the size_limit variable in the /var/qmail/control/simcontrol file. Furthermore, events where simscan is not activated are now logged at smtpd level (it was logged only when debug is active).

`ripMIME`

Info: https://pldaniels.com/ripmime/
Download latest version from github: https://github.com/inflex/ripMIME

ripMIME's primary purpose is to extract attachments out of a MIME encoded email packages. It is used by simscan. It is a recommended package.

RIPMIME_VER=1.4.1.0

cd /usr/local/src
wget https://github.com/inflex/ripMIME/archive/refs/tags/${RIPMIME_VER}.tar.gz
tar xzf ${RIPMIME_VER}.tar.gz
cd ripMIME-${RIPMIME_VER}
chown -R root:root .
make
make install

Testing

man ripmime for more info

Pick up an email file "message.eml" with an attachment.

mkdir tmp
ripmime --debug --disable-qmail-bounce -i message.eml -d tmp > ripmime.log

The extracted attachments should be inside the tmp folder.

# ls -l tmp/ 
total 2352 
-rw------- 1 root root 2396801 Aug  2 16:10 attached_file.jpeg 
-rw-r--r-- 1 root root       0 Aug  2 16:10 textfile0 
-rw-r--r-- 1 root root       4 Aug  2 16:10 textfile1 
-rw-r--r-- 1 root root      25 Aug  2 16:10 textfile2

As you can see, ripMIME extracted a file attached_file.jpeg which is not group readable. This is not a problem for us, because we are going to run simscan as the clamav user, but if you are planning to run it as simscan and then including clamav in the simscan group, you should patch ripMIME with this patch, otherwise clamav will not be allowed to read the attachments.

Installing `simscan`

Note that we have to explicitly tell the compiler where the clamav db is (--enable-clamavdb-path).

SIMSCAN_VER=1.4.6.2
cd /usr/local/src
wget https://github.com/sagredo-dev/simscan/archive/refs/tags/v${SIMSCAN_VER}.tar.gz
tar xzf v${SIMSCAN_VER}.tar.gz
cd simscan-${SIMSCAN_VER}
chown -R root:root .

./configure \
--enable-user=clamav \
--enable-clamav=y \
--enable-spam=y \
--enable-spam-passthru=y \
--enable-spam-hits=9.0 \
--enable-per-domain=y \
--enable-ripmime \
--enable-attach=y \
--enable-custom-smtp-reject=y \
--enable-spamc-user=y \
--enable-received=y \
--enable-clamavdb-path=/usr/local/share/clamav

make
make install-strip

Take a look to the README file for an explanation of all the configuration options. Concerning spam, I want to reject via smtp the spam with a score greater than 9.0 and pass to the user the spam below this score.

--enable-per-domain=y|n Turn on per domain based checking.
--enable-spam=y|n Turn on spam scanning. default no.
--enable-spam-passthru=y|n Pass spam email thru or reject. Default: disable (reject)
--enable-spam-hits=number Reject spam above this hit level. Default 10.0
--enable-custom-smtp-reject=y Turns custom smtp reject messages on and off. When enabled simscan will place the virus name in the reject message if a virus is detected. Requires the qmail-queue-custom-error.patch. Enabling dropmsg disables this option (more info here).
--enable-spamc-user=y Mandatory option if you want to allow the spamassassin user preferences via SQL.
--enable-received=y Add a Received: line to the message, showing the scanners that were used and some stats (you have to patch simscan)

Now create the temporary dir and assign it proper permissions:

mkdir /var/qmail/simscan
chown clamav:clamav /var/qmail/simscan

`qmail-queue-custom-error` patch

As you know the qmail-queue-custom-error patch (more info here) that we applyed before enables simscan to return the appropriate message for each e-mail it refuses to deliver.

Please refer to this page to understand how the smtp rejection works with simscan. This guide shortly remainds that:

For virus rejection, the message contains the name of the virus such as :

Your email was rejected because it contains the Worm.Bagle.AU virus

For spam rejection, the message is more generic, merely stating that the message was rejected because it was considered spam:

Your email is considered spam (53.5 spam-hits)

For attachment rejection, the message contains the name of the attachment :

Your email was rejected because it contains a bad attachment: trojan.exe

How to setup `simscan` to manage the spamming as better as possible

Let's assume that spamassassin is configured with a spam level of 5.0, so that hits above this score are labeled as spam.

Of course, soon or later, spamassassin will label as junk an important email for a customer of yours, and we will never want to reject such a message. On the other hand there will be a score level, say 9.0, above which we can absolutely trust in spamassassin response and let simscan reject those emails without storing them in the user's mailbox.

Therefore we will configure simscan/spamassassin in order to:

Reject the emails with a score > 9.0
Pass through the emails with a score between 5.0 and 9.0
Consider ham all the other emails with a score < 5.0

To accomplish this create a simcontrol like the following:

cat > /var/qmail/control/simcontrol << __EOF__
:clam=yes,spam=yes,spam_hits=9.0,attach=.vbs:.lnk:.scr:.wsh:.hta:.pif,size_limit=10000000
__EOF__

In addition, due to the size_limit=10000000 setting, attachments with size greater than 10000000 bytes (around 10MB) won't be passed to spamassassin (default is 250KB).

Remember to update simcontrol.cdb every time you modify simcontrol

# update simcontrol.cdb
/var/qmail/bin/simscanmk

Turning on scanning

echo ':allow,CHKUSER_WRONGRCPTLIMIT="3",QMAILQUEUE="/var/qmail/bin/simscan"' >> /var/qmail/control/tcp.smtp
qmailctl cdb

Now simscan/chkuser will close the smtp communication after 3 wrong recipient. You may want to add an instruction like CHKUSER_RCPTLIMIT="50" to limit to the number of recipient per SMTP connection. To be honest, these are settings for chkuser (not simscan).

Understanding the simcontrol file

You can setup rules for a specific user, a specific domain and a default rule as follows:

cat > /var/qmail/control/simcontrol << __EOF__
postmaster@example.com:clam=yes,spam=no,attach=.txt:.com
example.com:clam=no,spam=yes,attach=.mp3
:clam=yes,spam=yes,spam_hits=9.0,attach=.vbs:.lnk:.scr:.wsh:.hta:.pif,size_limit=10000000
__EOF__

The first line sets clam on and spam off for postmaster@example.com and checks for viruses inside attached file .txt and .com names.
The second line sets clam off and spam on for the example.com domain and disallows .mp3 files for the attachment scanner.
The third line sets the default for the whole machine to enable clam, spam scanning, and sets the reject level for spam hits to 9.0. It also sets the attachments size limit to be passed to spamassassin to around 10MB.

Configuring `simscan` with the `DKIM` patch

If you want to enable DKIM you have to modify the simscan configuration accordingly as explained in the DKIM page.

Updating `simscan`

The patch applied will add a line like this to the header:

Received: by simscan 1.4.0 ppid: 5613, pid: 5684, t: 0.7355s
          scanners: attach: 1.4.0 clamav: 0.98.4/m:55/d:19599 spam: 3.4.0

You have to update the simscan's database if you want to get the current versions of clamav and spamassassin:

# /var/qmail/bin/simscanmk -g
simscan versions cdb file built. /var/qmail/control/simversions.cdb

Since the update has to be done each time you refresh the virus database, you have to adjust you freshclam configutation as follows.

First of all let's download and install the program that will do the update:

wget --no-check-certificate https://qmail.jms1.net/simscan/update-simscan.c
gcc -s -o /usr/local/sbin/update-simscan update-simscan.c
chown root:clamav /usr/local/sbin/update-simscan
chmod 4110 /usr/local/sbin/update-simscan

Now modify the freshclam configuration file in order to run the update-simscan executable each time the database is changed. You have to edit the file /usr/local/etc/freshclam.conf and modify it in this way:

OnUpdateExecute
OnUpdateExecute /usr/local/sbin/update-simscan

/var/qmail/simscan on a ramdisk

On his simscan's information page, John Simpson suggests to mount the work directory of simscan on a ramdisk, in order to speed up the process of file load from the disk.

It is sufficient to mount that directory in this way in your /etc/fstab:

CLAMAV_UID=`id -u clamav` 
CLAMAV_GID=`id -g clamav` 
echo "none /var/qmail/simscan tmpfs nodev,noexec,noatime,uid=$CLAMAV_UID,gid=$CLAMAV_GID,mode=2750 0 0" >> /etc/fstab

Be aware that you have to adjust the uid and gid to the actual clamav user and group numbers respectively.

clamav-unofficial-sigs

Testing

simscan

add a comment

Comments

Adding new header

Shah Imran June 29, 2025 07:49 CET

Hi,

thanks for nice work. I'm using simscan with below config:

./configure \
--enable-user=clamav \
--enable-clamav=y \
--enable-attach=y \
--enable-spam=y \
--enable-dropmsg=y \
--enable-quarantinedir=/var/qmail/quarantine \
--enable-per-domain=y \
--enable-ripmime \
--enable-spamc-user=y \
--enable-received=y \
--enable-clamavdb-path=/usr/local/share/clamav

The drawback of this configuration is, all spam mail are dropped in the /var/qmail/quarantine/. Later I use a bash restore script to restore the mail to users. This is an example, not actual script:

for file in /home/vpopmail/domains/xyz.com/postmaster/Maildir/.Restore/cur/*;
do 
  /usr/bin/cat $file |/var/qmail/bin/qmail-inject && /usr/bin/rm $file; 
done

I can collect sender's address and match recipient's address from /var/qmail/control/*rcpthosts so no mail outside our domain is restored. But we get huge mail where recipient's addresses are in BCC. In that case, I need to get recipient's address from log file and manually use those dropped mail to restore to the users. It's very painful. If I fail to restore it, the user will miss the important mail. Due to company policy, I'm unable to tag spam mail and deliver to them (Because users are not aware of spam tagging. They click links or open files though spam tagging is enabled. All training attemptd failed several times, so company decided to drop all spam/virus mail and restore it later manually.

In the current situation, I'm thinking about to add a header (for example: X-REQ-BY-COMP: ) where all recipient's email addresses will be added under that header in the main mail and dropped to /var/qmail/quarantine/. While restoring mail, I'll collect email from that header, remove the header and deliver it to users. As a server admin, I think, doing so will not break the email BCC compliance set by intertionally. I can already see all BCC address from log file. To ease my daily work, I'm planning to do it. But I'm unable to find where to start. I'm requesting you to guide me where and if possible how to implement it in my server.

Your help is highly apprecieated.

Installing and configuring simscan

Version 1.4.6 details

ripMIME

Testing

Installing simscan

qmail-queue-custom-error patch

How to setup simscan to manage the spamming as better as possible

Turning on scanning

Understanding the simcontrol file

Configuring simscan with the DKIM patch

Updating simscan

/var/qmail/simscan on a ramdisk

Comments

qmail notes

LXC scripts

Other contents

Recent comments

See also...

Recent posts

`ripMIME`

Installing `simscan`

`qmail-queue-custom-error` patch

How to setup `simscan` to manage the spamming as better as possible

Configuring `simscan` with the `DKIM` patch

Updating `simscan`