mvmf: mvmda-sysrc man page

mvmf: mvmda-sysrc man page

MVMDA-SYSRC(5)                                     MVMDA-SYSRC(5)

       mvmda-sysrc - system-wide control script for mvmda

       mvmda requires a system-wide script that controls its exe-
       cution (removing hardwired-logic from the  program  itself
       and placing it in a script under the system administator's
       control).  The script is read from a  file  in  the  mvmda
       subdirectory  of  the 'mvmf_libdir' directory (configure's
       'datadir', by default /usr/local/share/mvmf).  The  script
       file,  if you haven't changed it, is called 'mvmda-rc.mfl'
       .  If this file is not found, mvmda  will  refuse  to  run
       (unless  it  was  configured  with --enable-mvmda-builtin-
       sysrc, in which case  a  compiled-in  skeletal  script  is
       used).   The  construction and flow of this control script
       is important.  This document gives an overview of how this
       file  is  invoked and some of the things it is expected to

       This script is run by mvmda  as  MFL  code.   When  it  is
       invoked,  mvmda has done very little.  (As the development
       of mvmda has progressed, more and more  of  its  flow  has
       been moved out of hardwired internal logic and simple com-
       mands, and into the MFL scripts where it can be more read-
       ily tailored by administrators and users.  Much of mvmda's
       flow has now been delegated to the system-wide rc script.)
       It  has processed its command line options, determined the
       operation mode, and made some information available to MFL
       so that the rc script can act on it.

   Configuration parameters
       Certain  configuration  information  is made available via
       environment variables.  This information can  be  used  by
       the rc script, e.g. for setting up directory paths.

       MVMF_LIBDIR, public directory
              the  directory  configured  as the mvmf_libdir, aka
              the datadir in configure.  This is the root of  the
              tree  where  generally-readable  mvmf data is kept.
              Data that is particular to mvmda is  probably  kept
              in a "mvmda" subdirectory.

       MVMF_SYSDIR, system directory
              the  directory configured as the mvmf_sysdir.  This
              is the root of the  tree  where  system-accessible-
              only  data  should be kept.  mvmda is not likely to
              need anything in this tree.

   Command-line arguments
       mvmda interprets the  command  line  options  that  it  is
       invoked  with, but does not touch any arguments that might
       follow those options.  Instead, it  leaves  interpretation
       of  those other arguments to the rc script.  The arguments
       might typically be script names, but they can be most any-

       The  command line arguments are given to the rc script via
       three MFL variables,  following  a  traditional  argc/argv

              $ArgV is an array of strings that correspond to the
              command line arguments.  $ArgV[0] is the exec name,
              $ArgV[1]  is  the  first option or argument, and so

              $ArgC is an int containing the number of strings in
              $ArgV, and

              $ArgN  is  an int containing the index of the first
              argument (first string in $ArgV)  not  consumed  by
              mvmda option processing.

       Generally,  an rc script will only concern itself with the
       arguments from $ArgN through $ArgC-1, and these are likely
       to be script filenames (but, again, the rc file can decide

   -e and -E
       -e and -E are two command-line options that mvmda  accepts
       but does nothing with, other than making them available to
       the rc script via MFL variables.  These are  nothing  spe-
       cial:  they  just  provide  a way to invoke mvmda and pass
       some things to the rc script, while  distinguishing  those
       things from regular command-line arguments.

       These  arguments  may  be repeated: any number of -e or -e
       options may be given.  All of them are supplied to MFL.

       For -e:

              $Opts_e is an  array  of  strings,  containing  the
              option  values.   $Opts_eC is an int containing the
              number of option value strings in  the  array,  and
              $Opts_eL is the length of the array (which might be
              greater than the number of options,  especially  if
              the latter is zero).

       Correspondingly, for -E:

              $Opts_E,   $Opts_EC,  and  $Opts_EL  are  similarly

   Incoming message
       At the time the rc script is  invoked,  nothing  has  been
       done  about any incoming message.  If there is an incoming
       message that should be processed, such as  when  mvmda  is
       operating in normal mode, the rc script is responsible for
       opening it.  This might surprise  you,  but  punting  this
       responsibility  to  the rc file gives extra flexibility to
       the system administrator.  It also allows the rc  file  to
       do  things  such as define hooks that might be called as a
       side-effect of opening and processing  the  incoming  mes-

   Operating mode
       mvmda  runs in one of several modes.  The mode is supplied
       to the rc script as the value of an  MFL  string  variable
       $OPMODE.  The values are as follows:

       "CHECK" -- check mode.
              In  check  mode,  mvmda is being asked to check the
              syntax of the scripts that it might otherwise  run.
              The rc script may elect to do other things, such as
              define the controls it would define for normal exe-
              cution,  and it should proceed to invoke scripts in
              a parse-only, check mode rather than a run mode.

       "CONTROLS" -- controls mode.
              In controls mode, mvmda is being  invoked  to  dump
              the  values  of  its controls and related settings.
              Presumably the invoker wants to  see  the  controls
              that  would be in effect during a normal operation,
              so the rc script should set up controls in the same
              way  it  would  if it were in normal mode.  Once it
              has done that, it should finish  up  without  doing
              other work.

       "INTERACTIVE" -- interactive mode.
              In interactive mode, the mvmda user will enter into
              an interactive terminal session with the  mvmda/mfl
              interpreter.  The rc script should probably do very
              little in this mode, but how little is really up to
              the administrator.

       "NORMAL" -- normal mode.
              In  this mode, mvmda is doing normal delivery.  The
              rc script should  open  up  the  incoming  message,
              determine  which script(s) it will be invoking, and
              run those scripts in normal delivery mode.

       Note that while there also appears to be a "test" mode (in
       which  scripts  are run but actions are only reported, and
       not taken), this mode is invisible to the rc script, which
       is executed in normal mode.

       The system administrator uses this rc script to direct the
       ways that mvmda executes.  There are a  number  of  things
       that  the system-wide rc script can attend to, but many of
       them are optional, and  probably  some  are  unpredictable
       here.   This  section just serves as a reminder of several
       of the things that might be done in the rc script.

       When your script wants to write a message to a folder, the
       folder name must select a namespace that has been defined.
       Your system startup script will probably  want  to  define
       some default namespace names.  In particular, the standard
       mailbox name used by mvmda is "INBOX" .  You will probably
       want  to  define  a  namespace that this mailbox name maps

       mvmda and MFL make use of hooks, which  are  specifically-
       named  MFL  functions that are called at certain points in
       application execution to affect  the  execution  in  user-
       defined  ways.   You (the system administrator, and poten-
       tially the end user)  can  define  these  hook  functions.
       Hook functions all have names beginning with "$hook_" .

       You  can  provide hook functions in many ways.  One way is
       simply to define them in-line in a script file (like,  for
       example, here in the system-wide rc script).  This is rea-
       sonable for hooks that are expected to be used every  time
       the  application  runs.   Another way is to let MFL search
       for them at the time they might be needed.   This  is  not
       the  place to document hooks, but briefly: there is a hook
       search path, which is a list of directories in which  hook
       functions  might  be  defined.  This path initially starts
       out empty; the rc script  can  add  to  it.   Whenever  an
       application  such  as  mvmda  wants  to invoke a hook, say
       "$hook_exitcode", as long as that hook is not yet  defined
       it  will look for and run (as MFL) a corresponding file in
       each directory in the hook path.  The file is named  after
       the hook, but without the "$hook_" prefix, and is expected
       to have MFL code that defines the hook function.

       The rc script can either define hook functions inline,  or
       set  up  (add  to)  the hook search path.  The logical and
       recommended place  for  system-defined  hooks  is  in  the
       "mvmf_libdir/mvmda/hooks" subdirectory.

   Include paths
       MFL's  preprocessor  has an "@include" facility that oper-
       ates much like "#include" in cpp.  There  are  two  search
       paths  for  the  include files: a system-level and a user-
       level path.  The rc  file  can  set  up  either  of  these
       include paths, and should at least set up the system-level

       Many if not most application settings and  parameters  are
       enacted  via  MFL's  controls.   For  mvmda,  these  might
       include specifying locking methods,  data  directory,  log
       file  names,  and  so forth.  It should be the system-wide
       rc's duty to set any of these that should be set.

   User script(s)
       A basic expectation of mvmda is that  it  will  process  a
       mail  message  using one or more delivery scripts.  If you
       want user scripts (perhaps  those  named  on  the  command
       line) to be used, it's up to the system-wide rc file to do
       this.  The example script below  illustrates  interpreting
       command-line  arguments  as script file names.  The script
       could be much more elaborate, e.g. perhaps  if  no  script
       names were supplied it would look for a particularly-named
       file, or one or more such files.

       Notice in the  example  how  the  MFL  function  $mfl_pro-
       tect_admin  is  used  to set admin mode to 0 while running
       each user-supplied script.

   User startup file
       A reasonable user expectation is that they can place  com-
       mon  script code into a startup file of their own, so that
       control definitions, variables, and so forth  will  always
       be  set  up no matter what other scripts they use.  If you
       want to provide this functionality, do it in  the  system-
       wide rc script.

       This  is  a  very  bare-bones  example of a system-wide rc
       script.  It is derived from (and may be identical to)  the
       built-in  script  that  is  potentially  enabled  via  the
       --enable-mvmda-builtin-sysrc configuration option.

       Avoid using variables beginning  with  '$'  --  these  are
       reserved  for  internal  use  (i.e., for the mvmf author).
       Use some other convention of reserving names  for  system-
       wide  use  vs  user  use;  perhaps names beginning with an
       underscore for system use.

       // Start by setting up some values depending on what mode we are in
       //  The '= 0' initializers aren't necessary, but they look good.
       char _rc_do_settings = 0;
       char _rc_do_scripts = 0;
       char _rc_do_message = 0;
       string _rc_script_mode;

       // Other scratch variables for the rc file
       string _rc_s, *_rc_sP;
       int _rc_i;

       // Most likely first
       if ( $OPMODE == "NORMAL" ) {
           _rc_do_settings = _rc_do_scripts = _rc_do_message = 1;
           _rc_script_mode = "Ow";
       else if ( $OPMODE == "CHECK" ) {
           _rc_do_settings = _rc_do_scripts = 1;
           _rc_script_mode = "MpOw";
       else if ( $OPMODE == "CONTROLS" ) {
           _rc_do_settings = 1;
       else if ( $OPMODE == "INTERACTIVE" ) {
           _rc_do_settings = 1;
       else {
           pv$ "sysrc: bad value for $OPMODE: ";
           pv$ $OPMODE;

       // If we are supposed to do controls settings, do them now.
       if ( _rc_do_settings ) {
           _rc_s = $env_variable( "MVMF_LIBDIR" );
           $mfl_incdir_add( "system", _rc_s + "/include" );
           $mfl_hookdir_add( _rc_s + "/mvmda/hooks" );

           // Define default settings for mailstore types we use.  These
           //  defaults can be changed for specific namespaces that use them.
           $msst_attr_string_set( "mbox", "locking", "dotlock, flock" );
           $msst_attr_string_set( "mbox", "layout", "fs" );
           $msst_attr_string_set( "maildir", "layout", "maildir++" );

           // Define a namespace to match INBOX -- here's one for
           //  /var/spool/mail mailboxes.
           $msns_define( "INBOX", "mbox" );
           $msns_attr_string_set( "INBOX", "path",
            (string)"/var/spool/mail/" + $env_variable( "USER" ) );

           // Define a namespace that will match all other references, since it
           //  has a null prefix.  This will cause folders to be created inside
           //  the Maildir in the home directory.
           _rc_sP = $env_homedir();
           if ( _rc_sP != 0 ) {
            $msns_define( "", "maildir" );
            $msns_attr_string_set( "", "path", *_rc_sP + "/Maildir" );

           // Next might include running a default user-rc script.
           // _rc_sP = $env_homedir();
           if ( _rc_sP != 0 )
                $mfl_run_fname( *_rc_sP + "/.mvmda-rc.mfl", "Mc" )

       // If we need to open the incoming message, do it.
       if ( _rc_do_message ) {
           if ( !$msg_open_fname( "", 0 ) )

       // Run any scripts now in the previously set mode.
       // One might look for default scriptfile name(s) here, or
       // use a system-wide user script if none are given, etc.
       if ( _rc_do_scripts ) {
           for ( _rc_i = $ArgN; _rc_i < $ArgC; ++_rc_i )
                $mfl_run_fname( $ArgV[ _rc_i ], _rc_script_mode )

       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

       MFL -- the mvmda language description.  mvmda(1), -- the official web site.

       M. Mallett  (   2006,2007

       You tell me..