=for comment $Id: asmtpd.pod,v 1.15 2005/11/24 21:47:28 dm Exp $

=head1 NAME

asmtpd - Avenger SMTP Daemon

=head1 SYNOPSIS

asmtpd [-d] [--verbose] [-f I<config-file>]

asmtpd [--spf] [-f I<config-file>]

asmtpd [--rbl] [-f I<config-file>]

asmtpd [--avenge] [-f I<config-file>] I<recipient> [I<sender> [I<IP-address>]]

asmtpd [--synfp] [I<tcp-port> [I<IP-address> [I<interface> ...]]]

asmtpd [--netpath] I<IP-address> [I<network-hops>]

=head1 DESCRIPTION

I<asmtpd> is the central server daemon for Mail Avanger.  Mail Avenger
is a highly-configurable MTA-independent SMTP (Simple Mail Transport
Protocol) server designed to let you filter and fight SPAM I<before>
accepting incoming mail from a client machine.  Filtering spam before
accepting a message from a remote machine offers a number of benefits.
First, while mail is in the process of being sent over the network,
more information is available about the client machine, allowing the
possibility of more accurate decisions about spam.  (For example,
machines infected with viruses may be able to be detected by probing.)

Second, filtering during mail transfer allows more options for what to
do with potential spam.  For instance, one can defer the
mail--essentially asking the client to send it again later--which
legitimate mail clients will do automatically, but "spam 'bots"
typically won't.  Moreover, it is much safer to reject spam before
accepting a message.  With typical after-delivery spam checkers, the
only options are to discard spam silently (risking false positives
that completely disappear), or to notify the sender, but if the sender
is forged, this causes more unwanted mail.  By rejecting mail during
an SMTP transaction, this ensures legitimate mail gets bounced to the
sender, while most spam will simply disappear.

Finally, filtering during an SMTP transaction saves resources, since
spam messages need never to be spooled in the mail queue.

There are many ways of fighting and detecting spam.  Though Mail
Avenger has a few basic mechanisms built-in, the philosophy of the
system is to let system administrators and individual users plug in
their own filtering criteria.  The intent is for Mail Avenger to do
the hard part--talk the SMTP network protocol, handle asynchronous DNS
resolution, SPF rule checking, probing of remote SMTP servers for
legitimacy, etc.--while users can set policy through configuration
files with simple shell commands.

The basic approach is for users to create scripts in a directory
called F<$HOME/.avenger> that specify policies for what mail to accept
and what to reject or defer.  System-wide fallback policies can also
be specified by files in F<@etcdir@/>.  The program that executes
these scripts is called I<avenger>, and is described more fully in its
own manual page.

asmtpd can be configured to map different email addresses and domains
to different local users, in addition to a large number of other
configurable features.  These are described more fully in the
L<asmtpd.conf(5)|asmtpd.conf(5)> manual page.

asmtpd also adds a new header field to messages, C<X-Avenger:>,
containing information that may be of use to spam filters.
C<X-Avenger:> contains a list of semi-colon-separated tokens, which if
present mean the following:

=over

=item B<version=>I<number>

Specifies the version of Mail Avenger that received the message.

=item B<receiver=>I<hostname>

Specifies that asmtpd was running on I<hostname> when it received the
message.

=item B<client-ip=>I<IP-address>

=item B<client-port=>I<port-number>

These specify that the client end of the TCP connection from which the
mail came used IP address I<IP-address> and port I<port-number>.

=item B<client-dnsfail=>I<error>

Specifies that a reverse lookup on the client's IP address (to
determine the client's hostname) resulted in I<error>.

=item B<bounce-res=>I<code>

Specifies that attempts to send bounces to the bounce address of the
sender result in SMTP error I<code>.  (This is the same value as the
B<SENDER_BOUNCERES> environment variable described in the
L<avenger(1)|avenger(1)> manual page.)

=item B<syn-fingerprint=>I<fingerprint>

Contains a description of the initial TCP SYN packet used by the
client to initiate the TCP connection over which the mail was sent.
See the description of B<CLIENT_SYNFP> in the L<avenger(1)|avenger(1)>
manual page for an explanation of the format.

=item B<eager-pipelining>

If present, means that the client attempted to pipeline SMTP commands
before receiving the C<250 PIPELINING> response to the SMTP C<HELO> or
C<EHLO> command.  This field has the same meaning as the
B<CLIENT_PIPELINING> environment variable in L<avenger(1)|avenger(1)>.

=item B<post>

