SPANK

部分：Slurm 组件 (8)
更新：Slurm 组件
索引

名称

SPANK - Slurm 插件架构用于节点和作业 (K)控制

描述

本手册简要描述了 Slurm 插件架构用于节点和作业控制 (SPANK) 的功能，以及 SPANK 配置文件：（默认：plugstack.conf。）

SPANK 提供了一个非常通用的接口，用于可堆叠的插件，可以用于动态修改 Slurm 中的作业启动代码。SPANK 插件可以在没有访问 Slurm 源代码的情况下构建。它们只需与 Slurm 的 spank.h 头文件编译，并添加到 SPANK 配置文件 plugstack.conf 中，它们将在下次作业启动时运行时加载。因此，SPANK 基础设施为管理员和其他开发人员提供了一种低成本、低努力的能力，以动态修改 Slurm 作业启动的运行时行为。

注意：在将 Slurm 升级到新的主要版本时，所有 SPANK 插件都应重新编译。SPANK API 不保证在主要版本之间保持 ABI 兼容性。任何链接到 Slurm 库的 SPANK 插件都应仔细检查，因为 Slurm 的 API 和头文件可能会在主要版本之间发生变化。

SPANK 插件

SPANK 插件在 Slurm 作业期间最多在五个独立的上下文中加载。简而言之，这五个上下文是：

local: 在 local 上下文中，插件由 srun 加载。（即并行作业的“本地”部分）。

remote: 在 remote 上下文中，插件由 slurmstepd 加载。（即并行作业的“远程”部分）。

allocator: 在 allocator 上下文中，插件在作业分配工具 salloc、sbatch 或 scrontab 中加载。

slurmd: 在 slurmd 上下文中，插件在 slurmd 守护进程本身中加载。注意：在 slurmd 上下文中加载的插件在 slurmd 运行的整个时间内持续存在，因此如果配置发生更改或插件更新，则必须重新启动 slurmd 以使更改生效。

job_script: 在 job_script 上下文中，插件在作业前置或后置脚本的上下文中加载。注意：在每次运行作业前置或后置脚本时，插件在 job_script 上下文中加载，处于与 slurmd 上下文中的插件不同的地址空间。这意味着此上下文与其他上下文之间没有共享状态，甚至在对 slurm_spank_job_prolog 或 slurm_spank_job_epilog 的一次调用与后续调用之间也没有共享状态。

在本地上下文中，仅调用 init、exit、init_post_opt 和 local_user_init 函数。在分配器上下文中，仅调用 init、exit 和 init_post_opt 函数。类似地，在 slurmd 上下文中，仅激活 init 和 slurmd_exit 回调，而在 job_script 上下文中，仅使用 job_prolog 和 job_epilog 回调。插件可以使用在 spank.h 中定义的 spank_context 和 spank_remote 函数查询它们正在运行的上下文。

SPANK 插件可以在 Slurm 作业启动期间从多个点调用。插件可以定义以下函数：

slurm_spank_init: 在插件加载后立即调用。在远程上下文中，这在作业步骤初始化后立即调用。此函数在任何插件选项处理之前调用。

slurm_spank_job_prolog: 在作业前置脚本同时调用。如果此函数返回非零值，并且包含它的 SPANK 插件在 plugstack.conf 中是必需的，则运行此函数的节点将被排空。

slurm_spank_init_post_opt: 在 slurm_spank_init 的同一点调用，但在处理完所有用户选项后调用。init 和 init_post_opt 回调分开的原因是为了让插件可以在 init 回调中处理在 plugstack.conf 中指定的系统范围选项，然后处理用户选项，并在必要时在 slurm_spank_init_post_opt 中采取一些行动。在异构作业的情况下，slurm_spank_init 每个作业组件调用一次。

slurm_spank_local_user_init: 仅在所有选项处理后在本地（srun）上下文中调用。此时作业 ID 和步骤 ID 可用。这发生在 srun 中，在分配完成后，但在任务启动之前。

slurm_spank_user_init: 在特权暂时被剥夺后调用。（仅限远程上下文）

slurm_spank_task_init_privileged: 在每个任务刚 fork 后调用，但在所有提升的特权被剥夺之前。（仅限远程上下文）

slurm_spank_task_init: 在每个任务 execve (2) 之前调用。如果您使用 cgroups 限制内存，则在此处分配的内存将位于作业的 cgroup 中。（仅限远程上下文）

slurm_spank_task_post_fork: 在父进程完成 fork (2) 后为每个任务调用。由于 slurmd 在所有任务完成 fork (2) 之前不执行任何任务，因此此调用保证在用户任务执行之前运行。（仅限远程上下文）

