Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc


Qmail Gentoo-Wiki How-To's

The Site:

Other Gentoo-wiki Qmail


Please format this article according to the guidelines and Wikification suggestions, then remove this notice {{Wikify}} from the article



Spam is now one of the most annoying things regarding Internet and any self-respected mail admin can pride him- or herself with sparing clients cleaning up their inbox. This guide will explain the basic techniques that (with the proper configuration) qmail can employ.

Lets's start with a diagram of the path that incoming data takes (one that comes from a remote host, not the one that is locally injected).

The blue boxes and connections are those of standard components while the grey ones are of the optional ones. The more boxes the data has to go through, before it's declared spam or invalid the more resources are used on the server. So one should aim to get rid of unwanted mail as soon as possible.

Consult the following link for more information:

Blacklisting / Whitelisting

Blacklisting is a quite effective method of blocking spammers. The address of the SMTP server which is sending the mail is compared to a database of known spammers and if spam is known to be sent by that server, the mail is not accepted. Whitelisting on the other hand means that the mail from certain IP addresses is always accepted. For more info please refer to links at the bottom of this section.

Usually, the most effective spammers databases are external (it's all about community work), which means that the contents of the blacklist are out of the scope of control of the mail admin (i.e. yourself) and as such prone to all kinds of problems. An example would be rejecting mail from non-spammers which share the SMTP server with spammers. For this reason the decision to use blacklisting should be made very carefully and preferrably only in combination with whitelisting.

Filtering using black lists can be applied at two points in the qmail mail-processing chain. The first possibility (which this section is dedicated to) is to outright reject any mail which comes from a blacklisted server using a program such as rblsmtpd (see graphic above). The other point where black lists can be used is after the mail has been accepted and is waiting in the queue to be delivered. This second method (for example using Spamassassin) is less dangerous, because the black list only accounts for a part of the decision whether mail is considered spam or not, but as such is also less effective.

Rejecting mail before qmail-smtpd

Using rblsmtpd

If not yet available, you will need to emerge sys-apps/ucspi-tcp, which will install the program rblsmtpd. Rblsmtpd compares the IP of the incoming server with a black list and if finding the IP to be spam, replies to the server that it will not accept spam. If there is no record of spam from the IP, it will call up qmail-smtpd and allow it to process the mail. Just to make it clear to those less familiar with qmail, at this point in the process your server knows nothing of the incoming mail except for where it is coming from and the decision to reject is based solely on that information.

Thus we need to activate rblsmtpd before the qmail-smtpd session.

File: /var/qmail/control/conf-smtpd
# You might want to use rblsmtpd with this, but you need to fill in a RBL
# server here first, see for more
# details
QMAIL_SMTP_PRE="${QMAIL_SMTP_PRE} rblsmtpd -r black_list_server"

to activate this feature. Note that the file should already contain most of these lines and the last one should just be uncommented. Instead of "black_list_server" you need to add your own trusted black list source. Take your time making the decision and realize the scope of control of delivery you are giving away. I personally use servers from Spamhaus, but I am herewith not making a statement of their quality.

Because some mail servers are wrongfully put on the list of spammers, or alternatively, for purposefully wanting to accept mail from known spammers, you can employ white lists. You could either run your own black-/ whitelist server, but for non-regular use, you can modify /etc/tcprules.d/tcp.qmail-smtp. Here you can define where rblsmtpd should be used or not. For example:

File: /etc/tcprules.d/tcp.qmail-smtp,RELAYCLIENT="",RBLSMTPD="",RBLSMTPD=""

The first line would mean that anything from this address would not be checked against RBL and can in addition relay anything. Be careful that you completely trust the IP address (e.g. private network), otherwise you are opening a relay. The second line retains the non-relaying mechanism whilst whitelisting the IP address. Refer to the file comments for more information and when finished with it run:

# tcprules /etc/tcprules.d/tcp.qmail-smtp.cdb /etc/tcprules.d/.tcp.qmail-smtp.tmp < /etc/tcprules.d/tcp.qmail-smtp

Restart qmail and check that the log /var/log/qmail/qmail-smtpd/current produce something like:

# @4000000043d6470511d905ec rblsmtpd: pid 22148: 451

As a final step, remove rbl checks downstream in the qmail path, notably in Spamassassin. You're checking at the door, that's quite enough.

Consult following links for more information:

Using spamdyke

An alternative to rblsmtpd is mail-filter/spamdyke. Like rblsmtpd, it will check DNS RBLs and block incoming connections. However, it also provides a large number of additional features, including much better logging, graylisting, SMTP AUTH support, TLS support, reverse DNS checking, reverse DNS/IP address blacklisting and whitelisting, configurable timeouts and more. Installing mail-filter/spamdyke does not require patching or recompiling qmail.

For information on how to use spamdyke instead of rblsmtpd please refer to: HOWTO Spam Filtering with Spamdyke in front of Qmail

Rejecting mail for invalid users

By default, qmail will accept mail for invalid users, process it and bounce it. To prevent it from processing mail for such users and instead reject the mail right away, during the smptd session (see above), qmail can take advantage of a plugin infrastructure qmail-spp which in mail-mta/qmail-1.03-r16 is already included by default. This is not the only way of doing it -- other patches exist (realrcptto or validrcptto), but they are not included in the Gentoo ebuild. Note that with this method spammers can by means of exclusion find out which accounts are valid.

Accounts managed by vpopmail

Warning: this plugin does not corrcetly identify ezmlm mail address's so dont use it if you want ezmlm list emails to be sent through the server.

This part covers setup where accounts are managed by net-mail/vpopmail. Go to the qmail-spp page, copy/paste the code from plugin vpopmail_check_recipient and place it into /var/qmail/plugins/ Then, edit the file to suit your needs. In general everything should be ok, but you might want to enable the log feature or adjust paths for non-standard vpopmail installations.

Make the shell script executable and ensure that the vpopmail binaries it uses to access the users database can be executed by anyone. This is at least necessary when vpopmail is used in conjunction with mysql, otherwise the plugin cannot access the vpopmail data and will reject all mail.

# chmod +x /var/qmail/plugins/
# chmod u+s /var/vpopmail/bin/vuserinfo
# chmod u+s /var/vpopmail/bin/vdominfo
# chmod u+s /var/vpopmail/bin/valias
Warning: The last 3 lines may annoy security-minded individuals.

The activation for the plugins is found in /var/qmail/control/smtpplugins. Edit the file to reflect the addition of the new plugin. The paths are relative from the point of view of the qmail directory (i.e. /var/qmail)

File: /var/qmail/control/smtpplugins

Not sure whether you have to do it, but just to make sure, restart qmail:

# /etc/init.d/svscan restart

And voila, qmail now denies mail for invalid users. Here is a log entry (make sure you enable logging if you want this) of a denied mail.

# @4000000043d6fec2373b3e7c qmail-spp ( [12276]: no such recipient: (/var/vpopmail/domains/

Only "real" local accounts

This part covers setup where you do not have vpopmail installed, users have local Linux accounts. This plugin also correctly handles qmail aliases.

Go to the Werner Maier's local_check_recipient page, copy/paste the code from plugin and place it into /var/qmail/plugins/

Then, edit the file to set list of domains your host accepts email for. Put them after line # put your domain(s) in here.. I think there is nothing else to change.

Make the shell script executable.

# chmod +x /var/qmail/plugins/

The activation for the plugins is found in /var/qmail/control/smtpplugins. Edit the file to reflect the addition of the new plugin. The paths are relative from the point of view of the qmail directory (i.e. /var/qmail)

File: /var/qmail/control/smtpplugins

You do not need to restart qmail, it should already work at this point.

qmail-queue Improvements

Once the e-mail has been received by qmail-smtpd, qmail-queue is called to queue the messages. Originally once queued, qmail-smtpd would signal that the message has been accepted. Nowadays with some additional queue programs we can enhance qmail to scan for viruses, spam or block attachments and upon finding a problematic e-mail, still communicate to the sender that the e-mail is not acceptable.

All these queue improvement programs require a patch, but that one is already included in the gentoo qmail ebuild. You can tell qmail to use the new queue program in /var/qmail/control/conf-common or per-server in /etc/tcprules.d/tcp.qmail-*.cdb.


Judging by the number of posts in the forum and howtos, mail-filter/qmail-scanner is one of the more popular queue upgrades available. It's a huge perl script so on the positive side very easy to adapt, but tends to be a bit resource consuming. On how to install and use it, please refer to:

Once everything works to your liking, I would recommend rejecting spam instead of accepting and discarding it. This will notify the sender that the mail hasn't been accepted and not let him wonder where it got lost.

File: /var/qmail/bin/
# st: If you enable sa-reject and sa-delete is properly set, # messages with a score higher than (required_hits + sa_delete) # will be rejected before the smtp session is closed. # Otherwise they are just dropped silently. (1/0) my $sa_reject_site='1'; my $sa_reject='';

Last modified: Sun, 13 Jul 2008 02:47:00 +0000 Hits: 16,818