avenger.local man page on DragonFly

Man page or keyword search:  
man Server   44335 pages
apropos Keyword Search (all sections)
Output format
DragonFly logo
[printable version]

avenger.local(8)	      Mail Avenger 0.8.4	      avenger.local(8)

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

Mail Avenger 0.8.4		  2013-07-13		      avenger.local(8)
[top]

List of man pages available for DragonFly

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net