slurm_spank_task_exit: 在 Slurm 收集每个任务的退出状态时调用。（仅限远程上下文）

slurm_spank_exit: 在远程上下文中，在 slurmstepd 退出之前调用。在本地上下文中，在 srun 退出之前调用。

slurm_spank_job_epilog: 在作业后置脚本同时调用。如果此函数返回非零值，并且包含它的 SPANK 插件在 plugstack.conf 中是必需的，则运行此函数的节点将被排空。

slurm_spank_slurmd_exit: 在 slurmd 关闭时调用。

所有这些函数具有相同的原型，例如：

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

其中 spank 是必须在插件调用 spank_get_item 和 spank_getenv 函数时传递回 Slurm 的 SPANK 句柄。配置参数（见下文的 CONFIGURATION）通过参数向量 argv 传递，参数计数为 ac。

插件还可以定义以下变量，供 Slurm 使用：

slurm_spank_init_failure_mode

当 slurm_spank_init 调用失败时，改变 Slurm 处理该失败的方式。识别的值有：

ESPANK_NODE_FAILURE: Slurm 认为节点有故障并将其标记为排空。作业可能会被重新排队。这是默认值。

ESPANK_JOB_FAILURE: Slurm 认为作业有故障并将其标记为失败（不再排队）。节点将不会被排空。

SPANK 插件可以查询当前支持的 slurm_spank 符号列表，以确定当前版本是否支持给定的插件钩子。这可能是有用的，因为插件符号的列表可能会在将来增加。查询是通过 spank_symbol_supported 函数完成的，该函数具有以下原型：

    int spank_symbol_supported (const char *sym);

返回值为 1 表示符号受支持，0 表示不受支持。

SPANK 插件没有直接访问内部定义的 Slurm 数据结构的权限。相反，有关当前执行作业的信息是通过 spank_get_item 函数调用获得的。

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

spank_get_item 调用必须传递当前的 SPANK 句柄以及请求的项，由传递的 spank_item_t 定义。还根据插件请求的项传递可变数量的指针参数。有效的 item 值的列表保存在 spank.h 头文件中。一些示例包括：

S_JOB_UID: 正在运行作业的用户 ID。（uid_t *）是 spank_get_item 的第三个参数

S_JOB_STEPID: 正在运行作业的作业步骤 ID。（uint32_t *）是 spank_get_item 的第三个参数。

S_TASK_EXIT_STATUS: 已退出任务的退出状态。仅在 slurm_spank_task_exit 中有效。（int *）是 spank_get_item 的第三个参数。

S_JOB_ARGV: 完整的作业命令行。第三和第四个参数为 spank_get_item 是（int *, char ***）。

有关更多详细信息，请参见 spank.h。

SPANK 函数在 local 和 allocator 环境中应使用 getenv、setenv 和 unsetenv 函数来查看和修改作业的环境。 SPANK 函数在 remote 环境中应使用 spank_getenv、spank_setenv 和 spank_unsetenv 函数来查看和修改作业的环境。spank_getenv 在作业的环境中搜索环境变量 var 并将当前值复制到长度为 len 的缓冲区 buf 中。spank_setenv 允许 SPANK 插件在作业的环境中设置或覆盖变量，而 spank_unsetenv 则在作业的环境中取消设置环境变量。原型为：

 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);

这些仅在远程上下文中是必要的，因为在本地上下文中可以使用 setenv (3)、getenv (3) 和 unsetenv (3) 修改标准进程环境。

还可以在 SPANK 插件中提供函数，以建立要导出到 Slurm 的环境变量 PrologSlurmctld、Prolog、Epilog 和 EpilogSlurmctld 程序（即所谓的 作业控制 环境）。这些调用建立的环境变量的名称将以字符串 SPANK_ 为前缀，以避免任意环境变量控制的任何安全隐患。（毕竟，作业控制脚本确实以 root 或 Slurm 用户身份运行。）。

这些函数仅在 local 上下文中可用。

  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);

有关更多信息，请参见 spank.h。

许多可用于插件的 SPANK 函数通过 spank_err_t 错误类型返回错误。成功时，返回值将设置为 ESPANK_SUCCESS，而在失败时，返回值将设置为 spank.h 中定义的多个错误值之一。SPANK 接口提供了一个简单的函数

  const char * spank_strerror(spank_err_t err);

可以用来将 spank_err_t 值转换为其字符串表示。

slurm_spank_log 函数可用于以错误级别向用户打印消息。这是为了让用户不必依赖 slurm_error 函数，因为它会在每条消息前加上“错误：”。

