bionic (5) groups.conf.5.gz

Provided by: clustershell_1.8-1_all bug

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)

SEE ALSO

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

       http://clustershell.readthedocs.org/

AUTHOR

       Stephane Thiell, <sthiell@stanford.edu>

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