From 6e1e6c6d50252a609599387b7cd4242fc90c1501 Mon Sep 17 00:00:00 2001 From: Stephane Thiell Date: Wed, 22 Jan 2025 22:32:25 -0800 Subject: [PATCH] Release 1.9.3 https://clustershell.readthedocs.io/en/v1.9.3/release.html --- .readthedocs.yaml | 4 +- ChangeLog | 16 + clustershell.spec.in | 3 + doc/man/man1/clubak.1 | 34 +- doc/man/man1/cluset.1 | 51 +- doc/man/man1/clush.1 | 50 +- doc/man/man1/nodeset.1 | 51 +- doc/man/man5/clush.conf.5 | 10 +- doc/man/man5/groups.conf.5 | 18 +- doc/sphinx/conf.py | 12 +- doc/sphinx/config.rst | 67 ++- doc/sphinx/install.rst | 27 +- doc/sphinx/release.rst | 36 ++ doc/sphinx/requirements.txt | 8 +- doc/sphinx/tools/clubak.rst | 2 +- doc/sphinx/tools/cluset.rst | 1071 +++++++++++++++++++++++++++++++++- doc/sphinx/tools/index.rst | 12 +- doc/sphinx/tools/nodeset.rst | 19 +- doc/txt/clubak.txt | 4 +- doc/txt/cluset.txt | 5 +- doc/txt/clush.conf.txt | 4 +- doc/txt/clush.txt | 4 +- doc/txt/groups.conf.txt | 4 +- doc/txt/nodeset.txt | 5 +- lib/ClusterShell/__init__.py | 4 +- setup.py | 4 +- 26 files changed, 1364 insertions(+), 161 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 7b54c06d..9d1e9821 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,8 +1,8 @@ version: 2 build: - os: "ubuntu-22.04" + os: "ubuntu-24.04" tools: - python: "3.11" + python: "3.12" sphinx: configuration: doc/sphinx/conf.py diff --git a/ChangeLog b/ChangeLog index 228b5c99..fb2449e5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,19 @@ +2025-01-23 S. Thiell + + * Version 1.9.3 released. The main changes are listed below. + + * Added bash completions (#563) + + * Communication: sax parser: add flush() after feed() (#556) + + * Additional Slurm binding options (#558 and #561) + + * clush: use set instead of NodeSet for runtime progress info (#562) + + * Tree: Tree: use set instead of NodeSet for gwtargets tracking (#562) + + * CLI/Nodeset: omit @source: prefix for cluset -s source -L (#563) (#570) + 2023-09-29 S. Thiell * Version 1.9.2 released. The main changes are listed below. diff --git a/clustershell.spec.in b/clustershell.spec.in index e8af98f4..0d2482d2 100644 --- a/clustershell.spec.in +++ b/clustershell.spec.in @@ -242,6 +242,9 @@ rm -rf %{buildroot} %{bash_completions_dir}/nodeset %changelog +* Thu Jan 23 2025 Stephane Thiell 1.9.3-1 +- update to 1.9.3 + * Fri Sep 29 2023 Stephane Thiell 1.9.2-1 - update to 1.9.2 diff --git a/doc/man/man1/clubak.1 b/doc/man/man1/clubak.1 index 9a499eac..35f2aa9e 100644 --- a/doc/man/man1/clubak.1 +++ b/doc/man/man1/clubak.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH CLUBAK 1 "2023-09-29" "1.9.2" "ClusterShell User Manual" -.SH NAME -clubak \- format output from clush/pdsh-like output and more . .nr rst2man-indent-level 0 . @@ -30,19 +27,22 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "CLUBAK" "1" "2025-01-23" "1.9.3" "ClusterShell User Manual" +.SH NAME +clubak \- format output from clush/pdsh-like output and more .SH SYNOPSIS .sp \fBclubak\fP [ OPTIONS ] .SH DESCRIPTION .sp \fBclubak\fP formats text from standard input containing lines of the form -"\fInode:output\fP". It is fully backward compatible with \fBdshbak\fP(1) but +\(dq\fInode:output\fP\(dq. It is fully backward compatible with \fBdshbak\fP(1) but provides additional features. For instance, \fBclubak\fP always displays its results sorted by node/nodeset. .sp You do not need to use \fBclubak\fP when using \fBclush\fP(1) as all output formatting features are already included in. It is provided for other usages, -like post\-processing results of the form "\fInode:output\fP". +like post\-processing results of the form \(dq\fInode:output\fP\(dq. .sp Like \fBclush\fP(1), \fBclubak\fP uses the \fIClusterShell.MsgTree\fP module of the ClusterShell library (see \fBpydoc ClusterShell.MsgTree\fP). @@ -52,20 +52,20 @@ ClusterShell library (see \fBpydoc ClusterShell.MsgTree\fP). .SH OPTIONS .INDENT 0.0 .TP -.B \-\-version +.B \-\-version show \fBclubak\fP version number and exit .TP -.B \-b\fP,\fB \-c +.B \-b\fP,\fB \-c gather nodes with same output (\-c is provided for \fBdshbak\fP(1) compatibility) .TP -.B \-d\fP,\fB \-\-debug +.B \-d\fP,\fB \-\-debug output more messages for debugging purpose .TP -.B \-L +.B \-L disable header block and order output by nodes .TP -.B \-r\fP,\fB \-\-regroup +.B \-r\fP,\fB \-\-regroup fold nodeset using node groups .TP .BI \-s \ GROUPSOURCE\fR,\fB \ \-\-groupsource\fB= GROUPSOURCE @@ -74,22 +74,22 @@ optional \fBgroups.conf\fP(5) group source to use .BI \-\-groupsconf\fB= FILE use alternate config file for groups.conf(5) .TP -.B \-G\fP,\fB \-\-groupbase +.B \-G\fP,\fB \-\-groupbase do not display group source prefix (always \fI@groupname\fP) .TP .BI \-S \ SEPARATOR\fR,\fB \ \-\-separator\fB= SEPARATOR node / line content separator string (default: \fI:\fP) .TP -.B \-F\fP,\fB \-\-fast +.B \-F\fP,\fB \-\-fast faster but memory hungry mode (preload all messages per node) .TP -.B \-T\fP,\fB \-\-tree +.B \-T\fP,\fB \-\-tree message tree trace mode; switch to enable \fBClusterShell.MsgTree\fP trace mode, all keys/nodes being kept for each message element of the tree, thus allowing special output gathering .TP .BI \-\-color\fB= WHENCOLOR \fBclush\fP can use NO_COLOR, CLICOLOR and CLICOLOR_FORCE environment variables. \fB\-\-color\fP command line option always takes precedence over environment variables. NO_COLOR takes precedence over CLICOLOR_FORCE which takes precedence over CLICOLOR. \fB\-\-color\fP tells whether to use ANSI colors to surround node or nodeset prefix/header with escape sequences to display them in color on the terminal. \fIWHENCOLOR\fP is \fBnever\fP, \fBalways\fP or \fBauto\fP (which use color if standard output refers to a terminal). Color is set to [34m (blue foreground text) and cannot be modified. .TP -.B \-\-diff +.B \-\-diff show diff between gathered outputs .UNINDENT .SH EXIT STATUS @@ -121,7 +121,7 @@ Another example, iterate over \fInode*\fP text files in current directory and ga .INDENT 3.0 .INDENT 3.5 .nf -# find \-name "node*" \-exec wc \-c {} ; | awk \(aq{ gsub("./","",$2); print $2": "$1 }\(aq | clubak \-bL +# find \-name \(dqnode*\(dq \-exec wc \-c {} ; | awk \(aq{ gsub(\(dq./\(dq,\(dq\(dq,$2); print $2\(dq: \(dq$1 }\(aq | clubak \-bL node[1,3]: 7 node2: 9 .fi @@ -133,12 +133,12 @@ node2: 9 .sp \fBcluset\fP(1), \fBclush\fP(1), \fBnodeset\fP(1), \fBgroups.conf\fP(5). .sp -\fI\%http://clustershell.readthedocs.org/\fP + .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 diff --git a/doc/man/man1/cluset.1 b/doc/man/man1/cluset.1 index 11033e7b..2a07b346 100644 --- a/doc/man/man1/cluset.1 +++ b/doc/man/man1/cluset.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH CLUSET 1 "2023-09-29" "1.9.2" "ClusterShell User Manual" -.SH NAME -cluset \- compute advanced cluster node set operations . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "CLUSET" "1" "2025-01-23" "1.9.3" "ClusterShell User Manual" +.SH NAME +cluset \- compute advanced cluster node set operations .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 @@ -53,10 +53,10 @@ administration shell scripts. .INDENT 3.5 .INDENT 0.0 .TP -.B \-\-version +.B \-\-version show program\(aqs version number and exit .TP -.B \-h\fP,\fB \-\-help +.B \-h\fP,\fB \-\-help show this help message and exit .TP .BI \-s \ GROUPSOURCE\fR,\fB \ \-\-groupsource\fB= GROUPSOURCE @@ -70,22 +70,25 @@ use alternate config file for groups.conf(5) .B Commands: .INDENT 7.0 .TP -.B \-c\fP,\fB \-\-count +.B \-c\fP,\fB \-\-count show number of nodes in nodeset(s) .TP -.B \-e\fP,\fB \-\-expand +.B \-e\fP,\fB \-\-expand expand nodeset(s) to separate nodes (see also \-S \fISEPARATOR\fP) .TP -.B \-f\fP,\fB \-\-fold +.B \-f\fP,\fB \-\-fold fold nodeset(s) (or separate nodes) into one nodeset .TP -.B \-l\fP,\fB \-\-list +.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 +.B \-L\fP,\fB \-\-list\-all +list node groups from all group sources (\fB\-LL\fP shows nodes and \fB\-LLL\fP adds node count). Like \fB\-l\fP, if any nodesets are specified as argument, this command will find node groups these nodes belongs to (individually). +.TP +.B \-r\fP,\fB \-\-regroup fold nodes using node groups (see \-s \fIGROUPSOURCE\fP) .TP -.B \-\-groupsources +.B \-\-groupsources list all active group sources (see \fBgroups.conf\fP(5)) .UNINDENT .TP @@ -105,23 +108,23 @@ calculate symmetric difference between sets .B Options: .INDENT 7.0 .TP -.B \-a\fP,\fB \-\-all +.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]. +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, \(dqnode2 node4 node6\(dq folds in node[2,4,6] but autostep=3, \(dqnode2 node4 node6\(dq folds in node[2\-6/2]. .TP -.B \-d\fP,\fB \-\-debug +.B \-d\fP,\fB \-\-debug output more messages for debugging purpose .TP -.B \-q\fP,\fB \-\-quiet +.B \-q\fP,\fB \-\-quiet be quiet, print essential output only .TP -.B \-R\fP,\fB \-\-rangeset +.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 +.B \-G\fP,\fB \-\-groupbase hide group source prefix (always \fI@groupname\fP) .TP .BI \-S \ SEPARATOR\fR,\fB \ \-\-separator\fB= SEPARATOR @@ -132,13 +135,13 @@ separator string to use when expanding nodesets output format (default: \(aq%s\(aq) .TP .BI \-I \ SLICE_RANGESET\fR,\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 +return sliced off result; examples of SLICE_RANGESET are \(dq0\(dq for simple index selection, or \(dq1\-9/2,16\(dq 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)""" +.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)\(dq\(dq\(dq .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 indices is counted from the end. Because some nodesets may have several different dimensions, axis indices are silently truncated to fall in the allowed range. @@ -225,7 +228,7 @@ node[0\-4,11\-13] .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 +.B \(dqAll nodes\(dq extension 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 @@ -469,17 +472,17 @@ dc3n[4\-5] .SH HISTORY .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. +command and also to conform with ClusterShell\(aqs \(dqclu*\(dq command nomenclature. .SH SEE ALSO .sp \fBclubak\fP(1), \fBclush\fP(1), \fBnodeset\fP(1), \fBgroups.conf\fP(5). .sp -\fI\%http://clustershell.readthedocs.org/\fP + .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 diff --git a/doc/man/man1/clush.1 b/doc/man/man1/clush.1 index aa8870c2..a9d6c737 100644 --- a/doc/man/man1/clush.1 +++ b/doc/man/man1/clush.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH CLUSH 1 "2023-09-29" "1.9.2" "ClusterShell User Manual" -.SH NAME -clush \- execute shell commands on a cluster . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "CLUSH" "1" "2025-01-23" "1.9.3" "ClusterShell User Manual" +.SH NAME +clush \- execute shell commands on a cluster .SH SYNOPSIS .sp \fBclush\fP \fB\-a\fP | \fB\-g\fP \fIgroup\fP | \fB\-w\fP \fInodes\fP [OPTIONS] @@ -156,13 +156,13 @@ local destination. .SH OPTIONS .INDENT 0.0 .TP -.B \-\-version +.B \-\-version show \fBclush\fP version number and exit .TP .BI \-s \ GROUPSOURCE\fR,\fB \ \-\-groupsource\fB= GROUPSOURCE optional \fBgroups.conf\fP(5) group source to use .TP -.B \-n\fP,\fB \-\-nostdin +.B \-n\fP,\fB \-\-nostdin do not watch for possible input from stdin; this should be used when \fBclush\fP is run in the background (or in scripts). .TP .BI \-\-groupsconf\fB= FILE @@ -185,7 +185,7 @@ nodes where to run the command .BI \-x \ NODES exclude nodes from the node list .TP -.B \-a\fP,\fB \-\-all +.B \-a\fP,\fB \-\-all run command on all nodes .TP .BI \-g \ GROUP\fR,\fB \ \-\-group\fB= GROUP @@ -207,43 +207,43 @@ pick N node(s) at random in nodeset .B Output behaviour: .INDENT 7.0 .TP -.B \-q\fP,\fB \-\-quiet +.B \-q\fP,\fB \-\-quiet be quiet, print essential output only .TP -.B \-v\fP,\fB \-\-verbose +.B \-v\fP,\fB \-\-verbose be verbose, print informative messages .TP -.B \-d\fP,\fB \-\-debug +.B \-d\fP,\fB \-\-debug output more messages for debugging purpose .TP -.B \-G\fP,\fB \-\-groupbase +.B \-G\fP,\fB \-\-groupbase do not display group source prefix .TP -.B \-L -disable header block and order output by nodes; if \-b/\-B is not specified, \fBclush\fP will wait for all commands to finish and then display aggregated output of commands with same return codes, ordered by node name; alternatively, when used in conjunction with \-b/\-B (eg. \-bL), \fBclush\fP will enable a "life gathering" of results by line, such as the next line is displayed as soon as possible (eg. when all nodes have sent the line) +.B \-L +disable header block and order output by nodes; if \-b/\-B is not specified, \fBclush\fP will wait for all commands to finish and then display aggregated output of commands with same return codes, ordered by node name; alternatively, when used in conjunction with \-b/\-B (eg. \-bL), \fBclush\fP will enable a \(dqlife gathering\(dq of results by line, such as the next line is displayed as soon as possible (eg. when all nodes have sent the line) .TP -.B \-N +.B \-N disable labeling of command line .TP -.B \-P\fP,\fB \-\-progress +.B \-P\fP,\fB \-\-progress show progress during command execution; if writing is performed to standard input, the live progress indicator will display the global bandwidth of data written to the target nodes .TP -.B \-b\fP,\fB \-\-dshbak +.B \-b\fP,\fB \-\-dshbak display gathered results in a dshbak\-like way (note: it will only try to aggregate the output of commands with same return codes) .TP -.B \-B +.B \-B like \-b but including standard error .TP -.B \-r\fP,\fB \-\-regroup +.B \-r\fP,\fB \-\-regroup fold nodeset using node groups .TP -.B \-S\fP,\fB \-\-maxrc +.B \-S\fP,\fB \-\-maxrc return the largest of command return codes .TP .BI \-\-color\fB= WHENCOLOR \fBclush\fP can use NO_COLOR, CLICOLOR and CLICOLOR_FORCE environment variables. NO_COLOR takes precedence over CLICOLOR_FORCE which takes precedence over CLICOLOR. When \fB\-\-color\fP option is used these environment variables are not taken into account. \fB\-\-color\fP tells whether to use ANSI colors to surround node or nodeset prefix/header with escape sequences to display them in color on the terminal. \fIWHENCOLOR\fP is \fBnever\fP, \fBalways\fP or \fBauto\fP (which use color if standard output/error refer to a terminal). Colors are set to [34m (blue foreground text) for stdout and [31m (red foreground text) for stderr, and cannot be modified. .TP -.B \-\-diff +.B \-\-diff show diff between common outputs (find the best reference output by focusing on largest nodeset and also smaller command return code) .TP .BI \-\-outdir\fB= OUTDIR @@ -256,10 +256,10 @@ output directory for stderr files (OPTIONAL) .B File copying: .INDENT 7.0 .TP -.B \-c\fP,\fB \-\-copy +.B \-c\fP,\fB \-\-copy copy local file or directory to remote nodes .TP -.B \-\-rcopy +.B \-\-rcopy copy file or directory from remote nodes .TP .BI \-\-dest\fB= DEST_PATH @@ -267,7 +267,7 @@ destination file or directory on the nodes (optional: use the first source directory path when not specified) .TP -.B \-p +.B \-p preserve modification times and modes .UNINDENT .TP @@ -281,7 +281,7 @@ do not execute more than FANOUT commands at the same time, useful to limit resou execute remote command as user .TP .BI \-o \ OPTIONS\fR,\fB \ \-\-options\fB= OPTIONS -can be used to give ssh options, eg. \fB\-o "\-p 2022 \-i ~/.ssh/myidrsa"\fP; these options are added first to ssh and override default ones +can be used to give ssh options, eg. \fB\-o \(dq\-p 2022 \-i ~/.ssh/myidrsa\(dq\fP; these options are added first to ssh and override default ones .TP .BI \-t \ CONNECT_TIMEOUT\fR,\fB \ \-\-connect_timeout\fB= CONNECT_TIMEOUT limit time to connect to a node @@ -408,12 +408,12 @@ File in which interactive \fBclush\fP command history is saved. .sp \fBclubak\fP(1), \fBcluset\fP(1), \fBnodeset\fP(1), \fBreadline\fP(3), \fBclush.conf\fP(5), \fBgroups.conf\fP(5). .sp -\fI\%http://clustershell.readthedocs.org/\fP + .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 diff --git a/doc/man/man1/nodeset.1 b/doc/man/man1/nodeset.1 index 26e0d52b..6133528e 100644 --- a/doc/man/man1/nodeset.1 +++ b/doc/man/man1/nodeset.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH NODESET 1 "2023-09-29" "1.9.2" "ClusterShell User Manual" -.SH NAME -nodeset \- compute advanced nodeset operations . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "NODESET" "1" "2025-01-23" "1.9.3" "ClusterShell User Manual" +.SH NAME +nodeset \- compute advanced nodeset operations .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 @@ -53,10 +53,10 @@ administration shell scripts. .INDENT 3.5 .INDENT 0.0 .TP -.B \-\-version +.B \-\-version show program\(aqs version number and exit .TP -.B \-h\fP,\fB \-\-help +.B \-h\fP,\fB \-\-help show this help message and exit .TP .BI \-s \ GROUPSOURCE\fR,\fB \ \-\-groupsource\fB= GROUPSOURCE @@ -70,22 +70,25 @@ use alternate config file for groups.conf(5) .B Commands: .INDENT 7.0 .TP -.B \-c\fP,\fB \-\-count +.B \-c\fP,\fB \-\-count show number of nodes in nodeset(s) .TP -.B \-e\fP,\fB \-\-expand +.B \-e\fP,\fB \-\-expand expand nodeset(s) to separate nodes (see also \-S \fISEPARATOR\fP) .TP -.B \-f\fP,\fB \-\-fold +.B \-f\fP,\fB \-\-fold fold nodeset(s) (or separate nodes) into one nodeset .TP -.B \-l\fP,\fB \-\-list +.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 +.B \-L\fP,\fB \-\-list\-all +list node groups from all group sources (\fB\-LL\fP shows nodes and \fB\-LLL\fP adds node count). Like \fB\-l\fP, if any nodesets are specified as argument, this command will find node groups these nodes belongs to (individually). +.TP +.B \-r\fP,\fB \-\-regroup fold nodes using node groups (see \-s \fIGROUPSOURCE\fP) .TP -.B \-\-groupsources +.B \-\-groupsources list all active group sources (see \fBgroups.conf\fP(5)) .UNINDENT .TP @@ -105,23 +108,23 @@ calculate symmetric difference between nodesets .B Options: .INDENT 7.0 .TP -.B \-a\fP,\fB \-\-all +.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]. +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, \(dqnode2 node4 node6\(dq folds in node[2,4,6] but autostep=3, \(dqnode2 node4 node6\(dq folds in node[2\-6/2]. .TP -.B \-d\fP,\fB \-\-debug +.B \-d\fP,\fB \-\-debug output more messages for debugging purpose .TP -.B \-q\fP,\fB \-\-quiet +.B \-q\fP,\fB \-\-quiet be quiet, print essential output only .TP -.B \-R\fP,\fB \-\-rangeset +.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 +.B \-G\fP,\fB \-\-groupbase hide group source prefix (always \fI@groupname\fP) .TP .BI \-S \ SEPARATOR\fR,\fB \ \-\-separator\fB= SEPARATOR @@ -132,13 +135,13 @@ separator string to use when expanding nodesets output format (default: \(aq%s\(aq) .TP .BI \-I \ SLICE_RANGESET\fR,\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 +return sliced off result; examples of SLICE_RANGESET are \(dq0\(dq for simple index selection, or \(dq1\-9/2,16\(dq 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)""" +.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)\(dq\(dq\(dq .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 indices is counted from the end. Because some nodesets may have several different dimensions, axis indices are silently truncated to fall in the allowed range. @@ -225,7 +228,7 @@ node[0\-4,11\-13] .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 +.B \(dqAll nodes\(dq extension 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 @@ -493,17 +496,17 @@ node[1\-2,4,7\-8] .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. +command and also to conform with ClusterShell\(aqs \(dqclu*\(dq command nomenclature. .SH SEE ALSO .sp \fBclubak\fP(1), \fBcluset\fP(1), \fBclush\fP(1), \fBgroups.conf\fP(5). .sp -\fI\%http://clustershell.readthedocs.org/\fP + .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 diff --git a/doc/man/man5/clush.conf.5 b/doc/man/man5/clush.conf.5 index f94fcf77..d2bab5c8 100644 --- a/doc/man/man5/clush.conf.5 +++ b/doc/man/man5/clush.conf.5 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH CLUSH.CONF 5 "2023-09-29" "1.9.2" "ClusterShell User Manual" -.SH NAME -clush.conf \- Configuration file for clush . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "CLUSH.CONF" "5" "2025-01-23" "1.9.3" "ClusterShell User Manual" +.SH NAME +clush.conf \- Configuration file for clush .SH DESCRIPTION .sp \fBclush\fP(1) obtains configuration options from the following sources in the @@ -76,7 +76,7 @@ initiate up to \fB16\fP connections to their target nodes at the same time. Optional list of directory paths where clush should look for \fI\&.conf\fP files which define run modes that can then be activated with \fB\-\-mode\fP\&. All other clush config file settings defined here might be overridden in a run mode. -Each mode section should have a name prefixed by "mode:" to clearly identify +Each mode section should have a name prefixed by \(dqmode:\(dq to clearly identify a section defining a mode. Duplicate modes are not allowed in those files. Configuration files that are not readable by the current user are ignored. The variable \fI$CFGDIR\fP is replaced by the path of the highest priority @@ -221,7 +221,7 @@ from \fIclush.conf\fP\&. External commands whose outputs were used by \fBclush\ .sp \fBclush\fP(1), \fBgroups.conf\fP(5), \fBsshpass\fP(1), \fBsudo\fP(8). .sp -\fI\%http://clustershell.readthedocs.org/\fP + .SH AUTHOR Stephane Thiell, .SH COPYRIGHT diff --git a/doc/man/man5/groups.conf.5 b/doc/man/man5/groups.conf.5 index 4640d1c9..d252b651 100644 --- a/doc/man/man5/groups.conf.5 +++ b/doc/man/man5/groups.conf.5 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH GROUPS.CONF 5 "2023-09-29" "1.9.2" "ClusterShell User Manual" -.SH NAME -groups.conf \- Configuration file for ClusterShell node groups . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "GROUPS.CONF" "5" "2025-01-23" "1.9.3" "ClusterShell User Manual" +.SH NAME +groups.conf \- Configuration file for ClusterShell node groups .SH DESCRIPTION .sp The ClusterShell library obtains its node groups configuration from the @@ -76,7 +76,7 @@ Configuration parameters of the \fBMain\fP section are described below. .TP .B 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"). +when the user does not explicitly specify the group source (eg. \(dq@io\(dq). .TP .B confdir Optional list of directories where the ClusterShell library should look for @@ -175,10 +175,10 @@ map: sed \-n \(aqs/^$GROUP:(.*)/1/p\(aq /etc/clustershell/groups list: sed \-n \(aqs/^\e(\fB[0\-9A\-Za\-z_\-]\fP*\e):.*/\e1/p\(aq /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 +map: sinfo \-h \-o \(dq%N\(dq \-p $GROUP +all: sinfo \-h \-o \(dq%N\(dq +list: sinfo \-h \-o \(dq%P\(dq +reverse: sinfo \-h \-N \-o \(dq%P\(dq \-n $NODE .fi .sp .SH FILES @@ -206,7 +206,7 @@ Local groups.conf user configuration file (default installation for pip \-\-user .sp \fBclubak\fP(1), \fBcluset\fP(1), \fBclush\fP(1), \fBnodeset\fP(1) .sp -\fI\%http://clustershell.readthedocs.org/\fP + .SH AUTHOR Stephane Thiell, .SH COPYRIGHT diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py index 4e474376..b348cc24 100644 --- a/doc/sphinx/conf.py +++ b/doc/sphinx/conf.py @@ -25,7 +25,7 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx_rtd_theme'] +extensions = ['sphinx.ext.autodoc', 'sphinx_rtd_theme', 'sphinxcontrib.asciinema'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -40,17 +40,17 @@ master_doc = 'index' # General information about the project. -project = u'clustershell' -copyright = u'2023, Stephane Thiell' +project = u'clustershell-test' +copyright = u'2025, Stephane Thiell' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '1.9.2' +version = '1.9.3' # The full version, including alpha/beta/rc tags. -release = '1.9.2' +release = '1.9.3' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -126,7 +126,7 @@ def setup(app): if 'READTHEDOCS' in os.environ: # RTD does not line wrap CSV tables, so we override this behavior. - app.add_stylesheet("theme_overrides.css") + app.add_css_file("theme_overrides.css") # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/doc/sphinx/config.rst b/doc/sphinx/config.rst index 9df32af4..6a626d0e 100644 --- a/doc/sphinx/config.rst +++ b/doc/sphinx/config.rst @@ -504,7 +504,28 @@ partitions named *kepler* and *pascal*:: .. highlight:: ini -The second section **slurmstate,st** defines a group source based on Slurm +The second section **slurmresv,sr** defines a group source based on Slurm +reservations. Each group is based on a different reservation and contains +the nodes currently in that reservation:: + + [slurmresv,sr] + map: scontrol -o show reservation $GROUP | grep -Po 'Nodes=\K[^ ]+' + all: scontrol -o show reservation | grep -Po 'Nodes=\K[^ ]+' + list: scontrol -o show reservation | grep -Po 'ReservationName=\K[^ ]+' + cache_time: 60 + +.. highlight:: console + +Example of use on a cluster having a reservation in place for an upcoming +system maintenance:: + + $ nodeset -s slurmresv -l + @slurmresv:Maintenance_2025-02-04 + $ clush -w @slurmresv:Maintenance_2025-02-04 uptime + +.. highlight:: ini + +The next section **slurmstate,st** defines a group source based on Slurm node states. Each group is based on a different state name and contains the nodes currently in that state:: @@ -530,7 +551,7 @@ are in the Slurm state *drained*:: .. highlight:: ini -The third section **slurmjob,sj** defines a group source based on Slurm jobs. +The next section **slurmjob,sj** defines a group source based on Slurm jobs. Each group is based on a running job ID and contains the nodes currently allocated for this job:: @@ -540,7 +561,7 @@ allocated for this job:: reverse: squeue -h -w $NODE -o "%i" cache_time: 60 -The fourth section **slurmuser,su** defines a group source based on Slurm users. +The next section **slurmuser,su** defines a group source based on Slurm users. Each group is based on a username and contains the nodes currently allocated for jobs belonging to the username:: @@ -550,6 +571,8 @@ allocated for jobs belonging to the username:: reverse: squeue -h -w $NODE -o "%i" cache_time: 60 +.. highlight:: console + Example of use with :ref:`clush ` to execute a command on all nodes with running jobs of username:: @@ -561,12 +584,44 @@ of the default (3600s) to avoid caching results in memory for too long, because this group source is likely very dynamic (this is only useful for long-running processes, not one-shot commands). +.. highlight:: ini + +The next section **slurmaccount,sa** defines a group source based on Slurm +accounts. Each group is based on a account and contains the nodes where there +are running jobs under this account:: + + [slurmaccount,sa] + map: squeue -h -A $GROUP -o "%N" -t R + list: squeue -h -o "%a" -t R + reverse: squeue -h -w $NODE -o "%a" 2>/dev/null || true + cache_time: 60 + +.. highlight:: console + +For example, to find all nodes that have running jobs from the account ``ruthm``:: + + $ cluset -f @sa:ruthm + sh02-01n57,sh03-09n51,sh03-11n10 + +.. highlight:: ini + +The next section **slurmqos,sq** defines a group source based on Slurm QoS. +Each group is based on a qos and contains the nodes where there are running +jobs under this qos:: + + [slurmqos,sq] + map: squeue -h -q $GROUP -o "%N" -t R + list: squeue -h -o "%q" -t R + reverse: squeue -h -w $NODE -o "%q" 2>/dev/null || true + cache_time: 60 + .. highlight:: console -You can then easily find nodes associated with a Slurm job ID:: +Then it is easy to find nodes currently running jobs in a specified qos, here +in qos ``long`` for example:: - $ nodeset -f @sj:686518 - cluster-[0003,0005,0010,0012,0015,0017,0021,0055] + $ cluset -f @slurmqos:long + sh02-01n[01-02,16-17,45,51,56],sh03-01n[02,29,61] .. _group-xcat-bindings: diff --git a/doc/sphinx/install.rst b/doc/sphinx/install.rst index 94dc511c..0d62fe48 100644 --- a/doc/sphinx/install.rst +++ b/doc/sphinx/install.rst @@ -19,6 +19,12 @@ Requirements ClusterShell should work with any Unix [#]_ operating systems which provides Python 2.7 or 3.x and OpenSSH or any compatible Secure Shell clients. +.. warning:: While we are making our best effort to maintain Python 2 + compatibility in ClusterShell 1.9.x, we no longer run tests for Python 2. + Therefore, functionality on Python 2 is not guaranteed and may break without + notice. For the best experience and continued support, it is strongly + recommended to use Python 3. + Furthermore, ClusterShell's engine has been optimized when the ``poll()`` syscall is available or even better, when the ``epoll_wait()`` syscall is available (Linux only). @@ -93,7 +99,7 @@ Red Hat Enterprise Linux ClusterShell packages are maintained on Extra Packages for Enterprise Linux `EPEL`_ for Red Hat Enterprise Linux (RHEL) and its compatible spinoffs such as `Alma Linux`_ and `Rocky Linux`_. At the time of writing, ClusterShell |version| -is available on EPEL 7, 8 and 9. +is available on EPEL 8 and 9. Install ClusterShell from EPEL @@ -103,25 +109,18 @@ First you have to enable the ``yum`` EPEL repository. We recommend to download and install the `EPEL`_ repository RPM package. On CentOS, this can be easily done using the following command:: - $ yum --enablerepo=extras install epel-release + $ dnf --enablerepo=extras install epel-release Then, the ClusterShell installation procedure is quite the same as for *Fedora Updates*, for instance:: - $ yum install clustershell + $ dnf install clustershell -With EPEL 7, the Python 2 modules and tools are installed by default. If -interested in Python 3 support, simply install the additional ClusterShell's +The Python 3 modules and tools are installed by default with ``clustershell``. +If interested in the Python 3 library only, you can install ClusterShell's Python 3 subpackage using the following command:: - $ yum install python36-clustershell - -.. note:: The Python 3 subpackage is named ``python34-clustershell`` or - ``python36-clustershell`` instead of ``python3-clustershell`` - on EPEL 7 only. - -On EPEL 7, Python 3 versions of the tools are installed as *tool-pythonversion*, -like ``clush-3.6``, ``cluset-3.6`` or ``nodeset-3.6``. + $ dnf install python3-clustershell With EPEL 8 and 9, however, Python 3 is the system default, and Python 2 has been deprecated. Thus only Python 3 is supported by the EPEL clustershell @@ -130,7 +129,7 @@ packages, the tools are using Python 3 by default and are not suffixed anymore. Fedora ^^^^^^ -At the time of writing, ClusterShell |version| is available on Fedora 37 +At the time of writing, ClusterShell |version| is available on Fedora 41 (releases being maintained by the Fedora Project). Install ClusterShell from *Fedora Updates* diff --git a/doc/sphinx/release.rst b/doc/sphinx/release.rst index d47f333d..9fcd6c8a 100644 --- a/doc/sphinx/release.rst +++ b/doc/sphinx/release.rst @@ -10,6 +10,41 @@ We are pleased to announce the availability of this new release, which comes with some exciting new features and improvements. We would like to thank everyone who participated in this release in a way or another. + +Version 1.9.3 +^^^^^^^^^^^^^ + +This version contains various performance improvements over 1.9.2, notably in +tree mode, and introduces bash completion for command line tools. + +* Added bash completions for :ref:`clush-tool`, + :ref:`nodeset-tool`/:ref:`cluset-tool` + + Demonstration of bash completions: + + .. asciinema:: 699526 + +* :ref:`Slurm group bindings `: additional Slurm group + source definitions have been included to enhance Slurm interaction + capabilities (added ``slurmaccount``, ``slurmqos`` and ``slurmresv``). + +* :ref:`clush-tool` now uses ``set`` instead of :class:`.NodeSet` for runtime + progress information which improves performance. + +* Updated :ref:`tree mode ` to use ``set`` instead of + :class:`.NodeSet` for gateway tracking, optimizing performance for large + clusters. + +For more details, please have a look at `GitHub Issues for 1.9.3 milestone`_. + +.. warning:: While we are making our best effort to maintain Python 2 + compatibility in ClusterShell 1.9.x, we no longer run tests for Python 2. + Therefore, functionality on Python 2 is not guaranteed and may break without + notice. For the best experience and continued support, it is strongly + recommended to use Python 3. + +.. note:: ClusterShell 1.9.3 has been tested with Python versions 3.6 to 3.13. + Version 1.9.2 ^^^^^^^^^^^^^ @@ -743,6 +778,7 @@ Please see :ref:`install-pip-user`. .. _GitHub Issues for 1.9 milestone: https://github.com/cea-hpc/clustershell/issues?utf8=%E2%9C%93&q=is%3Aissue+milestone%3A1.9 .. _GitHub Issues for 1.9.1 milestone: https://github.com/cea-hpc/clustershell/issues?q=milestone%3A1.9.1 .. _GitHub Issues for 1.9.2 milestone: https://github.com/cea-hpc/clustershell/issues?q=milestone%3A1.9.2 +.. _GitHub Issues for 1.9.3 milestone: https://github.com/cea-hpc/clustershell/issues?q=milestone%3A1.9.3 .. _LGPL v2.1+: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html .. _CeCILL-C V1: http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html .. _xCAT: https://xcat.org/ diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt index 93120e66..32355ece 100644 --- a/doc/sphinx/requirements.txt +++ b/doc/sphinx/requirements.txt @@ -1 +1,7 @@ -docutils<0.18 +sphinx==6.2.1 +sphinx-rtd-theme==1.2.2 +pillow==5.4.1 +mock==1.0.1 +commonmark==0.9.1 +recommonmark==0.5.0 +sphinxcontrib.asciinema==0.4.2 diff --git a/doc/sphinx/tools/clubak.rst b/doc/sphinx/tools/clubak.rst index 933ffa36..73ea5e38 100644 --- a/doc/sphinx/tools/clubak.rst +++ b/doc/sphinx/tools/clubak.rst @@ -39,7 +39,7 @@ Indeed, *clubak* formats text from standard input containing lines of the form with *pdsh* but provides additional features. For instance, *clubak* always displays its results sorted by node/nodeset. -But you do not need to execute *clubak* when using *clush* as all output +You do NOT need to execute *clubak* when using *clush* as all output formatting features are already included in *clush* (see *clush -b / -B / -L* examples, :ref:`clush-oneshot`). There are several advantages of having *clubak* features included in *clush*: for example, it is possible, with diff --git a/doc/sphinx/tools/cluset.rst b/doc/sphinx/tools/cluset.rst index 3a24bb08..5e419220 100644 --- a/doc/sphinx/tools/cluset.rst +++ b/doc/sphinx/tools/cluset.rst @@ -5,6 +5,1073 @@ cluset .. highlight:: console -The *cluset* command is the same as :ref:`nodeset-tool` and has been added -in ClusterShell 1.7.3 to avoid a conflict with xCAT's nodeset command. +.. note:: The **cluset** command is introduced in ClusterShell version 1.7.3 as + an alternative to the :ref:`nodeset-tool` command to avoid conflicts + with the **nodeset** command from xCAT. Users are encouraged to + transition to using **cluset** for their range/node/group set + management tasks. + +The *cluset* command enables easy manipulation of node and range sets, as +well as node groups, at the command line level. As it is user-friendly and +efficient, the *cluset* command can quickly improve traditional cluster +shell scripts. It is also full-featured as it provides most of the +:class:`.NodeSet` and :class:`.RangeSet` class methods (see also +:ref:`class-NodeSet`, and :ref:`class-RangeSet`). + +Most of the examples in this section are using simple indexed node sets, +however, *cluset* supports multidimensional node sets, like +``dc[1-2]n[1-99]``, introduced in version 1.7 (see :ref:`class-RangeSetND` +for more info). + +This section will guide you through the basics and also more advanced features +of *cluset*. + +Usage basics +^^^^^^^^^^^^ + +One exclusive command must be specified to *cluset*, for example:: + + $ cluset --expand node[13-15,17-19] + node13 node14 node15 node17 node18 node19 + + $ cluset --count node[13-15,17-19] + 6 + + $ cluset --fold node1-ipmi node2-ipmi node3-ipmi + node[1-3]-ipmi + + +Commands with inputs +"""""""""""""""""""" + +Some *cluset* commands require input (eg. node names, node sets or node +groups), and some only give output. The following table shows commands that +require some input: + ++-------------------+--------------------------------------------------------+ +| Command | Description | ++===================+========================================================+ +| ``-c``, | Count and display the total number of nodes in node | +| ``--count`` | sets or/and node groups. | ++-------------------+--------------------------------------------------------+ +| ``-e``, | Expand node sets or/and node groups as unitary node | +| ``--expand`` | names separated by current separator string (see | +| | ``--separator`` option described in | +| | :ref:`cluset-commands-formatting`). | ++-------------------+--------------------------------------------------------+ +| ``-f``, | Fold (compact) node sets or/and node groups into one | +| ``--fold`` | set of nodes (by previously resolving any groups). The | +| | resulting node set is guaranteed to be free from node | +| | ``--regroup`` below if you want to resolve node groups | +| | in result). Please note that folding may be time | +| | consuming for multidimensional node sets. | ++-------------------+--------------------------------------------------------+ +| ``-r``, | Fold (compact) node sets or/and node groups into one | +| ``--regroup`` | set of nodes using node groups whenever possible (by | +| | previously resolving any groups). | +| | See :ref:`cluset-groups`. | ++-------------------+--------------------------------------------------------+ + + +There are three ways to give some input to the *cluset* command: + +* from command line arguments, +* from standard input (enabled when no arguments are found on command line), +* from both command line and standard input, by using the dash special + argument ``-`` meaning you need to use stdin instead. + +The following example illustrates the three ways to feed *cluset*:: + + $ cluset -f node1 node6 node7 + node[1,6-7] + + $ echo node1 node6 node7 | cluset -f + node[1,6-7] + + $ echo node1 node6 node7 | cluset -f node0 - + node[0-1,6-7] + + +Furthermore, *cluset*'s standard input reader is able to process multiple +lines and multiple node sets or groups per line. The following example shows a +simple use case:: + + $ mount -t nfs | cut -d':' -f1 + nfsserv1 + nfsserv2 + nfsserv3 + + $ mount -t nfs | cut -d':' -f1 | cluset -f + nfsserv[1-3] + + +Other usage examples of *cluset* below show how it can be useful to provide +node sets from standard input (*sinfo* is a SLURM [#]_ command to view nodes +and partitions information and *sacct* is a command to display SLURM +accounting data):: + + $ sinfo -p cuda -o '%N' -h + node[156-159] + + $ sinfo -p cuda -o '%N' -h | cluset -e + node156 node157 node158 node159 + + $ for node in $(sinfo -p cuda -o '%N' -h | cluset -e); do + sacct -a -N $node > /tmp/cudajobs.$node; + done + +Previous rules also apply when working with node groups, for example when +using ``cluset -r`` reading from standard input (and a matching group is +found):: + + $ cluset -f @gpu + node[156-159] + + $ sinfo -p cuda -o '%N' -h | cluset -r + @gpu + +Most commands described in this section produce output results that may be +formatted using ``--output-format`` and ``--separator`` which are described in +:ref:`cluset-commands-formatting`. + +Commands with no input +"""""""""""""""""""""" + +The following table shows all other commands that are supported by +*cluset*. These commands don't support any input (like node sets), but can +still recognize options as specified below. + ++--------------------+-----------------------------------------------------+ +| Command w/o input | Description | ++====================+=====================================================+ +| ``-l``, ``--list`` | List node groups from selected *group source* as | +| | specified with ``-s`` or ``--groupsource``. If | +| | not specified, node groups from the default *group | +| | source* are listed (see :ref:`groups configuration | +| | ` for default *group source* | +| | configuration). | ++--------------------+-----------------------------------------------------+ +| ``--groupsources`` | List all configured *group sources*, one per line, | +| | as configured in *groups.conf* (see | +| | :ref:`groups configuration `). | +| | The default *group source* is appended with | +| | `` (default)``, unless the ``-q``, ``--quiet`` | +| | option is specified. This command is mainly here to | +| | avoid reading any configuration files, or to check | +| | if all work fine when configuring *group sources*. | ++--------------------+-----------------------------------------------------+ + +.. _cluset-commands-formatting: + +Output result formatting +"""""""""""""""""""""""" + +When using the expand command (``-e, --expand``), a separator string is used +when displaying results. The option ``-S``, ``--separator`` allows you to +modify it. The specified string is interpreted, so that you can use special +characters as separator, like ``\n`` or ``\t``. The default separator is the +space character *" "*. This is an example showing such separator string +change:: + + $ cluset -e --separator='\n' node[0-3] + node0 + node1 + node2 + node3 + +The ``-O, --output-format`` option can be used to format output results of +most *cluset* commands. The string passed to this option is used as a base +format pattern applied to each node or each result (depending on the command +and other options requested). The default format string is *"%s"*. Formatting +is performed using the Python builtin string formatting operator, so you must +use one format operator of the right type (*%s* is guaranteed to work in all +cases). Here is an output formatting example when using the expand command:: + + $ cluset --output-format='%s-ipmi' -e node[1-2]x[1-2] + node1x1-ipmi node1x2-ipmi node2x1-ipmi node2x2-ipmi + +Output formatting and separator combined can be useful when using the expand +command, as shown here:: + + $ cluset -O '%s-ipmi' -S '\n' -e node[1-2]x[1-2] + node1x1-ipmi + node1x2-ipmi + node2x1-ipmi + node2x2-ipmi + +When using the output formatting option along with the folding command, the +format is applied to each node but the result is still folded:: + + $ cluset -O '%s-ipmi' -f mgmt1 mgmt2 login[1-4] + login[1-4]-ipmi,mgmt[1-2]-ipmi + + +.. _cluset-stepping: + +Stepping and auto-stepping +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The *cluset* command, as does the *clush* command, is able to recognize by +default a factorized notation for range sets of the form *a-b/c*, indicating a +list of integers starting from *a*, less than or equal to *b* with the +increment (step) *c*. + +For example, the *0-6/2* format indicates a range of 0-6 stepped by 2; that +is 0,2,4,6:: + + $ cluset -e node[0-6/2] + node0 node2 node4 node6 + +However, by default, *cluset* never uses this stepping notation in output +results, as other cluster tools seldom if ever support this feature. Thus, to +enable such factorized output in *cluset*, you must specify +``--autostep=AUTOSTEP`` to set an auto step threshold number when folding +nodesets (ie. when using ``-f`` or ``-r``). This threshold number +(AUTOSTEP) is the minimum occurrence of equally-spaced integers needed to +enable auto-stepping. + +For example:: + + $ cluset -f --autostep=3 node1 node3 node5 + node[1-5/2] + + $ cluset -f --autostep=4 node1 node3 node5 + node[1,3,5] + +It is important to note that resulting node sets with enabled auto-stepping +never create overlapping ranges, for example:: + + $ cluset -f --autostep=3 node1 node5 node9 node13 + node[1-13/4] + + $ cluset -f --autostep=3 node1 node5 node7 node9 node13 + node[1,5-9/2,13] + +However, any ranges given as input may still overlap (in this case, *cluset* +will automatically spread them out so that they do not overlap), for example:: + + $ cluset -f --autostep=3 node[1-13/4,7] + node[1,5-9/2,13] + + +A minimum node count threshold **percentage** before autostep is enabled may +also be specified as autostep value (or ``auto`` which is currently 100%). In +the two following examples, only the first 4 of the 7 indexes may be +represented using the step syntax (57% of them):: + + $ cluset -f --autostep=50% node[1,3,5,7,34,39,99] + node[1-7/2,34,39,99] + + $ cluset -f --autostep=90% node[1,3,5,7,34,39,99] + node[1,3,5,7,34,39,99] + + +.. _cluset-zeropadding: + +Zero-padding +^^^^^^^^^^^^ + +Sometimes, cluster node names are padded with zeros (eg. *node007*). With +*cluset*, when leading zeros are used, resulting host names or node sets +are automatically padded with zeros as well. For example:: + + $ cluset -e node[08-11] + node08 node09 node10 node11 + + $ cluset -f node001 node002 node003 node005 + node[001-003,005] + +Zero-padding and stepping (as seen in :ref:`cluset-stepping`) together are +also supported, for example:: + + $ cluset -e node[000-012/4] + node000 node004 node008 node012 + +Since v1.9, mixed length padding is allowed, for example:: + + $ cluset -f node2 node01 node001 + node[2,01,001] + +When mixed length zero-padding is encountered, indexes with smaller padding +length are returned first, as you can see in the example above (``2`` comes +before ``01``). + +Since v1.9, when using node sets with multiple dimensions, each dimension (or +axis) may also use mixed length zero-padding:: + + $ cluset -f foo1bar1 foo1bar00 foo1bar01 foo004bar1 foo004bar00 foo004bar01 + foo[1,004]bar[1,00-01] + + +Leading and trailing digits +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Version 1.7 introduces improved support for bracket leading and trailing +digits. Those digits are automatically included within the range set, +allowing all node set operations to be fully supported. + +Examples with bracket leading digits:: + + $ cluset -f node-00[00-99] + node-[0000-0099] + + $ cluset -f node-01[01,09,42] + node-[0101,0109,0142] + +Examples with bracket trailing digits:: + + $ cluset -f node-[1-2]0-[0-2]5 + node-[10,20]-[05,15,25] + +Examples with both bracket leading and trailing digits:: + + $ cluset -f node-00[1-6]0 + node-[0010,0020,0030,0040,0050,0060] + + $ cluset --autostep=auto -f node-00[1-6]0 + node-[0010-0060/10] + +Example with leading digit and mixed length zero padding (supported since +v1.9):: + + $ cluset -f node1[00-02,000-032/8] + node[100-102,1000,1008,1016,1024,1032] + +Using this syntax can be error-prone especially if used with node sets +without 0-padding or with the */step* syntax and also requires additional +processing by the parser. In general, we recommend writing the whole rangeset +inside the brackets. + +.. warning:: Using the step syntax (seen above) within a bracket-delimited + range set is not compatible with **trailing** digits. For instance, this is + **not** supported: ``node-00[1-6/2]0`` + +.. _cluset-arithmetic: + +Arithmetic operations +^^^^^^^^^^^^^^^^^^^^^ + +As a preamble to this section, keep in mind that all operations can be +repeated/mixed within the same *cluset* command line, they will be +processed from left to right. + +Union operation +""""""""""""""" + +Union is the easiest arithmetic operation supported by *cluset*: there is +no special command line option for that, just provide several node sets and +the union operation will be computed, for example:: + + $ cluset -f node[1-3] node[4-7] + node[1-7] + + $ cluset -f node[1-3] node[2-7] node[5-8] + node[1-8] + +Other operations +"""""""""""""""" + +As an extension to the above, other arithmetic operations are available by +using the following command-line options (*working set* is the node set +currently processed on the command line -- always from left to right): + ++--------------------------------------------+---------------------------------+ +| *cluset* command option | Operation | ++============================================+=================================+ +| ``-x NODESET``, ``--exclude=NODESET`` | compute a new set with elements | +| | in *working set* but not in | +| | ``NODESET`` | ++--------------------------------------------+---------------------------------+ +| ``-i NODESET``, ``--intersection=NODESET`` | compute a new set with elements | +| | common to *working set* and | +| | ``NODESET`` | ++--------------------------------------------+---------------------------------+ +| ``-X NODESET``, ``--xor=NODESET`` | compute a new set with elements | +| | that are in exactly one of the | +| | *working set* and ``NODESET`` | ++--------------------------------------------+---------------------------------+ + + +If rangeset mode (``-R``) is turned on, all arithmetic operations are +supported by replacing ``NODESET`` by any ``RANGESET``. See +:ref:`cluset-rangeset` for more info about *cluset*'s rangeset mode. + + +Arithmetic operations usage examples:: + + $ cluset -f node[1-9] -x node6 + node[1-5,7-9] + + $ cluset -f node[1-9] -i node[6-11] + node[6-9] + + $ cluset -f node[1-9] -X node[6-11] + node[1-5,10-11] + + $ cluset -f node[1-9] -x node6 -i node[6-12] + node[7-9] + +.. _cluset-extended-patterns: + +*Extended patterns* support +""""""""""""""""""""""""""" + +*cluset* does also support arithmetic operations through its "extended +patterns" (inherited from :class:`.NodeSet` extended pattern feature, see +:ref:`class-NodeSet-extended-patterns`, there is an example of use:: + + $ cluset -f node[1-4],node[5-9] + node[1-9] + + $ cluset -f node[1-9]\!node6 + node[1-5,7-9] + + $ cluset -f node[1-9]\&node[6-12] + node[6-9] + + $ cluset -f node[1-9]^node[6-11] + node[1-5,10-11] + +.. _cluset-special: + +Special operations +^^^^^^^^^^^^^^^^^^ + +A few special operations are currently available: node set slicing, splitting +on a predefined node count, splitting non-contiguous subsets, choosing fold +axis (for multidimensional node sets) and picking N nodes randomly. They are +all explained below. + +.. _cluset-slice: + +Slicing +""""""" + +Slicing is a way to select elements from a node set by their index (or from a +range set when using ``-R`` toggle option, see :ref:`cluset-rangeset`. In +this case actually, and because *cluset*'s underlying :class:`.NodeSet` class +sorts elements as observed after folding (for example), the word *set* may +sound like a stretch of language (a *set* isn't usually sorted). Indeed, +:class:`.NodeSet` further guarantees that its iterator will traverse the set +in order, so we should see it as a *ordered set*. The following simple example +illustrates this sorting behavior:: + + $ cluset -f b2 b1 b0 b c a0 a + a,a0,b,b[0-2],c + +Slicing is performed through the following command-line option: + ++---------------------------------------+-----------------------------------+ +| *cluset* command option | Operation | ++=======================================+===================================+ +| ``-I RANGESET``, ``--slice=RANGESET`` | *slicing*: get sliced off result, | +| | selecting elements from provided | +| | rangeset's indexes | ++---------------------------------------+-----------------------------------+ + +Some slicing examples are shown below:: + + $ cluset -f -I 0 node[4-8] + node4 + + $ cluset -f --slice=0 bnode[0-9] anode[0-9] + anode0 + + $ cluset -f --slice=1,4,7,9,15 bnode[0-9] anode[0-9] + anode[1,4,7,9],bnode5 + + $ cluset -f --slice=0-18/2 bnode[0-9] anode[0-9] + anode[0,2,4,6,8],bnode[0,2,4,6,8] + + +Splitting into *n* subsets +"""""""""""""""""""""""""" + +Splitting a node set into several parts is often useful to get separate groups +of nodes, for instance when you want to check MPI comm between nodes, etc. +Based on :meth:`.NodeSet.split` method, the *cluset* command provides the +following additional command-line option (since v1.4): + ++--------------------------+--------------------------------------------+ +| *cluset* command option | Operation | ++==========================+============================================+ +| ``--split=MAXSPLIT`` | *splitting*: split result into a number of | +| | subsets | ++--------------------------+--------------------------------------------+ + +``MAXSPLIT`` is an integer specifying the number of separate groups of nodes +to compute. Input's node set is divided into smaller groups, whenever possible +with the same size (only the last ones may be smaller due to rounding). +Obviously, if ``MAXSPLIT`` is higher than or equal to the number N of elements +in the set, then the set is split to N single sets. + +Some node set splitting examples:: + + $ cluset -f --split=4 node[0-7] + node[0-1] + node[2-3] + node[4-5] + node[6-7] + + $ cluset -f --split=4 node[0-6] + node[0-1] + node[2-3] + node[4-5] + node6 + + $ cluset -f --split=10000 node[0-4] + foo0 + foo1 + foo2 + foo3 + foo4 + + $ cluset -f --autostep=3 --split=2 node[0-38/2] + node[0-18/2] + node[20-38/2] + + +Splitting off non-contiguous subsets +"""""""""""""""""""""""""""""""""""" + +It can be useful to split a node set into several contiguous subsets (with +same pattern name and contiguous range indexes, eg. *node[1-100]* or +*dc[1-4]node[1-100]*). The ``--contiguous`` option allows you to do that. It +is based on :meth:`.NodeSet.contiguous` method, and should be specified with +standard commands (fold, expand, count, regroup). The following example shows +how to split off non-contiguous subsets of a specified node set, and to +display each resulting contiguous node set in a folded manner to separated +lines:: + + $ cluset -f --contiguous node[1-100,200-300,500] + node[1-100] + node[200-300] + node500 + + +Similarly, the following example shows how to display each resulting +contiguous node set in an expanded manner to separate lines:: + + $ cluset -e --contiguous node[1-9,11-19] + node1 node2 node3 node4 node5 node6 node7 node8 node9 + node11 node12 node13 node14 node15 node16 node17 node18 node19 + + +Choosing fold axis (nD) +""""""""""""""""""""""" + +The default folding behavior for multidimensional node sets is to fold along +all *nD* axis. However, other cluster tools barely support nD nodeset syntax, +so it may be useful to fold along one (or a few) axis only. The ``--axis`` +option allows you to specify indexes of dimensions to fold. Using this +option, rangesets of unspecified axis there won't be folded. Please note +however that the obtained result may be suboptimal, this is because +:class:`.NodeSet` algorithms are optimized for folding along all axis. +``--axis`` value is a set of integers from 1 to n representing selected nD +axis, in the form of a number or a rangeset. A common case is to restrict +folding on a single axis, like in the following simple examples:: + + $ cluset --axis=1 -f node1-ib0 node2-ib0 node1-ib1 node2-ib1 + node[1-2]-ib0,node[1-2]-ib1 + + $ cluset --axis=2 -f node1-ib0 node2-ib0 node1-ib1 node2-ib1 + node1-ib[0-1],node2-ib[0-1] + +Because a single nodeset may have several different dimensions, axis indices +are silently truncated to fall in the allowed range. Negative indices are +useful to fold along the last axis whatever number of dimensions used:: + + $ cluset --axis=-1 -f comp-[1-2]-[1-36],login-[1-2] + comp-1-[1-36],comp-2-[1-36],login-[1-2] + +See also the :ref:`defaults-config-slurm` of Library Defaults for changing it +permanently. + +.. _cluset-pick: + +Picking N node(s) at random +""""""""""""""""""""""""""" + +Use ``--pick`` with a maximum number of nodes you wish to pick randomly from +the resulting node set (or from the resulting range set with ``-R``):: + + $ cluset --pick=1 -f node11 node12 node13 + node12 + $ cluset --pick=2 -f node11 node12 node13 + node[11,13] + + +.. _cluset-groups: + +Node groups +^^^^^^^^^^^ + +This section tackles the node groups feature available more particularly +through the *cluset* command-line tool. The ClusterShell library defines a +node groups syntax and allow you to bind these group sources to your +applications (cf. :ref:`node groups configuration `). Having +those group sources, group provisioning is easily done through user-defined +external shell commands. Thus, node groups might be very dynamic and their +nodes might change very often. However, for performance reasons, external call +results are still cached in memory to avoid duplicate external calls during +*cluset* execution. For example, a group source can be bound to a resource +manager or a custom cluster database. + +For further details about using node groups in Python, please see +:ref:`class-NodeSet-groups`. For advanced usage, you should also be able to +define your own group source directly in Python (cf. +:ref:`class-NodeSet-groups-override`). + +.. _cluset-groupsexpr: + +Node group expression rules +""""""""""""""""""""""""""" + +The general node group expression is ``@source:groupname``. For example, +``@slurm:bigmem`` represents the group *bigmem* of the group source *slurm*. +Moreover, a shortened expression is available when using the default group +source (defined by configuration); for instance ``@compute`` represents the +*compute* group of the default group source. + +Valid group source names and group names can contain alphanumeric characters, +hyphens and underscores (no space allowed). Indeed, same rules apply to node +names. + +Listing group sources +""""""""""""""""""""" + +As already mentioned, the following *cluset* command is available to list +configured group sources and also display the default group source (unless +``-q`` is provided):: + + $ cluset --groupsources + local (default) + genders + slurm + +Listing group names +""""""""""""""""""" + +It is always possible to list the groups from a group source if the source is +:ref:`file-based `. +If the source is an :ref:`external group source `, the +**list** upcall must be configured (see also: +:ref:`node groups configuration `). + +To list available groups *from the default source*, use the following command:: + + $ cluset -l + @mgnt + @mds + @oss + @login + @compute + +To list groups *from a specific group source*, use *-l* in conjunction +with *-s* (or *--groupsource*):: + + $ cluset -l -s slurm + @slurm:parallel + @slurm:cuda + +Or, to list groups *from all available group sources*, use *-L* (or +*--list-all*):: + + $ cluset -L + @mgnt + @mds + @oss + @login + @compute + @slurm:parallel + @slurm:cuda + +You can also use ``cluset -ll`` or ``cluset -LL`` to see each group's +associated node sets. + +.. _cluset-rawgroupnames: + +Listing group names in expressions +"""""""""""""""""""""""""""""""""" + +ClusterShell 1.9 introduces a new operator **@@** optionally followed by a +source name (e.g. **@@source**) to access the list of *raw group names* of +the source (without the **@** prefix). If no source is specified (as in *just* +**@@**), the default group source is used (see :ref:`groups_config_conf`). +The **@@** operator may be used in any node set expression to manipulate group +names as a node set. + +Example with the default group source:: + + $ cluset -l + @mgnt + @mds + @oss + @login + @compute + + $ cluset -e @@ + compute login mds mgnt oss + +Example with a group source "rack" that defines group names from rack +locations in a data center:: + + $ cluset -l -s rack + @rack:J1 + @rack:J2 + @rack:J3 + + $ cluset -f @@rack + J[1-3] + +A set of valid, indexed group sources is also accepted by the **@@** operator +(e.g. **@@dc[1-3]**). + + +.. warning:: An error is generated when using **@@** in an expression if the + source is not valid (e.g. invalid name, not configured or upcalls + not currently working). + + +Using node groups in basic commands +""""""""""""""""""""""""""""""""""" + +The use of node groups with the *cluset* command is very straightforward. +Indeed, any group name, prefixed by **@** as mentioned above, can be used in +lieu of a node name, where it will be substituted for all nodes in that group. + +A first, simple example is a group expansion (using default source) with +*cluset*:: + + $ cluset -e @oss + node40 node41 node42 node43 node44 node45 + +The *cluset* count command works as expected:: + + $ cluset -c @oss + 6 + +Also *cluset* folding command can always resolve node groups:: + + $ cluset -f @oss + node[40-45] + +There are usually two ways to use a specific group source (need to be properly +configured):: + + $ cluset -f @slurm:parallel + node[50-81] + + $ cluset -f -s slurm @parallel + node[50-81] + +.. _cluset-group-finding: + +Finding node groups +""""""""""""""""""" + +As an extension to the **list** command, you can search node groups that a +specified node set belongs to with ``cluset -l[ll]`` as follow:: + + $ cluset -l node40 + @all + @oss + + $ cluset -ll node40 + @all node[1-159] + @oss node[40-45] + +This feature is implemented with the help of the :meth:`.NodeSet.groups` +method (see :ref:`class-NodeSet-groups-finding` for further details). + +.. _cluset-regroup: + +Resolving node groups +""""""""""""""""""""" + +If needed group configuration conditions are met (cf. :ref:`node groups +configuration `), you can try group lookups thanks to the ``-r, +--regroup`` command. This feature is implemented with the help of the +:meth:`.NodeSet.regroup()` method (see :ref:`class-NodeSet-regroup` for +further details). Only exact matching groups are returned (all containing +nodes needed), for example:: + + $ cluset -r node[40-45] + @oss + + $ cluset -r node[0,40-45] + @mgnt,@oss + + +When resolving node groups, *cluset* always returns the largest groups +first, instead of several smaller matching groups, for instance:: + + $ cluset -ll + @login node[50-51] + @compute node[52-81] + @intel node[50-81] + + $ cluset -r node[50-81] + @intel + +If no matching group is found, ``cluset -r`` still returns folded result (as +does ``-f``):: + + $ cluset -r node40 node42 + node[40,42] + +Indexed node groups +""""""""""""""""""" + +Node groups are themselves some kind of group sets and can be indexable. To +use this feature, node groups external shell commands need to return indexed +group names (automatically handled by the library as needed). For example, +take a look at these indexed node groups:: + + $ cluset -l + @io1 + @io2 + @io3 + + $ cluset -f @io[1-3] + node[40-45] + + +Arithmetic operations on node groups +"""""""""""""""""""""""""""""""""""" + +Arithmetic and special operations (as explained for node sets in +:ref:`cluset-arithmetic` and :ref:`cluset-special`) are also supported with +node groups. +Any group name can be used in lieu of a node set, where it will be substituted +for all nodes in that group before processing requested operations. Some +typical examples are:: + + $ cluset -f @lustre -x @mds + node[40-45] + + $ cluset -r @lustre -x @mds + @oss + + $ cluset -r -a -x @lustre + @compute,@login,@mgnt + +More advanced examples, with the use of node group sets, follow:: + + $ cluset -r @io[1-3] -x @io2 + @io[1,3] + + $ cluset -f -I0 @io[1-3] + node40 + + $ cluset -f --split=3 @oss + node[40-41] + node[42-43] + node[44-45] + + $ cluset -r --split=3 @oss + @io1 + @io2 + @io3 + + +*Extended patterns* support with node groups +"""""""""""""""""""""""""""""""""""""""""""" + +Even for node groups, the *cluset* command supports arithmetic operations +through its *extended pattern* feature (see +:ref:`class-NodeSet-extended-patterns`). +A first example illustrates node groups intersection, that can be used in +practice to get nodes available from two dynamic group sources at a given +time:: + + $ cluset -f @db:prod\&@compute + +The following fictive example computes a folded node set containing nodes +found in node group ``@gpu`` and ``@slurm:bigmem``, but not in both, minus +the nodes found in odd ``@chassis`` groups from 1 to 9 (computed from left to +right):: + + $ cluset -f @gpu^@slurm:bigmem\!@chassis[1-9/2] + +Also, version 1.7 introduces a notation extension ``@*`` (or ``@SOURCE:*``) +that has been added to quickly represent *all nodes* (please refer to +:ref:`clush-all-nodes` for more details). + + +.. _cluset-all-nodes: + +Selecting all nodes +""""""""""""""""""" + +The option ``-a`` (without argument) can be used to select **all** nodes from +a group source (see :ref:`node groups configuration ` for more +details on special **all** external shell command upcall). Example of use for +the default group source:: + + $ cluset -a -f + example[4-6,32-159] + +Use ``-s/--groupsource`` to select another group source. + +If not properly configured, the ``-a`` option may lead to runtime errors +like:: + + $ cluset -s mybrokensource -a -f + cluset: External error: Not enough working methods (all or map + list) + to get all nodes + +A similar option is available with :ref:`clush-tool`, see +:ref:`selecting all nodes with clush `. + +.. _node-wildcards: + +Node wildcards +"""""""""""""" + +ClusterShell 1.8 introduces node wildcards: ``*`` means match zero or more +characters of any type; ``?`` means match exactly one character of any type. + +Any wildcard mask found is matched against **all** nodes from the group source +(see :ref:`cluset-all-nodes`). + +This can be especially useful for server farms, or when cluster node names +differ. Say that your :ref:`group configuration ` is set to +return the following "all nodes":: + + $ cluset -f -a + bckserv[1-2],dbserv[1-4],wwwserv[1-9] + +Then, you can use wildcards to select particular nodes, as shown below:: + + $ cluset -f 'www*' + wwwserv[1-9] + + $ cluset -f 'www*[1-4]' + wwwserv[1-4] + + $ cluset -f '*serv1' + bckserv1,dbserv1,wwwserv1 + +Wildcard masks are resolved prior to +:ref:`extended patterns `, but each mask is +evaluated as a whole node set operand. In the example below, we select +all nodes matching ``*serv*`` before removing all nodes matching ``www*``:: + + $ cluset -f '*serv*!www*' + bckserv[1-2],dbserv[1-4] + +.. _cluset-rangeset: + +Range sets +^^^^^^^^^^ + +Working with range sets +""""""""""""""""""""""" + +By default, the *cluset* command works with node or group sets and its +functionality match most :class:`.NodeSet` class methods. Similarly, *cluset* +will match :class:`.RangeSet` methods when you make use of the ``-R`` option +switch. In that case, all operations are restricted to numerical ranges. For +example, to expand the range "``1-10``", you should use:: + + $ cluset -e -R 1-10 + 1 2 3 4 5 6 7 8 9 10 + +Almost all commands and operations available for node sets are also available +with range sets. The only restrictions are commands and operations related to +node groups. For instance, the following command options are **not** available +with ``cluset -R``: + +* ``-r, --regroup`` as this feature is obviously related to node groups, +* ``-a / --all`` as the **all** external call is also related to node groups. + + +Using range sets instead of node sets doesn't change the general command +usage, like the need of one command option presence (cf. cluset-commands), or +the way to give some input (cf. cluset-stdin), for example:: + + $ echo 3 2 36 0 4 1 37 | cluset -fR + 0-4,36-37 + + $ echo 0-8/4 | cluset -eR -S'\n' + 0 + 4 + 8 + +Stepping and auto-stepping are supported (cf. :ref:`cluset-stepping`) and +also zero-padding (cf. cluset-zpad), which are both :class:`.RangeSet` class +features anyway. + +The following examples illustrate these last points:: + + $ cluset -fR 03 05 01 07 11 09 + 01,03,05,07,09,11 + + $ cluset -fR --autostep=3 03 05 01 07 11 09 + 01-11/2 + +Arithmetic and special operations +""""""""""""""""""""""""""""""""" + +All arithmetic operations, as seen for node sets (cf. +:ref:`cluset-arithmetic`:), are available for range sets, for example:: + + $ cluset -fR 1-14 -x 10-20 + 1-9 + + $ cluset -fR 1-14 -i 10-20 + 10-14 + + $ cluset -fR 1-14 -X 10-20 + 1-9,15-20 + +For now, there is no *extended patterns* syntax for range sets as for node +sets (cf. :ref:`cluset-extended-patterns`). However, as the union operator +``,`` is available natively by design, such expressions are still allowed:: + + $ cluset -fR 4-10,1-2 + 1-2,4-10 + + +Besides arithmetic operations, special operations may be very convenient for +range sets also (cf. :ref:`cluset-special`:). +Below is an example with ``-I / --slice`` (cf. :ref:`cluset-slice`:):: + + $ cluset -fR -I 0 100-131 + 100 + + $ cluset -fR -I 0-15 100-131 + 100-115 + +There is another special operation example with ``--split`` (cf. +cluset-splitting-n):: + + $ cluset -fR --split=2 100-131 + 100-115 + 116-131 + +Finally, an example of the special operation ``--contiguous`` (cf. +cluset-splitting-contiguous):: + + $ cluset -f -R --contiguous 1-9,11,13-19 + 1-9 + 11 + 13-19 + +*rangeset* alias +"""""""""""""""" + +When using *cluset* with range sets intensively (eg. for scripting), it may +be convenient to create a local command alias, as shown in the following +example (Bourne shell), making it sort of a super `seq(1)`_ command:: + + $ alias rangeset='cluset -R' + $ rangeset -e 0-8/2 + 0 2 4 6 8 + + +.. [#] Slurm is an open-source resource manager (https://slurm.schedmd.com/overview.html) + +.. _seq(1): http://linux.die.net/man/1/seq diff --git a/doc/sphinx/tools/index.rst b/doc/sphinx/tools/index.rst index 6c1008e9..362e7574 100644 --- a/doc/sphinx/tools/index.rst +++ b/doc/sphinx/tools/index.rst @@ -6,15 +6,19 @@ Tools Three Python scripts using the ClusterShell library are provided with the distribution: -* `cluset` or `nodeset`, both are the same tool to manage cluster node sets and groups, * `clush`, a powerful parallel command execution tool with output gathering, -* `clubak`, a tool to gather and display results from clush/pdsh-like output (and more). +* `clubak`, a tool to gather and display results from clush/pdsh-like output (and more), +* `cluset` or `nodeset`, both are the **same tool** to manage cluster node sets and groups. .. toctree:: :maxdepth: 2 - nodeset - cluset clush clubak + cluset + +.. toctree:: + :maxdepth: 1 + + nodeset diff --git a/doc/sphinx/tools/nodeset.rst b/doc/sphinx/tools/nodeset.rst index 57a99b03..c4071391 100644 --- a/doc/sphinx/tools/nodeset.rst +++ b/doc/sphinx/tools/nodeset.rst @@ -5,6 +5,12 @@ nodeset .. highlight:: console +.. note:: The :ref:`cluset-tool` command is introduced in ClusterShell + version 1.7.3 as an alternative to the **nodeset** command to avoid + conflicts with the **nodeset** command from xCAT. Users are + encouraged to transition to using **cluset** for their + range/node/group set management tasks. + The *nodeset* command enables easy manipulation of node sets, as well as node groups, at the command line level. As it is very user-friendly and efficient, the *nodeset* command can quickly improve traditional cluster @@ -339,6 +345,8 @@ inside the brackets. range set is not compatible with **trailing** digits. For instance, this is **not** supported: ``node-00[1-6/2]0`` +.. _nodeset-arithmetic: + Arithmetic operations ^^^^^^^^^^^^^^^^^^^^^ @@ -423,6 +431,8 @@ patterns" (inherited from :class:`.NodeSet` extended pattern feature, see $ nodeset -f node[1-9]^node[6-11] node[1-5,10-11] +.. _nodeset-special: + Special operations ^^^^^^^^^^^^^^^^^^ @@ -828,7 +838,8 @@ Arithmetic operations on node groups """""""""""""""""""""""""""""""""""" Arithmetic and special operations (as explained for node sets in -nodeset-arithmetic and nodeset-special are also supported with node groups. +:ref:`nodeset-arithmetic` and :ref:`nodeset-special` are also supported with +node groups. Any group name can be used in lieu of a node set, where it will be substituted for all nodes in that group before processing requested operations. Some typical examples are:: @@ -910,8 +921,6 @@ like:: A similar option is available with :ref:`clush-tool`, see :ref:`selecting all nodes with clush `. -.. _node-wildcards: - Node wildcards """""""""""""" @@ -1000,8 +1009,8 @@ The following examples illustrate these last points:: Arithmetic and special operations """"""""""""""""""""""""""""""""" -All arithmetic operations, as seen for node sets (cf. nodeset-arithmetic), are -available for range sets, for example:: +All arithmetic operations, as seen for node sets (cf. +:ref:`cluset-arithmetic`), are available for range sets, for example:: $ nodeset -fR 1-14 -x 10-20 1-9 diff --git a/doc/txt/clubak.txt b/doc/txt/clubak.txt index 911ff2d7..1349f36b 100644 --- a/doc/txt/clubak.txt +++ b/doc/txt/clubak.txt @@ -7,9 +7,9 @@ format output from clush/pdsh-like output and more -------------------------------------------------- :Author: Stephane Thiell -:Date: 2023-09-29 +:Date: 2025-01-23 :Copyright: GNU Lesser General Public License version 2.1 or later (LGPLv2.1+) -:Version: 1.9.2 +:Version: 1.9.3 :Manual section: 1 :Manual group: ClusterShell User Manual diff --git a/doc/txt/cluset.txt b/doc/txt/cluset.txt index 6a289df4..06482009 100644 --- a/doc/txt/cluset.txt +++ b/doc/txt/cluset.txt @@ -7,9 +7,9 @@ compute advanced cluster node set operations -------------------------------------------- :Author: Stephane Thiell -:Date: 2023-09-29 +:Date: 2025-01-23 :Copyright: GNU Lesser General Public License version 2.1 or later (LGPLv2.1+) -:Version: 1.9.2 +:Version: 1.9.3 :Manual section: 1 :Manual group: ClusterShell User Manual @@ -48,6 +48,7 @@ OPTIONS -e, --expand expand nodeset(s) to separate nodes (see also -S *SEPARATOR*) -f, --fold fold nodeset(s) (or separate nodes) into one nodeset -l, --list list node groups, list node groups and nodes (``-ll``) or list node groups, nodes and node count (``-lll``). When no argument is specified at all, this command will list all node group names found in selected group source (see also -s *GROUPSOURCE*). 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 ``-ll``), and also member count/total group node count (with ``-lll``). If a single hyphen-minus (-) is given as a nodeset, it will be read from standard input. + -L, --list-all list node groups from all group sources (``-LL`` shows nodes and ``-LLL`` adds node count). Like ``-l``, if any nodesets are specified as argument, this command will find node groups these nodes belongs to (individually). -r, --regroup fold nodes using node groups (see -s *GROUPSOURCE*) --groupsources list all active group sources (see ``groups.conf``\(5)) diff --git a/doc/txt/clush.conf.txt b/doc/txt/clush.conf.txt index cc22f415..d35eb468 100644 --- a/doc/txt/clush.conf.txt +++ b/doc/txt/clush.conf.txt @@ -7,9 +7,9 @@ Configuration file for `clush` ------------------------------ :Author: Stephane Thiell, -:Date: 2023-09-29 +:Date: 2025-01-23 :Copyright: GNU Lesser General Public License version 2.1 or later (LGPLv2.1+) -:Version: 1.9.2 +:Version: 1.9.3 :Manual section: 5 :Manual group: ClusterShell User Manual diff --git a/doc/txt/clush.txt b/doc/txt/clush.txt index 10d4c320..317f3704 100644 --- a/doc/txt/clush.txt +++ b/doc/txt/clush.txt @@ -7,9 +7,9 @@ execute shell commands on a cluster ----------------------------------- :Author: Stephane Thiell -:Date: 2023-09-29 +:Date: 2025-01-23 :Copyright: GNU Lesser General Public License version 2.1 or later (LGPLv2.1+) -:Version: 1.9.2 +:Version: 1.9.3 :Manual section: 1 :Manual group: ClusterShell User Manual diff --git a/doc/txt/groups.conf.txt b/doc/txt/groups.conf.txt index bc8667c8..0012cb30 100644 --- a/doc/txt/groups.conf.txt +++ b/doc/txt/groups.conf.txt @@ -7,9 +7,9 @@ Configuration file for ClusterShell node groups ----------------------------------------------- :Author: Stephane Thiell, -:Date: 2023-09-29 +:Date: 2025-01-23 :Copyright: GNU Lesser General Public License version 2.1 or later (LGPLv2.1+) -:Version: 1.9.2 +:Version: 1.9.3 :Manual section: 5 :Manual group: ClusterShell User Manual diff --git a/doc/txt/nodeset.txt b/doc/txt/nodeset.txt index dc71ad5e..3a6f6aac 100644 --- a/doc/txt/nodeset.txt +++ b/doc/txt/nodeset.txt @@ -7,9 +7,9 @@ compute advanced nodeset operations ----------------------------------- :Author: Stephane Thiell -:Date: 2023-09-29 +:Date: 2025-01-23 :Copyright: GNU Lesser General Public License version 2.1 or later (LGPLv2.1+) -:Version: 1.9.2 +:Version: 1.9.3 :Manual section: 1 :Manual group: ClusterShell User Manual @@ -48,6 +48,7 @@ OPTIONS -e, --expand expand nodeset(s) to separate nodes (see also -S *SEPARATOR*) -f, --fold fold nodeset(s) (or separate nodes) into one nodeset -l, --list list node groups, list node groups and nodes (``-ll``) or list node groups, nodes and node count (``-lll``). When no argument is specified at all, this command will list all node group names found in selected group source (see also -s *GROUPSOURCE*). 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 ``-ll``), and also member count/total group node count (with ``-lll``). If a single hyphen-minus (-) is given as a nodeset, it will be read from standard input. + -L, --list-all list node groups from all group sources (``-LL`` shows nodes and ``-LLL`` adds node count). Like ``-l``, if any nodesets are specified as argument, this command will find node groups these nodes belongs to (individually). -r, --regroup fold nodes using node groups (see -s *GROUPSOURCE*) --groupsources list all active group sources (see ``groups.conf``\(5)) diff --git a/lib/ClusterShell/__init__.py b/lib/ClusterShell/__init__.py index 8fc80091..6a559a18 100644 --- a/lib/ClusterShell/__init__.py +++ b/lib/ClusterShell/__init__.py @@ -34,8 +34,8 @@ - ClusterShell.Task """ -__version__ = '1.9.2' +__version__ = '1.9.3' __version_info__ = tuple([ int(_n) for _n in __version__.split('.')]) -__date__ = '2023/09/29' +__date__ = '2025/01/23' __author__ = 'Stephane Thiell ' __url__ = 'http://clustershell.readthedocs.org/' diff --git a/setup.py b/setup.py index b97bbfc7..bd901743 100755 --- a/setup.py +++ b/setup.py @@ -1,7 +1,7 @@ #!/usr/bin/env python # # Copyright (C) 2008-2016 CEA/DAM -# Copyright (C) 2016-2023 Stephane Thiell +# Copyright (C) 2016-2025 Stephane Thiell # # This file is part of ClusterShell. # @@ -23,7 +23,7 @@ from setuptools import setup, find_packages -VERSION = '1.9.2' +VERSION = '1.9.3' CFGDIR = 'etc/clustershell' MANDIR = 'share/man'