qmail-verify (OLD VERSION - v1.22)
This version of qmail-verify is the subject of a security advisory: Please upgrade to the latest version instead
On this page: • Introduction • License • Status/Warranty • Documentation • Download • Installation • Setup / Configuration • Migrating from realrcptto • Compatibility • Gotchas • Security • Programming Notes • Archives
This patchset adds a feature to
qmail-smtpd's behaviour, enabled by environment variables: Each recipient specified in the SMTP session (
RCPT command) may be verified to see if it is a valid address on the system. A new daemon,
qmail-verify is used by
qmail-smtpd to determine if addresses are valid;
qmail-smtpd communicates with
qmail-verify using UDP.
This is an update to Paul Jarc's realrcptto patch. The major changes are:
- Recipient verification is done by a separate daemon rather than as part of qmail-smtpd.
- UDP is used by qmail-smtpd to communicate with qmail-verify, the address verification daemon.
- Enabling recipient verification is different, and defaults to off.
- Currently no code has been written for qmail-qmtpd to use qmail-verify: If you use qmail-qmptd and need address verification, stick with the realrcptto patch.
I have used Paul Jarc's code as a basis for this patchset. He raises no objections to this patch. In turn, he has used code from qmail (by Dan Bernstein), who has recently placed qmail in the public domain (see Dan's page on Information for Distributors).
Status / Warranty
No warranty, express or implied is given - USE THIS SOFTWARE ENTIRELY AT YOUR OWN RISK. You will need to satisfy yourself as to the suitability of this software before deploying it in a production environment.
The documentation for this package consists of this web page and the included man pages (the qmail-smtpd man page is an updated version of the original):
Proceed as follows:
- Unpack the patch if you've downloaded a compressed version.
- Patch your qmail source: Enter your
netqmail-1.06source directory and type,
patch < path_to_the_patch/qmail-verify_v1.22.patch
which should apply the patch. If this fails, you will need to patch the failed parts by hand. If you're basing your installation on a Life with qmail style setup, you'd use this patch command just before you compile/build netqmail (
make setup check) in section 2.5.5.
- You can now compile qmail and install as normal.
- You will need to setup a new 'service' to run qmail-verify, and adjust your qmail-smtpd setup, see the Setup/Configuration section below.
- I'd appreciate your report on whether you could compile qmail successfully with this patch so that I can update the Compatibility section below - please email firstname.lastname@example.org with details of your system (esp. OS & CPU) - just
cat systypefrom within your qmail source directory is enough if you're in a hurry!
Setup / Configuration
You need to setup a 'service' for qmail-verify.
You need to enable recipient verification in qmail-smtpd.
If you're comfortable with qmail, daemontools etc. you can probably just skim-read this section; if you need a bit more detail, then this section should provide it...
Setting up qmail-verify as a 'service':
- You need to run
qmail-verify- it runs as a daemon. It normally listens for UDP requests on the loopback address,
127.0.0.1. For testing purposes you can run it from the command line (it will generate output when UDP requests come in).
- Assuming you have daemontools installed (as in LWQ), you can create a 'service' as follows (the example paths here follow those of LWQ esp. section 2.8.22, please adjust them for your own installation if necessary):
- Create supervise directories for
mkdir -p /var/qmail/supervise/qmail-verify/log
- Change into the
- Create the
exec /var/qmail/bin/qmail-verify 2>&1
- Alternatively if you wish to listen on a non-default IP address,
exec env LISTEN="192.168.5.5" /var/qmail/bin/qmail-verify 2>&1
- Create the
exec /usr/local/bin/setuidgid qmaill /usr/local/bin/multilog t /var/log/qmail-verify
- Make the
chmod +x run log/run
- Create the log directory you've just specified,
mkdir -p /var/log/qmail-verify
chown qmaill /var/log/qmail-verify
- Link the
ln -s /var/qmail/supervise/qmail-verify /service
svstat /service/qmail-verify /service/qmail-verify/logwhich should give a result like,
/service/qmail-verify: up (pid 16646) 100 seconds
/service/qmail-verify/log: up (pid 16831) 100 secondsIf either service shows 'up' for only a couple of seconds, you need to check that you've followed these instructions carefully, you can also get a clue looking at the
Enabling recipient verification in qmail-smtpd:
- Assuming you've setup your qmail-smtpd service with tcpserver and the
-xoption (as in LWQ), you just need to update the cdb file referenced by this
-xoption. The source for this file is typically
/etc/tcp.smtp. Decide whether you prefer
VERIFYDEFERbehaviour (see the qmail-smtpd(8) man page), and update the source file accordingly. For example,
:allow,VERIFYDEFER=""which would enable
VERIFYfor any 10.x.y.z address, and no recipient verification for 192.168.x.y addresses, nor for the loopback address.
- If you've setup
qmail-verifyon a non-default address (perhaps you're running
qmail-verifyon a separate machine), you'll also need to specify the address it's listening on - adjust the above to include
VERIFYSVR="192.168.5.5", for example.
- Finally, don't forget to update the cdb file corresponding to the source file you've just edited. If you have a LWQ setup that's,
qmailctl cdbotherwise (assuming
tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp
- Alternatively if you're not using the
tcpserveryou can enable recipient verification for all SMTP connections by setting
VERIFYDEFERin the environment in which
qmail-smtpdis started - for example your startup script might now contain the line
exec env VERIFY="" /usr/local/bin/tcpserver ...
Migrating from realrcptto
It is fairly straightforward to move between these two approaches to recipient verification.
For qmail-verify to do any recipient verification, environment variables
VERIFYDEFER must be enabled (exist).
Recipient verification with realrcptto (the version named qmail-1.03-realrcptto-2006.12.10.patch) is enabled by default. Additionally,
QMAILRRTDENYALL can be used to modify its behaviour.
QMAILRRTDENYALL is similar to qmail-verify's
VERIFYDEFER environment variable: Both invoke the same behaviour (refusal at
DATA stage), but their setup is slightly different:
QMAILRRTDENYALL needs to be set to
VERIFYDEFER just needs to be set.
If you're moving from realrcptto to qmail-verify, you should check your tcpserver cdb source file (if in use) (typically
- Change any occurrences of
- For lines without
QMAILRRTDENYALL="1", you need to add
- If you don't have a default/catch-all line (such as
:allow, you should add one (e.g.
Now rebuild the corresponding cdb file. Alternatively if you're not using a cdb file for tcpserver, you need to enable
VERIFY in the tcpserver/qmail-smtpd startup script instead (or
QMAILRRTDENYALL="1" is set in the script) to enable recipient verification (see above). Remember to rebuild your cdb file having made these changes.
Please let me know if you successfully install qmail-verify on systems not listed below (see the end of the installation section on this page).
Compatibility with qmail, netqmail: The qmail-verify patch should apply cleanly to the following:
- netqmail-1.05 (make sure you've followed its instructions re. collate.sh first). You will get a single 'fuzz' warning (
Hunk #2 succeeded at 59 with fuzz 2.) which is okay.
- netqmail-1.06: You will get a single 'fuzz' warning (
Hunk #2 succeeded at 59 with fuzz 2.) which is okay.
Compatibility with Unix / Linux: qmail 1.03 / netqmail 1.05 / netqmail 1.06 with the qmail-verify patch has been reported to compile successfully on the following:
- Fedora Core 3 / i386
- Fedora 8 / i386
- Debian 3.1 / i386
- Debian 4.0 / i386 (systype: linux-126.96.36.199-:i386-:-:ppro-:-)
- SuSE 9.3 / i586 (systype: linux-2.6.9-023stab043.1-smp-:i386-:-:ppro-:-)
- OpenBSD 4.0 / Ultrasparc
- OpenBSD 4.0 / i386
- OpenBSD 4.1 / i386
- OpenBSD 4.2 / i386
- FreeBSD 4.9 / i386: Add
#include "sys/time.h"to the
- FreeBSD 6.2 / i386 (the
#includefix for FreeBSD 4.9 is not needed)
Compatibility with common patches: In trying a few typical qmail patches, I note that they may clash in
Makefile. In patches I looked at (inluding SMTP AUTH patches, qmail-virusscan and qmail-dk) this will mean some work to finish off the patching by hand: This is however pretty straightforward - alternatively that's bread & butter work for qmail consultants such as the author of this patchset...
If you have a qmail system using
.qmail-default files for your domains, qmail-verify will consider all addresses in the domain 'valid' (since you have provided explicit delivery instructions for all the domain's addresses by using a
.qmail-default). This includes products such as vpopmail - which may have
.qmail-default files like:
| /home/vpopmail/bin/vdelivermail '' bounce-no-mailbox
One workaround may be to remove
.qmail-default files that are there purely to cause a bounce, instead leaving this task to qmail (and qmail-verify); but check that this doesn't confuse the back-end package.
Sean Newton gives an update here regarding vpopmail & qmail-admin: I just discovered yesterday that qmailadmin is one of the apps that cares a lot about .qmail-default files: It errors out when attempting to administer domains if it doesn't see a .qmail-default file. The fix was a few tweaks to user.c to make it treat the absence of .qmail-default as being equivalent to having read one that said "
bounce-no-mailbox\n". The space and the \n are both significant. - find his patch for user.c here - "this will render a qmailadmin-1.2.11 tarball perfectly qmail-verify happy."
Here are some notes relating to security with this patchset, these notes are unlikely to be exhaustive:
It is conceivable that an attacker or spammer could abuse a system patched using this patchset to mount dictionary attacks. To vary how a qmail-verify patched system responds, you should make sure you understand the difference between the
VERIFYDEFER environment variables that control the behaviour of
qmail-smtpd; the former is likely to be more attractive to an attacker/spammer.
On the other hand, with this patchset you have a greater degree of certainty that messages in the queue for local users are destined for real mailboxes.
This patchset deliberately splits the functionality of the original realrcptto patch such that the address verification part runs as a separate daemon,
qmail-verify (running as
qmail-smtpd still able to run as user
qmaild. This also means that the changes to
qmail-smtpd are minimal.
There is no attempt made to check that the replies to the queries to
qmail-verify are genuine: It is conceivable that an attacker might wish to generate spoof UDP replies to tell
qmail-smtpd that an address is valid. For this to occur, the attacker would either need to be a 'local' user to generate such 'replies' on the loopback interface (default configuration), or
qmail-verify would need to be running on an external interface. In the latter case it should be possible to block the qmail-verify port at a firewall.
All that said however, such an attack is of limited use, since qmail will still bounce the message at delivery time for an invalid recipient.
I've tried to ensure that the changes to
qmail-smtpd.c are minimal, this along with the desire to keep
qmail-smtpd running as user
qmaild forming the rationale behind updating the realrcptto patch.
Although I initially used pipes to split the functionality, I replaced this with a UDP client/server setup (with help from John Levine) which was simpler, cleaner and more flexible in how it can be deployed.
In the interests of future extensibility I've created a couple of new files with new functions that may be of use to other similar "call-out" type features. These files are
udpbits.c, the new functions being
connect_udp(). With this structure it should also be more straightforward to replace UDP with (say) Unix domain sockets if that is preferred, either for qmail-verify functionality or for other call-out functions.
qmail-verify.c has some commented-out debug statements, primarily to show - if desired - where in the code qmail-verify decides that an address is valid or not.
qmail-verify.h has ADDR_NOK_TEMP defined, although at present this is not used. This is for possible future use, to indicate that an address is temporarily invalid.
John Levine added code to show the "Controlling user" which is useful for logging esp. from qmail-verify (it can also be enabled in verifyrcpt.c, you'll need to add e.g. eout statements). This doesn't trim trailing 'extension' components to the address, relating to .qmail-abc files - evident when using virtualdomains.
This page last updated: AR, 13th May 2020.