Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
avenger(1)		      Mail Avenger 0.8.5		    avenger(1)

NAME
       avenger - Mail Avenger

DESCRIPTION
       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.  avenger is the
       script run on behalf of each user to decide whether to accept incoming
       mail.

       When a client attempts to send mail to a	user on	the system, the
       avenger SMTP daemon, asmtpd, runs avenger to process the	file
       .avenger/rcpt in	the user's home	directory.  That file, a shell script
       with access to special functions, determines how	the SMTP server	should
       proceed.	 The possible outcomes are:

       o   Provisionally accept	the mail, falling back to system-default rules

       o   Accept the mail immediately with no further checks

       o   Reject the mail immediately

       o   Defer the mail, telling the client to re-send it later

       o   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 AvengerUser	user.  In the later
	   case, avenger will be re-run	with a different user ID, and hence
	   can,	for example, employ utilities that maintain state across
	   multiple users (assuming they all redirect processing the same
	   way).

       o   Run a "bodytest" rule.  With	this outcome, the the SMTP 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.

       Mail Avenger should typically be	configured to have a Separator
       character, allowing each	user to	maintain multiple email	addresses.
       With sendmail, Separator	is typically "+", with qmail it	is typically
       "-".  If	the separator is "+", then any email sent to
       user+ext@your-host will be processed by files in	user's .avenger
       directory.

       Avenger first checks for	a file named rcpt+ext in a user's .avenger
       directory, then for rcpt+default.  If ext itself	contains the separator
       character, for example user+ext1+ext2@your-host,	avenger	will check
       first for rcpt+ext1+ext2, then for rcpt+ext1+default, then for
       rcpt+default.  The same algorithm is extended for arbitrarily many
       separator characters.  (If separator is "-", simply replace "+" with
       "-" throughout the above	description, including in the names of files
       such as rcpt-default.)

       If mail is rejected by the recipient checks but the sender address of a
       message is local	and UserMail is	1 in asmtpd.conf (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 mail instead of
       rcpt.  This mechanism can be used by local users	who want to relay mail
       through the server from an untrusted IP address.

       Using the mail configuration files, each	user can, for instance,
       configure a mail+... file to accept mail	from an	IP 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 mail+... script.)

       Error output of an avenger script rcpt+ext or mail+ext is redirected to
       a file called log+ext in	the same directory, for	use in debugging.

