Provided by: lam-runtime_7.1.4-7_amd64 
NAME
lamssi_boot - overview of LAM's boot SSI modules
DESCRIPTION
The "kind" for boot SSI modules is "boot". Specifically, the string "boot" (without the
quotes) is the prefix that can be used as the prefix to arguments when passing values to
boot modules at run time. For example:
lamboot -ssi boot rsh hostfile
Specifies to use the "rsh" boot module, and lamboot across all the nodes listed in the
file hostfile.
LAM currently has several boot modules: bproc, globus, rsh (which includes ssh), slurm,
and tm.
ADDITIONAL INFORMATION
The LAM/MPI User's Guide contains much detail about all of the boot modules. All users
are strongly encouraged to read it. This man page is a summary of the available
information.
SELECTING A BOOT MODULE
Only one boot module may be selected per command execution. Hence, the selection of which
module occurs once when a given command initializes. Once the module is chosen, it is
used for the duration of the program run.
In most cases, LAM will automatically select the "best" module at run-time. LAM will
query all available modules at run time to obtain a list of priorities. The module with
the highest priority will be used. If multiple modules return the same priority, LAM will
select one at random. Priorities are in the range of 0 to 100, with 0 being the lowest
priority and 100 being the highest. At run time, each module will examine the run-time
environment and return a priority value that is appropriate.
For example, when running a PBS job, the tm module will return a sufficiently high
priority value such that it will be selected and the other available modules will not.
Most modules allow run time parameters to override the priorities that they return that
allow changing the order (and therefore ultimate selection) of the available boot modules.
See below.
Alternatively, a specific module may be selected by the user by specifying a value for the
boot parameter (either by environment variable or by the -ssi command line parameter). In
this case, no other modules will be queried by LAM. If the named module returns a valid
priority, it will be used. For example:
lamboot -ssi boot rsh hostfile
Tells LAM to only query the rsh boot module and see if it is available to run.
If the boot module that is selected is unable to run (e.g., attempting to use the tm boot
module when not running in a PBS job), an appropriate error message will be printed and
execution will abort.
AVAILABLE MODULES
As with all SSI modules, it is possible to pass parameters at run time. This section
discusses the built-in LAM boot modules, as well as the run-time parameters that they
accept.
In the discussion below, parameters to boot modules are discussed in terms of name and
value. The name and value may be specified as command line arguments to the lamboot,
lamgrow, recon, and lamwipe commands with the -ssi switch, or they may be set in
environment variables of the form LAM_MPI_SSI_name=value. Note that using the -ssi
command line switch will take precendence over any previously-set environment variables.
bproc Boot Module
The bproc boot module uses native bproc functionality (e.g., the bproc_execmove library
call) to launch jobs on slaves nodes from the head node. Checks are made before launching
to ensure that the nodes are available and are "owned" by the user and/or the user's
group. Appropriate error messages will be displayed if the user is unable to execute on
the target nodes.
Hostnames should be specified using bproc notation: -1 indicates the head node, and
integer numbers starting with 0 represent slave nodes. The string "localhost" will
automatically be converted to "-1".
The default behavior is to mark the bproc head node as "non-scheduledable", meaning that
the expansion of "N" and "C" when used with mpirun and lamexec will exclude the bproc head
node. For example, "mpirun C my_mpi_program" will run copies of my_mpi_program on all
lambooted slave nodes, but not the bproc head node.
Note that the bproc boot module is only usable from the bproc head node.
The bproc boot module only has one tunable parameter:
boot_bproc_priority
Using the priority argument can override LAM's automatic run-time boot module
selection algorithms. This parameter only has effect when the tm module is eligible
to be run (i.e., when running on a bproc cluster).
See the bproc notes in the user documentation for more details.
globus Boot Module
The globus boot module uses the globus-job-run command to launch executables on remote
nodes. It is currently limited to only allowing jobs that can use the fork job manager on
the Globus gatekeeper. Other job managers are not yet supported.
LAM will effectively never select the globus boot module by default because it has an
extremely low default priority; it must be manually selected with the boot SSI parameter
or have its priority raised. Additionally, LAM must be able to find the globus-job-run
command in your PATH.
The boot schema requires hosts to be listed as the Globus contact string. For example:
"host1:port1:/O=xxx/OU=yyy/CN=aaa bbb ccc"
Note the use of quotes because the CN includes spaces -- the entire contact name must be
enclosed in quotes. Additionally, since globus-job-run does not invoke the user's "dot"
files on the remote nodes, no PATH or environment is setup. Hence, the attribute
lam_install_path must be specified for each contact string in the hostfile so that LAM
knows where to find its executables on the remote nodes. For example:
"host1:port1:/O=xxx/OU=yyy/CN=aaa bbb ccc" lam_install_path=/home/lam
The globus boot module only has one tunable parameter:
boot_globus_priority
Using the priority argument can override LAM's automatic run-time boot module
selection algorithms.
rsh Boot Module
The rsh boot module uses rsh or ssh (or any other command line agent that acts like
rsh/ssh) to launch executables on remote nodes. It requires that executables can be
started on remote nodes without being prompted for a password, and without outputting
anything to stderr.
The rsh boot module is always available, and unless overridden, always assigns itself a
priority of 0.
The rsh module accepts a few run-time parameters:
boot_rsh_agent
Used to override the compiled-in default remote agent program that was selected when
LAM is compiled. For example, this parameter can be set to use "ssh" if LAM was
compiled to use "rsh" by default. Previous versions of LAM/MPI used the LAMRSH
environment variable for this purpose. While the LAMRSH environment variable still
works, its use is deprecated in favor of the boot_rsh_agent SSI module argument.
boot_rsh_priority
Using the priority argument can override LAM's automatic run-time boot module
selection algorithms.
boot_rsh_username
If the user has a different username on the remote machine, this parameter can be used
to pass the -l argument to the underlying remote agent. Note that this is a coarse-
grained control -- this one username will be used for all remote nodes. If more fine-
grained control is required, the username should be specified in the boot schema file
on a per-host basis.
slurm Boot Module
The slurm boot module uses the srun command to launch the LAM daemons in a SLURM execution
environment (i.e., it detects that it is running under SLURM and automatically sets its
priority to 50). It can be used in two different modes: batch (where a script is
submitted to SLURM and it is run on the first node in the node allocation) and allocate
(where the -A option is used to srun to obtain an interactive allocation). The slurm boot
module does not support running in a script that is launched by SLURM on all nodes in an
allocation.
No boot schema file is required when using the slurm boot module; LAM will automatically
determine the host and CPU count from SLURM itself.
The slurm boot module only has one tunable parameter:
boot_slurm_priority
Using the priority argument can override LAM's automatic run-time boot module
selection algorithms. This parameter only has effect when the slurm module is
eligible to be run (i.e., when running in a SLURM allocation).
tm Boot Module
The tm boot module uses the Task Management (TM) interface to launch executables on remote
nodes. Currently, only OpenPBS and PBSPro are the only two systems that implement the TM
interface. Hence, when LAM detects that it is running in a PBS job, it will automatically
set the tm priority to 50. When not running in a PBS job, the tm module will not be
available.
The tm boot module only has one tunable parameter:
boot_tm_priority
Using the priority argument can override LAM's automatic run-time boot module
selection algorithms. This parameter only has effect when the tm module is eligible
to be run (i.e., when running in a PBS job).
SEE ALSO
lamssi(7), mpirun(1), LAM User's Guide