# SLURM Job Submit Plugin API

## Overview

This document describes SLURM job submit plugins and the API that defines them. It is intended as a resource to programmers wishing to write their own SLURM job submit plugins. This is version 100 of the API.

SLURM job submit plugins must conform to the SLURM Plugin API with the following specifications:

const char plugin_name[]="full text name"

A free-formatted ASCII text string that identifies the plugin.

const char plugin_type[]="major/minor"

The major type must be "job_submit." The minor type can be any suitable name for the type of accounting package. We include samples in the SLURM distribution for

- all_partitions—Set default partition to all partitions on the cluster.
- defaults—Set default values for job submission or modify requests.
- logging—Log select job submission and modification parameters.
- lua—Interface to Lua scripts implementing these functions (actually a slight variation of them). Sample Lua scripts can be found with the SLURM distribution in the directory contribs/lua. The default installation location of the Lua scripts is the same location as the SLURM configuration file, slurm.conf.
- partition—Sets a job's default partition based upon job submission parameters and available partitions.

SLURM can be configured to use multiple job_submit plugins if desired, however the lua plugin will only execute one lua script named "job_submit.lua" and located in default script directory (typically the subdirectory "etc" of the installation directory).

## API Functions

All of the following functions are required. Functions which are not implemented must be stubbed.

int job_submit(struct job_descriptor *job_desc, uint32_t submit_uid)

Description:
This function is called by the slurmctld daemon with job submission parameters supplied by the salloc, sbatch or srun command. It can be used to log and/or modify the job parameters supplied by the user as desired. Note that this function has access to the slurmctld's global data structures, for example to examine the available partitions, reservations, etc.

Arguments:
job_desc (input/output) the job allocation request specifications.
submit_uid (input) user ID initiating the request.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int job_modify(struct job_descriptor *job_desc, struct job_record *job_ptr, uint32_t submit_uid)

Description:
This function is called by the slurmctld daemon with job modification parameters supplied by the scontrol or sview command. It can be used to log and/or modify the job parameters supplied by the user as desired. Note that this function has access to the slurmctld's global data structures, for example to examine the available partitions, reservations, etc.

Arguments:
job_desc (input/output) the job allocation request specifications.
job_ptr (input/output) slurmctld daemon's current data structure for the job to be modified.
submit_uid (input) user ID initiating the request.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

## Lua Functions

The Lua functions differ slightly from those implemented in C for better ease of use. Sample Lua scripts can be found with the SLURM distribution in the directory contribs/lua. The default installation location of the Lua scripts is the same location as the SLURM configuration file, slurm.conf.

int job_submit(struct job_descriptor *job_desc, List part_list)

Description:
This function is called by the slurmctld daemon with job submission parameters supplied by the salloc, sbatch or srun command. It can be used to log and/or modify the job parameters supplied by the user as desired. Note that this function has access to the slurmctld's global data structures, for example to examine the available partitions, reservations, etc.

Arguments:
job_desc (input/output) the job allocation request specifications.
part_list (input) List of pointer to partitions which this user is authorized to use.

Returns:
0 on success, or an errno on failure. SLURM specific error numbers from slurm/slurm_errno.h may be used. On failure, the request will be rejected and the user will have an appropriate error message printed for that errno.

int job_modify(struct job_descriptor *job_desc, struct job_record *job_ptr, List part_list)

Description:
This function is called by the slurmctld daemon with job modification parameters supplied by the scontrol or sview command. It can be used to log and/or modify the job parameters supplied by the user as desired. Note that this function has access to the slurmctld's global data structures, for example to examine the available partitions, reservations, etc.

Arguments:
job_desc (input/output) the job allocation request specifications.
job_ptr (input/output) slurmctld daemon's current data structure for the job to be modified.
part_list (input) List of pointer to partitions which this user is authorized to use.
0 on success, or an errno on failure. SLURM specific error numbers from slurm/slurm_errno.h may be used. On failure, the request will be rejected and the user will have an appropriate error message printed for that errno.

## Versioning

This document describes version 100 of the SLURM Job Submission API. Future releases of SLURM may revise this API.

Last modified 16 January 2013