GROUPS.CONF(5)

🎀 NAME 🎀

groups.conf — the configuration file that tells ClusterShell all about node groups. bestie, this is where the magic lives 💖

---

✨ DESCRIPTION ✨

okay so here's the tea: the ClusterShell library goes hunting for its node groups configuration in a bunch of places, and it has OPINIONS about the order. Decreasing order of precedence, bestie, meaning the first one it finds wins:

1. $CLUSTERSHELL_CFGDIR/groups.conf (only used when $CLUSTERSHELL_CFGDIR is defined)
2. user configuration file ($XDG_CONFIG_HOME/clustershell/groups.conf, defaults to $HOME/.config/clustershell/groups.conf)
3. Python virtual environment ({sys.prefix}/etc/clustershell/groups.conf)
4. local pip user installation ($HOME/.local/etc/clustershell/groups.conf)
5. system-wide configuration file (/etc/clustershell/groups.conf)

For each parameter, the first obtained value is the one that gets used. periodt. And if no groups.conf is found anywhere at all? Group support is just… disabled. it's giving silence 😭

Additional configuration files also get read from the directories set by the confdir option, if it's present. Scroll down to the confdir option below for the whole lore.

Configuration files are formatted in the style of RFC 822 and can be made up of several sections that may appear in any order. There are exactly two types of sections: Main and Group_source:

• Main — global configuration options. There should be only one Main section, she's the main character 👑
• Group_source — the Group_source section(s) define the configuration for each node group source (or namespace). This configuration is made of external command definitions (map, mapall, all, list and reverse).

And heads up: only Group_source section(s) are allowed in additional configuration files. no Main sections sneaking into the extras, okay? 🙈

---

💅 [Main] OPTIONS 💅

Here are the configuration parameters of the Main section, explained with love:

• default — specifies the default group source (group namespace) used by the NodeSet parser when the user doesn't explicitly specify the group source (like "@io"). the default default, if you will ✨
• confdir — optional list of directories where the ClusterShell library should look for .conf files that define group sources to use. Each file in these directories with the .conf suffix should contain one or more Group_source sections, as documented in the [Group_source] options below. These get merged with the group sources defined in /etc/clustershell/groups.conf to form the complete set of group sources that ClusterShell will use. Duplicate Group_source sections are not allowed. Note: .conf files that aren't readable by the current user are ignored (except the one that defines the default group source). The variable $CFGDIR is replaced by the path of the highest priority configuration directory found (where groups.conf resides). The default confdir value enables both system-wide and any installed user configuration (thanks to $CFGDIR 🫶). Duplicate directory paths are ignored. Also groupsdir is accepted as an alias for confdir and takes precedence when both are defined — she's the understudy who got the part 💅
• autodir — optional list of directories where the ClusterShell library should look for .yaml files that define in-file group dictionaries. No need to call external commands for these files, they're parsed by the ClusterShell library itself (so efficient, we love that 🧚). Multiple group source definitions in the same file are supported. The variable $CFGDIR is replaced by the path of the highest priority configuration directory found (where groups.conf resides). The default autodir value enables both system-wide and any installed user configuration (thanks to $CFGDIR). Duplicate directory paths are ignored.

---

🌸 [Group_source] OPTIONS 🌸

And these are the configuration parameters of each group source section:

