Provided by: slurm-llnl_2.3.2-1ubuntu1_amd64 bug

NAME

       SPANK - SLURM Plug-in Architecture for Node and job (K)control

DESCRIPTION

       This  manual briefly describes the capabilities of the SLURM Plug-in architecture for Node
       and  job  Kontrol  (SPANK)  as  well  as  the  SPANK  configuration  file:  (By   default:
       plugstack.conf.)

       SPANK  provides  a  very  generic  interface  for  stackable plug-ins which may be used to
       dynamically modify the job launch code in SLURM. SPANK plugins may be built without access
       to  SLURM  source  code.  They  need only be compiled against SLURM's spank.h header file,
       added to the SPANK config file plugstack.conf, and they will be loaded at  runtime  during
       the  next  job  launch.  Thus,  the SPANK infrastructure provides administrators and other
       developers a low cost, low effort ability to dynamically modify the  runtime  behavior  of
       SLURM job launch.

SPANK PLUGINS

       SPANK plugins are loaded in up to three separate contexts during a SLURM job. Briefly, the
       three contexts are:

       local   In local context, the plugin is loaded by  srun.  (i.e.  the  "local"  part  of  a
               parallel job).

       remote  In  remote  context,  the plugin is loaded by slurmd. (i.e. the "remote" part of a
               parallel job).

       allocator
               In allocator context, the plugin is loaded in one of the job allocation  utilities
               sbatch or salloc.

       In  local  context,  only the init, exit, init_post_opt, and user_local_init functions are
       called. In allocator context, only the init, exit, and init_post_opt functions are called.
       Plugins  may  query  the  context  in  which  they  are running with the spank_context and
       spank_remote functions defined in <slurm/spank.h>.

       SPANK plugins may be called from multiple points during the SLURM job launch. A plugin may
       define the following functions:

       slurm_spank_init
         Called  just after plugins are loaded. In remote context, this is just after job step is
         initialized. This function is called before any plugin option processing.

       slurm_spank_init_post_opt
         Called at the same point as slurm_spank_init, but after all user options to  the  plugin
         have  been processed. The reason that the init and init_post_opt callbacks are separated
         is so that plugins can process system-wide options specified in  plugstack.conf  in  the
         init   callback,   then   process   user  options,  and  finally  take  some  action  in
         slurm_spank_init_post_opt if necessary.

       slurm_spank_local_user_init
         Called in local (srun) context only after all options  have  been  processed.   This  is
         called  after  the  job  ID  and step IDs are available.  This happens in srun after the
         allocation is made, but before tasks are launched.

       slurm_spank_user_init
         Called after privileges are temporarily dropped. (remote context only)

       slurm_spank_task_init_privileged
         Called for each task just after fork, but before all elevated  privileges  are  dropped.
         (remote context only)

       slurm_spank_task_init
         Called for each task just before execve (2). (remote context only)

       slurm_spank_task_post_fork
         Called  for  each  task from parent process after fork (2) is complete.  Due to the fact
         that slurmd does not exec any tasks until all tasks have completed fork (2),  this  call
         is guaranteed to run before the user task is executed. (remote context only)

       slurm_spank_task_exit
         Called for each task as its exit status is collected by SLURM.  (remote context only)

       slurm_spank_exit
         Called  once  just  before slurmstepd exits in remote context.  In local context, called
         before srun exits.

       All of these functions have the same prototype, for example:

          int slurm_spank_init (spank_t spank, int ac, char *argv[])

       Where spank is the SPANK handle which must be passed back to SLURM when the  plugin  calls
       functions  like  spank_get_item  and spank_getenv. Configured arguments (See CONFIGURATION
       below) are passed in the argument vector argv with argument count ac.

       SPANK plugins can query the current list of supported slurm_spank symbols to determine  if
       the  current version supports a given plugin hook.  This may be useful because the list of
       plugin symbols may grow in the future. The query is done using the  spank_symbol_supported
       function, which has the following prototype:

           int spank_symbol_supported (const char *sym);

       The return value is 1 if the symbol is supported, 0 if not.

       SPANK  plugins  do  not  have  direct  access to internally defined SLURM data structures.
       Instead, information about the currently executing job is obtained via the  spank_get_item
       function call.

         spank_err_t spank_get_item (spank_t spank, spank_item_t item, ...);

       The  spank_get_item  call  must  be  passed  the  current SPANK handle as well as the item
       requested, which is defined by the passed  spank_item_t.  A  variable  number  of  pointer
       arguments  are also passed, depending on which item was requested by the plugin. A list of
       the valid values for item is kept in the spank.h header file. Some examples are:

       S_JOB_UID
         User id for running job. (uid_t *) is third arg of spank_get_item

       S_JOB_STEPID
         Job step id for running job. (uint32_t *) is third arg of spank_get_item.

       S_TASK_EXIT_STATUS
         Exit status for exited task. Only valid from slurm_spank_task_exit.  (int  *)  is  third
         arg of spank_get_item.

       S_JOB_ARGV
         Complete  job  command  line.  Third  and fourth args to spank_get_item are (int *, char
         ***).

       See spank.h for more details, and EXAMPLES below for an example of spank_get_item usage.

       SPANK plugins may also use the spank_getenv, spank_setenv, and spank_unsetenv functions to
       view and modify the job's environment. spank_getenv searches the job's environment for the
       environment variable var and copies the current value into a buffer  buf  of  length  len.
       spank_setenv  allows  a  SPANK  plugin  to  set  or  overwrite  a  variable  in  the job's
       environment, and spank_unsetenv unsets an environment variable in the  job's  environment.
       The prototypes are:

        spank_err_t spank_getenv (spank_t spank, const char *var,
                            char *buf, int len);
        spank_err_t spank_setenv (spank_t spank, const char *var,
                            const char *val, int overwrite);
        spank_err_t spank_unsetenv (spank_t spank, const char *var);

       These  are  only  necessary  in remote context since modifications of the standard process
       environment using setenv (3), getenv (3), and unsetenv (3) may be used in local context.

       Functions are also available from  within  the  SPANK  plugins  to  establish  environment
       variables  to be exported to the SLURM PrologSlurmctld, Prolog, Epilog and EpilogSlurmctld
       programs (the so-called job control  environment).   The  name  of  environment  variables
       established  by these calls will be prepended with the string SPANK_ in order to avoid any
       security implications of arbitrary environment  variable  control.  (After  all,  the  job
       control scripts do run as root or the SLURM user.).

       These functions are available from local context only.

         spank_err_t spank_job_control_getenv(spank_t spank, const char *var,
                              char *buf, int len);
         spank_err_t spank_job_control_setenv(spank_t spank, const char *var,
                              const char *val, int overwrite);
         spank_err_t spank_job_control_unsetenv(spank_t spank, const char *var);

       See  spank.h  for  more  information,  and  EXAMPLES below for an example for spank_getenv
       usage.

       Many of the  described  SPANK  functions  available  to  plugins  return  errors  via  the
       spank_err_t  error type. On success, the return value will be set to ESPANK_SUCCESS, while
       on failure, the return value  will  be  set  to  one  of  many  error  values  defined  in
       slurm/spank.h. The SPANK interface provides a simple function

         const char * spank_strerror(spank_err_t err);

       which may be used to translate a spank_err_t value into its string representation.

