qmail-verify(8) 						       v1.32							   qmail-verify(8)

NAME

       qmail-verify - Address verification daemon

SYNOPSIS

       qmail-verify

DESCRIPTION

       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  vpop-
       mail  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 sepa-
       rate 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/virtual-
       domains.  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.

AUTHOR

       Andrew  Richards,  building  on	the  work  of Paul Jarc and Dan Bernstein, and with plenty of help along the way from Russell Nelson, John
       Levine and Charles Cazabon amongst others.

SEE ALSO

       qmail-smtpd(8).

28th August 2009						  Andrew Richards						   qmail-verify(8)