If present, means the client issued the invalid SMTP command B<POST>.
See B<CLIENT_POST> in L<avenger(1)|avenger(1)>.

=item B<network-hops=>I<nhops>

This is the number of network hops from the server to the client that
sent this mail (if Mail Avenger can figure this out).  See
B<CLIENT_NETHOPS> in L<avenger(1)|avenger(1)>.

=item B<network-path=>I<IP-list>

Set to a space-separated list of as many intermediary network hops as
Mail Avenger can efficiently discover on the way from the server to
the client that send the mail.  See B<CLIENT_NETHOPS> in
L<avenger(1)|avenger(1)>.

=item B<network-path-time=>I<time>

To save network traffic, Mail Avenger briefly caches routes to a
particular client.  B<network-path-time> specifies the precise time at
which the information in B<network-path> was discovered.  The time is
expressed as a standard Unix time (number of seconds since Jan 1,
1970).

=item B<RBL=>I<domain (IP-addrs)>B<[,> I<domain (IP-addrs)>B<, ...]>

For the each real-time blackhole list (RBL) domain specified in
F<asmtpd.conf> (see the B<RBL> directive in the
L<asmtpd.conf(5)|asmtpd.conf(5)> man page), if the client shows up
in the RBL, I<IP-addrs> specifies what the RBL returns.

Usually, RBLs just return 127.0.0.1 to specify that a client is
present in the blacklist.  However, some services use different IP
addresses to encode some information about why the client is listed.
If an RBL returns multiple IP addresses, asmtpd includes them all,
separated by spaces.

=item B<RBL-errors=>I<domain> B<(>I<error>B<)[,> I<domain> B<(>I<error>B<), ...]>

Lists any RBL domains Mail Avenger was unable to query at the time of
receipt of the message.

=back

=head2 GETTING STARTED

The following is a brief description of how to get started with
asmtpd.  More information is available in the installation guide
F<@sampledir@/INSTALL>, as well as the
L<asmtpd.conf(5)|asmtpd.conf(5)> and L<avenger(1)|avenger(1)> manual
pages.

=over

=item

If you haven't already, create a user called I<avenger> on your
system.  This is the user ID under which system-wide avenger scripts
will run.  (If you wish to use a name other than "avenger", you can
put the directive "B<AvengerUser> I<user>" in the asmtpd.conf
configuration file when you create that.)

=item

Create the directory F<@etcdir@>.

=item

Create a file F<@etcdir@/asmtpd.conf>.  Copy the sample file in
F<@sampledir@/asmtpd.conf> and edit to taste.

=item

Create a file F<@etcdir@/domains>.  List each domain for which you
would like to receive mail, followed by a colon, one per line.  For
example:

    my.first.domain:
    my.second.domain:
      
=item

Fire it up!  Run the command "asmtpd" as root.  You may also want to
set things up to run this command automatically on system startup.

=item

Play with scripts.  Read the man page for L<avenger(1)|avenger(1)>,
create a F<.avenger/rcpt> file in your home directory, and maybe
create a site-wide default file F<@etcdir@/default>.  You will also
very likely want to create a script F<@etcdir@/unknown> to reject mail
to unknown users.  See the man page for L<aliascheck(1)|aliascheck(1)>
and the sample F<@sampledir@/unknown> for an example of how to do
this.

=item

Finally, you may want to try the avenger.local delivery agent.  See
the L<avenger.local(8)|avenger.local(8)> man page for more
information.

=back

=head2 OPTIONS

Normally, when started, asmtpd runs as a daemon, sends its output to
the system log, and looks for its configuration file in
F<@etcdir@/asmtpd.conf>.  The following options change this behavior:

=over

=item B<-d>

Tells asmtpd to stay in the foreground and send its diagnostic
messages to standard error, rather than to the system log.

=item B<--verbose>

Ordinarily, asmtpd will attempt to avoid sending overly many duplicate
copies of a message to the system log file.  The B<--verbose> option
changes this behavior, so that certain error conditions (such as
missing directories) get reported each time they affect a piece of
mail.

=item B<-f> I<config-file>

Specifies an alternate location for the configuration file.

=back

In addition, several other options are available to run asmtpd in
various test modes, for making use of or debugging features.

=over

=item B<--spf> [B<-f> I<config-file>]

Runs in a mode where asmtpd simply performs SPF tests on
S<E<lt>IP-address, senderE<gt>> pairs it reads from standard input.
Can be used to validate asmtpd's SPF implementation against a
different implementation, or to debug SPF records (particularly in
conjunction with the B<SPF_TRACE> environment variable discussed
below).