SPANK OPTIONS

       SPANK plugins also have an interface through which they may define and implement extra job
       options. These options are made available to the  user  through  SLURM  commands  such  as
       srun(1),  salloc(1),  and  sbatch(1). if the option is specified by the user, its value is
       forwarded and registered with the plugin in slurmd when the job  is  run.   In  this  way,
       SPANK plugins may dynamically provide new options and functionality to SLURM.

       Each  option registered by a plugin to SLURM takes the form of a struct spank_option which
       is declared in <slurm/spank.h> as

          struct spank_option {
             char *         name;
             char *         arginfo;
             char *         usage;
             int            has_arg;
             int            val;
             spank_opt_cb_f cb;
          };

       Where

       name   is the name of the option. Its length is limited to SPANK_OPTION_MAXLEN defined  in
              <slurm/spank.h>.

       arginfo
              is  a  description  of  the  argument  to  the  option,  if the option does take an
              argument.

       usage  is a short description of the option suitable for --help output.

       has_arg
              0 if option takes no argument, 1 if option takes an argument, and 2 if  the  option
              takes an optional argument. (See getopt_long (3)).

       val    A plugin-local value to return to the option callback function.

       cb     A  callback  function  that  is  invoked  when the plugin option is registered with
              SLURM. spank_opt_cb_f is typedef'd in <slurm/spank.h> as

                typedef int (*spank_opt_cb_f) (int val, const char *optarg,
                                         int remote);

              Where val is the value of the val field in the spank_option struct, optarg  is  the
              supplied  argument  if  applicable, and remote is 0 if the function is being called
              from the "local" host (e.g. srun) or 1 from the "remote" host (slurmd).

       Plugin options may be registered with SLURM using the spank_option_register function. This
       function  is  only  valid  when  called  from  the  plugin's slurm_spank_init handler, and
       registers one option at a time. The prototype is

          spank_err_t spank_option_register (spank_t sp,
                    struct spank_option *opt);

       This function will return ESPANK_SUCCESS on  successful  registration  of  an  option,  or
       ESPANK_BAD_ARG  for  errors  including invalid spank_t handle, or when the function is not
       called from the slurm_spank_init function. All options need  to  be  registered  from  all
       contexts  in  which  they  will  be used. For instance, if an option is only used in local
       (srun) and remote (slurmd) contexts, then spank_option_register should only be called from
       within those contexts. For example:

          if (spank_context() != S_CTX_ALLOCATOR)
             spank_option_register (sp, opt);

       If,  however,  the  option  is used in all contexts, the spank_option_register needs to be
       called everywhere.

       In addition to spank_option_register, plugins may also export options to SLURM by defining
       a  table  of struct spank_option with the symbol name spank_options. This method, however,
       is not supported for use with sbatch and salloc  (allocator  context),  thus  the  use  of
       spank_option_register  is preferred. When using the spank_options table, the final element
       in the array must be filled with zeros. A SPANK_OPTIONS_TABLE_END  macro  is  provided  in
       <slurm/spank.h> for this purpose.

       When  an  option  is provided by the user on the local side, SLURM will immediately invoke
       the option's callback with remote=0. This is meant for  the  plugin  to  do  local  sanity
       checking  of  the option before the value is sent to the remote side during job launch. If
       the argument the user specified is invalid, the plugin should issue an error and  issue  a
       non-zero return code from the callback.

       On  the  remote  side, options and their arguments are registered just after SPANK plugins
       are loaded and before the spank_init handler is called.  This  allows  plugins  to  modify
       behavior  of  all  plugin functionality based on the value of user-provided options.  (See
       EXAMPLES below for a plugin that registers an option with SLURM).

