_       _               _
     __ _ _ __ ___ _ __ | |_ ___| |__   ___  ___| | __
    / _` | '__/ __| '_ \| __/ __| '_ \ / _ \/ __| |/ /
   | (_| | | | (__| |_) | || (__| | | |  __/ (__|   <
    \__, |_|  \___| .__/ \__\___|_| |_|\___|\___|_|\_\
       |_|        |_|


  Fabio Busatto

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program (see the file COPYING included with this
  distribution); if not, write to the Free Software Foundation, Inc.,
  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA



------------
INTRODUCTION
------------

This software checks email addresses in order to guess if relaying a mail
locally would find a valid recipient, avoiding bounces.
False positives could happen (you accept a mail but it turns into a bounce),
but they're not harmful.

The program accepts the email address as the only argument on the command line
and sentences if it has a valid recipient (exit 0) or not (exit 255).



------------
INSTALLATION
------------

Step 1: Configuration
---------------------
Configure qrcptcheck enabling the modules you need.

  # ./configure [configure options] [--enable-module1] [--enable-module2] ...

Remember that enabling unneeded modules will result in (maybe) some false
positives, but not enabling needed ones will result in your server to refuse
mails sent to valid users.

Step 2: Installation
--------------------

  # make && make install-strip (or just make install)

Probably you want to change permissions of qrcptcheck binary, and setuid it
in order to access the user database(s).

Step 3: Test
------------
Test your installation executing qrcptcheck with a set of well-known email
addresses (both valid and invalid), and check the exit code.

  # qrcptcheck root@example.net && echo VALID



------------------
ADDRESS EXTENSIONS
------------------

Address extensions are supported by modules, which look at the local part of
the address in order to create any valid lookup.
This should support mailing list managers implemented as address extension
aliases, like ezmlm and mlmmj.



-------
MODULES
-------

Module: vpopmail (--enable-vpopmail)
------------------------------------
This module checks in the vpopmail user database for a matching recipient.
Lookup is performed on local@domain, in both vpomail users and in vpopmail
aliases.
If domain has a catch-all account (in .qmail-default), an email address in
such domain is always recognized as having a valid recipient.
If domain is empty, the lookup fails.

Module: alias (--enable-alias)
------------------------------
This module checks in the qmail alias directory for a matching recipient.
Lookup is performed on local part, domain is ignored.
Aliases must be lowercase.

Module: passwd (--enable-passwd)
--------------------------------
This module checks in the system user database for a matching recipient.
Lookup is performed on local part, domain is ignored.
Users must be lowercase.

Module: users (--enable-users)
--------------------------------
This module checks in the qmail user database for a matching recipient.
Lookup is performed on local part, domain is ignored.
It is useful only if you directly modify the assign file, or if you use
some user management system that is not covered by other modules.
Because this module might create lots of false positives, use it only if
you really need it.
Users must be lowercase.



-----------
NEW MODULES
-----------

You can easily write your own module to lookup your users.
This is a quick-and-dirty qrcptcheck hacking howto:

1. write your new module in the src/ directory copying style
   and layout from other existing modules
2. edit qrcptcheck.c in the src/ directory and add support for your module
   in the main program structures
3. edit Makefile.am in the src/ directory and add your source file to the
   EXTRA_qrcptcheck_SOURCES variable
4. edit configure.ac and add AC_ARG_ENABLE and a testsuite for your module
5. run autoreconf --install
6. run ./configure --help

You should be able now to compile your new module into qrcptcheck.