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 its 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.

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)