namespace.yaml(5)

💅 namespace.yaml — the config file that runs the namespace/linux plugin 💅

So this is the manual page for namespace.yaml(5) from the Slurm Configuration File section, and honestly? It's a whole vibe once you get it. Sit with me, bestie 🫶

---

🌸 NAME 🌸

namespace.yaml — literally the Slurm configuration file for the namespace/linux plugin. That's it, that's the name, iconic.

---

✨ DESCRIPTION ✨

namespace.yaml is a YAML-formatted config file, and it defines the parameters that Slurm's namespace/linux plugin uses. Based on those parameters, the plugin creates the appropriate job-specific namespace(s) for you. No cap. 💖

Here's what it can actually do: the namespace/linux plugin can create a filesystem namespace, and it'll construct a private (or, if you want, shared) filesystem namespace and mount a list of directories inside it — defaults to /tmp and /dev/shm — which gives the job a private view of those directories. Those paths get mounted inside the location specified by base_path in the namespace.yaml file. And on top of all that, it can also create new User and PID namespaces for the job. Like, it's doing the most and we love it for that. 👑

When the job completes, the namespace is unmounted and every file inside it is automatically removed. Cleanup queen behavior, honestly. 🧹✨

Now — to actually make use of these plugins, PrologFlags=Contain must also be present in your slurm.conf file, like so:

NamespaceType=namespace/linux
PrologFlags=Contain

Bestie, do not skip that part. No PrologFlags=Contain, no containment. It's giving mandatory. 💀

The file will always live in the same directory as the slurm.conf.

Also, to say it twice because it matters: the file must be located in the same directory as slurm.conf. Any text following a # in this file is treated as a comment all the way through the end of that line. And changes to the configuration file take effect upon restart of Slurm daemons — not on reconfigure, we'll get to that. 🙈

---

🎀 PARAMETERS 🎀

namespace.yaml contains the following attributes:

• defaults — the default namespace configuration. If you specify it, it contains the fields described in options.
• disable_bpf_token — if you specify this, it disables the use of bpf tokens in the namespace plugin. Now listen: using this option when ConstrainDevices is set in the cgroup.conf file will result in devices only being constrained at the job level — individual steps won't actually be constrained if they request fewer devices than the job does. This will also permit ConstrainDevices to work on kernels where bpf tokens are not available. So like, tradeoffs, yk? 🦋
• node_confs — a list of node namespace configurations. The list element attributes are described below, keep scrolling.

🌈 node_confs list element definitions 🌈

Each node_confs element contains the following attributes:

• nodes — list of node names the options will be applied to.
• options — namespace configuration options. Any options you specify here will override those set by defaults.

👑 options definitions 👑

options contains the following attributes:

• auto_base_path — this determines if the plugin should create the BasePath directory or not. Set it to 'true' if the directory isn't pre-created before slurm startup. If set to true, the directory is created with permission 0755. The directory is not deleted during slurm shutdown. If set to 'false' or just not specified, the plugin would expect the directory to already exist. This option can be used on a global or per-line basis. When dir_confs is set, any per-directory base_path entries in dir_confs are also created. This parameter is optional.
• base_path — specify the PATH that the namespace plugin should use as a base to mount the private directories. This path must be readable and writable by the plugin. The plugin constructs a directory for each job inside this path, which is then used for mounting. The base_path gets mounted as 'private' during slurmd start and remains mounted until shutdown. The first "%h" within the name is replaced with the hostname on which the slurmd is running. The first "%n" within the name is replaced with the Slurm node name on which the slurmd is running. Set PATH to 'none' to disable the namespace/linux plugin on node subsets when there's a global setting in defaults.

NOTE: The base_path must be unique to each node. If base_path is on a shared filesystem, you can use "%h" or "%n" to create node-unique directories.

NOTE: The base_path parameter cannot be set to any of the paths specified by dirs. Using these directories will cause conflicts when trying to mount and unmount the private directories for the job. So don't. 🙅‍♀️

