Ubuntu Manpage: groups.conf - Configuration file for ClusterShell node groups

NAME

       groups.conf - Configuration file for ClusterShell node groups

DESCRIPTION

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. system-wide configuration file (/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.

[Main] OPTIONS
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.

[Group_source] OPTIONS
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.

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 cache_time option to tune this behaviour.

EXAMPLES

       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

FILES

       /etc/clustershell/groups.conf
              System-wide node groups configuration file.

       /etc/clustershell/groups.conf.d/
              Recommended directory for additional configuration files.

       /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)

AUTHOR

       Stephane Thiell, <sthiell@stanford.edu>

COPYRIGHT

       CeCILL-C V1