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 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.

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)