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