qmail-verify8

Usage

Overview

qmail-verify receives UDP packets containing local email addresses and returns a single byte to indicate if the address is valid or invalid to the sender of the UDP packet. qmail-smtpd or qmail-qmtpd are typical clients using the qmail-verify service, although at present only qmail-smtpd has had this functionality added. qmail-verify is based on Paul Jarc's realrcptto patch for qmail (http://code.dogmap.org/qmail/).

qmail-verify uses the files control/locals, control/virtualdomains, users/cdb, the system password file entries (typically in /etc/passwd ) as well as the existence or not of users' home directories and .qmail[-xxx] files to determine if a given address is valid.

Where a qmail system uses .qmail-default files on a per-domain basis in a virtual domains setup, this is likely to result in all addresses being considered 'valid'. This may not in fact be the case in certain situations, such as with extensions/adaptations to qmail like vpopmail which use .qmail-default files throughout (delivery in this case is subsequently handled by a vpopmail component). In these cases a replacement for qmail-verify will be required that can determine address validity.

Other customised qmail installations that use different methods to locate users' mailboxes are likely to need alternatives to qmail-verify or a modified version of it for address verification.

Invocation

qmail-verify should be invoked as user root to have sufficient privileges to determine the validity of a given address. In certain single-UID virtual domains setups, it may be sufficient to run qmail-verify as the single-UID.

By default, qmail-verify listens on localhost (127.0.0.1) on port 11113. This behaviour can be changed by setting the environment variable LISTEN to specify the IP address and/or port: Set this to the desired IP address, optionally followed by a colon and port, thus for example LISTEN="192.168.1.1:10101".

Address verification details

qmail-verify is implemented by taking the various pieces of qmail that parse an address and combining them in the same executable, qmail-verify. Thus logic is taken from qmail-send, qmail-lspawn, qmail-getpw and qmail-local.

Udp packet details

The incoming packet contains just the email address to be checked as a string. The string is optionally terminated with a 0 byte.

The response packet contains a single byte to indicate whether the address is valid. The lowest-order bit of this byte indicates the result: 0 for 'valid', 1 for 'invalid'. Other bits of this response byte are set by qmail-verify to give further debugging information; these other bits should generally be disregarded.

Although not especially designed as a new protocol, extensions to qmail-verify could require the query string to be 0 terminated to separate it from other data to follow. Currently the response packet contains the response byte and the 'Controlling user'; more information could potentially be returned if required.

Control files

At startup qmail-verify reads the following qmail control files: control/envnoathost, control/locals, control/percenthack, control/virtualdomains. If changes are made to any of these files, qmail-verify should be restarted for the changes to take effect in qmail-verify.

If you are using different machines for qmail-verify and qmail-smtpd you should ensure that the machine providing the qmail-verify service has a full set of control files as well as the mailboxes; the machine running qmail-smtpd still needs control/rcpthosts to be setup.

Logging

qmail-verify logs each decision it makes to stderr: The address followed by whether it's valid or not.