=for comment $Id: smtpdcheck.pod,v 1.3 2005/07/19 21:42:14 dm Exp $

=head1 NAME

smtpdcheck - check SMTP servers

=head1 SYNOPSIS

smtpdcheck [--stop {I<ip-addr>|I<name>}] [--timeout I<seconds>]
           [I<prio>:]I<server> [[I<prio>:]I<server>]

=head1 DESCRIPTION

smtpdcheck checks to see if SMTP servers are available.  The intent is
for use on secondary mail servers, which have no reason to accept mail
when the primary server is available.

The argument consists of a list of server names, each of which may
optionally be prefixed by a numeric MX priority and a colon.  (This is
exactly the format for MX records returned by the I<avenger> I<dns>
command.)  smtpdcheck will attempt to connect to each server in
succession.

If one of the servers specified on the command line is available,
smtpdcheck will print its name to standard output and exit with status
1.  If smtpdcheck cannot connect to any of the servers, it will exit
with status 0.  If a system error occurs, smtpdcheck will exit with
status 2.

=head2 OPTIONS

=over

=item B<--stop> {I<ip-addr>|I<name>}

Tells smtpdcheck to stop before checking a server with IP address
I<ip-addr> or hostname I<name>.  If such a host is encountered in the
list of servers and I<prio> is specified, then smtpdcheck will
consider it acceptable for other servers with the same priority to be
available, even if those servers were first in the list.  In other
words, given the following arguments:

       smtpdcheck --stop s2.domain.com \
		  10:s1.domain.com 10:s2.domain.com \
		  20:s3.domain.com

This command will always succeed, regardless of whether
C<s1.domain.com> is up, because C<s2.domain.com> has the same
priority.  On the other hand, the following command will fail and
output C<s1.domain.com> if C<s1.domain.com> is up:

       smtpdcheck --stop s2.domain.com \
		  10:s1.domain.com 20:s2.domain.com \
		  30:s3.domain.com

If a I<gethostbyname> lookup for the argument I<name> fails,
smtpdcheck will exit immediately with status 2.

=item B<--timeout> {I<seconds>]

By default, smtpdcheck spends 10 seconds probing each server.  This
includes the time to do a DNS lookup, to establish a TCP connection to
port 25 of the server, and to read the "220" SMTP code from the
server's SMTP greeting message.  To use a different value, specify it
with the B<--timeout> option.  The value 0 disables the timeout
completely, which is dangerous since smtpdcheck might then end up
waiting forever to read the "220" string.

=back

=head1 EXAMPLES

To refuse to relay mail at a secondary MX server when the primary
server is not down, you might place the following in
F</etc/avenger/secondary> (assuming B<MxLocalRcpt> is 1):

	dns RECIP_MXES mx "$RECIPIENT_HOST"
	setvars
	server=`smtpdcheck --stop $MYIP $RECIP_MXES`
	test -n "$server" && defer "Please use server $server"

=head1 SEE ALSO

L<avenger(1)|avenger(1)>
L<dbutil(1)|dbutil(1)>
L<asmtpd.conf(5)|asmtpd.conf(5)>,

The Mail Avenger home page: L<http://www.mailavenger.org/>.

=head1 BUGS

smtpdcheck could achieve much lower latency by probing all the servers
simultaneously.  It should also include some kind of caching, to avoid
repeatedly trying to contact an unavailable server.  Finally, hosts
with multiple IP addresses could be handled more cleanly, though what
smtpdcheck does should probably work in most cases.

=head1 AUTHOR

David MaziE<egrave>res