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>

COPYRIGHT

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