AVENGER	SYNTAX
       Avenger configuration files are simply shell scripts, using the syntax
       described in sh(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.

       errcheck
	   Certain error conditions result in Mail Avenger rejecting mail by
	   default, unless the message is explicitly accepted through an
	   accept or successful	bodytest check.	 These conditions are
	   indicated by	the MAIL_ERROR 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.  errcheck exits immediately
	   with	the default error if the default would be to reject or defer
	   the mail.

       accept [message]
	   Immediately accepts the message (without falling back to any
	   default rules).  If message is supplied, it will be returned	to the
	   SMTP	client.	 The default message is	"ok".

       reject [message]
	   Reject the mail, with message.  (The	default	message	is "command
	   rejected for	policy reasons").

       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
	   message is "temporary error in processing".

       bodytest	command	[arg ...]
	   Accept the current SMTP "RCPT" command.  However, once the whole
	   mail	message	has been received with the SMTP	"DATA" command,	run
	   command with	the message as its standard input.  Depending on the
	   exit	status of command return to the	client's "DATA"	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	bodytest in
	   the asmtpd/avenger interface	description for	more information on
	   bodytest (since this	function directly invokes bodytest in asmtpd).

	   Error output	from command will be redirected	to the same log	file
	   as output from the rcpt+... avenger script invoking the bodytest
	   function.  Standard output of command will be included as a
	   diagnostic the bounce message if the	exit code defers or rejects
	   the mail.

	   Note	that command and the arguments passed to bodytest will be run
	   by the shell.  Thus,	it is important	not to pass any	arguments that
	   might contain shell metacharacters such as ">" and "$".

       redirect	local
	   Finish processing, and re-run avenger as if mail were being sent to
	   a different username	local (possibly	belonging to the special
	   AvengerUser user).  See the description of redirect in the
	   asmtpd/avenger interface description	for more information on
	   redirect (since this	function directly invokes redirect in asmtpd).

       greylist	[sender-key]
	   This	command	defers mail the	first time mail	is received from a
	   particular sender at	a particular IP	address.  However, after a
	   certain interval, greylist_delay, 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 IP	address,
	   unless the sender stops sending mail	for a period of	greylist_ttl2
	   or more.  If, however, after	sending	the initial, defered piece of
	   mail, the client does not try again within a	period of
	   greylist_ttl1, then any record of the client	will be	erased,	and
	   the next time it tries to send mail it will be defered again.

	   The parameters can be tuned by setting variables in the script.
	   The default values are:

	       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

	   m means minutes, h hours, and D days.  For a	complete list of
	   allowed suffixes, see the documentation for dbutil(1) (in
	   particular for the --expire option).

	   sender-key, if supplied, is used to identify	the sender.  The
	   default value is "$CLIENT_IP	$RECIPIENT $SENDER".  If, for example,
	   you wanted to record	only the first 24-bits of IP address and
	   didn't care about the recipient, you	could use the command:

	       greylist	"${CLIENT_IP%.*} $SENDER"

       setvars
	   All functions that set a variable by	means of an external query to
	   asmtpd are performed	asynchronously.	 setvars actually waits	for
	   results and sets the	values of those	variables.  In this way, a
	   number of potentially slow requests (such as	DNS lookups) can be
	   initiated concurrently, and their latencies overlapped.  However,
	   one must remember to	call setvars, or else variables	that should
	   contain the results of operations will remain unset.

       dns var type domain-name
	   Performs a DNS lookup of domain-name	for records of type type, and
	   assigns the result to variable var when you call setvars.  type
	   must	be one of a, mx, ptr, or txt (lower-case only).

       rbl [-ipf] var domain
	   Looks up the	current	mail sender in a real-time blackhole list
	   (RBL).  domain is the domain	name of	the RBL	(e.g.,
	   "bl.spamcop.net").  If the sender is	listed,	set var	to the result
	   of the DNS lookup when you next call	setvars.  -i looks up the
	   sender's IP address (the default if no options are specified).  -p
	   looks up the	sender's domain	name (verified DNS PTR record).	 -f
	   looks up the	envelope sender	domain name in the RBL.

       spf0 var	[spf-mechanism ...]
       spf var [spf-mechanism ...]
	   Tests the sender against an arbitrary query formulated in the SPF
	   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 "yahoo.com"	reject any
	   mail	from users in the spamcop RBL, and for other users fall	back
	   to the default system-wide rules.  You might	use the	following rcpt
	   file:

	       spf MYSPF +include:spf.trusted-forwarder.org \
		   +ptr:yahoo.com -exists:%{ir}.bl.spamcop.net ?all
	       setvars
	       case "$MYSPF" in
		   pass)
		       accept "I like you"
		       ;;
		   fail)
		       reject "I don't like you"
		       ;;
		   error)
		       # Note, could instead fall through to default here
		       defer "Temporary	DNS error"
		       ;;
	       esac

	   Note	that commands spf0 and spf are synonymous, but spf is
	   deprecated, because in a later release of Mail Avenger spf will
	   become synonymous with spf1.

       spf1 var	[spf-mechanism ...]
	   Performs the	same tests as the spf directive, but returns the
	   result strings None,	Neutral, Pass, Fail, SoftFail, TempError, and
	   PermError instead of	none, neutral, pass, fail, softfail, error,
	   and unknown.

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, ENVIRONMENT.

       FILEX
	   The extension on the	file currently being processed.	 For example,
	   if file rcpt+ext is being processed,	will be	set to "+ext".	Empty
	   when	processing just	rcpt (or mail).	 May also contain default when
	   a default rule file for some	suffix is being	run.

       PREFIX
       SUFFIX
	   Assuming the	separator is "+", when processing a file
	   rcpt+base+default or	mail+base+default, PREFIX is set to base,
	   while SUFFIX	is set to the portion of the name for which default
	   was substituted.  When the file does	not end	with default, SUFFIX
	   is empty.  When the file is just rcpt with no extension, both
	   PREFIX and SUFFIX are empty.	 When SUFFIX itself contains a "+"
	   character, SUFFIX1 contains to the part of SUFFIX after the first
	   "+" character, SUFFIX2 contains the part after the second "+", and
	   so on for each "+" character	in suffix.

