asmtpd(8)

NAME
asmtpd - Avenger SMTP Daemon

SYNOPSIS
asmtpd [-d] [-f config-file]

asmtpd [--spf] [-f config-file]

asmtpd [--rbl] [-f config-file]

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

asmtpd [--synfp] [tcp-port [IP-address [interface ...]]]

asmtpd [--netpath] IP-address [network-hops]

DESCRIPTION
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 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 $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 /usr/local/etc/avenger/. The program that executes these scripts is called 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 asmtpd.conf(5) manual page.

  GETTING STARTED
The following is a brief description of how to get started with asmtpd. More information is available in the asmtpd.conf(5) and avenger(1) manual pages.

•   If you haven't already, create a user called 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 "AvengerUser user" in the asmtpd.conf configuration file when you create that.)

•   Create the directory /usr/local/etc/avenger.

•   Create a file /usr/local/etc/avenger/asmtpd.conf.

    The most important thing to put in this file is the proper separator character. This is the character that separates a user name from a mail extension in an email address. For instance, with sendmail, typically mail to user+extension goes to user, so you should configure Separator as +. With qmail, the character is -.

    If, for example, you determine the separator character on your system is +, the following might be a reasonable asmtpd.conf file:

    Separator +
    Hostname your.host.name
    Sendmail sendmail -oi -os -oee
    #EmptySender @
    SPFfail include:spf.trusted-forwarder.org
    AvengerUser avenger
    NoCheck postmaster
    NoCheck abuse

    Hostname should be replaced with the name of your host.

    Sendmail should be configured with the mail injection program. You may need to supply the full pathname for the sendmail executable if it is not on the default path (in particular, some systems place sendmail in /usr/lib/sendmail). Note also that some sendmail replacements, such as Exim, do not accept the -oee flag; for such systems you will need to use -oem. (But don't use -oem with real sendmail, or you can get duplicate bounce messages for bad mail.)

    EmptySender is the -f argument that must be passed to sendmail to send a bounce message from the empty envelope sender (i.e., messages that start "From MAILER-DAEMON" in Unix mbox-format files). On most systems this should be empty (the default). Some older versions of sendmail ignore the arguments -f "", however; on these systems you must use -f "@". If you are running such an old version of sendmail, you will want to uncomment the EmptySender line by deleting the "#" character.

    SPFfail you should set as above, or else you may be unable to receive mail from places such as evite.com. AvengerUser is the user under which to run system-wide default scripts. NoCheck specifies email addresses that should not be checked by external scripts. It is advisable to list any email addresses that are likely to get complaints about Mail Avenger not functioning properly.

•   Create a file /usr/local/etc/avenger/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:

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

•   Play with scripts. Read the man page for avenger(1), create a .avenger/rcpt file in your home directory, and maybe create a site-wide default file /usr/local/etc/avenger/default. You will also very likely want to create a script /usr/local/etc/avenger/unknown to reject mail to unknown users. See the man page for aliascheck(1) for an example of how to do this.

  OPTIONS
Normally, when started, asmtpd runs as a daemon, sends its output to the system log, and looks for its configuration file in /usr/local/etc/avenger/asmtpd.conf. The following options change this behavior:

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

-f config-file
    Specifies an alternate location for the configuration file.

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

--spf [-f config-file]
    Runs in a mode where asmtpd simply performs SPF tests on <IP-address, sender> 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 SPF_TRACE environment variable discussed below).

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

--avenge [-f config-file] recipient [sender [IP-address]]
    Tests the avenger script for recipient, which must be a fully-qualified email address with a domain. This simulates an SMTP transaction in which client IP-address tries to send mail from sender to recipient. If recipient is not specified, it defaults to postmaster@HostName (where Hostname is the local hostname, as specified in 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 DebugAvenger setting. At the end, outputs the SMTP response asmtpd would give to the "RCPT" command.

--synfp [tcp-port [IP-address [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 CLIENT_SYNFP in the man page for avenger(1).)

    By default, asmtpd will print the fingerprints of any incoming TCP connection. If tcp-port is non-zero, however, asmtpd will only consider SYN packets sent to that TCP port number. If 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 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 /dev/bpf* packet filter devices on your machine).

--netpath IP-address [network-hops]
    asmtpd records the network path to mail clients using a technique similar to the traceroute utility found on many operating systems. The --netpath option tests asmtpd's implementation of this functionality. If network-hops is positive, asmtpd will record only the first network-hops hops on the way to IP-address. If network-hops is negative, asmtpd will output only the last network-hops hops on the way to IP-address. If 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.

ENVIRONMENT

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

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

FILES
/usr/local/etc/avenger/asmtpd.conf, /usr/local/etc/avenger/domains, /usr/local/etc/avenger/aliases, /usr/local/etc/avenger/unknown, /usr/local/etc/avenger/default, $HOME/.avenger/rcpt*

SEE ALSO
asmtpd.conf(5), avenger(1)

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

BUGS
If the packet capture library (libpcap) header files were not available at compile time, asmtpd will not support TCP SYN fingerprints and the --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.

AUTHOR
David Mazieres