• clone_ns_script — specify the fully qualified pathname of an optional initialization script. This script runs after the namespace construction of a job. This script will be provided the SLURM_NS environment variable containing the path to the namespace that can be used by the nsenter command. This variable lets the script join the newly created namespace and do further setup work. This parameter is optional. ✨
• clone_ns_script_wait — the number of seconds to wait for the clone_ns_script to complete before considering the script failed. The default value is 10 seconds.
• clone_ns_epilog — specify the fully qualified pathname of an optional epilog script. This script runs just before the namespace is torn down. This script will be provided the SLURM_NS environment variable containing the path to the namespace that can be used by the nsenter command. This variable lets the script join the soon-to-be-removed namespace and do any cleanup work. This parameter is optional. 🧚
• clone_ns_epilog_wait — the number of seconds to wait for the clone_ns_epilog to complete before considering the script failed. The default value is 10 seconds.
• clone_ns_flags — this contains a list of string flag values. This parameter defines what additional namespaces should be created for the job. Valid values are "CLONE_NEWPID" and "CLONE_NEWUSER" to create new PID and USER namespaces respectively. "CLONE_NEWNS" will also be accepted, but it's always on anyway. NOTE: When CLONE_NEWUSER is specified, bpf token support is also required if you're using ConstrainDevices in cgroup.conf.
• dirs — a comma-separated list of directories to create private mount points for. This parameter is optional, and if it's not specified it defaults to "/tmp,/dev/shm". Mutually exclusive with dir_confs. If both are set, dir_confs will take precedence.

NOTE: /dev/shm has special handling — instead of a bind mount it's always a fresh tmpfs filesystem.

NOTE: When CLONE_NEWPID is specified, a unique /proc filesystem for the container will be mounted automatically. Cute, right? 🌸

• dir_confs — a structured list of per-directory mount configurations. Each entry specifies a path, optional per-directory backing storage, and optional mount options. When set, it supersedes dirs. The list element attributes are described in the dir_confs list element definitions below. This parameter is optional.
• init_script — specify the fully qualified pathname of an optional initialization script. This script runs before the namespace construction of a job. It can be used to make the job join additional namespaces prior to the construction of the /tmp namespace, or it can be used for any site-specific setup. This parameter is optional.
• shared — specifying Shared=true will propagate new mounts between the job-specific filesystem namespace and the root filesystem namespace, enabling the use of autofs on the node. This parameter is optional.
• user_ns_script — specifies the location of a script that will perform the user namespace setup. This script runs first when setting up the namespace. The environment variable "SLURM_NS_PID" is provided to allow constructing the path to the various map files that this script could write to. If it's not specified, every user and group will be mapped.

🦋 dir_confs list element definitions 🦋

Each dir_confs element contains the following attributes:

• path — the target directory to mount privately, e.g. "/tmp". The following substitutions are supported: %j (job ID), %S (SLUID), and %u (username). This parameter is required. Don't skip it, bestie. 💅
• base_path — optional per-directory backing storage root. It overrides the global base_path for this mount. A job-specific subdirectory will be created here to back the private mount. Ignored when tmpfs is set. This parameter is optional.
• options — comma-separated list of mount options. Support is included to pass the following options to the mount command:
  • noatime — do not update inode access times on this filesystem.
  • nodev — do not interpret character or block special devices on the filesystem.
  • nodiratime — do not update directory inode access times on this filesystem.
  • noexec — do not permit direct execution of any binaries on the mounted filesystem.
  • nosuid — do not honor set-user-ID and set-group-ID bits or file capabilities when executing programs from this filesystem.
  • relatime — update inode access times relative to modify or change time.
  • ro — mount the filesystem read-only.

For tmpfs mounts, additional data options such as size=4g and mode=1777 may also be specified and are passed directly to the kernel. Options not recognized as flags are treated as tmpfs mount data and silently ignored on bind mounts. This parameter is optional. 🙈

