NAME
Qmail::Deliverable - Determine deliverability of local addresses
SYNOPSIS
In a qpsmtpd plugin:
use Qmail::Deliverable ':all';
return DECLINED if not qmail_local $recip;
return DECLINED if deliverable $recip;
return DENY, "Who's that?";Probably also pretty useful:
my $dot_qmail_filename = dot_qmail 'foo@example.com';DESCRIPTION
qmail-smtpd does not know if a user exists. Lots of resources are wasted by scanning mail for spam and viruses for addresses that do not exist anyway, including the annoying backscatter or outscatter phenomenon.
Smtp daemons can use this module to quickly verify that a local email address is (probably) actually in use. Qmail::Deliverable uses the same logic that qmail itself (in qmail-send/lspawn/local) uses.
Bundled software
This module comes with a daemon program called qmail-deliverabled and a module called Qmail::Deliverable::Client that provides access to qmail_local and deliverable through via daemon. Typically, the daemon runs as the root user, and the client is used by the unprivileged smtpd.
Functions
All documented functions are exportable, and a tag :all is available for convenience.
Note that addresses and local user names must be in user@domain form, just like qmail internally uses. Comments, angle brackets, etcetera, must be stripped before you pass the address to these functions. Addresses and local user names may not begin with a dot, have two subsequent dots, have a dot before or after the @, have a dot at the beginning, or have any characters that are not in rfc2822's atext definition, with the exception of at most one "@". Given an invalid address, a warning is emitted and an empty list or undef is returned. A single dot at the end is allowed but ignored.
- qmail_local $address
-
Returns the local qmail user for $address, or undef if the address is not local.
Returns $address if it does not contain an @. Returns the left side of the @ if the right side is listed in /var/qmail/control/locals. Returns the left side of the @, prepended with the right prepend string, if the right side is listed in /var/qmail/control/virtualdomains.
- qmail_user $address
- qmail_user $local
-
Returns a list of $user, $uid, $gid, $homedir, $dash, $ext according to /var/qmail/users/assign or qmail-getpw.
- dot_qmail $address
- dot_qmail $user, $uid, $gid, $homedir, $dash, $ext
-
Returns the relevant dot-qmail filename for the given user info. Returns an empty string if a bare ".qmail" (without extension) does not exist, because that needs to be treated specially (defaultdelivery). Returns undef when the given $address is not local, and when no dot-qmail file was found.
No string validation is done if more than one argument is passed.
- deliverable $address
- deliverable $local
-
Returns true if the address is locally deliverable (or temporarily undeliverable), according to rules described in dot-qmail. Also returns true if deliverability could not be determined.
The system default delivery method, and mailbox, maildir, and forward instructions in dot-qmail files, are assumed to always succeed.
Possible return values are:
0x00 Not deliverable 0x11 Deliverability unknown: permission denied for any file 0x12 Deliverability unknown: qmail-command called in dot-qmail file 0x13 Deliverability unknown: bouncesaying with program 0x14 Deliverable, probable: ezmlm mailing list 0x21 Temporarily undeliverable: group/world writable 0x22 Temporarily undeliverable: homedir is sticky 0xf1 Deliverable, almost certainly 0xf2 Deliverable, vdelivermail: directory exists 0xf3 Deliverable, vdelivermail: valias exists 0xf4 Deliverable, vdelivermail: catch-all defined 0xf5 Deliverable, vdelivermail: vuser exists 0xf6 Deliverable, vdelivermail: qmail-ext 0xfe vpopmail (vdelivermail) detected but no domain was given 0xff Domain is not local(These values are, currently, not bitmasks. Do not treat them as such.)
For qmail-ext support (a vpopmail feature that is disabled by default), set
$Qmail::Deliverable::VPOPMAIL_EXT = 1.Status 0x12 is returned if any command is found in a dot-qmail file, regardless of its position relative to mailbox, maildir, and forward instructions.
A special case exists for vpopmail. If a dot-qmail file and calls (on the first line) a program with "vdelivermail" in the command name, then 0x00 or 0xf2 is returned. 0x00 is returned if the line also contains "bounce-no-mailbox" and no directory exists by the name of the local part of the address. For this to work, the full address (including
@domain) must be given.Another special case exists for bouncesaying (used by Plesk). 0x00 or 0x13 is returned.
- reread_config
-
Re-reads the config files /var/qmail/control/locals, /var/qmail/control/virtualdomains, and /var/qmail/users/assign.
CAVEATS
Although bouncesaying and vpopmail's vdeliver are special cased, normally if you have a catch-all .qmail-default and let a program do all the work, this module cannot determine deliverability in a useful way, because it would need to execute the program. It failsafes by allowing delivery.
This module does NOT support user-ext characters other than hyphen (dash). i.e. ".qmail+default" is not supported.
The "percent hack" (user%domain@ignored) is not supported.
The error message passed to bouncesaying is ignored. The default "No mailbox here by that name" is used.
Addresses are lower cased before comparison, but having upper cased user names or domain names in configuration may or may not work.
This module is relatively new and has not been used in production for a very long time.
CDB files are not supported (yet). The plain text source files are used.
This is not a replacement for existing relay checks. You still need those.
Don't forget to escape @ as \@ when testing with double quoted strings.
PERFORMANCE
The server on which I benchmarked this, easily reached 10_000 deliverability checks per second for assigned/virtual users. Real and virtual users are much slower. For my needs, this is still plenty fast enough.
To support local users automatically, qmail-getpw is executed for local addresses that are not matched by /var/qmail/users/assign. If you need it faster, you can use qmail-pw2u to build a users/assign file.
To support vpopmail's vdelivermail instruction, valias is executed for virtual email addresses, to test if a valias exists. If performance is a big issue, you could monkeypatch the valias subroutine in this module to access mysql directly, or if you don't use the valias mechanism at all, to always return false. (Or chmod -x all valias executables in your path.) Valias checking is only used for vdelivermail instructions, and does not impose performance penalties on non-vpopmail systems.
To support vpopmail's vdelivermail instruction on systems that use a "hashed" user directory tree, vuserinfo is executed for virtual email addresses, to test if a virtual user exists. To optimize the common case, this is only done if a directory with the same name as the local-part does not exist. Such directories are made by vpopmail for the first 100 users in a virtual domain. If performance is a big issue, you could monkeypatch the vuser subroutine in this module to access mysql directly. Vuser checking is only used for vdelivermail instructions, and does not impose performance penalties on non-vpopmail systems.
Rough linear performance benchmark of deliverable on our test machine:
vpopmail domain, vuser with top level dir 11000/s
vpopmail domain, valias exists 1500/s
vpopmail domain, vuser with hashed dir 1400/s
vpopmail domain, address unknown 1400/s
local, user listed in users/assign 15000/s
local, user exists, not listed 2000/s
local, user unknown 1800/s
experimental caching enabled 200000/sTo play with the experimental caching, see the four commented lines in the source code.
UNICODE SUPPORT
This module refuses non-ASCII data.
LICENSE
This software does not come with warranty or guarantee of any kind. Use it at your own risk.
This software may be redistributed under the terms of the GPL, LGPL, modified BSD, or Artistic license, or any of the other OSI approved licenses listed at http://www.opensource.org/licenses/alphabetical. Distribution is allowed under all of these these licenses, or any smaller subset of multiple or just one of these licenses.
When using a packaged version, please refer to the package metadata to see under which license terms it was distributed. Alternatively, a distributor may choose to replace the LICENSE section of the documentation and/or include a LICENSE file to reflect the license(s) they chose to redistribute under.
AUTHORS
Matt Simerson <msimerson@cpan.org> Juerd Waalboer <#####@juerd.nl>