I've spent some time writing a bit of documentation (and perhaps not enough
time writing code, but that's life). I enclose here the formatted manpage
for mj_shell. I expect that this is the first complete view some folks will
get of the new extended command syntax (with modes and multiline
arguments); hopefully nobody will see it as being completely outrageous.
Note that the section on executing multiple commands also describes how the
email parser works (since the same module is used), with the exception that
the external documents are MIME attachments.
Note also that I haven't really spellchecked this and that I'm not much
good with documentation. The section on executing multiple commands seems
especially awkward.
Comments are, as always, appreciated.
- J<
NAME
mj_shell - Majordomo command line interface
SYNOPSIS
mj_shell [-D] [-d domain] [-t topdir] [-p password]
DESCRIPTION
mj_shell provides a command line interface to the Majordomo core
functionality. It provides both a single command interface,
where a command is given directly on the command line, and an
interface into the full text parser, where commands are parsed
out of a file. Anything that can be done through the email
interface can be done through the shell interface.
mj_shell also provides a convenient 'configedit' command that
opens an editor on a set of config variables and allows them to
be edited directly.
Executing single commands
mj_shell allows the user to execute a single command directly,
just by placing it and its arguments on the command line:
mj_shell who mylist
mj_shell subscribe mylist whoever@example.com
For a list of supported commands, execute
mj_shell help commands
Passwords
The -p switch specifies that the command should be executed with
the given password. For general information on how passwords
work in Majordomo, execute
mj_shell help admin passwords
Command modes
The specific behavior of most of the commands can be altered
through the use of command modes. Most commands take the
'noinform' and 'nolog' modes, which turn off owner information
and logging, respectively. The subscribe command takes the
'nowelcome' mode, which prevents the introductory welcome
message from being sent out to new subscribers.
To specify one or more modes, separate them with commas and
attach them to the command with an equals sign, as follows:
mj_shell -p pass subscribe=noinform,nowelcome mylist user@example.com
For information on which commands take which modes, execute
mj_shell help admin commands
Commands taking multiple or array arguments
Some commands, like subscribe, can take multiple arguments (in
this case, a list of addresses to subscribe). Others, like
configset, sometimes take array arguments. These are handled in
mj_shell by placing the multiline part of the command in a file
and specifying the file using the -f switch. For example, if
'addr_file' contains a list of addresses, one per line, you can
do the following:
mj_shell -p pass -f addr_file subscribe=noinform,nowelcome mylist
For another example, if the file 'inform_file' contains the
following:
subscribe : all : ignore
unsubscribe : all : ignore
Then
mj_shell -p pass -f inform_file configset mylist inform
would set the inform variable such that the list owner would not
be informed of subscribe and unsubscribe requests. (Execute
mj_shell help admin config
for more information about configuration variables.)
Executing multiple commands
For performing more involved tasks, mj_shell gives access to the
full Majordomo text parser, which is also used to parse commands
from the body of an email message. Place multiple commands in a
file, and pass the filename to mj_shell using the -F switch.
For example, if 'cmd_file' contains the following lines:
subscribe mylist usera@example.com
subscribe mylist userb@example.com
show mylist usera@example.com
show mylist userb@example.com
all of the commands can be executed by calling mj_shell as
follows:
mj_shell -p pass -F cmd_file
The text parser also allows some advanced features. Multiline
arguments can be specified by a syntax similar to the shell
'here document' feature. An example is simpler than a
description; you could place the following in 'cmd_file':
subscribe mylist << ENDA
usera@example.com
userb@example.com
ENDA
show mylist << ENDB
usera@example.com
userb@example.com
ENDB
configset mylist inform << AAA
subscribe : all : ignore
unsubscribe : all : ignore
AAA
to additionally set the 'inform' variable. (In this example the
syntax is not much shorter, but for longer address lists it can
save much typing.) The '<<' begins the multiline argument, and
must be at the end of the command line. The tag must consist of
at least three uppercase letters, and appears both directly
after the '<<' and alone on a line after all of the data.
Multiline arguments can also be included in external files. The
external files given using one or more -f options on the
mj_shell command line, and their contents are referenced by
placing '<@' followed by a number; using '3' would reference the
file named by the third -f option. For example, if the file
'addrs' contains:
usera@example.com
userb@example.com
'inform' contains:
subscribe : all : ignore
unsubscribe : all : ignore
and 'commands' contains:
subscribe mylist <@1
show mylist <@1
configset mylist inform <@2
then the command
mj_shell -F commands -f addrs -f inform
would do the same as the previous example.
In addition, the text parser supports the special 'default'
command, which sets some default parameter for following
commands. The 'default list' command (followed by a list name)
sets the default list, while the 'default password' command sets
the password. Thus the 'commands' file in the previous example
can be replaced by:
default list mylist
subscribe <@1
show <@1
configset inform <@2
The default list or password can be cleared by using 'default
list' or 'default password' with no list or password.
The configedit command
There is one command which is exclusive to mj_shell, the
configedit command. This enables a list owner to retrieve the
values of one or more configuration variables, modify them in an
editor, and save the new values in a single operation.
Note that the configedit command is not supported on all
platforms, but can be emulated by the following set of
operations:
mj_shell -p pass configshow list vars > tempfile
(edit tempfile)
mj_shell -p pass -F tempfile
Switches
Here are all of the command line switches that mj_shell takes:
-D Specifies that full debugging information will be sent to
standard output.
-d *domain*
Specifies the domain of lists to operate on. The default
domain is chosen at install time; for installations
supporting more than one domain, this switch must be used to
distinguish between them.
-F *filename*
Specifies that the text parser will be run on *filename*.
All non-option arguments on the mj_shell command line will
be ignored.
-f *filename*
Specifies that the contents of *filename* will be used
either as a multiline argument for a given command, or for
an external argument for a '<@' specifier in the text
parser.
More than one -f argument is permitted, though multiple
instances are only used by the text parser.
*filename* can also be the string '-', in which case
standard input is read.
-p *password*
Specifies a password that a command will be run with, or the
default password for commands run by the text parser.
-t *directory*
This specifies the directory which is the top level of the
Majordomo lists directory structure. This is generally
compiled in at installation time, but some sites may have
different directory structures.
-u *user*
Specifies the user that commands will run as. Note that this
does not change the system UID, but only affects the user
(really the email address) that is passed to the Majordomo
core for access checking and which is used as the default
for certain commands. Normally the user is determined from a
combination of environment variables and the result of the
'hostname' function, but this information is not always
accurate.
Please note that this can be used for nefarious purposes,
but that it does not pose any additional security risk since
mail sent to the email processor can be trivially forged.
List owners are strongly urged not to rely on users and
email addresses for security, but instead to rely on
passwords and to enable confirmation on all security
sensitive commands.
-Z Specifies that UID/GID tests will not be done. Normally mj_shell
will check to make sure that it is running as the user and
group specified during installation. Failure of this test
generally indicates an installation error; either the
wrappers or the scripts themselves shouldf be installed
setuid and setgid to the Majordomo user and group. Using the
-Z option enables mj_shell to run even with this
misconfiguration, though other operations may fail and file
ownerships will not be set correctly.
This option is mainly used by the test scripts, so that they
can run before the software has been completely installed.
--id
Forces mj_shell to print out the real and effective user and
group IDs at the beginning of execution. Used for debugging.
|
|