• map — specify the external shell command used to resolve a group name into a nodeset, list of nodes or list of nodeset (separated by space characters or by carriage returns). The variable $GROUP is replaced before executing the command. Either map or mapall must be defined. (yes, one of them, no skipping 🚨)
• mapall — optional external shell command that should return all group-to-nodes mappings for this group source in a single call, one group: nodes line per group. Super useful when the source can dump all its groups at once (e.g. with sinfo or ansible-inventory --list), because a single call then serves both map and list queries from the cache. mapall output takes precedence over the list upcall. If map is also defined, it's used as a fallback for groups missing from the mapall output (or all groups if caching is disabled); otherwise, missing groups resolve to an empty nodeset. The first : on each line separates the group name from the nodes, so group names must be single words without :. Duplicate group lines are merged. A malformed output line makes the whole mapall call fail (nothing is cached and the next query retries), and a failing mapall command does not fall back to map. no partial credit, she's strict 💀
• all — optional external shell command that should return a nodeset, list of nodes or list of nodeset of all nodes for this group source. If it's not specified, the library will try to resolve all nodes by using the list external command in the same group source followed by map for each group. resourceful queen ✨
• list — optional external shell command that should return the list of all groups for this group source (separated by space characters or by carriage returns). Not used when mapall is defined, unless caching is disabled.
• reverse — optional external shell command used to find the group(s) of a single node. The variable $NODE is replaced beforehand. If this upcall isn't specified, the reverse operation is computed in memory by the library from the list and map external calls. Also, if the number of nodes to reverse is greater than the number of available groups, the reverse external command is avoided automatically. smart, honestly 🧠
• cache_time — number of seconds each upcall result is kept in cache, in memory only. Default is 3600 seconds. This is useful only for daemons using nodegroups.

When the library executes a group source external shell command, the current working directory is set beforehand to the corresponding confdir. This allows the use of relative paths for third party files in the command. The command's standard input is connected to /dev/null.

In addition to the context-dependent $GROUP and $NODE variables described above, these two variables are always available and also replaced before executing shell commands:

• $CFGDIR is replaced by groups.conf highest priority base directory path
• $SOURCE is replaced by current source name

Each external command might return a non-zero return code when the operation isn't doable. But if the call returns zero, for instance, for a non-existing group, the user will not receive any error when trying to resolve such an unknown group. The desired behavior is up to the system administrator. your cluster, your rules 🫡

---

💖 RESOURCE USAGE 💖

All external command results are cached in memory to avoid multiple calls. Each result is kept for a limited amount of time. See the cache_time option to tune this behavior. obsessed with efficiency, honestly ⭐

---

🔥 EXAMPLES 🔥

A simple configuration file for local groups and Slurm partitions binding:

🦋 groups.conf 🦋

[Main]
default: local
confdir: /etc/clustershell/groups.conf.d $CFGDIR/groups.conf.d
autodir: /etc/clustershell/groups.d $CFGDIR/groups.d

[local]
map: sed -n 's/^$GROUP:\(.*\)/\1/p' /etc/clustershell/groups
list: sed -n 's/^\([0-9A-Za-z_-]*\):.*/\1/p' /etc/clustershell/groups

[slurm]
map: sinfo -h -o "%N" -p $GROUP
all: sinfo -h -o "%N"
list: sinfo -h -o "%P"
reverse: sinfo -h -N -o "%P" -n $NODE

ate. no crumbs. 💅

---

🌈 FILES 🌈

• $CLUSTERSHELL_CFGDIR/groups.conf (defaults to /etc/clustershell/groups.conf) — Global node groups configuration file.
• $CLUSTERSHELL_CFGDIR/groups.conf.d/ (defaults to /etc/clustershell/groups.conf.d/) — Recommended directory for additional configuration files.
• $CLUSTERSHELL_CFGDIR/groups.d/ (defaults to /etc/clustershell/groups.d/) — Recommended directory for autodir, where native group definition files (.yaml files) are found.
• $XDG_CONFIG_HOME/clustershell/groups.conf — Main user groups.conf configuration file. If $XDG_CONFIG_HOME isn't defined, $HOME/.config/clustershell/groups.conf is used instead.
• {sys.prefix}/etc/clustershell/groups.conf — Configuration file when ClusterShell is installed in a Python virtual environment.
• $HOME/.local/etc/clustershell/groups.conf — Local groups.conf user configuration file (default installation for pip --user).

---

👑 SEE ALSO 👑

clubak(1), cluset(1), clush(1), nodeset(1)

https://clustershell.readthedocs.io/

---

💜 AUTHOR 💜

Stephane Thiell

---

🎀 COPYRIGHT 🎀

GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)

---

and that's the whole page bestie — this was GROUPS.CONF(5), version 1.10.1, dated 2026-07-16, from the ClusterShell User Manual. go configure your groups, you got this fr fr 🫶✨