Slurm REST API

Slurm provides a REST API daemon named slurmrestd. This daemon is designed to allow clients to communicate with Slurm via a REST API (in addition to the command line interface (CLI) or C API).

Prerequisites

slurmrestd requires additional libraries for compilation:

Run modes

Slurmrestd currently supports two run modes: inet service mode and listening mode.

Inet Service Mode

The Slurmrestd daemon acts as an Inet Service treating STDIN and STDOUT as the client. This mode allows clients to use inetd, xinetd, or systemd socket activated services and avoid the need to run a daemon on the host at all times. This mode creates an instance for each client and does not support reusing the same instance for different clients.

Listening Mode

The Slurmrestd daemon acts as a full UNIX service and continuously listens for new TCP connections. Each connection is independently authenticated.

Configuration

slurmrestd can be configured either by environment variables or command line arguments. Please see the doc/man/man1/slurmrestd.1 man page for details.

IPv6 Support

Slurmrestd supports IPv6 clients. On dual stack systems, it will likely provide the source IP as an IPv6 IP for IPv4 clients . Slurmrestd must still be able to talk to slurmctld and slurmdbd via IPv4.

OpenAPI Specification (OAS)

Slurmrestd is compliant with OpenAPI 3.0.2 . The OAS can be viewed at the following URLs:

  • /openapi.json
  • /openapi.yaml
  • /openapi/v3

The OAS is designed to be the primary documentation for the request methods. There are several third party tools that automatically generate documentation against the OAS output listed by openapi.tools.

Security

The Slurm REST API is written to provide the necessary functionality for clients to control Slurm using REST commands. It is not designed to be directly internet facing. Only unencrypted and uncompressed HTTP communications are supported. Slurmrestd also has no protection against man in the middle or replay attacks. Slurmrestd should only be placed in a trusted network that will communicate with a trusted client.

JSON Web Token (JWT) Authentication

slurmrestd supports using JWT to authenticate users. JWT can be used to authenticate user over REST protocol.

  • User Name Header: X-SLURM-USER-NAME
  • JWT Header: X-SLURM-USER-TOKEN
SlurmUser or root can provide alternative user names to act as a proxy for the given user. While using JWT authentication, slurmrestd should be run as unique unprivileged user and group. slurmrestd should not be provided a SLURM_JWT environment variable at startup, but rather users should provide their own JWT tokens while authenticating to the proxy.

When using JWT, it is important that the "AuthType=auth/jwt" in slurm.conf for slurmrestd. It is suggested to use the following slurm.conf wrapper (adjust path as needed) to ensure slurmrestd is using JWT authentication.

include /etc/slurm/slurm.conf
AuthType=auth/jwt

Then to start slurmrestd with the wrapper slurm.conf:

env SLURM_CONF=$PATH_TO_WRAPPER_SLURM.CONF slurmrestd $ARGS

Local Authentication

slurmrestd supports using UNIX domain sockets to have the kernel authenticate local users. slurmrestd must be run as SlurmUser or root to allow multiple different users at the same time but it is not required if users wish to run as only themselves. Slurmrestd must be located in the Munge security domain in order to function and communicate with Slurm in local authentication mode.

Last modified 7 February 2020