SPANK 选项

SPANK 插件还具有一个接口，通过该接口可以定义和实现额外的作业选项。这些选项通过 Slurm 命令提供给用户，例如 srun(1)、salloc(1) 和 sbatch(1)。如果用户指定了该选项，则其值将在作业运行时转发并在 slurmd 中注册。通过这种方式，SPANK 插件可以动态提供新的选项和功能给 Slurm。

每个插件注册到 Slurm 的选项的形式为 struct spank_option，该结构在 spank.h 中声明为

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

其中

name

是选项的名称。其长度限制为 SPANK_OPTION_MAXLEN，该值在 spank.h 中定义。

arginfo

是对选项参数的描述（如果该选项确实需要参数）。

usage

是适合 --help 输出的选项简短描述。

has_arg

如果选项不需要参数，则为 0；如果选项需要参数，则为 1；如果选项需要可选参数，则为 2。（见 getopt_long (3)）。

val

要返回给选项回调函数的插件本地值。

cb

在插件选项注册到 Slurm 时调用的回调函数。spank_opt_cb_f 在 spank.h 中被定义为

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

其中 val 是 spank_option 结构中 val 字段的值，optarg 是提供的参数（如果适用），而 remote 是 0 表示函数是从“本地”主机（例如，调用 srun 或 sbatch/salloc 的主机）调用的，或 1 表示从“远程”主机（运行 slurmd/slurmstepd 的主机）调用，但仅在该选项为此上下文注册时由 slurmstepd 执行。

插件选项可以使用 spank_option_register 函数注册到 Slurm。此函数仅在从插件的 slurm_spank_init 处理程序调用时有效，并一次注册一个选项。原型为

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

此函数在成功注册选项时将返回 ESPANK_SUCCESS，在出现错误时返回 ESPANK_BAD_ARG，包括无效的 spank_t 句柄，或当该函数未从 slurm_spank_init 函数调用时。所有选项都需要在它们将被使用的所有上下文中注册。例如，如果选项仅在本地（srun）和远程（slurmd）上下文中使用，则 spank_option_register 应仅在这些上下文中调用。例如：

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

但是，如果该选项在所有上下文中使用，则需要在所有地方调用 spank_option_register。

除了 spank_option_register，插件还可以通过定义 struct spank_option 的表来将选项导出到 Slurm，表的符号名称为 spank_options。但是，此方法不支持与 sbatch 和 salloc（分配器上下文）一起使用，因此建议使用 spank_option_register。使用 spank_options 表时，数组中的最后一个元素必须填充为零。SPANK_OPTIONS_TABLE_END 宏在 spank.h 中提供，用于此目的。

当用户在本地侧提供选项时，无论是通过命令行选项还是通过环境变量，Slurm 将立即调用选项的回调，remote=0。这是为了让插件在将值发送到远程侧进行作业启动之前对选项进行本地有效性检查。如果用户指定的参数无效，插件应发出错误并从回调中返回非零返回代码。插件应能够处理通过环境变量和命令行选项多次设置 spank 选项的情况。环境变量在命令行选项之前处理。

在远程侧，选项及其参数在 SPANK 插件加载后、spank_init 处理程序调用之前注册。这允许插件根据用户提供的选项的值修改所有插件功能的行为。

作为使用选项回调和全局变量的替代，插件可以使用 spank_option_getopt 选项在选项处理后检查提供的选项。此函数的原型为：

   spank_err_t spank_option_getopt(spank_t sp,
       struct spank_option *opt, char **optargp);

如果结构 spank_option opt 中定义的选项已被用户使用，则此函数返回 ESPANK_SUCCESS。如果 optargp 非 NULL，则设置为传递的任何选项参数（如果该选项需要参数）。此方法在 job_script 上下文中处理选项时是必需的（slurm_spank_job_prolog 和 slurm_spank_job_epilog）。此函数在以下上下文中有效：slurm_spank_job_prolog、slurm_spank_local_user_init、slurm_spank_user_init、slurm_spank_task_init_privileged、slurm_spank_task_init、slurm_spank_task_exit 和 slurm_spank_job_epilog。

配置

默认的 SPANK 插件堆栈配置文件为与 slurm.conf(5) 位于同一目录下的 plugstack.conf，但可以通过 Slurm 配置参数 PlugStackConfig 更改。通常，plugstack.conf 文件应在集群的所有节点上相同。配置文件列出了 SPANK 插件，每行一个，以及插件是否为必需或可选，以及要传递给插件的任何全局参数以进行运行时配置。注释以 '#' 开头，并延伸到行尾。如果配置文件缺失或为空，将被忽略。