=item B<--rbl> [B<-f> I<config-file>]

Tests asmtpd's RBL (realtime black hole) list implementation.  The
configuration file should contain one or more B<RBL> directives (see
the manual page for L<asmtpd.conf(5)|asmtpd.conf(5)>).  In this mode,
asmtpd will simply read IP addresses from its input and output the
result of RBL checks.

=item B<--avenge> [B<-f> I<config-file>] I<recipient> [I<sender> [I<IP-address>]]

Tests the avenger script for I<recipient>, which must be a
fully-qualified email address with a domain.  This simulates an SMTP
transaction in which client I<IP-address> tries to send mail from
I<sender> to I<recipient>.  If I<recipient> is not specified, it
defaults to B<postmaster@HostName> (where B<Hostname> is the local
hostname, as specified in F<asmtpd.conf>).  If <IP-address> is not
specified, the local address is used.

With this option, asmtpd will log a transcript of avenger's requests
to standard error, regardless of the actual B<DebugAvenger> setting.
At the end, outputs the SMTP response asmtpd would give to the C<RCPT>
command.

=item B<--synfp> [I<tcp-port> [I<IP-address> [I<interface> ...]]]

Tests asmtpd's SYN fingerprinting implementation.  Listens to the
network and for each incoming TCP connection, prints the IP address
and port of the client, along with a fingerprint describing the
characteristics of the initial SYN packet from the TCP connection.
(For a description of the SYN fingerprint format, see the description
of B<CLIENT_SYNFP> in the man page for L<avenger(1)|avenger(1)>.)

By default, asmtpd will print the fingerprints of any incoming TCP
connection.  If I<tcp-port> is non-zero, however, asmtpd will only
consider SYN packets sent to that TCP port number.  If I<IP-address>
is supplied and is not 0.0.0.0, asmtpd will only took at TCP packets
for that particular IP address (useful if your local machine has
multiple IP addresses).  Finally, by default asmtpd will listen to
whatever network interfaces correspond to I<IP-address> (or all
active non-loopback interfaces for 0.0.0.0 or unspecified).  You can
alternatively specify explicitly which network interfaces asmtpd
should listen on (e.g., "eth0 eth1").

To use this option, you must be root (or at least have permission to
open the F</dev/bpf*> packet filter devices on your machine).

=item B<--netpath> I<IP-address> [I<network-hops>]

asmtpd records the network path to mail clients using a technique
similar to the B<traceroute> utility found on many operating systems.
The B<--netpath> option tests asmtpd's implementation of this
functionality.  If I<network-hops> is positive, asmtpd will record
only the first I<network-hops> hops on the way to I<IP-address>.  If
I<network-hops> is negative, asmtpd will output only the last
I<network-hops> hops on the way to I<IP-address>.  If I<network-hops>
is zero, or is not supplied, asmtpd will output the entire route (or
as much as it can discover, firewall permitting).

To use this option, you must run asmtpd as root for it to use raw
sockets.

=back

=head1 ENVIRONMENT

=over

=item B<SPF_TRACE>

When set to a positive integer, causes asmtpd to send to standard
error a trace of the checks it is performing while processing SPF
records.  If set to 1, simply records which SPF traces are happening.
Setting it to 2 provides more information, while setting it to 3
provides a complete trace.  (Setting the value to 4 or higher
additionally causes asmtpd to send the results of all SPF-related DNS
queries to its standard output, a feature mostly useful to the
implementor.)

=item B<TMPDIR>

asmtpd creates temporary files to hold incoming mail messages before
injecting them into the mail system.  It usually creates a temporary
subdirectory of F</var/tmp> to hold these files (and cleans up the
directory on exit).  If B<TMPDIR> is set, its value will be used in
place of F</var/tmp>.

=back

=head1 FILES

F<@etcdir@/asmtpd.conf>,
F<@etcdir@/domains>,
F<@etcdir@/aliases>,
F<@etcdir@/unknown>,
F<@etcdir@/default>,
F<$HOME/.avenger/rcpt*>
F<@sampledir@/*>

=head1 SEE ALSO

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

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

=head1 BUGS

If the packet capture library (libpcap) header files were not
available at compile time, asmtpd will not support TCP SYN
fingerprints and the B<--synfp> option will not be available.  You may
be able to fix this by installing a package for your OS called pcap,
libpcap, or libpcap-devel (depending on the distribution), then
re-running ./configure and re-compiling Mail Avenger.

=head1 AUTHOR

David MaziE<egrave>res