NAME¶
avenger.local - deliver mail for a local user
SYNOPSIS¶
avenger.local [-f
sender] [-D
recip] [-a
extra] [-d]
user
DESCRIPTION¶
avenger.local is a local mail delivery agent that enables users to set up
multiple "extension" email addresses and process mail differently
for each addresses. The popular qmail MTA (<
http://www.qmail.org/>) has
a mechanism for processing such extension addresses. avenger.local provides a
similar facility for users of other MTAs, such as sendmail.
To use avenger.local, you should configure your MTA so that it delivers mail to
user+extra@host by executing
avenger.local -D
user+extra@host -d
user+ extra. Alternatively, you can execute
avenger.local -a extra -d user, but then
you lose information about the host. However, the latter syntax has the
advantage of being command-line compatible with procmail; thus, if your MTA
has support for procmail as a local delivery agent, you should be able to use
that by simply substituting avenger.local's path for procmail's.
Note that either way you invoke it, avenger.local rejects recipients containing
the string ".." in the local part. Such mailbox names are not
allowed by RFC822, and could potentially lead to security problems if parts of
mailbox names are used as file names. Out of paranoia, avenger.local
additionally rejects mailbox names containing the "/" character in
the extra portion after the local username.
avenger.local is designed to be unobtrusive for users who do not want to take
advantage of its functionality. When delivering mail for
user, if
user's home directory does not contain a subdirectory
.avenger,
avenger.local simply executes the default mail delivery agent (usually called
mail.local).
For users who do have
.avenger directories, mail is delivered according
to rule files called
.avenger/local*. Mail to
user@host is delivered according to rules in
.avenger/local. Mail to
user+ext1@host is delivered according to
rules in
.avenger/local+ext1 if such a file exists, or else
.avenger/local+default if such a file exists; if neither file exists,
the mail is bounced. Addresses containing multiple "+" characters
are handled as expected. Mail to
user+ext1+ext2 @host is
governed by, in order of decreasing precedence,
.avenger/local+ext1+ext2,
.avenger/local+ext1+default, or
.avenger/local+default; it is bounced if none of those files exist.
Local rule files can be in one of two formats. If the first two characters of
the file are "#!", then the file is simply executed as a script,
with the message on standard input. The script's standard input will be
read-only, but seekable, so, for example, the message can be delivered to
multiple mailboxes using the deliver utility.
Otherwise, if the first two characters of a file are not "#!",
avenger.local uses a syntax similar to (but not identical to) qmail's, where
each line is one of the following types, depending on the first character:
- # comment
- Lines starting with "#" are treated as comments and ignored. The
exception is that if the first line begins "#!", the file is
executed as a script. Note that if the first two characters of a file are
"#!" but the file's execute permission bits are not set, then
mail sent to that address will be deferred. (This mechanism can be used
for intentionally deferring mail while performing maintenance.)
- ./maildir/
- /path/to/maildir/
- A line starting "." or "/" and ending with a
"/" character is treated as a mail directory. Mail is delivered
there using the qmail maildir format.
- ./file
- /path/to/file
- A line starting "." or "/" and NOT ending with a
"/" character specifies an ordinary Unix mbox file into which
the message should be delivered.
- &address
- "&" indicates that a copy of the message should be forwarded
to address. You may not place a space between & and
address, nor can address contain angle brackets, comments, or
anything other than an email address with a fully-qualified domain name.
(Note that in qmail, the & character is optional for certain
email addresses, while avenger.local always requires the &
character.)
Forwarding happens after all other lines in the file are processed. If any
other configuration line fails, for instance because a command executed on
behalf of a | line exits non-zero, the mail is not forwarded to any
of the addresses. (The exception is if a command exits with status 99, in
which case mail is forwarded to addresses in all preceding &
lines, but subsequent lines are ignored.)
- | command
- Specifies that command should be run as a shell command, with the
mail message as its standard input. If command exits with a status
other than 0, processing of the local rule file terminates immediately,
with avenger.local's exit status determined by command's.
If command's status is 99, avenger.local exits with status 0,
effectively pretending the command just executed was the last line in the
.avenger/local* file. If command's exit status is between 64
and 78, inclusive, avenger.local exits with the same status as
command. If command exits with status 100 or 112,
avenger.local exits with status 70. For all other exit values, or if
command terminates because of a signal, avenger.local exits with
status 75. Note that the --qmailexit flag changes this behavior, as
described below.
See the file /usr/include/sysexits.h for more information on the
meaning of various exit statuses to sendmail.
- <address
- <!command
- This sets the envelope sender (i.e., bounce address) for copies of the
message forwarded to users with & lines. Note that one sender
address applies to all recipients, regardless of where in the
.avenger/local* file the bounce address is set. It is not possible
to forward from different bounce addresses for different recipients.
The first form of this line simply sets the envelope sender to
address. No spaces are allowed between < and the address.
No angle brackets or comments are allowed either.
The second form of this line executes command with the shell, giving
it the message body as standard input. If command exits with status
0 and outputs exactly one line of text, this line will be interpreted as
the new envelope sender for forwarded copies the message. If
command exits with any of statuses 64-78, 99-100, or 111-112,
processing of the avenger/.local* halts exactly as for the |
command. For other exit statuses, or if command outputs no lines or
more than one line, the command's result is ignored and processing
continues with the envelope sender unchanged.
- ! command
- Runs command with the shell, giving it the mail message on standard
input. If the command exits 0 and outputs exactly one line of text
beginning "." or "/", the output is interpreted as
either a maildir (if the line ends "/") or a mailbox (if it
doesn't) to which the message should be delivered. In other cases, either
the ! line is ignored, or processing halts, as described for the
<! command.
A completely empty file (not even containing a comment or blank line), or a
missing
.avenger/local (with no extension file), is treated as
equivalent to a file with the line "./Mailbox".
OPTIONS¶
- -a extra
- Specifies the extra portion of the local part of the email address after
the user name. In other words, if avenger.local is invoked with arguments
-a extra -d user, it is equivalent to invoking
it with the arguments -d user+extra. The
-a option allows command-line compatibility with sendmail's
procmail interface, which separates out the user name from the extension
portion of the address.
- -d user
- Specifies the local user to deliver mail to. Note that for compatibility
with other local mailers, the -d is optional, you can simply
specify user as the final command-line argument.
- -f sender
- -r sender
- The -f option specifies the envelope sender of the message. For
historical reasons, -r is synonymous with -f.
- -t
- This option is silently ignored, for command-line compatibility with
procmail.
- -B
- Ordinarily, when forwarding a bounce message, avenger.local will invoke
sendmail with the argument -f followed by an empty string argument
(i.e., specifying an empty from address). This does not work with some
older versions of sendmail. The -B option says that bounce messages
should be forwarded with arguments -f @ instead, which appears to
produce the desired (MAILER-DAEMON) result with older versions of
sendmail.
- -Y
- This option is silently ignored, for command-line compatibility with
procmail.
- --fallback program
- If the user specified on the command line does not exist or have a
$HOME/.avenger/ directory, or else has UID 0 (root),
or has an invalid shell or an expired account, then avenger.local will not
attempt to deliver mail to the user. Instead, it will attempt to run the
system's normal mail delivery agent as a fallback. This program is usually
called mail.local, but you can specify an alternative with the
--falback option. Note that this should be the full path of the
program, and should not contain any arguments. avenger.local will supply
the arguments -f from -d user.
- --fcntl
- This option enables fcntl (a.k.a. POSIX) file locking of mail spools, in
addition to flock and dotfile locking. The advantage of fcntl locking is
that it may do the right thing over NFS. However, if either the NFS client
or server does not properly support fcntl locking, or the file system is
not mounted with the appropriate options, fcntl locking can fail in one of
several ways. It can allow different processes to lock the same file
concurrently--even on the same machine. It can simply hang when trying to
acquire a lock, even if no other process holds a lock on the file. Also,
on some OSes it can interact badly with flock locking, because those OSes
actually implement flock in terms of fcntl. For these reasons,
avenger.local performs dotfile and flock locking by default, but not fcntl
locking.
- --qmailexit
- When programs from |, !, and <! exit with non-zero
exit status, the --qmailexit flag causes avenger.local to translate
the exit codes to ones more suitable for qmail. Any code that would cause
a hard error in sendmail causes avenger.local to exit with 100, any soft
error causes exit code 111, and exit code 99 is passed through.
- --sendmail program
- Specifies the program to run to send mail, when users have lines beginning
"&" in their .avenger/local* files. If program
contains spaces, it is broken into multiple arguments. The default value
for program is "sendmail -oi -os -oee".
- --separator char
- Specifies a separator character to place between portions of the address
extension. The default value is "+". Thus, the argument -a
a+b would cause avenger.local to search for files
$HOME/.avenger/local+a+b,
$HOME/.avenger/local+a+default, and
$HOME /.avenger/local+default. Specifying a different
char, say "-", would change the "+" to
"-" in both the email address and file names.
- --smuser user
- By default, sendmail is run as the user under which avenger.local is
invoked, which will ordinarily be root. To drop privileges before running
sendmail, you can specify this argument and avenger.local will run
sendmail as user. Note that avenger doesn't run sendmail as the
recipient user, because this often results in undesirable
"X-Authentication-Warning" fields in the header. If you wish the
header to reflect a trail of how a message has been forwarded, see the
--to option below.
- --tmpfile template
- avenger.local creates a copy of the message in a local file.
template is a template for the name of the file, which must end
with a number of "X" characters, which will be replaced by a
unique identifier. (This is for use with the mkstemp(3) library
call.) The default value is "/tmp/msg.XXXXXXXXXX".
- --to address (-D address)
- Specifies the full envelope recipient address to which this message is
being delivered. With this option, avenger.local adds a line
"Delivered-To: address" to the header of the mail
message. It also checks that the header did not previously contain the
same line--if the message has already been delivered to the same address,
this indicates a loop, and avenger.local exits with status 70.
ENVIRONMENT¶
The following environment variables are set when running commands specified in
lines starting
|.
- EXT
- The local portion of the email address following the first separator
character (which is the "+" character, unless set otherwise by
--separator). This variable is not set if there is no extension in
the email address.
- EXT1, EXT2, ...
- When EXT itself contains a the separator character, EXT1
contains the part of EXT after the first separator, EXT2 the
part after the second separator, and so on for each separator character in
EXT.
- HOST
- If a recipient has been specified with the -D recip flag,
this variable will contain the host portion of recip.
- LOCAL
- If a recipient has been specified with the -D recip flag,
this variable will contain the local portion of recip.
- PREFIX
- SUFFIX, SUFFIX1, SUFFIX2, ...
- Assuming the separator is "+", when processing a file
local+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 not set. When the file is just local with no
extension, neither PREFIX nor SUFFIX is set. 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.
- RECIPIENT
- If the --to option was specified, the RECIPIENT environment
variable is set to the address specified in that option. Otherwise,
RECIPIENT is not set.
- RECIPIENT_HOST
- RECIPIENT_LOCAL
- These are the same as HOST and LOCAL, but with all
characters folded to lower-case.
- RPLINE
- A "Return-Path:" line suitable for prepending to the message
header.
- SENDER
- The envelope sender of the message.
- SENDMAIL
- The value of the --sendmail option, or "sendmail -oi -os
-oee" by default.
- SENDFROM
- This is the same as $SENDER, unless envelope sender
is empty (for a bounce message) and the -B option has been
specified, in which case SENDFROM is "@". You can forward
a message on from the same sender with a line like this:
| $SENDMAIL -f "$SENDFROM" -- recpient1@host1.com ...
- SEPARATOR
- The separator character specified by --separator, or the default
"+" if none has been explicitly specified.
- UFLINE
- An mbox "From " line suitable for prepending to the message
before appending it to a mailbox or passing it to a filter that expects
such a line.
- USER
- The user to whom the message is being delivered.
EXAMPLES¶
To use avenger.local with sendmail, you might put the following in your sendmail
m4 configuration file (this is the file ending
.mc that produces your
sendmail.cf file):
FEATURE(`local_procmail',
`/usr/local/libexec/avenger.local',
`avenger.local -a $h -d $u')
To deliver mail to a maildir directory called
inbox in your home
directory, you would place the following line in the file
$HOME/.avenger/local:
./inbox/
If you are subscribed to several mailing lists, you might wish to spool them in
separate files, so as to read them separately. (For example, the emacs editor
has a newsreader, GNUS, that lets you read multiple mailboxes more like
newsgroups.) To do this, you should subscribe to each mailing list under a
different address. If your address is
user@host, you
might subscribe to the Mail Avenger mailing list as
user+avenger@ host. To spool mail in file
$HOME /Mail/incoming/avenger-list.spool, create a file
$HOME/Mail/.avenger/local+avenger with the following
line:
./Mail/incoming/avenger-list.spool
To create a mailing list
user+friends@host for yourself and
your friends, create a file
$HOME/Mail/.avenger/local+friends with your inbox and
their addresses, for example:
./inbox/
&friend1@host1.com
&friend2@host2.com
FILES¶
/usr/local/libexec/avenger.local,
$HOME/.avenger/local,
$HOME/.avenger/local*,
/etc/mail/sendmail.cf,
/usr/local/share/avenger/avsendmail.m4
SEE ALSO¶
avenger(1),
deliver(1),
dotlock(1),
mail.local(8)
The Mail Avenger home page: <
http://www.mailavenger.org/>.
BUGS¶
avenger.local doesn't necessarily report problems in a the most useful place
when it encounters errors in a
.avenger/local* file. It does send some
diagnostics to standard error, but these will typically end up in the mail log
or in bounce messages returned to the sender.
avenger.local should always provide the exact envelope recipient in the
RECIPIENT environment variable. Unfortunately, this information is not
available unless it has been supplied with the
-D flag. Often the
envelope recipient is just "
${USER}${SEPARATOR}${EXT}@your.host.name", but it might not be if
there are aliases or virtual domains. On servers with virtual hosts, the
actual hostname used will be unavailable in the general case (though you may
be able to deduce it from
$USER and
$EXT if you know your particular setup). Note that it is
possible to configure sendmail to supply the full recipient address. Mail
avenger comes with example sendmail configuration directives that can be
included in your
sendmail.mc m4 configuration file; see
/usr/local/share/avenger/avsendmail.m4.
To protect against concurrent accesses to mbox format files, avenger.local uses
both
flock and dotfiles to lock mailboxes. However, it does not use
fcntl/
lockf-style locking by default. Thus, if your mail reader
exclusively uses
fcntl for locking, there will be race conditions
unless you specify the
--fcntl option.
AUTHOR¶
David Mazieres