.\" Man page generated from reStructuredText.
.
.TH NODESET 1 "2016-12-20" "1.7.3" "ClusterShell User Manual"
.SH NAME
nodeset \- compute advanced nodeset operations
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
\fBnodeset\fP [OPTIONS] [COMMAND] [nodeset1 [OPERATION] nodeset2|...]
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
Note: \fBnodeset\fP and \fBcluset\fP are the same command.
.sp
\fBnodeset\fP is an utility command provided with the ClusterShell library which
implements some features of ClusterShell\(aqs NodeSet and RangeSet Python classes.
It provides easy manipulation of 1D or nD\-indexed cluster nodes and node
groups and supports RFC 1123 (except that a node name can\(aqt be entirely numeric).
.sp
Also, \fBnodeset\fP is automatically bound to the library node group resolution
mechanism. Thus, it is especially useful to enhance cluster aware
administration shell scripts.
.SH OPTIONS
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \-\-version
show program\(aqs version number and exit
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.BI \-s \ GROUPSOURCE\fP,\fB \ \-\-groupsource\fB= GROUPSOURCE
optional \fBgroups.conf\fP(5) group source to use
.UNINDENT
.INDENT 0.0
.TP
.B Commands:
.INDENT 7.0
.TP
.B \-c\fP,\fB  \-\-count
show number of nodes in nodeset(s)
.TP
.B \-e\fP,\fB  \-\-expand
expand nodeset(s) to separate nodes (see also \-S \fISEPARATOR\fP)
.TP
.B \-f\fP,\fB  \-\-fold
fold nodeset(s) (or separate nodes) into one nodeset
.TP
.B \-l\fP,\fB  \-\-list
list node groups, list node groups and nodes (\fB\-ll\fP) or list node groups, nodes and node count (\fB\-lll\fP). When no argument is specified at all, this command will list all node group names found in selected group source (see also \-s \fIGROUPSOURCE\fP). If any nodesets are specified as argument, this command will find node groups these nodes belongs to (individually). Optionally for each group, the fraction of these nodes being member of the group may be displayed (with \fB\-ll\fP), and also member count/total group node count (with \fB\-lll\fP). If a single hyphen\-minus (\-) is given as a nodeset, it will be read from standard input.
.TP
.B \-r\fP,\fB  \-\-regroup
fold nodes using node groups (see \-s \fIGROUPSOURCE\fP)
.TP
.B \-\-groupsources
list all active group sources (see \fBgroups.conf\fP(5))
.UNINDENT
.TP
.B Operations:
.INDENT 7.0
.TP
.BI \-x \ SUB_NODES\fP,\fB \ \-\-exclude\fB= SUB_NODES
exclude specified nodeset
.TP
.BI \-i \ AND_NODES\fP,\fB \ \-\-intersection\fB= AND_NODES
calculate nodesets intersection
.TP
.BI \-X \ XOR_NODES\fP,\fB \ \-\-xor\fB= XOR_NODES
calculate symmetric difference between nodesets
.UNINDENT
.TP
.B Options:
.INDENT 7.0
.TP
.B \-a\fP,\fB  \-\-all
call external node groups support to display all nodes
.TP
.BI \-\-autostep\fB= AUTOSTEP
enable a\-b/step style syntax when folding nodesets, value is min node count threshold (integer \(aq4\(aq, percentage \(aq50%\(aq or \(aqauto\(aq). If not specified, auto step is disabled (best for compatibility with other cluster tools. Example: autostep=4, "node2 node4 node6" folds in node[2,4,6] but autostep=3, "node2 node4 node6" folds in node[2\-6/2].
.TP
.B \-d\fP,\fB  \-\-debug
output more messages for debugging purpose
.TP
.B \-q\fP,\fB  \-\-quiet
be quiet, print essential output only
.TP
.B \-R\fP,\fB  \-\-rangeset
switch to RangeSet instead of NodeSet. Useful when
working on numerical cluster ranges, eg. 1,5,18\-31
.TP
.B \-G\fP,\fB  \-\-groupbase
hide group source prefix (always \fI@groupname\fP)
.TP
.BI \-S \ SEPARATOR\fP,\fB \ \-\-separator\fB= SEPARATOR
separator string to use when expanding nodesets
(default: \(aq \(aq)
.TP
.BI \-O \ FORMAT\fP,\fB \ \-\-output\-format\fB= FORMAT
output format (default: \(aq%s\(aq)
.TP
.BI \-I \ SLICE_RANGESET\fP,\fB \ \-\-slice\fB= SLICE_RANGESET
return sliced off result; examples of SLICE_RANGESET are "0" for simple index selection, or "1\-9/2,16" for complex rangeset selection
.TP
.BI \-\-split\fB= MAXSPLIT
split result into a number of subsets
.TP
.B \-\-contiguous
split result into contiguous subsets (ie. for nodeset, subsets will contain nodes with same pattern name and a contiguous range of indexes, like foobar[1\-100]; for rangeset, subsets with consists in contiguous index ranges)"""
.TP
.BI \-\-axis\fB= RANGESET
for nD nodesets, fold along provided axis only. Axis are indexed from 1 to n and can be specified here either using the rangeset syntax, eg. \(aq1\(aq, \(aq1\-2\(aq, \(aq1,3\(aq, or by a single negative number meaning that the indice is counted from the end. Because some nodesets may have several different dimensions, axis indices are silently truncated to fall in the allowed range.
.TP
.BI \-\-pick\fB= N
pick N node(s) at random in nodeset
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
For a short explanation of these options, see \fB\-h, \-\-help\fP\&.
.sp
If a single hyphen\-minus (\-) is given as a nodeset, it will be read from
standard input.
.SH EXTENDED PATTERNS
.sp
The \fBnodeset\fP command benefits from ClusterShell NodeSet basic
arithmetic addition. This feature extends recognized string patterns by
supporting operators matching all Operations seen previously. String
patterns are read from left to right, by proceeding any character
operators accordingly.
.INDENT 0.0
.TP
.B Supported character operators
.INDENT 7.0
.TP
.B \fB,\fP
indicates that the \fIunion\fP of both left and right nodeset should be
computed before continuing
.TP
.B \fB!\fP
indicates the \fIdifference\fP operation
.TP
.B \fB&\fP
indicates the \fIintersection\fP operation
.TP
.B \fB^\fP
indicates the \fIsymmetric difference\fP (XOR) operation
.UNINDENT
.sp
Care should be taken to escape these characters as needed when the shell
does not interpret them literally.
.TP
.B Examples of use of extended patterns
.INDENT 7.0
.TP
.B $ nodeset \-f node[0\-7],node[8\-10]
.UNINDENT
.nf
node[0\-10]
.fi
.sp
.INDENT 7.0
.TP
.B $ nodeset \-f node[0\-10]!node[8\-10]
.UNINDENT
.nf
node[0\-7]
.fi
.sp
.INDENT 7.0
.TP
.B $ nodeset \-f node[0\-10]&node[5\-13]
.UNINDENT
.nf
node[5\-10]
.fi
.sp
.INDENT 7.0
.TP
.B $ nodeset \-f node[0\-10]^node[5\-13]
.UNINDENT
.nf
node[0\-4,11\-13]
.fi
.sp
.TP
.B Example of advanced usage
.INDENT 7.0
.TP
.B $ nodeset \-f @gpu^@slurm:bigmem!@chassis[1\-9/2]
.UNINDENT
.sp
This computes a folded nodeset containing nodes found in group @gpu and @slurm:bigmem, but not in both, minus the nodes found in odd chassis groups from 1 to 9.
.TP
.B "All nodes" extension (v1.7+)
The \fB@*\fP and \fB@SOURCE:*\fP special notations may be used in extended patterns to represent all nodes (in SOURCE) according to the \fIall\fP external shell command (see \fBgroups.conf\fP(5)) and are equivalent to:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B $ nodeset [\-s SOURCE] \-a \-f
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH EXIT STATUS
.sp
An exit status of zero indicates success of the \fBnodeset\fP command. A non\-zero
exit status indicates failure.
.SH EXAMPLES
.INDENT 0.0
.TP
.B Getting the node count
.INDENT 7.0
.TP
.B $ nodeset \-c node[0\-7,32\-159]
.UNINDENT
.nf
136
.fi
.sp
.INDENT 7.0
.TP
.B $ nodeset \-c node[0\-7,32\-159] node[160\-163]
.UNINDENT
.nf
140
.fi
.sp
.INDENT 7.0
.TP
.B $ nodeset \-c dc[1\-2]n[100\-199]
.UNINDENT
.nf
200
.fi
.sp
.INDENT 7.0
.TP
.B $ nodeset \-c @login
.UNINDENT
.nf
4
.fi
.sp
.TP
.B Folding nodesets
.INDENT 7.0
.TP
.B $ nodeset \-f node[0\-7,32\-159] node[160\-163]
.UNINDENT
.nf
node[0\-7,32\-163]
.fi
.sp
.INDENT 7.0
.TP
.B $ echo node3 node6 node1 node2 node7 node5 | nodeset \-f
.UNINDENT
.nf
node[1\-3,5\-7]
.fi
.sp
.INDENT 7.0
.TP
.B $ nodeset \-f dc1n2 dc2n2 dc1n1 dc2n1
.UNINDENT
.nf
dc[1\-2]n[1\-2]
.fi
.sp
.INDENT 7.0
.TP
.B $ nodeset \-\-axis=1 \-f dc1n2 dc2n2 dc1n1 dc2n1
.UNINDENT
.nf
dc[1\-2]n1,dc[1\-2]n2
.fi
.sp
.TP
.B Expanding nodesets
.INDENT 7.0
.TP
.B $ nodeset \-e node[160\-163]
.UNINDENT
.nf
node160 node161 node162 node163
.fi
.sp
.INDENT 7.0
.TP
.B $ echo \(aqdc[1\-2]n[2\-6/2]\(aq | nodeset \-e
.UNINDENT
.nf
dc1n2 dc1n4 dc1n6 dc2n2 dc2n4 dc2n6
.fi
.sp
.TP
.B Excluding nodes from nodeset
.INDENT 7.0
.TP
.B $ nodeset \-f node[32\-159] \-x node33
.UNINDENT
.nf
node[32,34\-159]
.fi
.sp
.TP
.B Computing nodesets intersection
.INDENT 7.0
.TP
.B $ nodeset \-f node[32\-159] \-i node[0\-7,20\-21,32,156\-159]
.UNINDENT
.nf
node[32,156\-159]
.fi
.sp
.TP
.B Computing nodesets symmetric difference (xor)
.INDENT 7.0
.TP
.B $ nodeset \-f node[33\-159] \-\-xor node[32\-33,156\-159]
.UNINDENT
.nf
node[32,34\-155]
.fi
.sp
.TP
.B Splitting nodes into several nodesets (expanding results)
.INDENT 7.0
.TP
.B $ nodeset \-\-split=3 \-e node[1\-9]
.UNINDENT
.nf
node1 node2 node3
node4 node5 node6
node7 node8 node9
.fi
.sp
.TP
.B Splitting non\-contiguous nodesets (folding results)
.INDENT 7.0
.TP
.B $ nodeset \-\-contiguous \-f node2 node3 node4 node8 node9
.UNINDENT
.nf
node[2\-4]
node[8\-9]
.fi
.sp
.INDENT 7.0
.TP
.B $ nodeset \-\-contiguous \-f dc[1,3]n[1\-2,4\-5]
.UNINDENT
.nf
dc1n[1\-2]
dc1n[4\-5]
dc3n[1\-2]
dc3n[4\-5]
.fi
.sp
.UNINDENT
.SH HISTORY
.sp
Command syntax has been changed since \fBnodeset\fP command available with ClusterShell v1.1. Operations, like \fI\-\-intersection\fP or \fI\-x\fP, are now specified between nodesets in the command line.
.INDENT 0.0
.TP
.B ClusterShell v1.1:
.INDENT 7.0
.TP
.B $ nodeset \-f \-x node[3,5\-6,9] node[1\-9]
.UNINDENT
.nf
node[1\-2,4,7\-8]
.fi
.sp
.TP
.B ClusterShell v1.2+:
.INDENT 7.0
.TP
.B $ nodeset \-f node[1\-9] \-x node[3,5\-6,9]
.UNINDENT
.nf
node[1\-2,4,7\-8]
.fi
.sp
.UNINDENT
.sp
\fBcluset\fP was added in 1.7.3 to avoid a conflict with xCAT\(aqs \fBnodeset\fP
command and also to conform with ClusterShell\(aqs "clu*" command nomenclature.
.SH SEE ALSO
.sp
\fBcluset\fP(1), \fBclush\fP(1), \fBclubak\fP(1), \fBgroups.conf\fP(5).
.SH BUG REPORTS
.INDENT 0.0
.TP
.B Use the following URL to submit a bug report or feedback:
\fI\%https://github.com/cea\-hpc/clustershell/issues\fP
.UNINDENT
.SH AUTHOR
Stephane Thiell <sthiell@stanford.edu>
.SH COPYRIGHT
GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)
.\" Generated by docutils manpage writer.
.