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 (email@example.com) 2003,2004,2005,2006,2007 BUGS You tell me..