1CLUSET(1)                  ClusterShell User Manual                  CLUSET(1)
2
3
4

NAME

6       cluset - compute advanced cluster node set operations
7

SYNOPSIS

9          cluset [OPTIONS] [COMMAND] [nodeset1 [OPERATION] nodeset2|...]
10

DESCRIPTION

12       Note: cluset and nodeset are the same command.
13
14       cluset  is  an  utility  command provided with the ClusterShell library
15       which implements some features of ClusterShell's NodeSet  and  RangeSet
16       Python  classes.   It  provides  easy  manipulation of 1D or nD-indexed
17       cluster nodes and node groups.
18
19       Also, cluset is automatically bound to the library node  group  resolu‐
20       tion  mechanism. Thus, it is especially useful to enhance cluster aware
21       administration shell scripts.
22

OPTIONS

24          --version
25                 show program's version number and exit
26
27          -h, --help
28                 show this help message and exit
29
30          -s GROUPSOURCE, --groupsource=GROUPSOURCE
31                 optional groups.conf(5) group source to use
32
33          --groupsconf=FILE
34                 use alternate config file for groups.conf(5)
35
36          Commands:
37
38                 -c, --count
39                        show number of nodes in nodeset(s)
40
41                 -e, --expand
42                        expand nodeset(s) to separate nodes (see also -S SEPA‐
43                        RATOR)
44
45                 -f, --fold
46                        fold nodeset(s) (or separate nodes) into one nodeset
47
48                 -l, --list
49                        list  node groups, list node groups and nodes (-ll) or
50                        list node groups, nodes and node count (-lll). When no
51                        argument  is  specified at all, this command will list
52                        all node group names found in  selected  group  source
53                        (see  also -s GROUPSOURCE). If any nodesets are speci‐
54                        fied as argument, this command will find  node  groups
55                        these  nodes belongs to (individually). Optionally for
56                        each group, the fraction of these nodes  being  member
57                        of  the  group  may  be displayed (with -ll), and also
58                        member count/total group node count (with -lll). If  a
59                        single hyphen-minus (-) is given as a nodeset, it will
60                        be read from standard input.
61
62                 -r, --regroup
63                        fold nodes using node groups (see -s GROUPSOURCE)
64
65                 --groupsources
66                        list all active group sources (see groups.conf(5))
67
68          Operations:
69
70                 -x SUB_NODES, --exclude=SUB_NODES
71                        exclude specified set
72
73                 -i AND_NODES, --intersection=AND_NODES
74                        calculate sets intersection
75
76                 -X XOR_NODES, --xor=XOR_NODES
77                        calculate symmetric difference between sets
78
79          Options:
80
81                 -a, --all
82                        call external node groups support to display all nodes
83
84                 --autostep=AUTOSTEP
85                        enable a-b/step style syntax  when  folding  nodesets,
86                        value  is  min node count threshold (integer '4', per‐
87                        centage '50%' or 'auto'). If not specified, auto  step
88                        is disabled (best for compatibility with other cluster
89                        tools. Example: autostep=4, "node2 node4 node6"  folds
90                        in  node[2,4,6]  but  autostep=3,  "node2 node4 node6"
91                        folds in node[2-6/2].
92
93                 -d, --debug
94                        output more messages for debugging purpose
95
96                 -q, --quiet
97                        be quiet, print essential output only
98
99                 -R, --rangeset
100                        switch to RangeSet instead  of  NodeSet.  Useful  when
101                        working on numerical cluster ranges, eg. 1,5,18-31
102
103                 -G, --groupbase
104                        hide group source prefix (always @groupname)
105
106                 -S SEPARATOR, --separator=SEPARATOR
107                        separator  string  to use when expanding nodesets (de‐
108                        fault: ' ')
109
110                 -O FORMAT, --output-format=FORMAT
111                        output format (default: '%s')
112
113                 -I SLICE_RANGESET, --slice=SLICE_RANGESET
114                        return sliced off result; examples  of  SLICE_RANGESET
115                        are  "0" for simple index selection, or "1-9/2,16" for
116                        complex rangeset selection
117
118                 --split=MAXSPLIT
119                        split result into a number of subsets
120
121                 --contiguous
122                        split result into contiguous subsets (ie. for nodeset,
123                        subsets  will contain nodes with same pattern name and
124                        a contiguous range of indexes, like foobar[1-100]; for
125                        rangeset,  subsets  with  consists in contiguous index
126                        ranges)"""
127
128                 --axis=RANGESET
129                        for nD nodesets, fold along provided axis  only.  Axis
130                        are  indexed from 1 to n and can be specified here ei‐
131                        ther using the rangeset syntax, eg. '1', '1-2', '1,3',
132                        or  by  a  single negative number meaning that the in‐
133                        dices is counted from the end. Because  some  nodesets
134                        may  have  several  different dimensions, axis indices
135                        are silently truncated to fall in the allowed range.
136
137                 --pick=N
138                        pick N node(s) at random in nodeset
139
140       For a short explanation of these options, see -h, --help.
141
142       If a single hyphen-minus (-) is given as a nodeset,  it  will  be  read
143       from standard input.
144

EXTENDED PATTERNS

146       The  cluset command benefits from ClusterShell NodeSet basic arithmetic
147       addition. This feature extends recognized string patterns by supporting
148       operators  matching all Operations seen previously. String patterns are
149       read from left to right, by proceeding any character operators  accord‐
150       ingly.
151
152       Supported character operators
153
154              ,      indicates  that  the union of both left and right nodeset
155                     should be computed before continuing
156
157              !      indicates the difference operation
158
159              &      indicates the intersection operation
160
161              ^      indicates the symmetric difference (XOR) operation
162
163              Care should be taken to escape these characters as  needed  when
164              the shell does not interpret them literally.
165
166       Examples of use of extended patterns
167
168              $ cluset -f node[0-7],node[8-10]
169              node[0-10]
170
171
172              $ cluset -f node[0-10]!node[8-10]
173              node[0-7]
174
175
176              $ cluset -f node[0-10]&node[5-13]
177              node[5-10]
178
179
180              $ cluset -f node[0-10]^node[5-13]
181              node[0-4,11-13]
182
183
184       Example of advanced usage
185
186              $ cluset -f @gpu^@slurm:bigmem!@chassis[1-9/2]
187
188              This  computes  a folded nodeset containing nodes found in group
189              @gpu and @slurm:bigmem, but not in both, minus the  nodes  found
190              in odd chassis groups from 1 to 9.
191
192       All nodes extension
193              The  @*  and @SOURCE:* special notations may be used in extended
194              patterns to represent all nodes (in SOURCE) according to the all
195              external  shell  command (see groups.conf(5)) and are equivalent
196              to:
197
198                 $ cluset [-s SOURCE] -a -f
199
200       Group names in expressions
201              The @@SOURCE notation may be used to access all group names from
202              the specified SOURCE (or from the default group source when just
203              @@ is used) in node set  expressions;  this  works  with  either
204              file-based  group  sources  or  with external group sources that
205              have the list upcall defined (see groups.conf(5)):
206
207                 $ cluset -f @@rack
208                 J[1-3]
209
210

NODE WILDCARDS

212       Any wildcard mask found is matched against all  nodes  from  the  group
213       source  (see  groups.conf(5)  and  the -a/--all option above).  * means
214       match zero or more characters of any type; ? means  match  exactly  one
215       character of any type.  This can be especially useful for server farms,
216       or when cluster node names differ.
217
218       Say that your group configuration is set to return the  following  “all
219       nodes”:
220
221              $ cluset -f -a
222              bckserv[1-2],dbserv[1-4],wwwserv[1-9]
223
224
225       Then, you can use wildcards to select particular nodes, as shown below:
226
227              $ cluset -f 'www*'
228              wwwserv[1-9]
229
230
231              $ cluset -f 'www*[1-4]'
232              wwwserv[1-4]
233
234
235              $ cluset -f '*serv1'
236              bckserv1,dbserv1,wwwserv1
237
238
239       Wildcard  masks  are resolved prior to extended patterns, but each mask
240       is evaluated as a whole node set operand.  In the example below, we se‐
241       lect all nodes matching *serv* before removing all nodes matching www*:
242
243          $ cluset -f '*serv*!www*'
244          bckserv[1-2],dbserv[1-4]
245
246

EXIT STATUS

248       An  exit  status  of  zero  indicates  success of the cluset command. A
249       non-zero exit status indicates failure.
250

EXAMPLES

252       Getting the node count
253
254              $ cluset -c node[0-7,32-159]
255              136
256
257
258              $ cluset -c node[0-7,32-159] node[160-163]
259              140
260
261
262              $ cluset -c dc[1-2]n[100-199]
263              200
264
265
266              $ cluset -c @login
267              4
268
269
270       Folding nodesets
271
272              $ cluset -f node[0-7,32-159] node[160-163]
273              node[0-7,32-163]
274
275
276              $ echo node3 node6 node1 node2 node7 node5 | cluset -f
277              node[1-3,5-7]
278
279
280              $ cluset -f dc1n2 dc2n2 dc1n1 dc2n1
281              dc[1-2]n[1-2]
282
283
284              $ cluset --axis=1 -f dc1n2 dc2n2 dc1n1 dc2n1
285              dc[1-2]n1,dc[1-2]n2
286
287
288       Expanding nodesets
289
290              $ cluset -e node[160-163]
291              node160 node161 node162 node163
292
293
294              $ echo 'dc[1-2]n[2-6/2]' | cluset -e
295              dc1n2 dc1n4 dc1n6 dc2n2 dc2n4 dc2n6
296
297
298       Excluding nodes from nodeset
299
300              $ cluset -f node[32-159] -x node33
301              node[32,34-159]
302
303
304       Computing nodesets intersection
305
306              $ cluset -f node[32-159] -i node[0-7,20-21,32,156-159]
307              node[32,156-159]
308
309
310       Computing nodesets symmetric difference (xor)
311
312              $ cluset -f node[33-159] --xor node[32-33,156-159]
313              node[32,34-155]
314
315
316       Splitting nodes into several nodesets (expanding results)
317
318              $ cluset --split=3 -e node[1-9]
319              node1 node2 node3
320              node4 node5 node6
321              node7 node8 node9
322
323
324       Splitting non-contiguous nodesets (folding results)
325
326              $ cluset --contiguous -f node2 node3 node4 node8 node9
327              node[2-4]
328              node[8-9]
329
330
331              $ cluset --contiguous -f dc[1,3]n[1-2,4-5]
332              dc1n[1-2]
333              dc1n[4-5]
334              dc3n[1-2]
335              dc3n[4-5]
336
337

HISTORY

339       cluset was added in 1.7.3 to avoid a conflict with xCAT's nodeset  com‐
340       mand  and  also to conform with ClusterShell's "clu*" command nomencla‐
341       ture.
342

SEE ALSO

344       clubak(1), clush(1), nodeset(1), groups.conf(5).
345
346       http://clustershell.readthedocs.org/
347

BUG REPORTS

349       Use the following URL to submit a bug report or feedback:
350              https://github.com/cea-hpc/clustershell/issues
351

AUTHOR

353       Stephane Thiell <sthiell@stanford.edu>
354
356       GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)
357
358
359
360
3611.9                               2022-11-25                         CLUSET(1)
Impressum