mvmf: mvmda-sysrc man page
mvmf: mvmda-sysrc man page
MVMDA-SYSRC(5) File Formats Manual MVMDA-SYSRC(5)
NAME
mvmda-sysrc - system-wide control script for mvmda
DESCRIPTION
mvmda requires a system-wide script that controls its execution (remov-
ing 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 (config-
ure'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 do.
INVOCATION
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 sim-
ple commands, and into the MFL scripts where it can be more readily tai-
lored 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 set-
ting 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-
thing.
The command line arguments are given to the rc script via three MFL
variables, following a traditional argc/argv model:
$ArgV is an array of strings that correspond to the command line
arguments. $ArgV[0] is the exec name, $ArgV[1] is the first op-
tion or argument, and so forth.
$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 that).
-e and -E
-e and -E are two command-line options that mvmda accepts but does noth-
ing with, other than making them available to the rc script via MFL
variables. These are nothing special: 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 defined.
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 message.
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 execution, 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 oper-
ation, 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 interac-
tive terminal session with the mvmda/mfl interpreter. The rc
script should probably do very little in this mode, but how lit-
tle 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 in-
visible to the rc script, which is executed in normal mode.
TASKS
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 sev-
eral of the things that might be done in the rc script.
Namespaces
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
into.
Hooks
mvmda and MFL make use of hooks, which are specifically-named MFL func-
tions that are called at certain points in application execution to af-
fect the execution in user-defined ways. You (the system administrator,
and potentially 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 de-
fine them in-line in a script file (like, for example, here in the sys-
tem-wide rc script). This is reasonable 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 ex-
pected 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 operates 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 one.
Controls
Many if not most application settings and parameters are enacted via
MFL's controls. For mvmda, these might include specifying locking meth-
ods, 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 us-
ing 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_protect_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 common script code
into a startup file of their own, so that control definitions, vari-
ables, 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 sys-
tem-wide rc script.
EXAMPLE
This is a very bare-bones example of a system-wide rc script. It is de-
rived from (and may be identical to) the built-in script that is poten-
tially enabled via the --enable-mvmda-builtin-sysrc configuration op-
tion.
Avoid using variables beginning with '$' -- these are reserved for in-
ternal 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;
return;
}
// 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_protect_admin(
$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 ) )
return;
}
// 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_protect_admin(
$mfl_run_fname( $ArgV[ _rc_i ], _rc_script_mode )
);
}
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.
SEE ALSO
MFL -- the mvmda language description. mvmda(1),
http://www.mvmf.org/ -- the official web site.
CREDITS TO
M. Mallett (mem@mvmf.org) 2006-2025
BUGS
You tell me..
MVMDA-SYSRC(5)