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

LAM 7.1.4                                          July, 2007                                     lamssi_boot(7)