注意：SPANK 插件需要安装在执行 slurmd（计算节点）的机器上，以及在执行作业分配工具如 salloc、sbatch 等（登录节点）的机器上。

配置文件中每个非注释行的格式为：

  required/optional   plugin   arguments

例如：

  optional /usr/lib/slurm/test.so

告诉 slurmd 加载插件 test.so，不传递任何参数。如果 SPANK 插件是必需，则任何插件函数的失败将导致 slurmd 或作业分配命令终止作业，而可选插件只会导致警告。

如果未为插件指定完全限定的路径，则将在 slurm.conf(5) 中搜索当前配置的 PluginDir。

SPANK 插件是可堆叠的，这意味着可以将多个插件放入配置文件中。插件将按顺序依次调用，并根据插件的可选标志的状态采取适当的措施。

可以使用 include 关键字在 plugstack.conf 中包含其他配置文件或配置文件目录。include 关键字必须单独出现在一行上，并以 glob 作为其参数，因此可以从一个 include 行中包含多个文件。例如，以下语法将加载 /etc/slurm/plugstack.conf.d 目录中的所有配置文件，按本地排序顺序：

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

这可能被认为是构建 spank 插件堆栈的更灵活的方法。

SPANK 配置文件在每次作业启动时重新读取，因此编辑配置文件不会影响正在运行的作业。但是应注意，不要让正在编辑的部分配置文件被启动的作业读取。

错误

当 SPANK 插件返回非零结果时，将导致以下更改：

命令	功能	上下文	退出代码	排空节点	失败作业
srun	slurm_spank_init	本地	1	否	是
srun	slurm_spank_init_post_opt	本地	1	否	是
srun	slurm_spank_local_user_init	本地	1	否	是
srun	slurm_spank_init	远程	1	否	否
srun	slurm_spank_user_init	远程	0	否	否
srun	slurm_spank_task_init_privileged	远程	1	否	是
srun	slurm_spank_task_post_fork	远程	0	否	否
srun	slurm_spank_task_init	远程	1	否	是
srun	slurm_spank_task_exit	远程	0	否	否
srun	slurm_spank_exit	本地	0	否	是

salloc	slurm_spank_init	分配器	1	否	是
salloc	slurm_spank_init_post_opt	分配器	1	否	是
salloc	slurm_spank_init	远程	1	否	否
salloc	slurm_spank_user_init	远程	1	否	是
salloc	slurm_spank_task_init_privileged	远程	1	否	是
salloc	slurm_spank_task_post_fork	远程	1	否	是
salloc	slurm_spank_task_init	远程	1	否	是
salloc	slurm_spank_task_exit	远程	0	否	否
salloc	slurm_spank_exit	分配器	0	否	是

sbatch	slurm_spank_init	分配器	1	否	是
sbatch	slurm_spank_init_post_opt	分配器	1	否	是
sbatch	slurm_spank_init	远程	1	是	否
sbatch	slurm_spank_user_init	远程	1	是	是
sbatch	slurm_spank_task_init_privileged	远程	1	否	是
sbatch	slurm_spank_task_post_fork	远程	1	是	是
sbatch	slurm_spank_task_init	远程	1	否	是
sbatch	slurm_spank_task_exit	远程	0	否	否
sbatch	slurm_spank_exit	分配器	0	否	否

scrontab	slurm_spank_init	分配器	1	否	否
scrontab	slurm_spank_exit	分配器	0	否	否

注意：ProctrackType=proctrack/pgid 的行为可能会导致在失败时 slurm_spank_task_post_fork 的 remote 上下文超时。

版权

此文件是 Slurm 的一部分，资源管理程序。有关详细信息，请参见 <https://slurm.schedmd.com/>。

Slurm 是自由软件；您可以根据自由软件基金会发布的 GNU 通用公共许可证的条款重新分发和/或修改它；许可证的第 2 版，或（根据您的选择）任何更高版本。

Slurm 的分发希望它能有用，但不提供任何担保；甚至没有适销性或特定用途适用性的隐含担保。有关详细信息，请参见 GNU 通用公共许可证。

文件

/etc/slurm/slurm.conf - Slurm 配置文件。
/etc/slurm/plugstack.conf - SPANK 配置文件。
/usr/include/slurm/spank.h - SPANK 头文件。

另见

srun(1)、slurm.conf(5)

此文档由 man2html 使用手册页创建。
时间：2025年7月2日 13:21:55 GMT