mvmf: mvmda man page
mvmf: mvmda man page
MVMDA(1) 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 its built-in mfl lan-
guage, which is a sort of mongrelization of C and Sieve.
mfl, which is described in another document, allows pro-
grammed 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 gener-
ate 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 applying 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 con-
figuration/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 actually 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 error 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 executed (and thus the new type name
is not installed).
-d user
Specifies that mvmda should run as the given user-
name. 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 pro-
cess), 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 vari-
able USER according to whatever user it thinks it
is running as.
This option is chosen for compatibility with vari-
ous other delivery 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 $Opt_e is an array of string
types, one per -e argument. The MFL variable
$Opt_eL is an int containing the length of the
array (number of elements), and $Opt_eC is an int
containing the number of strings in the array.
Usually, $Opt_eC is the same as $Opt_eL, but it
isn't guaranteed to be (for example, when no -e
arguments are given, the array length is 1 but the
string count is 0.)
-E string.
This option is just like -e except that the MFL
variables created are $Opt_E, $Opt_EL, and $Opt_EC.
-i Enter interactive mode. In this mode, mvmda
accepts program input from stdin, and executes each
program statement when it is complete. This can be
used for testing scripts or simply accessing 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 mail-
box 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 actually 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 con-
tinue." If no explicit delivery has been attempted
by the mfl script, mvmda will not file the email
into the default mailbox, and will exit with a sta-
tus code indicating that delivery should continue.
This "pass through" operation is relevant 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 externally (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 created. 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 future 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 explicitly overridden by whatever
invokes the script).
-v prints mvmda's version number. The version number
has three decimal parts separated by periods: first
a major version number, next a minor version num-
ber, 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 incremented 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 ini-
tial release features or that may not yet be con-
sidered fully tested).
-V prints mvmda's version number, the path to the sys-
tem-wide rc file and related info, and control set-
tings, 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 options, 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 com-
mand 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 administrator
to see how this works in your environment.
When run in normal, non-interactive mode, mvmda processess
the mail message 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 command line, or a
default script, or both).
In interactive mode, mvmda repeatedly interprets and exe-
cutes 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 imme-
diately.)
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 documen-
tation for a full list, but one or more significant hooks
are:
$hook_exitcode(code)
is called when mvmda exits. The passed code is one
of the internal 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 important 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 envi-
ronment), which are tested by the 'dnsbl' state-
ments. If this function is not defined, 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.
FILES
The default mvmf_libdir directory, unless it was changed
by a configuration 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@mv.mv.com) 2003,2004,2005,2006,2007
BUGS
You tell me..