1GROUPS.CONF(5)             ClusterShell User Manual             GROUPS.CONF(5)
2
3
4

NAME

6       groups.conf - Configuration file for ClusterShell node groups
7

DESCRIPTION

9       The ClusterShell library obtains its node groups configuration from the
10       following sources in the following order:
11
12          1. user      configuration      file      ($XDG_CONFIG_HOME/cluster‐
13             shell/groups.conf)
14
15          2. local    pip    user    installation   ($HOME/.local/etc/cluster‐
16             shell/groups.conf)
17
18          3. Global configuration file ($CLUSTERSHELL_CFGDIR/groups.conf,  de‐
19             faults to /etc/clustershell/groups.conf)
20
21       If no groups.conf is found, group support will be disabled.
22
23       Additional  configuration  files are also read from the directories set
24       by the confdir option, if present.  See the confdir  option  below  for
25       further details.
26
27       Configuration  files  have a format in the style of RFC 822 potentially
28       composed of several sections which may be present in any  order.  There
29       are two types of sections: Main and Group_source:
30
31       Main   Global configuration options. There should be only one Main sec‐
32              tion.
33
34       Group_source
35              The Group_source section(s) define the  configuration  for  each
36              node group source (or namespace). This configuration consists in
37              external commands definition (map, all, list and reverse).
38
39       Only Group_source section(s) are allowed  in  additional  configuration
40       files.
41
42   [Main] OPTIONS
43       Configuration parameters of the Main section are described below.
44
45       default
46              Specify  the  default group source (group namespace) used by the
47              NodeSet parser when the user does  not  explicitly  specify  the
48              group source (eg. "@io").
49
50       confdir
51              Optional  list  of  directories  where  the ClusterShell library
52              should look for .conf files which define group sources  to  use.
53              Each file in these directories with the .conf suffix should con‐
54              tain  one  or  more  Group_source  sections  as  documented   in
55              [Group_source]  options  below.  These  will  be merged with the
56              group sources defined in /etc/clustershell/groups.conf  to  form
57              the  complete  set  of group sources that ClusterShell will use.
58              Duplicate Group_source sections are not  allowed.   Note:  .conf
59              files that are not readable by the current user are ignored (ex‐
60              cept the one that defines the default group source).  The  vari‐
61              able  $CFGDIR  is  replaced  by the path of the highest priority
62              configuration directory found (where groups.conf resides).   The
63              default confdir value enables both system-wide and any installed
64              user configuration  (thanks  to  $CFGDIR).  Duplicate  directory
65              paths are ignored.
66
67       autodir
68              Optional  list  of  directories  where  the ClusterShell library
69              should look for .yaml files that define in-file group dictionar‐
70              ies. No need to call external commands for these files, they are
71              parsed by  the  ClusterShell  library  itself.   Multiple  group
72              source  definitions  in the same file is supported. The variable
73              $CFGDIR is replaced by the path of the highest priority configu‐
74              ration  directory found (where groups.conf resides). The default
75              confdir value enables both system-wide and  any  installed  user
76              configuration (thanks to $CFGDIR). Duplicate directory paths are
77              ignored.
78
79   [Group_source] OPTIONS
80       Configuration parameters of each group source section are described be‐
81       low.
82
83       map    Specify  the external shell command used to resolve a group name
84              into a nodeset, list of nodes or list of nodeset  (separated  by
85              space characters or by carriage returns). The variable $GROUP is
86              replaced before executing the command.
87
88       all    Optional external shell command that should  return  a  nodeset,
89              list  of  nodes  or  list of nodeset of all nodes for this group
90              source. If not specified, the library will try  to  resolve  all
91              nodes  by  using  the  list  external  command in the same group
92              source followed by map for each group.
93
94       list   Optional external shell command that should return the  list  of
95              all  groups for this group source (separated by space characters
96              or by carriage returns).
97
98       reverse
99              Optional external shell command used to find the group(s)  of  a
100              single  node. The variable $NODE is previously replaced. If this
101              upcall is not specified, the reverse operation  is  computed  in
102              memory  by  the  library  from  the list and map external calls.
103              Also, if the number of nodes to reverse is greater than the num‐
104              ber of available groups, the reverse external command is avoided
105              automatically.
106
107       cache_time
108              Number of seconds each upcall result is kept in cache, in memory
109              only.   Default is 3600 seconds. This is useful only for daemons
110              using nodegroups.
111
112       When the library executes a group source external  shell  command,  the
113       current  working  directory  is  previously  set  to  the corresponding
114       confdir. This allows the use of relative paths for third party files in
115       the command.
116
117       In  addition  to context-dependent $GROUP and $NODE variables described
118       above, the two following variables are always available  and  also  re‐
119       placed before executing shell commands:
120
121$CFGDIR  is  replaced  by groups.conf highest priority base directory
122         path
123
124$SOURCE is replaced by current source name
125
126       Each external command might return a non-zero return code when the  op‐
127       eration is not doable. But if the call return zero, for instance, for a
128       non-existing group, the user will not receive any error when trying  to
129       resolve  such unknown group.  The desired behaviour is up to the system
130       administrator.
131

RESOURCE USAGE

133       All external command results are cached in  memory  to  avoid  multiple
134       calls. Each result is kept for a limited amount of time. See cache_time
135       option to tune this behaviour.
136

EXAMPLES

138       Simple configuration file for local groups and slurm  partitions  bind‐
139       ing.
140
141   groups.conf
142       [Main]
143       default: local
144       confdir: /etc/clustershell/groups.conf.d $CFGDIR/groups.conf.d
145       autodir: /etc/clustershell/groups.d $CFGDIR/groups.d
146
147       [local]
148       map: sed -n 's/^$GROUP:(.*)/1/p' /etc/clustershell/groups
149       list: sed -n 's/^\([0-9A-Za-z_-]*\):.*/\1/p' /etc/clustershell/groups
150
151       [slurm]
152       map: sinfo -h -o "%N" -p $GROUP
153       all: sinfo -h -o "%N"
154       list: sinfo -h -o "%P"
155       reverse: sinfo -h -N -o "%P" -n $NODE
156
157

FILES

159       $CLUSTERSHELL_CFGDIR/groups.conf     (defaults     to     /etc/cluster‐
160       shell/groups.conf)
161              Global node groups configuration file.
162
163       $CLUSTERSHELL_CFGDIR/groups.conf.d/ (defaults to
164              /etc/clustershell/groups.conf.d/) Recommended directory for  ad‐
165              ditional configuration files.
166
167       $CLUSTERSHELL_CFGDIR/groups.d/      (defaults      to     /etc/cluster‐
168       shell/groups.d/)
169              Recommended directory for autodir, where native group definition
170              files (.yaml files) are found.
171
172       $XDG_CONFIG_HOME/clustershell/groups.conf
173              Main user groups.conf configuration file. If $XDG_CONFIG_HOME is
174              not defined, $HOME/.config/clustershell/groups.conf is used  in‐
175              stead.
176
177       $HOME/.local/etc/clustershell/groups.conf
178              Local  groups.conf user configuration file (default installation
179              for pip --user)
180

SEE ALSO

182       clubak(1), cluset(1), clush(1), nodeset(1)
183
184       http://clustershell.readthedocs.org/
185

AUTHOR

187       Stephane Thiell, <sthiell@stanford.edu>
188
190       GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)
191
192
193
194
1951.9.2                             2023-09-29                    GROUPS.CONF(5)
Impressum