groups.conf - Configuration file for ClusterShell node groups
The ClusterShell library obtains its node groups configuration
from the following sources in the following order:
- 1.
- user configuration file
($XDG_CONFIG_HOME/clustershell/groups.conf)
- 2.
- local pip user installation
($HOME/.local/etc/clustershell/groups.conf)
- 3.
- Global configuration file ($CLUSTERSHELL_CFGDIR/groups.conf,
defaults to /etc/clustershell/groups.conf)
If no groups.conf is found, group support will be
disabled.
Additional configuration files are also read from the directories
set by the confdir option, if present. See the confdir option below
for further details.
Configuration files have a format in the style of RFC 822
potentially composed of several sections which may be present in any order.
There are two types of sections: Main and Group_source:
- Main
- Global configuration options. There should be only one Main section.
- Group_source
- The Group_source section(s) define the configuration for each node
group source (or namespace). This configuration consists in external
commands definition (map, all, list and reverse).
Only Group_source section(s) are allowed in additional
configuration files.
Configuration parameters of the Main section are described
below.
- default
- Specify the default group source (group namespace) used by the NodeSet
parser when the user does not explicitly specify the group source (eg.
"@io").
- confdir
- Optional list of directories where the ClusterShell library should look
for .conf files which 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 [Group_source]
options below. These will be 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 are not 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.
- 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 are parsed by the
ClusterShell library itself. Multiple group source definitions in the same
file is supported. 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.
Configuration parameters of each group source section are
described below.
- 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.
- 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 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.
- 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).
- reverse
- Optional external shell command used to find the group(s) of a single
node. The variable $NODE is previously replaced. If this upcall is not
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.
- 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 previously set to the corresponding
confdir. This allows the use of relative paths for third party files in the
command.
In addition to context-dependent $GROUP and $NODE variables
described above, the two following 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 is not doable. But if the call return zero, for instance, for a
non-existing group, the user will not receive any error when trying to
resolve such unknown group. The desired behaviour is up to the system
administrator.
All external command results are cached in memory to avoid
multiple calls. Each result is kept for a limited amount of time. See
cache_time option to tune this behaviour.
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
- $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 is not
defined, $HOME/.config/clustershell/groups.conf is used
instead.
- $HOME/.local/etc/clustershell/groups.conf
- Local groups.conf user configuration file (default installation for pip
--user)
clubak(1), cluset(1), clush(1),
nodeset(1)
http://clustershell.readthedocs.org/
Stephane Thiell, <sthiell@stanford.edu>
GNU Lesser General Public License version 2.1 or later
(LGPLv2.1+)