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