mvmf: mvmda man page
mvmf: mvmda man page
MVMDA(1) General Commands Manual MVMDA(1)
NAME
mvmda - mvmf's Mail Delivery Agent (MDA)
SYNOPSIS
mvmda [-b] [-c] [-d user] [-e string] [-E string] [-i] [-l layout] [-m
default-mailbox] [-n] [-p] [-q] [-r path] [-s storage-type] [-S] [-v]
[-V] [args]
DESCRIPTION
mvmda is a Mail Delivery Agent (MDA), used to perform final delivery of
mail, applying delivery script logic to the delivery.
mvmda includes an interpreter for the built-in mfl language, which is a
sort of mongrelization of C and Sieve. mfl, which is described in an-
other document, allows programmed control over what happens to email,
and includes a number of intrinsics to accomodate final delivery. Most
users will probably use an intelligent front-end to generate mfl scripts
for mvmda; however the language is also suitable for hand construction
by programmers.
mvmda is designed to deliver to both mbox and Maildir (and Maildir++)
formats.
In general, the function of mvmda is to process a mail message, by ap-
plying script(s) against it. However, mvmda can operate in other modes,
such as checking the syntax of a script or reporting what processing
steps might be taken without actually taking them.
One of the goals of mvmda is to strike a balance between the needs of
system administrators and the needs of system users. To that end, much
of what mvmda actually does is directed by a system-wide control script,
aka the 'rc' script. This script is simply mfl, and is installed by the
system administrator (or someone else, e.g. whoever built the mvmf
package). See the mvmf-sysrc man page for more detail on this.
Options which may be given are as follows:
-b Forces the use of the internal MFL script rather than the system-
wide one provided by the system administrator. This option must
be enabled at configuration/compile time. Also, if this option
has been enabled, mvmda will not automatically use the built-in
script if the system-wide one is not available: you must use -b
explicitly.
-c Specifies "check" mode. This is a signal that you would like
mvmda to interpret scripts and report syntax errors, without ac-
tually executing them. This signal is provided to the system-
wide startup script which actually acts on it. In order to pro-
vide this functionality, the startup script must honor this cue.
"check" mode can help to find obvious syntax errors in scripts.
However, inhibiting the execution can introduce false syntax er-
ror reports in some cases. For example, if you use a typedef to
declare a new C-like type, any statements using that type name
will result in a syntax error since the typedef does not get exe-
cuted (and thus the new type name is not installed).
-d user
Specifies that mvmda should run as the given username. If mvmda
is running as root (e.g. if it is installed suid root for some
unfathomable reason, or if it is being invoked by an already-root
process), it will attempt to become that user. Regardless of
that, if mvmda is not running as the specified user, it will
refuse to run.
Note that mvmda will publish the environment variable USER ac-
cording to whatever user it thinks it is running as.
This option is chosen for compatibility with various other deliv-
ery agents.
-e string
This option may be given multiple times. Each string argument is
remembered, and all of them are given to the script language via
three variables. The MFL variable $Opts_e is an array of string
types, one per -e argument. The MFL variable $Opts_eL is an int
containing the length of the array (number of elements), and
$Opts_eC is an int containing the number of strings in the array.
Usually, $Opts_eC is the same as $Opts_eL, but it isn't guaran-
teed to be (for example, when no -e arguments are given, the ar-
ray length is 1 but the string count is 0.)
-E string.
This option is just like -e except that the MFL variables created
are $Opts_E, $Opts_EL, and $Opts_EC.
-i Enter interactive mode. In this mode, mvmda accepts program in-
put from stdin, and executes each program statement when it is
complete. This can be used for testing scripts or simply access-
ing the interpreter for other reasons.
-l layout
(OBSOLETE) Specifies the sort of folder layout in use. A layout
type of FS indicates that folders may appear anywhere in the
filesystem (below any root given by -r ). A layout type of
Maildir++ (or simply maildir) indicates that folders are arranged
per Maildir++ format, which is to create specially-named folders
inside the Maildir directory itself.
This option is now obsolete (the layout now being associated with
each namespace), and has no effect. In some future release, the
option will be removed.
-m default-mailbox
"default-mailbox" will be used as the default mailbox or folder
name. This is where mvmda will store the mail message if no
other action has been taken (or if the mail message is designated
for keeping at the time mvmda finishes).
-n operate in "test" mode. Here, mvmda will report the actions it
would have taken, rather than take them. These reports may be
inexact because of the interactions between various actions actu-
ally taken (vs those not taken in test mode).
-p operate in "pass-through" mode. In this mode, mvmda does not
necessarily do final delivery-- instead turning "implicit keep"
into "implicit continue." If no explicit delivery has been at-
tempted by the mfl script, mvmda will not file the email into the
default mailbox, and will exit with a status code indicating that
delivery should continue. This "pass through" operation is rele-
vant only to qmail mode, allowing mvmda to be used to intercept
mail if so guided by its script, while letting qmail delivery
continue on to the next step if mvmda has not handled the mail.
Note that the default mailbox information is still required on
the command line, even if that information is never used by the
script.
-q is an obsolete option. Its former purpose was to hardcode some
knowledge about being in a qmail environment. The main thing was
to define a default $hook_exitcode() hook to give proper exit
codes to qmail. If wanted, this hook must now be provided exter-
nally (e.g. by the system rc script or by including it in the
hook path). -q now does nothing, but is maintained so that old
scripts invoking mvmda don't have to be changed.
-r root
(OBSOLETE) "root" is a path below which all folders must be cre-
ated. i.e. all folder creations are restricted to this directory
or any subdirectories contained in this root.
This option is now obsolete (the path now being associated with
each namespace), and has no effect. In some future release, the
option will be removed.
-s storage-type
(OBSOLETE) Provides the default storage type. Storage types are
"mbox" and "Maildir". If not otherwise overridden, any new mail
folder created will be of this default type. Any mail saved to
an already existing folder will use the type of that folder.
This option is now obsolete (the default storage type now being
associated with each namespace), and has no effect. In some fu-
ture release, the option will be removed.
-S Sets the "mfl_mode_sieve" control to 1. When this is set,
scripts will start out in sieve mode by default (unless explic-
itly overridden by whatever invokes the script).
-v prints mvmda's version number. The version number has three dec-
imal parts separated by periods: first a major version number,
next a minor version number, and finally a fix number. The fix
number is incremented whenever a new version contains only fixes
and enhancements to existing features. The minor number is in-
cremented whenever a new facility or technique is added, and the
major number is incremented when enough new things have been
added to consider it a major new edition of the program. A major
number of zero (0) indicates a prerelease version (one that
doesn't yet include all its initial release features or that may
not yet be considered fully tested).
-V prints mvmda's version number, the path to the system-wide rc
file and related info, and control settings, in a form suitable
to be re-read via MFL. This will show the effects of any initial
startup configuration. As an added bonus, if you give two -V op-
tions, and if an internal MFL script has been enabled at compile
time, the source of that script will be printed to stdout.
Any other arguments (args) are interpreted by the system-wide startup
script. A likely implementation is that command line arguments are
names of script files to apply to the incoming message that's on stdin.
However, check with your system-wide script and/or your system adminis-
trator to see how this works in your environment.
When run in normal, non-interactive mode, mvmda processess the mail mes-
sage given to its stdin, using the script(s) that the system-wide rc
file applies to it (e.g., perhaps including the files named on the com-
mand line, or a default script, or both).
In interactive mode, mvmda repeatedly interprets and executes language
elements from stdin. (Note one thing that is sometimes forgotten: when
you interactively type a "if" statement in C-like mode, the interpreter
needs to see if there is a following "else" -- so you may have to enter
another semicolon if you expect the "if" to execute immediately.)
HOOKS
At certain points in its execution, mvmda will invoke specifically-named
mfl functions in order to give user or admin options at these control
points. See other documentation for a full list, but one or more sig-
nificant hooks are:
$hook_exitcode(code)
is called when mvmda exits. The passed code is one of the inter-
nal mvmda exit codes; this hook returns a new exit code for mvmda
to use. This hook may be installed to translate the internal
exit code to something that is more friendly to the invoker. If
this hook is not defined, mvmda does not define one. It's impor-
tant that if you need exit code translations (such as when you
are using qmail), this hook be supplied.
$hook_msg_read_after()
is called immediately after the email message is read and
scanned. Among other things, this hook can scan the message
headers in order to generate the list of responsible IP addresses
(the IP addresses of systems that are believed to have had a hand
in delivering the message to the local environment), which are
tested by the 'dnsbl' statements. If this function is not de-
fined, no such processing of the incoming message is done.
But again, see other documentation for more complete information about
these and other hooks.
ENVIRONMENT VARIABLES
The following environment variables are defined by mvmda, available for
use by MFL scripts.
USER This is the name of the user that mvmda is running as.
MTA notes
This section has any notes that I feel like making about mvmda's use
with specific MTAs (Mail Transport Agents). While mvmda was originally
written to be used with qmail, it can, or should be able to, be used
with any common MTA.
QMAIL
qmail can invoke mvmda in various ways. The standard method is to spec-
ify it in a dot-qmail file (aka a .qmail file), either a dash-mode
.qmail file or a default type. dot-qmail files are handled by qmail-lo-
cal, which finds the apropriate dot-qmail file for the destination email
address (if any, or a default). There are other ways to specify delivery
such as using .forward files.
dot-qmail
We're not going into too much detail about dot-qmail (presumably
if it matters to you you know something about it already). dot-
qmail is a term used to describe the delivery of local mail by
qmail-local, both in the format of the dot-qmail file itself and
in how that file is found. Check other documentation for a more
complete description of these things. For this simple discussion,
let's just assume that there's a dot-qmail file in use. Essen-
tially, a dot-qmail file can specify zero or more delivery desti-
nations. Each destination can be the name of a mailbox, a new
email address to forward to, or a program to handle the delivery.
It is with this last case that we can invoke mvmda as a delivery
agent. This kind of entry starts with a pipe symbol (vertical
bar) and specifies how mvmda is invoked. For example,
|/usr/local/bin/mvmda -m Mailbox $HOME/filter.mfl
Note that the qmail-local program is responsible both for figur-
ing out what dot-qmail file will be used to handle delivery for a
possibly-extended local address, based on the format of the email
address, and for interpreting the delivery instructions in that
file. As we've noted, this splits the job of the MDA in ways that
make it difficult to drop in an alternative MDA because because
qmail-local does some of the MDA work, and does this inconsis-
tently across the different kinds of deliveries that it supports.
Where a destination address or a mailbox is given, qmail-local
does some extra things. It checks to see if there's a "Delivered-
To" header field in the message, and if it finds one that matches
the current destination address it rejects the message. If not,
it adds a new "Delivered-To" header field and also adds a "Re-
turn-Path" address identifying the envelope sender. However, if
the dot-qmail entry specifies a program, as it would when mvmda
is being invoked, qmail-local does not do these things. The
original qmail included a filter program called "preline" which
mainly exists just to optionally add a "Return-Path" or "Deliv-
ered-To" header field and a "From " mbox introducer line (which
is a quasi- header field). You can use this to invoke mvmda, e.g.
like
|preline /usr/local/bin/mvmda -m Mailbox $HOME/filter.mfl
preline allows some control over what it does. For example to en-
able adding "Delivered-To" but suppress adding "Return-Path" you
might:
|preline -D -r /usr/local/bin/mvmda -m Mailbox $HOME/filter.mfl
(not all options are documented in the preline man page, but for
reference, single letter options 'd' and 'f' and 'r' are for "De-
livered-To" and "From " and "Return-Path" with lowercase letter
suppressing the item and uppercase enabling it.) We should note
that mvmda, by itself, orchestrates the maintenace of the "From "
(aka From_) header field for mbox files, so what preline does
with it is irrelevant. Also note that mvmda does not, at
present, implement the detection of duplicates via "Delivered-To"
header fields. This should probably be added.
A possible future enhancement to mvmda would have it handle the
job of locating and interpreting the dot-qmail file, tying the
pieces of the MDA together. This could obviate the need of adding
the "Delivered-To" check in mvmda and perhaps that's why we
haven't done it yet. He says, convincingly.
others including .forward
There are other ways to handle delivery, depending on how qmail-
send is invoked. If configured to allow dot-forward, the delivery
process looks for a .forward file and, if one is found, the de-
livery will be done according to the information in that file
(typically one or more new email addresses to deliver to).
postfix, exim, sendmail
Nothing much to say, except that those MTAs exist and mvmda can be used
with them. If nothing else you can use a .forward file. There may be
slight variations in the format in each. But for example, with dummy
paths and arguments:
postfix
|"/bindir/mvmda -a -b -c $HOME/x.mfl"
sendmail
"|/bindir/mvmda -a -b -c x.mfl"
qmail (as mentioned above) "|/bindir/mvmda -a -b -c $HOME/x.mfl"
It's possible to specify mvmda in a sendmail mailer definition. The ex-
perience we have with that is pretty old and isn't provided here.
FILES
The default mvmf_libdir directory, unless it was changed by a configura-
tion option when the package was built, is /usr/local/share/mvmf .
Within this directory are:
mvmda/mvmda-rc.mfl -- the default system-wide startup mfl file.
include -- default directory for system include scripts.
dnsbl.conf -- the system-wide DNS blacklist definition file
SEE ALSO
MFL -- the mvmda language description.
mvmda-sysrc(5),
http://www.mvmf.org/ -- the official web site.
CREDITS TO
M. Mallett (mem@mvmf.org) 2003-2025
BUGS
You tell me..
MVMDA(1)