.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "avenger 1"
.TH avenger 1 "2010-04-11" "Mail Avenger 0.8.1" "Mail Avenger 0.8.1"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
avenger \- Mail Avenger
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mail Avenger is a highly-configurable MTA-independent \s-1SMTP\s0 (Simple
Mail Transport Protocol) server designed to let you filter and fight
\&\s-1SPAM\s0 \fIbefore\fR accepting incoming mail from a client machine.
\&\fIavenger\fR is the script run on behalf of each user to decide whether
to accept incoming mail.
.PP
When a client attempts to send mail to a user on the system, the
avenger \s-1SMTP\s0 daemon, asmtpd, runs avenger to process the file
\&\fI.avenger/rcpt\fR in the user's home directory.  That file, a shell
script with access to special functions, determines how the \s-1SMTP\s0
server should proceed.  The possible outcomes are:
.IP "\(bu" 4
Provisionally accept the mail, falling back to system-default rules
.IP "\(bu" 4
Accept the mail immediately with no further checks
.IP "\(bu" 4
Reject the mail immediately
.IP "\(bu" 4
Defer the mail, telling the client to re-send it later
.IP "\(bu" 4
Redirect the processing to another local name.  The name can be
another email address belonging to the current user, or an email
address belonging to the special \fBAvengerUser\fR user.  In the later
case, avenger will be re-run with a different user \s-1ID\s0, and hence can,
for example, employ utilities that maintain state across multiple
users (assuming they all redirect processing the same way).
.IP "\(bu" 4
Run a \*(L"bodytest\*(R" rule.  With this outcome, the the \s-1SMTP\s0 transaction
continues on to receive the entire contents of the mail message, after
which a program is run on the contents of the mail message.  That
program can decide, based on the contents, whether to accept, reject,
defer, or silently discard the message.
.PP
Mail Avenger should typically be configured to have a \fBSeparator\fR
character, allowing each user to maintain multiple email addresses.
With sendmail, \fBSeparator\fR is typically \f(CW\*(C`+\*(C'\fR, with qmail it is
typically \f(CW\*(C`\-\*(C'\fR.  If the separator is \f(CW\*(C`+\*(C'\fR, then any email sent to
\&\fBuser+\fR\fIext\fR\fB\f(CB@your\fB\-host\fR will be processed by files in \fBuser\fR's
\&\fI.avenger\fR directory.
.PP
Avenger first checks for a file named \fIrcpt+\fR\fIext\fR in a user's
\&\fI.avenger\fR directory, then for \fIrcpt+default\fR.  If \fIext\fR itself
contains the separator character, for example
\&\fBuser+\fR\fIext1\fR\fB+\fR\fIext2\fR\fB\f(CB@your\fB\-host\fR, avenger will check first for
\&\fIrcpt+\fR\fIext1\fR\fI+\fR\fIext2\fR, then for \fIrcpt+\fR\fIext1\fR\fI+default\fR, then
for \fIrcpt+default\fR.  The same algorithm is extended for arbitrarily
many separator characters.  (If separator is \f(CW\*(C`\-\*(C'\fR, simply replace \f(CW\*(C`+\*(C'\fR
with \f(CW\*(C`\-\*(C'\fR throughout the above description, including in the names of
files such as \fIrcpt-default\fR.)
.PP
If mail is rejected by the recipient checks but the sender address of
a message is local and \fBUserMail\fR is 1 in \fIasmtpd.conf\fR (which is
not the default), then before rejecting mail, avenger will be run on
behalf of the sending user.  In this case, the address will be parsed
as above, but avenger will look for rules in files beginning \fImail\fR
instead of \fIrcpt\fR.  This mechanism can be used by local users who
want to relay mail through the server from an untrusted \s-1IP\s0 address.
.PP
Using the \fImail\fR configuration files, each user can, for instance,
configure a \fImail+...\fR file to accept mail from an \s-1IP\s0 address he or
she trusts, even if that address is not trusted by all users.
(Alternatively, using tools such as macutil, a user might set up
relaying of mail in which the envelope sender contains a cryptographic
code, checked by the \fImail+...\fR script.)
.PP
Error output of an avenger script \fIrcpt+\fR\fIext\fR or \fImail+\fR\fIext\fR is
redirected to a file called \fIlog+\fR\fIext\fR in the same directory, for
use in debugging.
.SH "AVENGER SYNTAX"
.IX Header "AVENGER SYNTAX"
Avenger configuration files are simply shell scripts, using the syntax
described in \fIsh\fR\|(1).  Each line of the file contains a
variable assignment, command, or function to run.  Scripts can
additionally make use of a number of avenger-specific functions and
variables.  This section describes avenger functions.  The next two
sections describe variables.
.IP "\fBerrcheck\fR" 4
.IX Item "errcheck"
Certain error conditions result in Mail Avenger rejecting mail by
default, unless the message is explicitly accepted through an
\&\fBaccept\fR or successful \fBbodytest\fR check.  These conditions are
indicated by the \fB\s-1MAIL_ERROR\s0\fR environment variable described below.
If your script either rejects mail or falls through to the default
behavior, there is often no reason to run tests on a message that will
end up being rejected either way.  \fBerrcheck\fR exits immediately with
the default error if the default would be to reject or defer the mail.
.IP "\fBaccept\fR [\fImessage\fR]" 4
.IX Item "accept [message]"
Immediately accepts the message (without falling back to any default
rules).  If message is supplied, it will be returned to the \s-1SMTP\s0
client.  The default message is \f(CW\*(C`ok\*(C'\fR.
.IP "\fBreject\fR [\fImessage\fR]" 4
.IX Item "reject [message]"
Reject the mail, with \fImessage\fR.  (The default message is \f(CW\*(C`command
rejected for policy reasons\*(C'\fR).
.IP "\fBdefer\fR [\fImessage\fR]" 4
.IX Item "defer [message]"
Reject the mail with a temporary error code, so that a legitimate mail
client will attempt to re-send it later.  The default for \fImessage\fR
is \f(CW\*(C`temporary error in processing\*(C'\fR.
.IP "\fBbodytest\fR \fIcommand\fR [\fIarg\fR ...]" 4
.IX Item "bodytest command [arg ...]"
Accept the current \s-1SMTP\s0 \f(CW\*(C`RCPT\*(C'\fR command.  However, once the whole mail
message has been received with the \s-1SMTP\s0 \f(CW\*(C`DATA\*(C'\fR command, run
\&\fIcommand\fR with the message as its standard input.  Depending on the
exit status of \fIcommand\fR return to the client's \f(CW\*(C`DATA\*(C'\fR command
either success, temporary, or permanent failure.  Exit code 0 means
accept the mail, 100 means reject, 111 means reject with a temporary
error code (i.e., defer the mail).  See the description of \fBbodytest\fR
in the asmtpd/avenger interface description for more information on
\&\fBbodytest\fR (since this function directly invokes \fBbodytest\fR in
asmtpd).
.Sp
Error output from \fIcommand\fR will be redirected to the same log file
as output from the \fIrcpt+...\fR avenger script invoking the \fBbodytest\fR
function.  Standard output of \fIcommand\fR will be included as a
diagnostic the bounce message if the exit code defers or rejects the
mail.
.Sp
Note that \fIcommand\fR and the arguments passed to \fBbodytest\fR will be
run by the shell.  Thus, it is important not to pass any arguments
that might contain shell metacharacters such as \f(CW\*(C`>\*(C'\fR and \f(CW\*(C`$\*(C'\fR.
.IP "\fBredirect\fR \fIlocal\fR" 4
.IX Item "redirect local"
Finish processing, and re-run avenger as if mail were being sent to a
different username \fIlocal\fR (possibly belonging to the special
\&\fBAvengerUser\fR user).  See the description of \fBredirect\fR in the
asmtpd/avenger interface description for more information on
\&\fBredirect\fR (since this function directly invokes \fBredirect\fR in
asmtpd).
.IP "\fBgreylist\fR [\fIsender-key\fR]" 4
.IX Item "greylist [sender-key]"
This command defers mail the first time mail is received from a
particular sender at a particular \s-1IP\s0 address.  However, after a
certain interval, \fBgreylist_delay\fR, if the client re-sends the mail,
it will be accepted.  Furthermore, from that point on, all mail will
be immediately accepted from that sender and \s-1IP\s0 address, unless the
sender stops sending mail for a period of \fBgreylist_ttl2\fR or more.
If, however, after sending the initial, defered piece of mail, the
client does not try again within a period of \fBgreylist_ttl1\fR, then
any record of the client will be erased, and the next time it tries to
send mail it will be defered again.
.Sp
The parameters can be tuned by setting variables in the script.  The
default values are:
.Sp
.Vb 3
\&    greylist_delay=30m  # Time to wait before allowing message
\&    greylist_ttl1=5h    # How long to remember first\-time senders
\&    greylist_ttl2=36D   # How long to remember ok senders
.Ve
.Sp
\&\fBm\fR means minutes, \fBh\fR hours, and \fBD\fR days.  For a complete list of
allowed suffixes, see the documentation for \fIdbutil\fR\|(1) (in
particular for the \fB\-\-expire\fR option).
.Sp
\&\fIsender-key\fR, if supplied, is used to identify the sender.  The
default value is \f(CW\*(C`$CLIENT_IP $RECIPIENT $SENDER\*(C'\fR.  If, for example,
you wanted to record only the first 24\-bits of \s-1IP\s0 address and didn't
care about the recipient, you could use the command:
.RS 4
.Sp
.RS 4
\&\fBgreylist \*(L"${CLIENT_IP%.*} \f(CB$SENDER\fB\*(R"\fR
.RE
.RE
.RS 4
.RE
.IP "\fBsetvars\fR" 4
.IX Item "setvars"
All functions that set a variable by means of an external query to
asmtpd are performed asynchronously.  \fBsetvars\fR actually waits for
results and sets the values of those variables.  In this way, a number
of potentially slow requests (such as \s-1DNS\s0 lookups) can be initiated
concurrently, and their latencies overlapped.  However, one must
remember to call \fBsetvars\fR, or else variables that should contain the
results of operations will remain unset.
.IP "\fBdns\fR \fIvar\fR \fItype\fR \fIdomain-name\fR" 4
.IX Item "dns var type domain-name"
Performs a \s-1DNS\s0 lookup of \fIdomain-name\fR for records of type \fItype\fR,
and assigns the result to variable \fIvar\fR when you call \fBsetvars\fR.
\&\fItype\fR must be one of \fBa\fR, \fBmx\fR, \fBptr\fR, or \fBtxt\fR (lower-case
only).
.IP "\fBrbl\fR [\fB\-ipf\fR] \fIvar\fR \fIdomain\fR" 4
.IX Item "rbl [-ipf] var domain"
Looks up the current mail sender in a real-time blackhole list (\s-1RBL\s0).
\&\fIdomain\fR is the domain name of the \s-1RBL\s0 (e.g., \f(CW\*(C`bl.spamcop.net\*(C'\fR).  If
the sender is listed, set \fIvar\fR to the result of the \s-1DNS\s0 lookup when
you next call \fBsetvars\fR.  \fB\-i\fR looks up the sender's \s-1IP\s0 address (the
default if no options are specified).  \fB\-p\fR looks up the sender's
domain name (verified \s-1DNS\s0 \s-1PTR\s0 record).  \fB\-f\fR looks up the envelope
sender domain name in the \s-1RBL\s0.
.IP "\fBspf0\fR \fIvar\fR [\fIspf-mechanism\fR ...]" 4
.IX Item "spf0 var [spf-mechanism ...]"
.PD 0
.IP "\fBspf\fR \fIvar\fR [\fIspf-mechanism\fR ...]" 4
.IX Item "spf var [spf-mechanism ...]"
.PD
Tests the sender against an arbitrary query formulated in the \s-1SPF\s0
language.  This is a powerful way to whitelist or blacklist particular
senders.  For example, suppose you want to accept any mail from
machines in the list maintained by trusted\-forwarder.org, accept mail
from any machine name ending \f(CW\*(C`yahoo.com\*(C'\fR reject any mail from users
in the spamcop \s-1RBL\s0, and for other users fall back to the default
system-wide rules.  You might use the following \fIrcpt\fR file:
.Sp
.Vb 10
\&    spf MYSPF +include:spf.trusted\-forwarder.org \e
\&        +ptr:yahoo.com \-exists:%{ir}.bl.spamcop.net ?all
\&    setvars
\&    case "$MYSPF" in
\&        pass)
\&            accept "I like you"
\&            ;;
\&        fail)
\&            reject "I don\*(Aqt like you"
\&            ;;
\&        error)
\&            # Note, could instead fall through to default here
\&            defer "Temporary DNS error"
\&            ;;
\&    esac
.Ve
.Sp
Note that commands \fBspf0\fR and \fBspf\fR are synonymous, but \fBspf\fR is
deprecated, because in a later release of Mail Avenger \fBspf\fR will
become synonymous with \fBspf1\fR.
.IP "\fBspf1\fR \fIvar\fR [\fIspf-mechanism\fR ...]" 4
.IX Item "spf1 var [spf-mechanism ...]"
Performs the same tests as the \fBspf\fR directive, but returns the
result strings \fBNone\fR, \fBNeutral\fR, \fBPass\fR, \fBFail\fR, \fBSoftFail\fR,
\&\fBTempError\fR, and \fBPermError\fR instead of \fBnone\fR, \fBneutral\fR,
\&\fBpass\fR, \fBfail\fR, \fBsoftfail\fR, \fBerror\fR, and \fBunknown\fR.
.SH "AVENGER VARIABLES"
.IX Header "AVENGER VARIABLES"
These variables are set by the avenger script.  In addition, asmtpd
sets a number of environment variables before running avenger.  These
are documented in the next section, \s-1ENVIRONMENT\s0.
.IP "\fB\s-1FILEX\s0\fR" 4
.IX Item "FILEX"
The extension on the file currently being processed.  For example, if
file \fIrcpt+ext\fR is being processed, will be set to \f(CW\*(C`+ext\*(C'\fR.  Empty
when processing just \fIrcpt\fR (or \fImail\fR).  May also contain
\&\fIdefault\fR when a default rule file for some suffix is being run.
.IP "\fB\s-1PREFIX\s0\fR" 4
.IX Item "PREFIX"
.PD 0
.IP "\fB\s-1SUFFIX\s0\fR" 4
.IX Item "SUFFIX"
.PD
Assuming the separator is \f(CW\*(C`+\*(C'\fR, when processing a file
\&\fIrcpt+base+default\fR or \fImail+base+default\fR, \fB\s-1PREFIX\s0\fR is set to
\&\fIbase\fR, while \fB\s-1SUFFIX\s0\fR is set to the portion of the name for which
\&\fIdefault\fR was substituted.  When the file does not end with
\&\fIdefault\fR, \fB\s-1SUFFIX\s0\fR is empty.  When the file is just \fIrcpt\fR with no
extension, both \fB\s-1PREFIX\s0\fR and \fB\s-1SUFFIX\s0\fR are empty.  When \fB\s-1SUFFIX\s0\fR
itself contains a \f(CW\*(C`+\*(C'\fR character, \fB\s-1SUFFIX1\s0\fR contains to the part of
\&\fB\s-1SUFFIX\s0\fR after the first \f(CW\*(C`+\*(C'\fR character, \fB\s-1SUFFIX2\s0\fR contains the part
after the second \f(CW\*(C`+\*(C'\fR, and so on for each \f(CW\*(C`+\*(C'\fR character in suffix.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "\fB\s-1AUTH_USER\s0\fR" 4
.IX Item "AUTH_USER"
If Mail Avenger was compiled with \s-1SASL\s0 support (which is not the
default, unless you supplied the \fB\-\-enable\-sasl\fR argument to
\&\f(CW\*(C`configure\*(C'\fR), and if the client successfully authenticates to the
server using \s-1SASL\s0, then \fB\s-1AUTH_USER\s0\fR will be set to the name of the
authenticated user.
.IP "\fB\s-1AVENGER_MODE\s0\fR" 4
.IX Item "AVENGER_MODE"
Set to \f(CW\*(C`rcpt\*(C'\fR when testing whether a recipient should receive mail.
Set to \f(CW\*(C`mail\*(C'\fR (possibly after an \f(CW\*(C`rcpt\*(C'\fR check fails) when checking
whether to relay mail (possibly on behalf of a local user).
.IP "\fB\s-1AVUSER\s0\fR" 4
.IX Item "AVUSER"
The effective local username for which avenger is being run.
Ordinarily, this will be the same as:
.RS 4
.ie n .IP "$USER${\s-1PREFIX+$SEPARATOR\s0}$PREFIX\e" 4
.el .IP "\f(CW$USER\fR${\s-1PREFIX+$SEPARATOR\s0}$PREFIX\e" 4
.IX Item "$USER${PREFIX+$SEPARATOR}$PREFIX"
.PD 0
.IP "${\s-1SUFFIX+$SEPARATOR\s0}$SUFFIX" 4
.IX Item "${SUFFIX+$SEPARATOR}$SUFFIX"
.RE
.RS 4
.PD
.Sp
However, for special avenger files like \fIunknown\fR and \fIdefault\fR, it
can contain useful information, because unlike the \fB\s-1RECIPIENT_LOCAL\s0\fR
environment variable, \fB\s-1AVUSER\s0\fR reflects substitutions from the
Mail Avenger \fIdomains\fR and \fIaliases\fR files.
.RE
.IP "\fB\s-1CLIENT\s0\fR" 4
.IX Item "CLIENT"
This variable contains the name of the client machine, as typically
reported in \*(L"Received:\*(R" headers.  Its value has the form:
.RS 4
.Sp
.RS 4
[\fIuser\fR\fB@\fR]\fIhost\fR
.RE
.RE
.RS 4
.Sp
\&\fIuser\fR is the user name for the connection reported by the client, if
the client supports the \s-1RFC\s0 1413 identification protocol, otherwise it
is omitted.  \fIhost\fR is a verified \s-1DNS\s0 hostname for the \s-1IP\s0, if asmtpd
could find one.  Otherwise, it is simply the numeric \s-1IP\s0 address.
.RE
.IP "\fB\s-1CLIENT_COLONSPACE\s0\fR" 4
.IX Item "CLIENT_COLONSPACE"
Set to \f(CW1\fR if the client included a space between the colon in the
command \f(CW\*(C`MAIL FROM:\*(C'\fR or \f(CW\*(C`RCPT TO:\*(C'\fR and the subsequent \f(CW\*(C`<\*(C'\fR that
begins an email address.
.IP "\fB\s-1CLIENT_DNSFAIL\s0\fR" 4
.IX Item "CLIENT_DNSFAIL"
If \fBAllowDNSFail\fR is set to 1 in the \fIasmtpd.conf\fR file and
resolving the client's \s-1IP\s0 to a hostname returns a temporary error,
then this variable will be set to a description of the error.
.IP "\fB\s-1CLIENT_HELO\s0\fR" 4
.IX Item "CLIENT_HELO"
Set to the argument the client supplied to the \s-1SMTP\s0 \f(CW\*(C`HELO\*(C'\fR or \f(CW\*(C`EHLO\*(C'\fR
command.
.IP "\fB\s-1CLIENT_IP\s0\fR" 4
.IX Item "CLIENT_IP"
Set to the \s-1IP\s0 address of the client.
.IP "\fB\s-1CLIENT_NAME\s0\fR" 4
.IX Item "CLIENT_NAME"
Set to the verified \s-1DNS\s0 name of the client, if asmtpd can find one.
.IP "\fB\s-1CLIENT_NETHOPS\s0\fR" 4
.IX Item "CLIENT_NETHOPS"
Set to the number of network hops between the server and the client,
if asmtpd can get the client or its firewall to return an \s-1ICMP\s0
destination unreachable (type 3 packet) in response to a \s-1UDP\s0 probe.
Whether or not this is set will depend on firewall configurations.
.IP "\fB\s-1CLIENT_NETPATH\s0\fR" 4
.IX Item "CLIENT_NETPATH"
Set to as many intermediary network hops as asmtpd can determine
between the server and the client.  How close to the client asmtpd can
probe will depend on firewalls.
.IP "\fB\s-1CLIENT_PIPELINING\s0\fR" 4
.IX Item "CLIENT_PIPELINING"
Set to \f(CW1\fR if the client wrote data after the \s-1SMTP\s0 \fB\s-1HELO\s0\fR or \fB\s-1EHLO\s0\fR
command, before receiving its response.  A correct \s-1SMTP\s0 client should
not \*(L"pipeline\*(R" commands until after receiving the result of the
\&\fB\s-1HELO\s0\fR command and verifying that the server accepts pipelined
commands.
.IP "\fB\s-1CLIENT_PORT\s0\fR" 4
.IX Item "CLIENT_PORT"
The \s-1TCP\s0 port number of the client.
.IP "\fB\s-1CLIENT_POST\s0\fR" 4
.IX Item "CLIENT_POST"
Set to \f(CW1\fR if the client sent a \f(CW\*(C`POST\*(C'\fR command at some point during
the \s-1SMTP\s0 session.  \f(CW\*(C`POST\*(C'\fR is not a valid \s-1SMTP\s0 command; it is an \s-1HTTP\s0
command.  However, one technique for sending spam involves exploiting
an open web proxy to \*(L"post\*(R" an \s-1SMTP\s0 session to a mail server.  The
initial \s-1HTTP\s0 headers (including the \s-1HTTP\s0 post command) simply cause
\&\s-1SMTP\s0 syntax errors, while the body of the \s-1POST\s0 command contains \s-1SMTP\s0
commands.  By checking the \fB\s-1CLIENT_POST\s0\fR environment variable, you to
reject mail sent in this way.
.IP "\fB\s-1CLIENT_REVIP\s0\fR" 4
.IX Item "CLIENT_REVIP"
The value of \fB\s-1CLIENT_IP\s0\fR with the order of the bytes reversed.
Suitable for prepending to \f(CW\*(C`.in\-addr.arpa\*(C'\fR or an \s-1RBL\s0 domain to
perform a \s-1DNS\s0 lookup based on \s-1IP\s0 address.
.IP "\fB\s-1CLIENT_SYNFP\s0\fR" 4
.IX Item "CLIENT_SYNFP"
Contains a fingerprint, abstracting the contents of the initial \s-1TCP\s0
\&\s-1SYN\s0 packet the client sent to establish the \s-1TCP\s0 connection.  The exact
contents of \s-1SYN\s0 packets depends on the operating system and version of
the client, and can therefore reveal interesting information about the
type of client connecting to your mail server.  The format of the
fingerprint is:
.RS 4
.Sp
.RS 4
\&\fIwwww\fR\fB:\fR\fIttt\fR\fB:\fR\fID\fR\fB:\fR\fIss\fR\fB:\fR\fI\s-1OOO\s0\fR
.RE
.RE
.RS 4
.Sp
Where the fields are as follows:
.IP "\fIwwww\fR" 4
.IX Item "wwww"
the initial \s-1TCP\s0 window size
.IP "\fIttt\fR" 4
.IX Item "ttt"
the \s-1IP\s0 ttl of the received packet
.IP "\fID\fR" 4
.IX Item "D"
the \s-1IP\s0 \*(L"don't fragment\*(R" bit
.IP "\fIss\fR" 4
.IX Item "ss"
total size of the \s-1SYN\s0 packet (including \s-1IP\s0 header)
.IP "\fI\s-1OOO\s0\fR" 4
.IX Item "OOO"
a comma-separated list of \s-1TCP\s0 options, as follows:
.RS 4
.IP "\fBN\fR" 4
.IX Item "N"
\&\s-1NOP\s0 option
.IP "\fBW\fR\fInnn\fR" 4
.IX Item "Wnnn"
window scaling option with value \fInnn\fR
.IP "\fBM\fR\fInnn\fR" 4
.IX Item "Mnnn"
maximum segment size value \fInnn\fR
.IP "\fBS\fR" 4
.IX Item "S"
Selective \s-1ACK\s0 \s-1OK\s0
.IP "\fBT\fR" 4
.IX Item "T"
timestamp option
.IP "\fBT0\fR" 4
.IX Item "T0"
timestamp option with value zero
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.IP "\fB\s-1CLIENT_SYNOS\s0\fR" 4
.IX Item "CLIENT_SYNOS"
If asmtpd can guess the client's operating system based on
\&\fB\s-1CLIENT_SYNFP\s0\fR, it will set \fB\s-1CLIENT_SYNOS\s0\fR to the value of that
guess.  For example, to greylist mail from Windows machines, you can
run:
.Sp
.Vb 1
\&   match \-q "*Windows*" "$CLIENT_SYNOS" && greylist
.Ve
.IP "\fB\s-1DATA_BYTES\s0\fR" 4
.IX Item "DATA_BYTES"
This variable is not really an avenger variable, as it is only
available in \fBbodytest\fR commands.  It specifies the number of bytes
of message transfered in the \s-1SMTP\s0 \s-1DATA\s0 command, but after converting
\&\s-1CR\s0 \s-1NL\s0 sequences to \s-1NL\s0.  Roughly speaking this is how many bytes are in
the message including all headers after the X\-Avenger:, SPF-Received,
or Received: header.
.IP "\fB\s-1ETCDIR\s0\fR" 4
.IX Item "ETCDIR"
The value of \fBEtcDir\fR from the asmtpd configuration file (or
\&\fI/etc/avenger\fR by default).
.IP "\fB\s-1EXT\s0\fR" 4
.IX Item "EXT"
When avenger runs on behalf of a user \fB\s-1EXT\s0\fR is set to the part of the
address that determines the suffix of the \fIrcpt\fR or \fImail\fR file.
For example, suppose \fBSeparator\fR is \f(CW\*(C`\-\*(C'\fR and the recipient is
\&\fBlist\-subscribe@\fR\fIhost\fR, where \fIhost\fR is not a virtual domain.  If
the \fBAliasFile\fR contains:
.Sp
.Vb 1
\&    list: user\-mylist
.Ve
.Sp
Then avenger will be run on behalf of \f(CW\*(C`user\*(C'\fR (because alias expansion
yields \fBuser-mylist-subscribe\fR).  \fB\s-1EXT\s0\fR will be set to
\&\fBmylist-subscribe\fR.
.Sp
Note that \fB\s-1EXT\s0\fR is empty when there is no suffix, and that it is
equal to the name of the system file being processed when avenger is
run on a system file.  Like \fB\s-1RECIPIENT\s0\fR, this variable is not set for
\&\fBbodytest\fR commands.
.IP "\fB\s-1HOST\s0\fR" 4
.IX Item "HOST"
Set to the name of the local host, as specified by the \fBHostName\fR
directive in \fIavenger.conf\fR.
.IP "\fB\s-1MAIL_ERROR\s0\fR" 4
.IX Item "MAIL_ERROR"
This variable is set when the \s-1SPF\s0 disposition of the sender is
\&\fBfail\fR, or when asmtpd is unable to send a bounce message to the
sender address.  In either case, Mail Avenger will reject the mail if
the script falls through to the default.
.IP "\fB\s-1MSGID\s0\fR" 4
.IX Item "MSGID"
A randomly generated string for this message, which can be useful to
correlate calls to rcpt scripts with bodytest scripts.  Note this is
unrelated to the Message-ID header in the message, but does show up in
the Received header that Mail Avenger inserts.
.IP "\fB\s-1MYIP\s0\fR" 4
.IX Item "MYIP"
\&\s-1IP\s0 address of local end of \s-1SMTP\s0 \s-1TCP\s0 connection.
.IP "\fB\s-1MYPORT\s0\fR" 4
.IX Item "MYPORT"
\&\s-1TCP\s0 port number of local end of \s-1SMTP\s0 \s-1TCP\s0 connection.  Ordinarily this
will be 25.
.IP "\fB\s-1RECIPIENT\s0\fR" 4
.IX Item "RECIPIENT"
The envelope recipient of the message.  Note that this environment
variable is not present for \fBbodytest\fR programs, since such programs
may be run on behalf of multiple users.
.IP "\fB\s-1RECIPIENT_HOST\s0\fR" 4
.IX Item "RECIPIENT_HOST"
The domain part of \fB\s-1RECIPIENT\s0\fR, folded to lower\-case\*(--i.e., \fIhost\fR
when \fB\s-1RECIPIENT\s0\fR is \fIlocal\fR\fB@\fR\fIhost\fR.  Not present for \fBbodytest\fR
programs, as noted in the description of \fB\s-1RECIPIENT\s0\fR.
.IP "\fB\s-1RECIPIENT_LOCAL\s0\fR" 4
.IX Item "RECIPIENT_LOCAL"
The local part of \fB\s-1RECIPIENT\s0\fR, folded to lower\-case\*(--i.e., \fIlocal\fR
when \fB\s-1RECIPIENT\s0\fR is \fIlocal\fR\fB@\fR\fIhost\fR.  Not present for \fBbodytest\fR
programs, as noted in the description of \fB\s-1RECIPIENT\s0\fR.
.IP "\fB\s-1SENDER\s0\fR" 4
.IX Item "SENDER"
The envolope sender of this mail message (i.e., the argument supplied
by the client to the \f(CW\*(C`MAIL FROM:\*(C'\fR \s-1SMTP\s0 command.)
.IP "\fB\s-1SENDER_HOST\s0\fR" 4
.IX Item "SENDER_HOST"
The hostname part of \fB\s-1SENDER\s0\fR, converted to lower-case (i.e., \fIhost\fR
in \fIuser\fR\fB@\fR\fIhost\fR).
.IP "\fB\s-1SENDER_LOCAL\s0\fR" 4
.IX Item "SENDER_LOCAL"
The local part of \fB\s-1SENDER\s0\fR, converted to lower-case (i.e., \fIuser\fR in
\&\fIuser\fR\fB@\fR\fIhost\fR).
.IP "\fB\s-1SENDER_MXES\s0\fR" 4
.IX Item "SENDER_MXES"
A list of \s-1DNS\s0 \s-1MX\s0 records for \fB\s-1SENDER_HOST\s0\fR, if that hostname has any
\&\s-1MX\s0 records.
.IP "\fB\s-1SENDER_BOUNCERES\s0\fR" 4
.IX Item "SENDER_BOUNCERES"
For non-empty envelope senders, asmtpd attempts to see if it is
possible to deliver bounce messages for the sender.  If not,
\&\fB\s-1SENDER_BOUNCERES\s0\fR is set to a three-digit \s-1SMTP\s0 error code.  If the
first digit is 4, the error was temporary.  If the first digit is 5,
the error was permanent.  Note that failure to accept bounce messages
is considered a \fB\s-1MAIL_ERROR\s0\fR as described above, and will cause mail
to be rejected by default.
.IP "\fB\s-1SEPARATOR\s0\fR" 4
.IX Item "SEPARATOR"
The value of \fBSeparator\fR from the asmtpd configuration file.  There
is no default (\fB\s-1SEPARATOR\s0\fR will not be set if no \fBSeparator\fR is
specified in the configuration file).  However, it should be
configured for \f(CW\*(C`+\*(C'\fR with sendmail and \f(CW\*(C`\-\*(C'\fR with qmail.
.IP "\fB\s-1SPF0\s0\fR" 4
.IX Item "SPF0"
.PD 0
.IP "\fB\s-1SPF\s0\fR" 4
.IX Item "SPF"
.PD
The result of performing an \s-1SPF\s0 check on the message.  Will be one of:
\&\fBnone\fR, \fBneutral\fR, \fBpass\fR, \fBfail\fR, \fBsoftfail\fR, \fBerror\fR, or
\&\fBunknown\fR.  Note that \fB\s-1SPF0\s0\fR and \fB\s-1SPF\s0\fR are synonymous, but \fB\s-1SPF\s0\fR
is deprecated as a future release of Mail Avenger will make \fB\s-1SPF\s0\fR
synonymous with \fB\s-1SPF1\s0\fR.
.IP "\fB\s-1SPF1\s0\fR" 4
.IX Item "SPF1"
Also the result of performing an \s-1SPF\s0 check on the message, but returns
different names for the results, to be compatible with newer revisions
of the \s-1SPF\s0 protocol specification.  The new names are \fBNone\fR,
\&\fBNeutral\fR, \fBPass\fR, \fBFail\fR, \fBSoftFail\fR, \fBTempError\fR, and
\&\fBPermError\fR.
.IP "\fB\s-1SPF_EXPL\s0\fR" 4
.IX Item "SPF_EXPL"
The explanation string that goes along with a bad \s-1SPF\s0 status.
.IP "\fB\s-1SSL_CIPHER\s0\fR" 4
.IX Item "SSL_CIPHER"
If the Mail Avenger has been compiled with support for the \s-1STARTTLS\s0
command (using the \fB\-\-enable\-ssl\fR option to \f(CW\*(C`configure\*(C'\fR), and the
client is communicating over \s-1SSL/TLS\s0, this variable will contain a
textual description of the algorithm.
.IP "\fB\s-1SSL_CIPHER_BITS\s0\fR" 4
.IX Item "SSL_CIPHER_BITS"
.PD 0
.IP "\fB\s-1SSL_ALG_BITS\s0\fR" 4
.IX Item "SSL_ALG_BITS"
.PD
\&\fB\s-1SSL_CIPHER_BITS\s0\fR contains the number of secret key bits used by the
\&\s-1SSL/TLS\s0 ciphers.  \fB\s-1SSL_ALG_BITS\s0\fR is the number of bits used by the
algorithm.  For example, if you are using 128\-bit \s-1RC4\s0 with 88 bits
sent in cleartext, \fB\s-1SSL_CIPHER_BITS\s0\fR will only be 40, since that is
the effective security, while \fB\s-1SSL_ALG_BITS\s0\fR will be 128.
.IP "\fB\s-1SSL_ISSUER\s0\fR" 4
.IX Item "SSL_ISSUER"
.PD 0
.IP "\fB\s-1SSL_ISSUER_DN\s0\fR" 4
.IX Item "SSL_ISSUER_DN"
.PD
If the client has successfully authenticated itself using an \s-1SSL\s0
certificate, \fB\s-1SSL_ISSUER\s0\fR will be set to the certificate signer's
common name, while \fB\s-1SSL_ISSUER_DN\s0\fR will be set to a compact
representation of the signer's full distinguished name.  The full
distinguished name is in the form output by the command:
.Sp
.Vb 1
\&        openssl x509 \-noout \-issuer \-in cert.pem
.Ve
.Sp
Note that this variable is mostly useful if the \fBSSLCAcert\fR file you
have given to Mail Avenger contains more than one certificate
authority, or signs other \s-1CA\s0 certificates.  Mail Avenger will not
accept client certificates if it does not recognize the signer of the
certificate.
.IP "\fB\s-1SSL_SUBJECT\s0\fR" 4
.IX Item "SSL_SUBJECT"
.PD 0
.IP "\fB\s-1SSL_SUBJECT_DN\s0\fR" 4
.IX Item "SSL_SUBJECT_DN"
.PD
If the client has successfully authenticated itself using an \s-1SSL\s0
certificate, \fB\s-1SSL_SUBJECT\s0\fR will be set to the client's common name in
the certificate, while \fB\s-1SSL_SUBJECT_DN\s0\fR will be set to a compact
representation of the client's full distinguished name.  The full
distinguished name is in the form output by the command:
.Sp
.Vb 1
\&        openssl x509 \-noout \-subject \-in cert.pem
.Ve
.IP "\fB\s-1SSL_VERSION\s0\fR" 4
.IX Item "SSL_VERSION"
The version of the \s-1SSL/TLS\s0 protocol in use.
.IP "\fB\s-1UFLINE\s0\fR" 4
.IX Item "UFLINE"
An mbox \f(CW\*(C`From \*(C'\fR line suitable for prepending to the message before
passing the message to a delivery program.  (This is mostly useful for
bodytest rules.)
.IP "\fB\s-1USER\s0\fR" 4
.IX Item "USER"
The name of the user under which avenger is running.
.SH "AVENGER/ASMTPD INTERFACE"
.IX Header "AVENGER/ASMTPD INTERFACE"
avenger is just a simple shell script.  You can inspect the file to
see what it is doing.  Most of the interesting operations happen in
either asmtpd, or in external programs spawned from avenger.  This
section documents the interface between asmtpd and avenger.
.PP
avenger inherits a unix-domain socket connected to asmtpd on its
standard input and output.  It sends commands to asmtpd over this
socket, and similarly reads replies from it.  In order to avoid mixing
messages to and from asmtpd with the output of other programs you run,
however, the avenger shell script reorganizes its file descriptors so
that all communication to and from asmtpd happens over file descriptor
number 3.
.PP
Each command consists of a single line, followed by a newline (except
the \fBreturn\fR command, which can optionally take multiple lines).
There may or may not be a reply, possibly depending on the outcome of
the command.  Most replies consist of zero or more lines of the form
.Sp
.RS 4
\&\fI\s-1VARIABLE\s0\fR\fB=\fR\fIvalue\fR
.RE
.PP
\&\fI\s-1VARIABLE\s0\fR is typically a variable name that was supplied as part of
the command.  The avenger shell script records results by setting the
environment variable \fI\s-1VARIABLE\s0\fR to \fIvalue\fR, so that it can be
accessed by subsequent lines of the script.
.PP
Replies are sent in the order in which the corresponding commands were
received.  However, asmtpd executes requests asynchronously.  Thus,
one can perform several concurrent operations (such as \s-1DNS\s0 requests or
\&\s-1SPF\s0 tests) by simply writing multiple commands to asmtpd before
receiving any of the responses.
.PP
The \f(CW\*(C`.\*(C'\fR command is a no-op, but asmtpd echoes the \f(CW\*(C`.\*(C'\fR back to
avenger as the reply.  This allows one to synchronize the avenger
process's state after issuing one or more commands.  For example, one
might issue several \s-1DNS\s0 lookups to check various RBLs (real-time
blackhole lists), then issue a \fI.\fR command, then wait for replies.
When the \fI.\fR comes back, all previous commands will also have
completed.  The avenger \fBsetvars\fR command simply sends a \f(CW\*(C`.\*(C'\fR, then
loops until it reads back the \f(CW\*(C`.\*(C'\fR, setting variables from any
previous commands whose replies it reads in the process.
.PP
The following commands are available:
.IP "\fB.\fR" 4
.IX Item "."
The \fB.\fR command is simply echoed back by asmtpd.
.IP "\fBbodytest\fR \fIcommand\fR" 4
.IX Item "bodytest command"
Ends the current avenger script.  Specifies that asmtpd should receive
the entire body of the message, then run \fIcommand\fR (under the same
user \s-1ID\s0 as the current avenger script) with the entire mail message as
its standard input.  asmtpd then replies to the \s-1SMTP\s0 \f(CW\*(C`DATA\*(C'\fR command
based on the exit status of \fIcommand\fR as follows:
.RS 4
.IP "0" 4
If \fIcommand\fR exits with status 0, asmtpd will reply to the \f(CW\*(C`DATA\*(C'\fR
command with success (\s-1SMTP\s0 code 250), and will pass the message to
sendmail (or whatever you have configured as \fBSendmail\fR in
\&\fIasmtpd.conf\fR) for delivery.
.IP "99" 4
.IX Item "99"
If \fIcommand\fR exits with status 99, asmtpd will still reply to the
\&\f(CW\*(C`DATA\*(C'\fR command with a successful 250 reply code, but will not spool
the data.  Either \fIcommand\fR must have done something with the data,
or the message will be lost.
.IP "100 (also 64, 65, 70, 76, 77, 78, 112)" 4
.IX Item "100 (also 64, 65, 70, 76, 77, 78, 112)"
If \fIcommand\fR exits with status 100 (or any of the above exit
statuses), avenger will reject the mail with a hard \s-1SMTP\s0 error (code
554).  If \fIcommand\fR wrote output to its standard output, this output
will be passed back to the mail client.  Otherwise, asmtpd will supply
the text \*(L"message contents rejected.\*(R"
.IP "111 (or any other exit status)" 4
.IX Item "111 (or any other exit status)"
If \fIcommand\fR exits with status 111, the result is the same as exit
status 100, except that asmtpd will use a temporary error code (451)
instead of 554.
.IP "signal" 4
.IX Item "signal"
If \fIcommand\fR exits abnormally because of a signal, asmtpd will also
use 451, but in this case will not pass the program's output back to
the client.  It will instead pass back a description of the problem.
.RE
.RS 4
.Sp
Note that asmtpd can only run one \fBbodytest\fR command per message.  If
there are multiple recipients of a message, all must run the same
\&\fBbodytest\fR under the same user \s-1ID\s0.  If two users wish to run
different \fBbodytest\fR commands, or even run the same command under
different user IDs, asmtpd will defer the second \s-1SMTP\s0 \f(CW\*(C`RCPT\*(C'\fR command
with the message:
.Sp
.RS 4
452 send a separate copy of the message to this user
.RE
.RE
.RS 4
.Sp
This will cause the mail client to re-send the message later to the
second user.  To avoid forcing clients to send multiple copies of
messages, you can place \fBbodytest\fR commands in system wide files
(such as the \fIdefault\fR rule file), or use a \fBredirect\fR command to
redirect to the \fBAvengerUser\fR, so that commands for multiple users
can be run under the \fBAvengerUser\fR user \s-1ID\s0.
.Sp
Note that file descriptor 0 inherited by \fIcommand\fR is opened for both
reading and writing.  Thus, it is possible to modify the message
before it is spooled by the local \s-1MTA\s0.  The command
\&\fIedinplace\fR\|(1) is useful for running messages through
spam filters that annotate messages before spooling them.
.RE
.IP "\fBdns-a\fR \fI\s-1VARIABLE\s0\fR \fIdomain-name\fR" 4
.IX Item "dns-a VARIABLE domain-name"
Requests that asmtpd perform a \s-1DNS\s0 lookup for A (IPv4 address) records
on \fIdomain-name\fR.  If such an A record exists, the reply is a list of
one or more \s-1IP\s0 addresses:
.RS 4
.Sp
.RS 4
\&\fI\s-1VARIABLE\s0\fR\fB=\fR\fIIP-address\fR ...
.RE
.RE
.RS 4
.Sp
If no such A record exists, the reply is simply:
.Sp
.RS 4
\&\fI\s-1VARIABLE\s0\fR\fB=\fR
.RE
.RE
.RS 4
.Sp
With the standard avenger script, this sets \fI\s-1VARIABLE\s0\fR to the empty
string.  If there is a temporary error in \s-1DNS\s0 name resolution, there
is no reply, and hence with the default avenger script \fI\s-1VARIABLE\s0\fR
will remain unset.
.Sp
When checking such things as RBLs, it is advisable not to reject mail
because of a temporary \s-1DNS\s0 error.  You can use the shell construct
${\fI\s-1VARIABLE\s0\fR\-\fIdefault\fR}$ to return $\fI\s-1VARIABLE\s0\fR when \fI\s-1VARIABLE\s0\fR is
set, and \fIdefault\fR when \fI\s-1VARIABLE\s0\fR is not set.  Similarly
${\fI\s-1VARIABLE\s0\fR+\fIset\fR} returns \fIset\fR if \fI\s-1VARIABLE\s0\fR is set, and the
empty string otherwise.
.Sp
For example, if bad\-senders.org contained an \s-1RBL\s0 of undesirable sender
hosts:
.Sp
.Vb 5
\&    echo dns\-a BADSENDER "$SENDER_HOST".bad\-senders.org >&3
\&    setvars
\&    test \-n "$BADSENDER" && reject "$SENDER_HOST is a bad sender"
\&    test \-z "${BADSENDER+set}" \e
\&        && defer "$SENDER_HOST.bad\-senders.org: DNS error"
.Ve
.Sp
Note that when using the avenger script, there is already a function
\&\fBrbl\fR to check RBLs.
.RE
.IP "\fBdns-mx\fR \fI\s-1VARIABLE\s0\fR \fIdomain-name\fR" 4
.IX Item "dns-mx VARIABLE domain-name"
Similar to \fBdns-a\fR, but looks up \s-1MX\s0 records.  A successful reply is
of the form:
.RS 4
.Sp
.RS 4
\&\fI\s-1VARIABLE\s0\fR\fB=\fR\fIpriority\-1\fR\fB:\fR\fIhost\-1\fR [\fIpriority\-2\fR\fB:\fR\fIhost\-2\fR ...]
.RE
.RE
.RS 4
.Sp
Where \fIpriority\-1\fR is the \s-1MX\s0 priority of \fIhost\-1\fR.  As before, an
empty string indicates no \s-1MX\s0 records exist, and no reply indicates an
error.
.RE
.IP "\fBdns-ptr\fR \fI\s-1VARIABLE\s0\fR \fIIP-address\fR" 4
.IX Item "dns-ptr VARIABLE IP-address"
Returns a list of verified \s-1DNS\s0 hostnames for \fIIP-address\fR.  As
before, an empty string for \fI\s-1VARIABLE\s0\fR indicates no \s-1PTR\s0 records
exist, and no reply indicates an error.
.IP "\fBdns-txt\fR \fI\s-1VARIABLE\s0\fR \fIdomain-name\fR" 4
.IX Item "dns-txt VARIABLE domain-name"
Similar to the other \fBdns\fR commands, but looks up a record of type
\&\s-1TXT\s0.  If multiple \s-1TXT\s0 records exist, returns only one.  Places some
restrictions on the \s-1TXT\s0 records, for example will not return one that
contains a newline character.
.IP "\fBnetpath\fR \fI\s-1VARIABLE\s0\fR \fIIP-address\fR" 4
.IX Item "netpath VARIABLE IP-address"
Maps out the network hops to \fIIP-address\fR (this is similar to the
traceroute system utility, but more efficient).  The reply is of the
form:
.RS 4
.Sp
.RS 4
\&\fI\s-1VARIABLE\s0\fR\fB=\fR\fI#hops\fR \fIhop1\fR \fIhop2\fR ...
.RE
.RE
.RS 4
.Sp
\&\fI#hops\fR is the total number of network hops to \fIIP-address\fR if
asmtpd can figure this out.  (It won't always be able to if
\&\fIIP-address\fR is behind a firewall.)  If asmtpd cannot figure this
out, the value is \-1.  \fIhop1\fR and the remaining arguments are the
addresses of routers along the way to \fIIP-address\fR.
.RE
.IP "\fBredirect\fR \fIlocal\fR" 4
.IX Item "redirect local"
Terminates the current avenger process, and instead processes the mail
as though it is being sent to \fIlocal\fR.  This command is only
available in \*(L"rcpt\*(R" mode, as opposed to \*(L"mail\*(R" mode (in which asmtpd
runs avenger to see if it should relay mail for a local user on a
non-local client machine).
.Sp
\&\fIlocal\fR can be a local user name, or a local user name followed by
the separator character and an extension.  The name is mapped using
the \fIaliases\fR (specified by \fBAliasFile\fR in \fIasmtpd.conf\fR).
.Sp
Note that while the \fBAvengerUser\fR user can redirect to other users,
ordinary users can only redirect to themselves or the \fBAvengerUser\fR.
.IP "\fBreturn\fR \fIcode\fR \fIexplanation\fR" 4
.IX Item "return code explanation"
.PD 0
.IP "            or" 4
.IX Item "            or"
.IP "\fBreturn\fR \fIcode\fR\fB\-\fR\fIexplanation\fR" 4
.IX Item "return code-explanation"
.IP "\fIcode\fR\fB\-\fR\fIexplanation\fR" 4
.IX Item "code-explanation"
.IP "\fIcode\fR\fB \fR\fIexplanation\fR" 4
.IX Item "code explanation"
.PD
Specifies the \s-1SMTP\s0 reponse desired.  Also avoids further processing of
the message with system-wide default rulesets (as typically happens
when avenger simply exits with status 0).  \fIcode\fR must be a three
digit number beginning 2, 4, or 5.  (usually 250 for success, 451 to
defer mail, and 554 to reject mail).
.Sp
The first form of this command (with a space between \fIcode\fR and
\&\fIexplanation\fR) gives a single line explanation along with the result
code.  In the second form, avenger specifies a multi-line response.
In this case all but the last line must contain a \fB\-\fR between the
\&\fIcode\fR and \fIexplanation\fR, while the last line must contain a space.
(Note that the \fBreturn\fR keyword only appears on the first line; after
starting to issue a \fBreturn\fR command, no further commands can be
issued.)
.IP "\fBspf\fR \fI\s-1VARIABLE\s0\fR \fISPF-mechanism\fR ..." 4
.IX Item "spf VARIABLE SPF-mechanism ..."
.PD 0
.IP "\fBspf0\fR \fI\s-1VARIABLE\s0\fR \fISPF-mechanism\fR ..." 4
.IX Item "spf0 VARIABLE SPF-mechanism ..."
.IP "\fBspf1\fR \fI\s-1VARIABLE\s0\fR \fISPF-mechanism\fR ..." 4
.IX Item "spf1 VARIABLE SPF-mechanism ..."
.PD
Evaluates the mail client based on \s-1SPF\s0 mechanisms.  It will return:
.RS 4
.Sp
.RS 4
\&\fI\s-1VARIABLE\s0\fR\fB=\fR\fIdisposition\fR
.RE
.RE
.RS 4
.Sp
where, for \fBspf0\fR, \fIdisposition\fR is one of:  \fBnone\fR, \fBneutral\fR,
\&\fBpass\fR, \fBfail\fR, \fBsoftfail\fR, \fBerror\fR, or \fBunknown\fR (though the
disposition \fBnone\fR is actually impossible).  For \fBspf1\fR, the
equivalent \fIdisposition\fR names are \fBNone\fR, \fBNeutral\fR, \fBPass\fR,
\&\fBFail\fR, \fBSoftFail\fR, \fBTempError\fR, \fBPermError\fR.  (Currently \fBspf\fR is
a synonym for \fBspf0\fR, but it is recommended that you avoid using
\&\fBspf\fR as in a future release it may become an alias for \fBspf1\fR.)
.Sp
As an example, suppose that your username is \f(CW\*(C`joe\*(C'\fR, \fBSeparator\fR is
\&\f(CW\*(C`+\*(C'\fR, and you have subscribed to a number of yahoo mailing lists using
email address \f(CW\*(C`joe+yahoo\*(C'\fR.  If spammers started sending mail to
\&\f(CW\*(C`joe+yahoo\*(C'\fR, you would want to reject all mail to that address except
that originating from yahoo's computers.  Yahoo's computers might
correspond to anything ending \f(CW\*(C`.yahoo.com\*(C'\fR or sharing a 24\-bit
IP-address prefix with any of yahoo.com's \s-1MX\s0 records.  This can be
accomplished with the following script in
\&\fI\f(CI$HOME\fI/.avenger/rcpt+yahoo\fR:
.Sp
.Vb 10
\&    echo spf YAHOO ptr:yahoo.com mx:yahoo.com/24 \-all >&3
\&    setvars
\&    case "$YAHOO" in
\&    fail)
\&        reject "Sorry, this private alias for Yahoo lists only"
\&        ;;
\&    error)
\&        defer "Sorry, temporary DNS error"
\&        ;;
\&    esac
.Ve
.RE
.SH "EXAMPLES"
.IX Header "EXAMPLES"
If you never use your email address as an envelope sender, you can
reject all bounces to that address with these commands in your \fIrcpt\fR
file:
.PP
.Vb 3
\&    test \-z "$SENDER" \e
\&        && reject "<$RECIPIENT> not a valid sender;" \e
\&        " should not receive bounces"
.Ve
.PP
The following script runs spamassassin (a popular spam filter,
available from <http://www.spamassassin.org/>) on the body of a
message, unless the sender of the message has an \s-1SPF\s0 disposition of
pass or is already going to be rejected by default.
.PP
.Vb 4
\&    # The next line immediately falls through to the default reject
\&    # disposition when mail has an SPF disposition of fail or the
\&    # sender does not accept bounce messages.
\&    errcheck
\&
\&    test "$SPF" = pass \e
\&        || bodytest edinplace \-x 111 spamassassin \-e 100
.Ve
.PP
The following script immediately accepts any mail from any machine at
\&\s-1MIT\s0 or \s-1NYU\s0 (provided \s-1MAIL_ERROR\s0 is not set), \*(L"greylists\*(R" machines not
in one of those domains, and if the greylist passes, falls through to
the the default, system-wide rules:
.PP
.Vb 1
\&    errcheck
\&
\&    spf TRUSTED ptr:nyu.edu ptr:mit.edu ?all
\&    setvars
\&    test pass = "$TRUSTED" && accept Trusted sender OK
\&
\&    greylist_delay=5m
\&    greylist
.Ve
.PP
The following script rejects mail from clients that have issued an
\&\s-1SMTP\s0 \*(L"\s-1POST\s0\*(R" command (which doesn't exist) or used aggressive,
premature pipelining of commands.  If the client put a space after the
colon in the \s-1MAIL\s0 \s-1FROM:\s0 or \s-1RCPT\s0 \s-1TO:\s0 \s-1SMTP\s0 commands, it greylists the
message using a key that includes the \s-1SYN\s0 fingerprint and first
24\-bits of the \s-1IP\s0 address.  If the \s-1SPF\s0 disposition of the message is
error, it defers the message.  If the \s-1SPF\s0 disposition of the message
is softfail or none, it runs the body of the message through
spamassassin.
.PP
.Vb 1
\&    errcheck
\&
\&    test \-n "$CLIENT_POST" \-o \-n "$CLIENT_PIPELINING" \e
\&        && reject "no spam please"
\&
\&    test \-n "$CLIENT_COLONSPACE" \e
\&        && greylist "${CLIENT_IP%.*} $CLIENT_SYNFP $SENDER"
\&
\&    case "$SPF" in
\&        error)
\&            defer "Temporary error in SPF record processing"
\&            ;;
\&        softfail|none)
\&            bodytest edinplace \-x 111 spamassassin \-e 100
\&            ;;
\&    esac
.Ve
.PP
If you set your \fB\s-1MACUTIL_SENDER\s0\fR environment variable to be
\&\f(CW\*(C`user+bounce+*@your.host.com\*(C'\fR and send mail with \fBmacutil
\&\-\-sendmail\fR, you can create the following \fIrcpt+bounce+default\fR to
accept mail only to valid bounce addresses.
.PP
.Vb 2
\&    macutil \-\-check "$SUFFIX" > /dev/null \e
\&        || reject "<$RECIPIENT>.. user unknown"
.Ve
.PP
In conjunction with this script, you may want to reject bounce
messages to your regular email addresss with your \fIrcpt\fR script, as
described in the first example.
.PP
This example is slightly more complicated, and shows how to use a
bodytest to reject mail based on message contents.  The goal of this
set-up is to check each message with the ClamAV anti-virus software
(from <http://www.clamav.net/>) and the spamassassin mail filter.  If
the message contains a virus or is flagged as spam, it should be
rejected with an explanation of the problem.  We construct a shell
script, \fI\f(CI$HOME\fI/.avenger/body\fR, to run these tests on message bodies.
The script can be invoked with the line
.Sp
.RS 4
\&\fBbodytest \f(CB$HOME\fB/.avenger/body\fR
.RE
.PP
in your \fI\f(CI$HOME\fI/.avenger/rcpt\fR file.  Or, alternatively the script
could be configured to run in the system-wide \fI/etc/avenger/default\fR file
(in which case you want to make sure that the \fBAvengerUser\fR can write
its own home directory, so as to store spamassassin files).  The
script is as follows:
.PP
.Vb 8
\&    #!/bin/sh
\&    out="\`clamscan \-i \-\-no\-summary \-\-mbox \-  2>&1\`"
\&    if test "$?" = 1; then
\&        echo This message appears to be infected with a virus
\&        printf "%s\en" "$out" \e
\&            | sed \-e \*(Aq/Warning:/d\*(Aq \-e \*(Aqs/^[^:]*: //\*(Aq | sort \-u
\&        exit 100
\&    fi
\&
\&    out="\`edinplace \-x 111 spamassassin \-e 100\`"
\&    case "$?" in
\&        0)
\&            exit 0
\&            ;;
\&        100)
\&            echo Sorry, spamassassin has flagged your message as spam
\&            while read a b c; do
\&                test "$a $b" = "Content analysis" && break
\&            done
\&            read a
\&            read a
\&            read a
\&            while read a b c; do
\&                case "$a" in
\&                "")
\&                    break
\&                    ;;
\&                \-*)
\&                    ;;
\&                [0\-9]*)
\&                    printf "  %s\en" "$c"
\&                    ;;
\&                *)
\&                    printf "    %s\en" "$a $b $c"
\&                    ;;
\&                esac
\&            done
\&            exit 100
\&            ;;
\&        *)
\&            if test \-n "$out"; then
\&                echo spamassassin failure:
\&                printf "%s\en" "$out"
\&            else
\&                echo system error in spamassassin
\&            fi
\&            exit 111
\&            ;;
\&    esac
.Ve
.PP
The first half of this script runs the clamscan virus checker, storing
the output in variable out.  clamscan exits with code 1 when a virus
is found, exits 0 on success, and uses other error codes to indicate
various system errors.  We only want to reject mail if clamscan exits
with code 1.  When this happens, we take the output of clamscan,
format it in a more pleasing way (stripping out warnings), and send it
to standard output.  An example of an \s-1SMTP\s0 transaction using this
bodytest and detecting a virus will look like this (tested with the
special \s-1EICAR\s0 test string that flags a positive with most virus
checkers):
.PP
.Vb 3
\&    DATA
\&    354 enter mail, end with "." on a line by itself
\&    Subject: eicar test
\&
\&    X5O!P%@AP[4\ePZX54(P^)7CC)7}$EICAR\-STANDARD\-ANTIVIRUS\-TEST\-FILE!$H+H*
\&    .
\&    554\-This message appears to be infected with a virus
\&    554 Eicar\-Test\-Signature FOUND
.Ve
.PP
If the virus check fails, the script runs the message through
spamassassin to check for spam.  Note that spamassassin modifies the
mail message, so that we must run it with edinplace.  Note also that
clamscan will read to the end of the input file, but this is okay
since edinplace rewinds its standard input.  We use the \fB\-e\fR flag to
tell spamassassin to exit 100 on spam.  Then, if spamassassin exits 0,
we accept the mail.  If it exits with anything but 100, something went
wrong and we temporarily defer the mail.  Note that it might also be
possible to accept the mail at this point, but since spamassassin
edits the file in place, the message may be truncated if spamassassin
exits unexpectedly.
.PP
If spamassassin exits 100, we reject the mail.  We also report on why
spamassassin has rejected the mail.  Here again we take advantage of
the fact that edinplace rewinds its standard input both before and
after processing a message.  Because the file descriptor has been
rewound, we can start processing the message one line at a time with
the shell script.  Spamassassin by default (if you have not configred
it with \f(CW\*(C`report_safe 0\*(C'\fR) contains a spam report like this:
.PP
.Vb 1
\& Content analysis details:   (11.7 points, 5.0 required)
\&
\&  pts rule name        description
\& \-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  1.0 RATWARE_RCVD_AT Bulk email fingerprint (Received @) found
\&  4.2 X_MESSAGE_INFO  Bulk email fingerprint (X\-Message\-Info) found
\&  0.0 MONEY_BACK      BODY: Money back guarantee
\&  0.5 BIZ_TLD         URI: Contains a URL in the BIZ top\-level domain
\&  0.6 URIBL_SBL       Contains a URL listed in the SBL blocklist
\&                      [URIs: crocpeptide.biz]
\&  0.5 URIBL_WS_SURBL  Contains a URL listed in the WS SURBL blocklist
\&                      [URIs: crocpeptide.biz]
\& ...
.Ve
.PP
We skip over the headers, and for each result, print it to the \s-1SMTP\s0
session.  Negative/whitelist results (those starting \-), we do not
report, and comment lines (not starting with a number) we print
indented.  A typical \s-1SMTP\s0 session looks like this (using the special
\&\s-1GTUBE\s0 test line that triggers spam filters):
.PP
.Vb 3
\&    DATA
\&    354 enter mail, end with "." on a line by itself
\&    Subject: gtube test
\&
\&    XJS*C4JDBQADN1.NSBN3*2IDNEN*GTUBE\-STANDARD\-ANTI\-UBE\-TEST\-EMAIL*C.34X
\&    .
\&    554\-Sorry, spamassassin has flagged your message as spam
\&    554\-  Missing Date: header
\&    554   BODY: Generic Test for Unsolicited Bulk Email
.Ve
.PP
Here's an example of how to use \s-1SSL\s0 client certificates for
authentication.  If you have a private \s-1CA\s0 with common name \*(L"My \s-1CA\s0\*(R"
that signs the certificates of all your authorized mail clients, you
can place the following in \fI/etc/avenger/relay\fR to permit those clients
to relay:
.PP
.Vb 3
\&    test "My CA" = "$SSL_ISSUER" \e
\&        && accept "Relaying permitted for client $SSL_SUBJECT"
\&    reject "relaying denied"
.Ve
.SH "FILES"
.IX Header "FILES"
\&\fI/usr/local/libexec/avenger\fR,
\&\fI/etc/avenger/default\fR,
\&\fI\f(CI$HOME\fI/.avenger/rcpt\fR,
\&\fI\f(CI$HOME\fI/.avenger/rcpt*\fR
\&\fI\f(CI$HOME\fI/.avenger/mail\fR,
\&\fI\f(CI$HOME\fI/.avenger/mail*\fR
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIdbutil\fR\|(1),
\&\fIdeliver\fR\|(1),
\&\fIedinplace\fR\|(1),
\&\fIescape\fR\|(1),
\&\fImacutil\fR\|(1),
\&\fImatch\fR\|(1),
\&\fIsynos\fR\|(1),
\&\fIasmtpd.conf\fR\|(5),
\&\fIasmtpd\fR\|(8),
\&\fIavenger.local\fR\|(8)
.PP
The Mail Avenger home page: <http://www.mailavenger.org/>.
.SH "BUGS"
.IX Header "BUGS"
avenger (and the configuration files it reads) are shell scripts.  In
a shell script, it is sometimes tempting to use \f(CW\*(C`echo ...\*(C'\fR where one
should instead use the command \f(CW\*(C`printf \*(Aq%s\en\*(Aq ...\*(C'\fR.  (The later just
prints its argument to standard output, while the former interprets
various \f(CW\*(C`\e\*(C'\fR escape codes.)
.PP
In shell scripts, one must be careful about variables containing shell
metacharacters.  For example, it is not safe to run something like:
.PP
.Vb 1
\&        bodytest "echo $VAR > $PWD/log"
.Ve
.PP
if variable \f(CW\*(C`VAR\*(C'\fR has untrusted contents that might contain
characters like \f(CW\*(C`>\*(C'\fR or \f(CW\*(C`;\*(C'\fR.  The reason is that \f(CW$VAR\fR will be
expanded and sent back to the \s-1SMTP\s0 server, which will then pass the
expansion to the shell to execute the bodytest.  (\f(CW$VAR\fR effectively
gets expanded twice.)  The escape utility can be used to avoid these
problems.  For example:
.PP
.Vb 1
\&        bodytest echo \`escape "$VAR"\` ">" $PWD/log
.Ve
.PP
It is easy to forget to call \fBsetvars\fR after a \fBdns\fR, \fBrbl\fR, or
\&\fBspf\fR command.
.SH "AUTHOR"
.IX Header "AUTHOR"
David Mazie\*`res