mvmf: mvmda-sysrc man page
mvmf: mvmda-sysrc man page
MVMDA-SYSRC(5) MVMDA-SYSRC(5)
NAME
mvmda-sysrc - system-wide control script for mvmda
DESCRIPTION
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
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 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-
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 option 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 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
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 mes-
sage.
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.
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 several
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 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
one.
Controls
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.
EXAMPLE
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;
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 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.
SEE ALSO
MFL -- the mvmda language description. mvmda(1),
http://www.mvmf.org/ -- the official web site.
CREDITS TO
M. Mallett (mem@mv.mv.com) 2006,2007
BUGS
You tell me..