ENVIRONMENT
       AUTH_USER
	   If Mail Avenger was compiled	with SASL support (which is not	the
	   default, unless you supplied	the --enable-sasl argument to
	   "configure"), and if	the client successfully	authenticates to the
	   server using	SASL, then AUTH_USER will be set to the	name of	the
	   authenticated user.

       AVENGER_MODE
	   Set to "rcpt" when testing whether a	recipient should receive mail.
	   Set to "mail" (possibly after an "rcpt" check fails)	when checking
	   whether to relay mail (possibly on behalf of	a local	user).

       AVUSER
	   The effective local username	for which avenger is being run.
	   Ordinarily, this will be the	same as:

	   $USER${PREFIX+$SEPARATOR}$PREFIX\
	   ${SUFFIX+$SEPARATOR}$SUFFIX

	   However, for	special	avenger	files like unknown and default,	it can
	   contain useful information, because unlike the RECIPIENT_LOCAL
	   environment variable, AVUSER	reflects substitutions from the	Mail
	   Avenger domains and aliases files.

       CLIENT
	   This	variable contains the name of the client machine, as typically
	   reported in "Received:" headers.  Its value has the form:

	       [user@]host

	   user	is the user name for the connection reported by	the client, if
	   the client supports the RFC 1413 identification protocol, otherwise
	   it is omitted.  host	is a verified DNS hostname for the IP, if
	   asmtpd could	find one.  Otherwise, it is simply the numeric IP
	   address.

       CLIENT_COLONSPACE
	   Set to 1 if the client included a space between the colon in	the
	   command "MAIL FROM:"	or "RCPT TO:" and the subsequent "<" that
	   begins an email address.

       CLIENT_DNSFAIL
	   If AllowDNSFail is set to 1 in the asmtpd.conf file and resolving
	   the client's	IP to a	hostname returns a temporary error, then this
	   variable will be set	to a description of the	error.

       CLIENT_HELO
	   Set to the argument the client supplied to the SMTP "HELO" or
	   "EHLO" command.

       CLIENT_IP
	   Set to the IP address of the	client.

       CLIENT_NAME
	   Set to the verified DNS name	of the client, if asmtpd can find one.

       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
	   ICMP	destination unreachable	(type 3	packet)	in response to a UDP
	   probe.  Whether or not this is set will depend on firewall
	   configurations.

       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.

       CLIENT_PIPELINING
	   Set to 1 if the client wrote	data after the SMTP HELO or EHLO
	   command, before receiving its response.  A correct SMTP client
	   should not "pipeline" commands until	after receiving	the result of
	   the HELO command and	verifying that the server accepts pipelined
	   commands.

       CLIENT_PORT
	   The TCP port	number of the client.

       CLIENT_POST
	   Set to 1 if the client sent a "POST"	command	at some	point during
	   the SMTP session.  "POST" is	not a valid SMTP command; it is	an
	   HTTP	command.  However, one technique for sending spam involves
	   exploiting an open web proxy	to "post" an SMTP session to a mail
	   server.  The	initial	HTTP headers (including	the HTTP post command)
	   simply cause	SMTP syntax errors, while the body of the POST command
	   contains SMTP commands.  By checking	the CLIENT_POST	environment
	   variable, you to reject mail	sent in	this way.

       CLIENT_REVIP
	   The value of	CLIENT_IP with the order of the	bytes reversed.
	   Suitable for	prepending to ".in-addr.arpa" or an RBL	domain to
	   perform a DNS lookup	based on IP address.

       CLIENT_SYNFP
	   Contains a fingerprint, abstracting the contents of the initial TCP
	   SYN packet the client sent to establish the TCP connection.	The
	   exact contents of SYN 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:

	       wwww:ttt:D:ss:OOO

	   Where the fields are	as follows:

	   wwww
	       the initial TCP window size

	   ttt the IP ttl of the received packet

	   D   the IP "don't fragment" bit

	   ss  total size of the SYN packet (including IP header)

	   OOO a comma-separated list of TCP options, as follows:

	       N   NOP option

	       Wnnn
		   window scaling option with value nnn

	       Mnnn
		   maximum segment size	value nnn

	       S   Selective ACK OK

	       T   timestamp option

	       T0  timestamp option with value zero

       CLIENT_SYNOS
	   If asmtpd can guess the client's operating system based on
	   CLIENT_SYNFP, it will set CLIENT_SYNOS to the value of that guess.
	   For example,	to greylist mail from Windows machines,	you can	run:

	      match -q "*Windows*" "$CLIENT_SYNOS" && greylist

       DATA_BYTES
	   This	variable is not	really an avenger variable, as it is only
	   available in	bodytest commands.  It specifies the number of bytes
	   of message transfered in the	SMTP DATA command, but after
	   converting CR NL sequences to NL.  Roughly speaking this is how
	   many	bytes are in the message including all headers after the
	   X-Avenger:, SPF-Received, or	Received: header.

       ETCDIR
	   The value of	EtcDir from the	asmtpd configuration file (or
	   /etc/avenger	by default).

       EXT When	avenger	runs on	behalf of a user EXT is	set to the part	of the
	   address that	determines the suffix of the rcpt or mail file.	 For
	   example, suppose Separator is "-" and the recipient is
	   list-subscribe@host,	where host is not a virtual domain.  If	the
	   AliasFile contains:

	       list: user-mylist

	   Then	avenger	will be	run on behalf of "user"	(because alias
	   expansion yields user-mylist-subscribe).  EXT will be set to
	   mylist-subscribe.

	   Note	that EXT 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 RECIPIENT, this variable is not set
	   for bodytest	commands.

       HOST
	   Set to the name of the local	host, as specified by the HostName
	   directive in	avenger.conf.

       MAIL_ERROR
	   This	variable is set	when the SPF disposition of the	sender is
	   fail, 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.

       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.

       MYIP
	   IP address of local end of SMTP TCP connection.

       MYPORT
	   TCP port number of local end	of SMTP	TCP connection.	 Ordinarily
	   this	will be	25.

       RECIPIENT
	   The envelope	recipient of the message.  Note	that this environment
	   variable is not present for bodytest	programs, since	such programs
	   may be run on behalf	of multiple users.

       RECIPIENT_HOST
	   The domain part of RECIPIENT, folded	to lower-case--i.e., host when
	   RECIPIENT is	local@host.  Not present for bodytest programs,	as
	   noted in the	description of RECIPIENT.

       RECIPIENT_LOCAL
	   The local part of RECIPIENT,	folded to lower-case--i.e., local when
	   RECIPIENT is	local@host.  Not present for bodytest programs,	as
	   noted in the	description of RECIPIENT.

       SENDER
	   The envolope	sender of this mail message (i.e., the argument
	   supplied by the client to the "MAIL FROM:" SMTP command.)

       SENDER_HOST
	   The hostname	part of	SENDER,	converted to lower-case	(i.e., host in
	   user@host).

       SENDER_LOCAL
	   The local part of SENDER, converted to lower-case (i.e., user in
	   user@host).

       SENDER_MXES
	   A list of DNS MX records for	SENDER_HOST, if	that hostname has any
	   MX records.

       SENDER_BOUNCERES
	   For non-empty envelope senders, asmtpd attempts to see if it	is
	   possible to deliver bounce messages for the sender.	If not,
	   SENDER_BOUNCERES is set to a	three-digit SMTP 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 MAIL_ERROR as described above, and will
	   cause mail to be rejected by	default.

       SEPARATOR
	   The value of	Separator from the asmtpd configuration	file.  There
	   is no default (SEPARATOR will not be	set if no Separator is
	   specified in	the configuration file).  However, it should be
	   configured for "+" with sendmail and	"-" with qmail.

       SPF0
       SPF The result of performing an SPF check on the	message.  Will be one
	   of: none, neutral, pass, fail, softfail, error, or unknown.	Note
	   that	SPF0 and SPF are synonymous, but SPF is	deprecated as a	future
	   release of Mail Avenger will	make SPF synonymous with SPF1.

       SPF1
	   Also	the result of performing an SPF	check on the message, but
	   returns different names for the results, to be compatible with
	   newer revisions of the SPF protocol specification.  The new names
	   are None, Neutral, Pass, Fail, SoftFail, TempError, and PermError.

       SPF_EXPL
	   The explanation string that goes along with a bad SPF status.

       SSL_CIPHER
	   If the Mail Avenger has been	compiled with support for the STARTTLS
	   command (using the --enable-ssl option to "configure"), and the
	   client is communicating over	SSL/TLS, this variable will contain a
	   textual description of the algorithm.

       SSL_CIPHER_BITS
       SSL_ALG_BITS
	   SSL_CIPHER_BITS contains the	number of secret key bits used by the
	   SSL/TLS ciphers.  SSL_ALG_BITS is the number	of bits	used by	the
	   algorithm.  For example, if you are using 128-bit RC4 with 88 bits
	   sent	in cleartext, SSL_CIPHER_BITS will only	be 40, since that is
	   the effective security, while SSL_ALG_BITS will be 128.

       SSL_ISSUER
       SSL_ISSUER_DN
	   If the client has successfully authenticated	itself using an	SSL
	   certificate,	SSL_ISSUER will	be set to the certificate signer's
	   common name,	while SSL_ISSUER_DN 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:

		   openssl x509	-noout -issuer -in cert.pem

	   Note	that this variable is mostly useful if the SSLCAcert file you
	   have	given to Mail Avenger contains more than one certificate
	   authority, or signs other CA	certificates.  Mail Avenger will not
	   accept client certificates if it does not recognize the signer of
	   the certificate.

       SSL_SUBJECT
       SSL_SUBJECT_DN
	   If the client has successfully authenticated	itself using an	SSL
	   certificate,	SSL_SUBJECT will be set	to the client's	common name in
	   the certificate, while SSL_SUBJECT_DN 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:

		   openssl x509	-noout -subject	-in cert.pem

       SSL_VERSION
	   The version of the SSL/TLS protocol in use.

       UFLINE
	   An mbox "From " line	suitable for prepending	to the message before
	   passing the message to a delivery program.  (This is	mostly useful
	   for bodytest	rules.)

       USER
	   The name of the user	under which avenger is running.

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.

       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.

       Each command consists of	a single line, followed	by a newline (except
       the return 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

	   VARIABLE=value

       VARIABLE	is typically a variable	name that was supplied as part of the
       command.	 The avenger shell script records results by setting the
       environment variable VARIABLE to	value, so that it can be accessed by
       subsequent lines	of the script.

       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 DNS requests or SPF
       tests) by simply	writing	multiple commands to asmtpd before receiving
       any of the responses.

       The "." command is a no-op, but asmtpd echoes the "." 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 DNS lookups to check various RBLs (real-time blackhole lists),
       then issue a . command, then wait for replies.  When the	. comes	back,
       all previous commands will also have completed.	The avenger setvars
       command simply sends a ".", then	loops until it reads back the ".",
       setting variables from any previous commands whose replies it reads in
       the process.

       The following commands are available:

       .   The . command is simply echoed back by asmtpd.

       bodytest	command
	   Ends	the current avenger script.  Specifies that asmtpd should
	   receive the entire body of the message, then	run command (under the
	   same	user ID	as the current avenger script) with the	entire mail
	   message as its standard input.  asmtpd then replies to the SMTP
	   "DATA" command based	on the exit status of command as follows:

	   0   If command exits	with status 0, asmtpd will reply to the	"DATA"
	       command with success (SMTP code 250), and will pass the message
	       to sendmail (or whatever	you have configured as Sendmail	in
	       asmtpd.conf) for	delivery.

	   99  If command exits	with status 99,	asmtpd will still reply	to the
	       "DATA" command with a successful	250 reply code,	but will not
	       spool the data.	Either command must have done something	with
	       the data, or the	message	will be	lost.

	   100 (also 64, 65, 70, 76, 77, 78, 112)
	       If command exits	with status 100	(or any	of the above exit
	       statuses), avenger will reject the mail with a hard SMTP	error
	       (code 554).  If command wrote output to its standard output,
	       this output will	be passed back to the mail client.  Otherwise,
	       asmtpd will supply the text "message contents rejected."

	   111 (or any other exit status)
	       If command 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.

	   signal
	       If command 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.

	   Note	that asmtpd can	only run one bodytest command per message.  If
	   there are multiple recipients of a message, all must	run the	same
	   bodytest under the same user	ID.  If	two users wish to run
	   different bodytest commands,	or even	run the	same command under
	   different user IDs, asmtpd will defer the second SMTP "RCPT"
	   command with	the message:

	       452 send	a separate copy	of the message to this user

	   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 bodytest commands in	system wide files
	   (such as the	default	rule file), or use a redirect command to
	   redirect to the AvengerUser,	so that	commands for multiple users
	   can be run under the	AvengerUser user ID.

	   Note	that file descriptor 0 inherited by command is opened for both
	   reading and writing.	 Thus, it is possible to modify	the message
	   before it is	spooled	by the local MTA.  The command edinplace(1) is
	   useful for running messages through spam filters that annotate
	   messages before spooling them.

       dns-a VARIABLE domain-name
	   Requests that asmtpd	perform	a DNS lookup for A (IPv4 address)
	   records on domain-name.  If such an A record	exists,	the reply is a
	   list	of one or more IP addresses:

	       VARIABLE=IP-address ...

	   If no such A	record exists, the reply is simply:

	       VARIABLE=

	   With	the standard avenger script, this sets VARIABLE	to the empty
	   string.  If there is	a temporary error in DNS name resolution,
	   there is no reply, and hence	with the default avenger script
	   VARIABLE will remain	unset.

	   When	checking such things as	RBLs, it is advisable not to reject
	   mail	because	of a temporary DNS error.  You can use the shell
	   construct ${VARIABLE-default}$ to return $VARIABLE when VARIABLE is
	   set,	and default when VARIABLE is not set.  Similarly
	   ${VARIABLE+set} returns set if VARIABLE is set, and the empty
	   string otherwise.

	   For example,	if bad-senders.org contained an	RBL of undesirable
	   sender hosts:

	       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}" \
		   && defer "$SENDER_HOST.bad-senders.org: DNS error"

	   Note	that when using	the avenger script, there is already a
	   function rbl	to check RBLs.

       dns-mx VARIABLE domain-name
	   Similar to dns-a, but looks up MX records.  A successful reply is
	   of the form:

	       VARIABLE=priority-1:host-1 [priority-2:host-2 ...]

	   Where priority-1 is the MX priority of host-1.  As before, an empty
	   string indicates no MX records exist, and no	reply indicates	an
	   error.

       dns-ptr VARIABLE	IP-address
	   Returns a list of verified DNS hostnames for	IP-address.  As
	   before, an empty string for VARIABLE	indicates no PTR records
	   exist, and no reply indicates an error.

       dns-txt VARIABLE	domain-name
	   Similar to the other	dns commands, but looks	up a record of type
	   TXT.	 If multiple TXT records exist,	returns	only one.  Places some
	   restrictions	on the TXT records, for	example	will not return	one
	   that	contains a newline character.

       netpath VARIABLE	IP-address
	   Maps	out the	network	hops to	IP-address (this is similar to the
	   traceroute system utility, but more efficient).  The	reply is of
	   the form:

	       VARIABLE=#hops hop1 hop2	...

	   #hops is the	total number of	network	hops to	IP-address if asmtpd
	   can figure this out.	 (It won't always be able to if	IP-address is
	   behind a firewall.)	If asmtpd cannot figure	this out, the value is
	   -1.	hop1 and the remaining arguments are the addresses of routers
	   along the way to IP-address.

       redirect	local
	   Terminates the current avenger process, and instead processes the
	   mail	as though it is	being sent to local.  This command is only
	   available in	"rcpt" mode, as	opposed	to "mail" mode (in which
	   asmtpd runs avenger to see if it should relay mail for a local user
	   on a	non-local client machine).

	   local 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 aliases (specified by AliasFile in asmtpd.conf).

	   Note	that while the AvengerUser user	can redirect to	other users,
	   ordinary users can only redirect to themselves or the AvengerUser.

       return code explanation
		   or
       return code-explanation
       code-explanation
       code explanation
	   Specifies the SMTP reponse desired.	Also avoids further processing
	   of the message with system-wide default rulesets (as	typically
	   happens when	avenger	simply exits with status 0).  code must	be a
	   three digit number beginning	2, 4, or 5.  (usually 250 for success,
	   451 to defer	mail, and 554 to reject	mail).

	   The first form of this command (with	a space	between	code and
	   explanation)	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 - between the
	   code	and explanation, while the last	line must contain a space.
	   (Note that the return keyword only appears on the first line; after
	   starting to issue a return command, no further commands can be
	   issued.)

       spf VARIABLE SPF-mechanism ...
       spf0 VARIABLE SPF-mechanism ...
       spf1 VARIABLE SPF-mechanism ...
	   Evaluates the mail client based on SPF mechanisms.  It will return:

	       VARIABLE=disposition

	   where, for spf0, disposition	is one of:  none, neutral, pass, fail,
	   softfail, error, or unknown (though the disposition none is
	   actually impossible).  For spf1, the	equivalent disposition names
	   are None, Neutral, Pass, Fail, SoftFail, TempError, PermError.
	   (Currently spf is a synonym for spf0, but it	is recommended that
	   you avoid using spf as in a future release it may become an alias
	   for spf1.)

	   As an example, suppose that your username is	"joe", Separator is
	   "+",	and you	have subscribed	to a number of yahoo mailing lists
	   using email address "joe+yahoo".  If	spammers started sending mail
	   to "joe+yahoo", 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 ".yahoo.com" or sharing a
	   24-bit IP-address prefix with any of	yahoo.com's MX records.	 This
	   can be accomplished with the	following script in
	   $HOME/.avenger/rcpt+yahoo:

	       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

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 rcpt
       file:

	   test	-z "$SENDER" \
	       && reject "<$RECIPIENT> not a valid sender;" \
	       " should	not receive bounces"

       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	SPF disposition	of
       pass or is already going	to be rejected by default.

	   # 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 \
	       || bodytest edinplace -x	111 spamassassin -e 100

       The following script immediately	accepts	any mail from any machine at
       MIT or NYU (provided MAIL_ERROR is not set), "greylists"	machines not
       in one of those domains,	and if the greylist passes, falls through to
       the the default,	system-wide rules:

	   errcheck

	   spf TRUSTED ptr:nyu.edu ptr:mit.edu ?all
	   setvars
	   test	pass = "$TRUSTED" && accept Trusted sender OK

	   greylist_delay=5m
	   greylist

       The following script rejects mail from clients that have	issued an SMTP
       "POST" command (which doesn't exist) or used aggressive,	premature
       pipelining of commands.	If the client put a space after	the colon in
       the MAIL	FROM: or RCPT TO: SMTP commands, it greylists the message
       using a key that	includes the SYN fingerprint and first 24-bits of the
       IP address.  If the SPF disposition of the message is error, it defers
       the message.  If	the SPF	disposition of the message is softfail or
       none, it	runs the body of the message through spamassassin.

	   errcheck

	   test	-n "$CLIENT_POST" -o -n	"$CLIENT_PIPELINING" \
	       && reject "no spam please"

	   test	-n "$CLIENT_COLONSPACE"	\
	       && 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

       If you set your MACUTIL_SENDER environment variable to be
       "user+bounce+*@your.host.com" and send mail with	macutil	--sendmail,
       you can create the following rcpt+bounce+default	to accept mail only to
       valid bounce addresses.

	   macutil --check "$SUFFIX" > /dev/null \
	       || reject "<$RECIPIENT>.. user unknown"

       In conjunction with this	script,	you may	want to	reject bounce messages
       to your regular email addresss with your	rcpt script, as	described in
       the first example.

       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, $HOME/.avenger/body, to run these tests on message bodies.  The
       script can be invoked with the line

	   bodytest $HOME/.avenger/body

       in your $HOME/.avenger/rcpt file.  Or, alternatively the	script could
       be configured to	run in the system-wide /etc/avenger/default file (in
       which case you want to make sure	that the AvengerUser can write its own
       home directory, so as to	store spamassassin files).  The	script is as
       follows:

	   #!/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\n" "$out" \
		   | sed -e '/Warning:/d' -e 's/^[^:]*:	//' | 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\n" "$c"
			   ;;
		       *)
			   printf "    %s\n" "$a $b $c"
			   ;;
		       esac
		   done
		   exit	100
		   ;;
	       *)
		   if test -n "$out"; then
		       echo spamassassin failure:
		       printf "%s\n" "$out"
		   else
		       echo system error in spamassassin
		   fi
		   exit	111
		   ;;
	   esac

       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 SMTP transaction using this bodytest
       and detecting a virus will look like this (tested with the special
       EICAR test string that flags a positive with most virus checkers):

	   DATA
	   354 enter mail, end with "."	on a line by itself
	   Subject: eicar test

	   X5O!P%@AP[4\PZX54(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

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

       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 "report_safe 0")	contains a spam	report like this:

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

       We skip over the	headers, and for each result, print it to the SMTP
       session.	 Negative/whitelist results (those starting -),	we do not
       report, and comment lines (not starting with a number) we print
       indented.  A typical SMTP session looks like this (using	the special
       GTUBE test line that triggers spam filters):

	   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

       Here's an example of how	to use SSL client certificates for
       authentication.	If you have a private CA with common name "My CA" that
       signs the certificates of all your authorized mail clients, you can
       place the following in /etc/avenger/relay to permit those clients to
       relay:

	   test	"My CA"	= "$SSL_ISSUER"	\
	       && accept "Relaying permitted for client	$SSL_SUBJECT"
	   reject "relaying denied"

FILES
       /usr/local/libexec/avenger, /etc/avenger/default, $HOME/.avenger/rcpt,
       $HOME/.avenger/rcpt* $HOME/.avenger/mail, $HOME/.avenger/mail*

SEE ALSO
       dbutil(1), deliver(1), edinplace(1), escape(1), macutil(1), match(1),
       synos(1), asmtpd.conf(5), asmtpd(8), avenger.local(8)

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

BUGS
       avenger (and the	configuration files it reads) are shell	scripts.  In a
       shell script, it	is sometimes tempting to use "echo ..."	where one
       should instead use the command "printf '%s\n' ...".  (The later just
       prints its argument to standard output, while the former	interprets
       various "\" escape codes.)

       In shell	scripts, one must be careful about variables containing	shell
       metacharacters.	For example, it	is not safe to run something like:

	       bodytest	"echo $VAR > $PWD/log"

       if variable "VAR" has untrusted contents	that might contain characters
       like ">"	or ";".	 The reason is that $VAR will be expanded and sent
       back to the SMTP	server,	which will then	pass the expansion to the
       shell to	execute	the bodytest.  ($VAR effectively gets expanded twice.)
       The escape utility can be used to avoid these problems.	For example:

	       bodytest	echo `escape "$VAR"` ">" $PWD/log

       It is easy to forget to call setvars after a dns, rbl, or spf command.

AUTHOR
       David Mazieres

Mail Avenger 0.8.5		  2018-10-09			    avenger(1)

NAME | DESCRIPTION | AVENGER SYNTAX | AVENGER VARIABLES | ENVIRONMENT | AVENGER/ASMTPD INTERFACE | EXAMPLES | FILES | SEE ALSO | BUGS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=avenger&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help