CONFIGURATION

       The default SPANK plug-in stack configuration file is plugstack.conf in the same directory
       as   slurm.conf(5),   though   this   may  be  changed  via  the  SLURM  config  parameter
       PlugStackConfig.  Normally the plugstack.conf file should be identical on all nodes of the
       cluster.  The config file lists SPANK plugins, one per line, along with whether the plugin
       is required or optional, and any global arguments that are to be passed to the plugin  for
       runtime  configuration.  Comments are preceded with '#' and extend to the end of the line.
       If the configuration file is missing or empty, it will simply be ignored.

       The format of each non-comment line in the configuration file is:

         required/optional   plugin   arguments

        For example:

         optional /usr/lib/slurm/test.so

       Tells slurmd to load the plugin test.so passing  no  arguments.   If  a  SPANK  plugin  is
       required, then failure of any of the plugin's functions will cause slurmd to terminate the
       job, while optional plugins only cause a warning.

       If a fully-qualified path is not specified for a plugin,  then  the  currently  configured
       PluginDir in slurm.conf(5) is searched.

       SPANK  plugins  are  stackable,  meaning  that more than one plugin may be placed into the
       config file. The plugins will simply  be  called  in  order,  one  after  the  other,  and
       appropriate action taken on failure given that state of the plugin's optional flag.

       Additional  config  files or directories of config files may be included in plugstack.conf
       with the include keyword. The include keyword must appear on its own  line,  and  takes  a
       glob  as  its  parameter,  so  multiple  files  may be included from one include line. For
       example,   the   following   syntax    will    load    all    config    files    in    the
       /etc/slurm/plugstack.conf.d directory, in local collation order:

         include /etc/slurm/plugstack.conf.d/*

       which might be considered a more flexible method for building up a spank plugin stack.

       The  SPANK  config file is re-read on each job launch, so editing the config file will not
       affect running jobs. However care should be taken so that a partially edited  config  file
       is not read by a launching job.

EXAMPLES

       Simple SPANK config file:

       #
       # SPANK config file
       #
       # required?       plugin                     args
       #
       optional          renice.so                  min_prio=-10
       required          /usr/lib/slurm/test.so

       The  following is a simple SPANK plugin to modify the nice value of job tasks. This plugin
       adds a --renice=[prio] option to srun which users can use  to  set  the  priority  of  all
       remote  tasks.  Priority  may also be specified via a SLURM_RENICE environment variable. A
       minimum priority may be established via a  "min_prio"  parameter  in  plugstack.conf  (See
       above for example).

       /*
        *   To compile:
        *    gcc -shared -o renice.so renice.c
        *
        */
       #include <sys/types.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <string.h>
       #include <sys/resource.h>

       #include <slurm/spank.h>

       /*
        * All spank plugins must define this macro for the SLURM plugin loader.
        */
       SPANK_PLUGIN(renice, 1);

       #define PRIO_ENV_VAR "SLURM_RENICE"
       #define PRIO_NOT_SET 42

       /*
        *  Minimum allowable value for priority. May be set globally
        *   via plugin option min_prio=<prio>
        */
       static int min_prio = -20;

       static int prio = PRIO_NOT_SET;

       static int _renice_opt_process (int val, const char *optarg, int remote);
       static int _str2prio (const char *str, int *p2int);

       /*
        *  Provide a --renice=[prio] option to srun:
        */
       struct spank_option spank_options[] =
       {
           { "renice", "[prio]", "Re-nice job tasks to priority [prio].", 2, 0,
               (spank_opt_cb_f) _renice_opt_process
           },
           SPANK_OPTIONS_TABLE_END
       };

       /*
        *  Called from both srun and slurmd.
        */
       int slurm_spank_init (spank_t sp, int ac, char **av)
       {
           int i;

            /* Don't do anything in sbatch/salloc
             */
            if (spank_context () == S_CTX_ALLOCATOR)
                 return (0);

           for (i = 0; i < ac; i++) {
               if (strncmp ("min_prio=", av[i], 9) == 0) {
                   const char *optarg = av[i] + 9;
                   if (_str2prio (optarg, &min_prio) < 0)
                       slurm_error ("Ignoring invalid min_prio value: %s", av[i]);
               }
               else {
                   slurm_error ("renice: Invalid option: %s", av[i]);
               }
           }

           if (!spank_remote (sp))
               slurm_verbose ("renice: min_prio = %d", min_prio);

           return (0);
       }

       int slurm_spank_task_post_fork (spank_t sp, int ac, char **av)
       {
           pid_t pid;
           int taskid;

           if (prio == PRIO_NOT_SET) {
               /*
                *  See if SLURM_RENICE env var is set by user
                */
               char val [1024];

               if (spank_getenv (sp, PRIO_ENV_VAR, val, 1024) != ESPANK_SUCCESS)
                   return (0);

               if (_str2prio (val, &prio) < 0) {
                   slurm_error ("Bad value for %s: %s", PRIO_ENV_VAR, optarg);
                   return (-1);
               }

           if (prio < min_prio)
               slurm_error ("%s=%d not allowed, using min=%d",
                   PRIO_ENV_VAR, prio, min_prio);
           }

           if (prio < min_prio)
               prio = min_prio;

           spank_get_item (sp, S_TASK_GLOBAL_ID, &taskid);
           spank_get_item (sp, S_TASK_PID, &pid);

           slurm_info ("re-nicing task%d pid %ld to %ld", taskid, pid, prio);

           if (setpriority (PRIO_PROCESS, (int) pid, (int) prio) < 0) {
               slurm_error ("setpriority: %m");
               return (-1);
           }

           return (0);
       }

       static int _str2prio (const char *str, int *p2int)
       {
           long int l;
           char *p;

           l = strtol (str, &p, 10);
           if ((*p != ' ') || (l < -20) || (l > 20))
               return (-1);

           *p2int = (int) l;

           return (0);
       }

       static int _renice_opt_process (int val, const char *optarg, int remote)
       {
           if (optarg == NULL) {
               slurm_error ("renice: invalid argument!");
               return (-1);
           }

           if (_str2prio (optarg, &prio) < 0) {
               slurm_error ("Bad value for --renice: %s", optarg);
               return (-1);
           }

           if (prio < min_prio)
               slurm_error ("--renice=%d not allowed, will use min=%d",
                            prio, min_prio);

           return (0);
       }

COPYING

       Copyright  (C)  2006  The  Regents  of the University of California.  Produced at Lawrence
       Livermore National Laboratory (cf, DISCLAIMER).  CODE-OCEC-09-009. All rights reserved.

       This  file  is  part  of  SLURM,  a  resource  management  program.   For   details,   see
       <http://www.schedmd.com/slurmdocs/>.

       SLURM  is  free  software; you can redistribute it and/or modify it under the terms of the
       GNU General Public License as published by the Free Software Foundation; either version  2
       of the License, or (at your option) any later version.

       SLURM is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
       even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

FILES

       /etc/slurm/slurm.conf - SLURM configuration file.
       /etc/slurm/plugstack.conf - SPANK configuration file.
       /usr/include/slurm/spank.h - SPANK header file.

SEE ALSO

       srun(1), slurm.conf(5)