NOTE: tmpfs mounts always have nosuid and nodev applied regardless of this setting. Yeah, even if you didn't ask. That's just how it is. 💀

• tmpfs — if set to true, mounts a fresh tmpfs at this path instead of creating a bind mount backed by the base_path. This parameter is optional.

---

⭐ NOTES ⭐

If any parameters in namespace.yaml are changed while slurm is running, then slurmd on the respective nodes will need to be restarted for the changes to take effect (scontrol reconfigure is not sufficient, sorry bestie 😭). Additionally, this can be disruptive to jobs already running on the node. So care must be taken to make sure no jobs are running if any changes to namespace.yaml are deployed. Fr fr.

Restarting slurmd is safe and non-disruptive to running jobs — as long as namespace.yaml is not changed between restarts, in which case the above point applies. 🌈

🌈 EXAMPLE 💖

okay bestie, here's a full-ass example that just... ate. look at it. study it. it's giving "everything everywhere all at once" but for namespace configs ✨

---
defaults:
  auto_base_path: true
  base_path: "/var/nvme/storage_0"
  clone_ns_flags:
    - "CLONE_NEWPID"
    - "CLONE_NEWUSER"
    - "CLONE_NEWNS"
  clone_ns_epilog: "/path/to/epilog_script"
  clone_ns_epilog_wait: 10
  clone_ns_script: "/path/to/ns_script"
  init_script: "/path/to/init_script"
  shared: true
node_confs:
  - nodes:
    - "n1"
    - "n[2-4,6]"
    options:
      auto_base_path: true
      base_path: "/var/nvme/storage_1"
      clone_ns_script_wait: 20
      dir_confs:
        - path: "/tmp"
          options: "noexec,nosuid,size=8g"
          tmpfs: true
        - path: "/scratch"
          base_path: "/var/nvme/storage_1"
          options: "noexec,nosuid"
      shared: false
      user_ns_script: "/path/to/user_script"
  - nodes:
    - "n[7-10]"
    options:
      auto_base_path: true
      base_path: "/var/nvme/storage_2"
      init_script: "/etc/slurm/init.sh"

so what's happening here, bestie? the defaults block is the main character, setting the vibe for everyone 🌸 — auto_base_path: true, base_path: "/var/nvme/storage_0", the whole clone_ns_flags trio ("CLONE_NEWPID", "CLONE_NEWUSER", "CLONE_NEWNS"), plus clone_ns_epilog: "/path/to/epilog_script", clone_ns_epilog_wait: 10, clone_ns_script: "/path/to/ns_script", init_script: "/path/to/init_script" and shared: true.

then node_confs comes in and does its own thing per node group 💅 — first group is "n1" and "n[2-4,6]", and those are not getting the same treatment. they get their own base_path: "/var/nvme/storage_1", a clone_ns_script_wait: 20, shared: false, a user_ns_script: "/path/to/user_script", and a whole little dir_confs moment:

• one for /tmp with options: "noexec,nosuid,size=8g" and tmpfs: true
• one for /scratch with base_path: "/var/nvme/storage_1" and options: "noexec,nosuid"

and then the second group — the "n[7-10]" girlies — get auto_base_path: true, base_path: "/var/nvme/storage_2" and init_script: "/etc/slurm/init.sh". iconic. no notes. 👑

---

💜 COPYING 💜

Copyright (C) 2025 SchedMD LLC.

This file is part of Slurm, a resource management program. For details, see <https://slurm.schedmd.com/>.

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.

fr fr, read the license, it's not a vibe suggestion 😭 legal girlies stay winning.

---

👀 SEE ALSO 🫶

• slurm.conf(5)

---

and that's a wrap bestie 💖 this was Slurm 26.05, a Slurm Configuration File, filed under namespace.yaml(5) — go forth, configure your namespaces, and slay ✨🦋🌸