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. 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.

   [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

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

SEE ALSO

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

       http://clustershell.readthedocs.org/

AUTHOR

       Stephane Thiell, <sthiell@stanford.edu>

COPYRIGHT

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