ClusterShell 1.10__tar.gz → 1.10.1__tar.gz

{clustershell-1.10 → clustershell-1.10.1}/ChangeLog

@@ -1,3 +1,52 @@
+2026-07-16 S. Thiell <stephane@thiell.com>
+
+	* Version 1.10.1 released. The main changes are listed below.
+
+	* setup: install the ansible.conf.example group source example, which
+	was missing from binary packages in 1.10 (#645)
+
+	* NodeSet: fix stepped slices across multiple patterns on Python 3 (#661)
+
+	* RangeSet: fix unpickling of empty sets (#658)
+
+	* Communication: pin the pickle protocol used for gateway messages, fixing
+	tree mode across mixed Python versions with Python 3.14 (#658)
+
+	* Communication: fix TypeError when reporting channel errors (#673)
+
+	* Tree: report gateway errors received before channel setup (#674)
+
+	* Tree: fix rcopy extraction error reporting (#663)
+
+	* EngineClient: remove stream on broken pipe, fixing a possible hang with
+	the select engine (#651, #652)
+
+	* Engine: fix error handling in the EPoll and Select event loops (#662)
+
+	* conf: remove the deprecated Cray ACE group source example (#644)
+
+	* packaging: remove the unmaintained in-repo RPM spec file; RPM packaging
+	is maintained in the Fedora and EPEL repositories (#643)
+
+	* doc: refresh the installation guide (#653)
+
+	* doc: port library examples to Python 3 (#654)
+
+	* doc: coverage, accuracy and rendering improvements across man pages and
+	Sphinx docs (#648, #655, #666, #671, #675)
+
+	* doc: modernize the Sphinx build: remove stale epydoc config, enable
+	viewcode, update build requirements; animate the tree mode diagram
+	(#667, #668, #669, #670)
+
+	* tests: add bash completion tests and improve test portability and
+	reliability (#650, #664, #665)
+
+	* CI: build the documentation with warnings as errors on every change (#649)
+
+	* CI: publish releases to PyPI with a GitHub Actions workflow using
+	Trusted Publishing (#646)
+
 2026-07-04 S. Thiell <sthiell@stanford.edu>
 
 	* Version 1.10 released. The main changes are listed below.

{clustershell-1.10 → clustershell-1.10.1}/MANIFEST.in

@@ -18,7 +18,6 @@ include doc/man/man1/*.1
 include doc/man/man5/*.5
 include doc/sphinx/Makefile
 include doc/sphinx/conf.py
-include doc/sphinx/*.png
 include doc/sphinx/*.rst
 include doc/sphinx/_static/*.png
 include doc/sphinx/_static/*.css
@@ -30,6 +29,5 @@ include doc/extras/vim/syntax/*.vim
 include doc/extras/vim/ftdetect/*.vim
 include doc/examples/*.py
 include doc/examples/defaults.conf-rsh
-include doc/epydoc/*.conf
 include tests/*.py
 include tests/bin/*

{clustershell-1.10/lib/ClusterShell.egg-info → clustershell-1.10.1}/PKG-INFO

@@ -1,11 +1,10 @@
 Metadata-Version: 2.4
 Name: ClusterShell
-Version: 1.10
+Version: 1.10.1
 Summary: ClusterShell library and tools
 Home-page: https://clustershell.readthedocs.io/
-Download-URL: https://github.com/clustershell/clustershell/archive/refs/tags/v1.10.tar.gz
+Download-URL: https://github.com/clustershell/clustershell/archive/refs/tags/v1.10.1.tar.gz
 Author: Stephane Thiell
-Author-email: sthiell@stanford.edu
 License: LGPLv2+
 Keywords: clustershell,clush,clubak,nodeset
 Platform: GNU/Linux
@@ -28,7 +27,6 @@ Description-Content-Type: text/x-rst
 License-File: COPYING.LGPLv2.1
 Requires-Dist: PyYAML
 Dynamic: author
-Dynamic: author-email
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type

{clustershell-1.10 → clustershell-1.10.1}/README.md

@@ -24,7 +24,7 @@ of the library features.
 Requirements
 ------------
 
- * GNU/Linux, BSD, Mac OS X
+ * GNU/Linux, BSD, macOS
  * OpenSSH (ssh/scp) or rsh
  * Python 2.x (x >= 7) or Python 3.x (x >= 6)
  * PyYAML
@@ -43,9 +43,9 @@ Online documentation is available here:
     https://clustershell.readthedocs.io/
 
 The Sphinx documentation source is available under the doc/sphinx directory.
-Type 'make' to see all available formats (you need Sphinx installed and
-sphinx_rtd_theme to build the documentation). For example, to generate html
-docs, just type:
+Type 'make' to see all available formats (you need the packages listed in
+doc/sphinx/requirements.txt to build the documentation). For example, to
+generate html docs, just type:
 
     make html BUILDDIR=/dest/path
 
@@ -55,7 +55,25 @@ For local library API documentation, just type:
 
 The following man pages are also provided:
 
-    clush(1), clubak(1), nodeset(1), clush.conf(5), groups.conf(5)
+    clush(1), clubak(1), cluset(1), nodeset(1), clush.conf(5), groups.conf(5)
+
+Building
+--------
+
+To build the Python source distribution and wheel from a source checkout:
+
+    $ python -m build
+
+The resulting tarball and wheel are written to the 'dist' directory.
+
+RPM packaging is not maintained in this repository. RPM packages for Fedora,
+RHEL and compatible distributions are maintained in the Fedora and EPEL
+dist-git repositories:
+
+    https://src.fedoraproject.org/rpms/clustershell
+
+To build RPMs locally, use that spec file, for example with 'fedpkg' or
+'rpmbuild'.
 
 Test Suite
 ----------
@@ -80,13 +98,12 @@ Python code (simple example)
 >>> from ClusterShell.NodeSet import NodeSet
 >>> task = task_self()
 >>> task.run("/bin/uname -r", nodes="linux[4-6,32-39]")
-<ClusterShell.Worker.Ssh.WorkerSsh object at 0x20a5e90>
+<ClusterShell.Worker.Ssh.WorkerSsh object at 0x7f45287db910>
 >>> for buf, key in task.iter_buffers():
-...     print NodeSet.fromlist(key), buf
+...     print(NodeSet.fromlist(key), buf.message().decode())
 ... 
-linux[32-39] 2.6.40.6-0.fc15.x86_64
-
-linux[4-6] 2.6.32-71.el6.x86_64
+linux[32-39] 6.14.9-300.fc42.x86_64
+linux[4-6] 5.14.0-570.12.1.el9_6.x86_64
 ```
 
 Links

{clustershell-1.10 → clustershell-1.10.1}/conf/groups.conf.d/ansible.conf.example

@@ -10,6 +10,9 @@
 # Replace /path/to/inventory with your inventory path or directory,
 # or set ANSIBLE_INVENTORY in your environment to override it.
 #
+# Hostnames can be post-processed in jq, for instance to strip a DNS domain
+# suffix; see the Ansible inventory bindings section of the online docs.
+#
 [ansible]
 
 # Resolve group members, recursing into child groups

{clustershell-1.10 → clustershell-1.10.1}/doc/examples/check_nodes.py

@@ -1,7 +1,7 @@
-#!/usr/bin/python
+#!/usr/bin/python3
 # check_nodes.py: ClusterShell simple example script.
 #
-# This script runs a simple command on remote nodes and report node
+# This script runs a simple command on remote nodes and reports node
 # availability (basic health check) and also min/max boot dates.
 # It shows an example of use of Task, NodeSet and EventHandler objects.
 # Feel free to copy and modify it to fit your needs.
@@ -10,7 +10,6 @@
 
 import optparse
 from datetime import date, datetime
-import time
 
 from ClusterShell.Event import EventHandler
 from ClusterShell.NodeSet import NodeSet
@@ -29,10 +28,10 @@ class CheckNodesResult(object):
     def show(self):
         """Display results"""
         if self.nodes_ok:
-            print "%s: OK (boot date: min %s, max %s)" % \
-                (self.nodes_ok, self.min_boot_date, self.max_boot_date)
+            print("%s: OK (boot date: min %s, max %s)" %
+                  (self.nodes_ok, self.min_boot_date, self.max_boot_date))
         if self.nodes_ko:
-            print "%s: FAILED" % self.nodes_ko
+            print("%s: FAILED" % self.nodes_ko)
 
 class CheckNodesHandler(EventHandler):
     """Our ClusterShell EventHandler"""
@@ -45,20 +44,18 @@ class CheckNodesHandler(EventHandler):
     def ev_read(self, worker, node, sname, msg):
         """Read event from remote nodes"""
         # this is an example to demonstrate remote result parsing
-        bootime = " ".join(msg.strip().split()[2:])
-        date_boot = None
-        for fmt in ("%Y-%m-%d %H:%M",): # formats with year
+        bootime = " ".join(msg.decode().strip().split()[2:])
+        # 'who -b' prints the boot date with or without the year
+        try:
+            date_boot = datetime.strptime(bootime, "%Y-%m-%d %H:%M")
+        except ValueError:
             try:
-                # datetime.strptime() is Python2.5+, use old method instead
-                date_boot = datetime(*(time.strptime(bootime, fmt)[0:6]))
+                # no year: prepend the current one before parsing
+                # (yearless dates are deprecated as of Python 3.13)
+                date_boot = datetime.strptime(
+                    "%d %s" % (date.today().year, bootime), "%Y %b %d %H:%M")
             except ValueError:
-                pass
-        for fmt in ("%b %d %H:%M",):    # formats without year
-            try:
-                date_boot = datetime(date.today().year, \
-                    *(time.strptime(bootime, fmt)[1:6]))
-            except ValueError:
-                pass
+                date_boot = None
         if date_boot:
             if not self.result.min_boot_date or \
                 self.result.min_boot_date > date_boot:
@@ -98,7 +95,7 @@ def main():
     nodes_target = NodeSet(options.nodes)
     task.set_info("fanout", options.fanout)
     if options.debug:
-        print "nodeset : %s" % nodes_target
+        print("nodeset : %s" % nodes_target)
         task.set_info("debug", True)
 
     # Create ClusterShell event handler

{clustershell-1.10 → clustershell-1.10.1}/doc/man/man1/clubak.1

@@ -27,7 +27,7 @@ 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 "2026-07-04" "1.10" "ClusterShell User Manual"
+.TH "CLUBAK" 1 "2026-07-16" "1.10.1" "ClusterShell User Manual"
 .SH NAME
 clubak \- format output from clush/pdsh-like output and more
 .SH SYNOPSIS
@@ -41,7 +41,7 @@ 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,
+formatting features are already included in it. It is provided for other usages,
 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
@@ -55,9 +55,18 @@ ClusterShell library (see \fBpydoc ClusterShell.MsgTree\fP).
 .B  \-\-version
 show \fBclubak\fP version number and exit
 .TP
-.B  \-b\fP,\fB  \-c
-gather nodes with same output (\-c is provided for \fBdshbak\fP(1)
-compatibility)
+.B  \-b\fP,\fB  \-c\fP,\fB  \-\-dshbak
+gather nodes with same output (\-c and \-\-dshbak are provided
+for \fBdshbak\fP(1) compatibility)
+.TP
+.B  \-B
+same as \-b; accepted for compatibility with \fBclush\fP(1), where \-B also gathers standard error
+.TP
+.B  \-q\fP,\fB  \-\-quiet
+be quiet, print essential output only (e.g. suppress the node count displayed next to gathered nodeset headers)
+.TP
+.B  \-v\fP,\fB  \-\-verbose
+be verbose, print informative messages; also echo each input line to standard output prefixed by \fBINPUT\fP
 .TP
 .B  \-d\fP,\fB  \-\-debug
 output more messages for debugging purpose
@@ -65,17 +74,20 @@ output more messages for debugging purpose
 .B  \-L
 disable header block and order output by nodes
 .TP
+.B  \-N
+disable labeling of command output
+.TP
 .B  \-r\fP,\fB  \-\-regroup
 fold nodeset using node groups
 .TP
 .BI \-\-axis\fB= RANGESET
-for nD nodesets, fold the displayed nodeset (eg. in gathered output headers) 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 index is counted from the end. Because some nodesets may have several different dimensions, axis indices are silently truncated to fall in the allowed range. This is the per\-invocation equivalent of the \fBfold_axis\fP library default.
+for nD nodesets, fold the displayed nodeset (e.g. in gathered output headers) along provided axis only. Axes are indexed from 1 to n and can be specified here either using the rangeset syntax, e.g. \(aq1\(aq, \(aq1\-2\(aq, \(aq1,3\(aq, or by a single negative number meaning that the index is counted from the end. Because some nodesets may have several different dimensions, axis indices are silently truncated to fall in the allowed range. This is the per\-invocation equivalent of the \fBfold_axis\fP library default.
 .TP
 .BI \-s \ GROUPSOURCE\fR,\fB \ \-\-groupsource\fB= GROUPSOURCE
 optional \fBgroups.conf\fP(5) group source to use
 .TP
 .BI \-\-groupsconf\fB= FILE
-use alternate config file for groups.conf(5)
+use alternate config file for \fBgroups.conf\fP(5)
 .TP
 .B  \-G\fP,\fB  \-\-groupbase
 do not display group source prefix (always \fI@groupname\fP)
@@ -87,10 +99,13 @@ node / line content separator string (default: \fI:\fP)
 faster but memory hungry mode (preload all messages per node)
 .TP
 .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
+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 display
+.TP
+.BI \-\-interpret\-keys\fB= INTERPRET_KEYS
+whether to interpret keys (the field before the separator on each input line) as node sets. \fIINTERPRET_KEYS\fP is \fBnever\fP, \fBalways\fP or \fBauto\fP (the default). With \fBnever\fP, each key is kept as a plain string; with \fBalways\fP, every key must be a valid node set; with \fBauto\fP, keys are interpreted as node sets, but if any key cannot be parsed, \fBclubak\fP silently switches to treating all keys as plain strings.
 .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.
+\fBclubak\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 uses color if standard output refers to a terminal). Color is set to [34m (blue foreground text) and cannot be modified.
 .TP
 .B  \-\-diff
 show diff between gathered outputs
@@ -144,7 +159,7 @@ node2: 9
 \fI\%https://github.com/clustershell/clustershell/issues\fP
 .UNINDENT
 .SH AUTHOR
-Stephane Thiell <sthiell@stanford.edu>
+Stephane Thiell
 .SH COPYRIGHT
 GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)
 .\" Generated by docutils manpage writer.

{clustershell-1.10 → clustershell-1.10.1}/doc/man/man1/cluset.1

@@ -27,7 +27,7 @@ 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 "2026-07-04" "1.10" "ClusterShell User Manual"
+.TH "CLUSET" 1 "2026-07-16" "1.10.1" "ClusterShell User Manual"
 .SH NAME
 cluset \- compute advanced cluster node set operations
 .SH SYNOPSIS
@@ -40,7 +40,7 @@ cluset \- compute advanced cluster node set operations
 .sp
 Note: \fBcluset\fP and \fBnodeset\fP are the same command.
 .sp
-\fBcluset\fP is an utility command provided with the ClusterShell library which
+\fBcluset\fP is a 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.
@@ -63,7 +63,7 @@ show this help message and exit
 optional \fBgroups.conf\fP(5) group source to use
 .TP
 .BI \-\-groupsconf\fB= FILE
-use alternate config file for groups.conf(5)
+use alternate config file for \fBgroups.conf\fP(5)
 .UNINDENT
 .INDENT 0.0
 .TP
@@ -80,10 +80,10 @@ expand nodeset(s) to separate nodes (see also \-S \fISEPARATOR\fP)
 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.
+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 belong 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  \-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).
+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 belong to (individually).
 .TP
 .B  \-r\fP,\fB  \-\-regroup
 fold nodes using node groups (see \-s \fIGROUPSOURCE\fP)
@@ -91,7 +91,7 @@ fold nodes using node groups (see \-s \fIGROUPSOURCE\fP)
 .BI \-\-index\fB= NODE
 output the index of NODE in the nodeset (reverse of \-I/\-\-slice)
 .TP
-.B  \-\-groupsources
+.B  \-\-list\-sources\fP,\fB  \-\-groupsources
 list all active group sources (see \fBgroups.conf\fP(5))
 .UNINDENT
 .TP
@@ -99,13 +99,13 @@ list all active group sources (see \fBgroups.conf\fP(5))
 .INDENT 7.0
 .TP
 .BI \-x \ SUB_NODES\fR,\fB \ \-\-exclude\fB= SUB_NODES
-exclude specified set
+exclude specified nodeset
 .TP
 .BI \-i \ AND_NODES\fR,\fB \ \-\-intersection\fB= AND_NODES
-calculate sets intersection
+calculate nodesets intersection
 .TP
 .BI \-X \ XOR_NODES\fR,\fB \ \-\-xor\fB= XOR_NODES
-calculate symmetric difference between sets
+calculate symmetric difference between nodesets
 .UNINDENT
 .TP
 .B Options:
@@ -115,7 +115,7 @@ calculate symmetric difference between sets
 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, \(dqnode2 node4 node6\(dq folds in node[2,4,6] but autostep=3, \(dqnode2 node4 node6\(dq 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
 output more messages for debugging purpose
@@ -125,10 +125,10 @@ 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
+working on numerical cluster ranges, e.g. 1,5,18\-31
 .TP
 .B  \-G\fP,\fB  \-\-groupbase
-hide group source prefix (always \fI@groupname\fP)
+do not display group source prefix (always \fI@groupname\fP)
 .TP
 .BI \-S \ SEPARATOR\fR,\fB \ \-\-separator\fB= SEPARATOR
 separator string to use when expanding nodesets
@@ -144,10 +144,10 @@ return sliced off result; examples of SLICE_RANGESET are \(dq0\(dq for simple in
 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)\(dq\(dq\(dq
+split result into contiguous subsets (i.e. for nodeset, subsets will contain nodes with same pattern name and a contiguous range of indexes, like foobar[1\-100]; for rangeset, subsets consist of 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 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.
+for nD nodesets, fold along provided axis only. Axes are indexed from 1 to n and can be specified here either using the rangeset syntax, e.g. \(aq1\(aq, \(aq1\-2\(aq, \(aq1,3\(aq, or by a single negative number meaning that the index 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
@@ -165,7 +165,7 @@ standard input.
 The \fBcluset\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
+patterns are read from left to right, by processing any character
 operators accordingly.
 .INDENT 0.0
 .TP
@@ -229,7 +229,7 @@ node[0\-4,11\-13]
 .B $ cluset \-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.
+This computes a folded nodeset containing nodes found in groups @gpu and @slurm:bigmem, but not in both, minus the nodes found in odd chassis groups from 1 to 9.
 .TP
 .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:
@@ -243,7 +243,7 @@ The \fB@*\fP and \fB@SOURCE:*\fP special notations may be used in extended patte
 .UNINDENT
 .TP
 .B Group names in expressions
-The \fB@@SOURCE\fP notation may be used to access all group names from the specified SOURCE (or from the default group source when just \fB@@\fP is used) in node set expressions; this works with either file\-based group sources or with external group sources that have the \fIlist\fP upcall defined (see \fBgroups.conf\fP(5)):
+The \fB@@SOURCE\fP notation may be used to access all group names from the specified SOURCE (or from the default group source when just \fB@@\fP is used) in node set expressions; this works with either file\-based group sources or with external group sources that have the \fIlist\fP or \fImapall\fP upcall defined (see \fBgroups.conf\fP(5)):
 .INDENT 7.0
 .INDENT 3.5
 .INDENT 0.0
@@ -264,7 +264,7 @@ Any wildcard mask found is matched against all nodes from the group source (see
 This can be especially useful for server farms, or when cluster node names differ.
 .INDENT 0.0
 .TP
-.B Say that your group configuration is set to return the following “all nodes”:
+.B Say that your group configuration is set to return the following \(dqall nodes\(dq:
 .INDENT 7.0
 .TP
 .B $ cluset \-f \-a
@@ -488,7 +488,7 @@ command and also to conform with ClusterShell\(aqs \(dqclu*\(dq command nomencla
 \fI\%https://github.com/clustershell/clustershell/issues\fP
 .UNINDENT
 .SH AUTHOR
-Stephane Thiell <sthiell@stanford.edu>
+Stephane Thiell
 .SH COPYRIGHT
 GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)
 .\" Generated by docutils manpage writer.

{clustershell-1.10 → clustershell-1.10.1}/doc/man/man1/clush.1

@@ -27,7 +27,7 @@ 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 "2026-07-04" "1.10" "ClusterShell User Manual"
+.TH "CLUSH" 1 "2026-07-16" "1.10.1" "ClusterShell User Manual"
 .SH NAME
 clush \- execute shell commands on a cluster
 .SH SYNOPSIS
@@ -66,7 +66,7 @@ gathered output results.
 .sp
 The \fB\-w\fP option allows you to specify remote hosts by using ClusterShell
 NodeSet syntax, including the node groups \fB@group\fP special syntax and the
-\fBExtended Patterns\fP syntax to benefits from NodeSet basic arithmetic
+\fBExtended Patterns\fP syntax to benefit from NodeSet basic arithmetic
 (like \fB@Agroup\e&@Bgroup\fP). See EXTENDED PATTERNS in \fBnodeset\fP(1) and
 also \fBgroups.conf\fP(5) for more information.
 .sp
@@ -100,7 +100,7 @@ terminal, \fBclush\fP runs interactively. In this mode, \fBclush\fP uses the GNU
 searching through the command history for lines containing a specified
 string. For instance, type Control\-R to search in the history for the next
 entry matching the search string typed so far.  \fBclush\fP also recognizes
-special single\-character prefixes that allows the user to see and modify
+special single\-character prefixes that allow the user to see and modify
 the current nodeset (the nodes where the commands are executed).
 .INDENT 7.0
 .TP
@@ -134,7 +134,9 @@ Instead of running provided command on remote nodes, \fBclush\fP can use the
 dedicated \fIexec\fP worker to launch the command \fIlocally\fP, for each node.
 Some parameters could be used in the command line to make a different
 command for each node. \fB%h\fP or \fB%host\fP will be replaced by node name and
-\fB%n\fP or \fB%rank\fP by the remote rank [0\-N] (to get a literal % use %%)
+\fB%n\fP or \fB%rank\fP by the remote rank [0\-N] (to get a literal % use %%).
+\fB%hosts\fP will be replaced by the full target nodeset, in which case the
+command is executed only once.
 .TP
 .B File copying mode ( \fB\-\-copy\fP )
 When \fBclush\fP is started with the \fB\-c\fP or \fB\-\-copy\fP option, it will
@@ -166,10 +168,10 @@ optional \fBgroups.conf\fP(5) group source to use
 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
-use alternate config file for groups.conf(5)
+use alternate config file for \fBgroups.conf\fP(5)
 .TP
 .BI \-\-conf\fB= FILE
-use alternate config file for clush.conf(5)
+use alternate config file for \fBclush.conf\fP(5)
 .TP
 .BI \-O \ <KEY=VALUE>\fR,\fB \ \-\-option\fB= <KEY=VALUE>
 override any key=value \fBclush.conf\fP(5) options (repeat as needed)
@@ -204,7 +206,7 @@ topology configuration file to use for tree mode
 pick N node(s) at random in nodeset
 .UNINDENT
 .TP
-.B Output behaviour:
+.B Output behavior:
 .INDENT 7.0
 .TP
 .B  \-q\fP,\fB  \-\-quiet
@@ -217,13 +219,13 @@ be verbose, print informative messages
 output more messages for debugging purpose
 .TP
 .B  \-G\fP,\fB  \-\-groupbase
-do not display group source prefix
+do not display group source prefix (always \fB@groupname\fP)
 .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 \(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)
+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 (e.g. \-bL), \fBclush\fP will enable a \(dqlive gathering\(dq of results by line, so that the next line is displayed as soon as possible (e.g. when all nodes have sent the line)
 .TP
 .B  \-N
-disable labeling of command line
+disable labeling of command output
 .TP
 .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
@@ -238,13 +240,13 @@ like \-b but including standard error
 fold nodeset using node groups
 .TP
 .BI \-\-axis\fB= RANGESET
-for nD nodesets, fold the displayed nodeset (eg. in gathered output headers) 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 index is counted from the end. Because some nodesets may have several different dimensions, axis indices are silently truncated to fall in the allowed range. This is the per\-invocation equivalent of the \fBfold_axis\fP library default.
+for nD nodesets, fold the displayed nodeset (e.g. in gathered output headers) along provided axis only. Axes are indexed from 1 to n and can be specified here either using the rangeset syntax, e.g. \(aq1\(aq, \(aq1\-2\(aq, \(aq1,3\(aq, or by a single negative number meaning that the index is counted from the end. Because some nodesets may have several different dimensions, axis indices are silently truncated to fall in the allowed range. This is the per\-invocation equivalent of the \fBfold_axis\fP library default.
 .TP
 .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.
+\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 uses 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
 show diff between common outputs (find the best reference output by focusing on largest nodeset and also smaller command return code)
@@ -284,7 +286,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 \(dq\-p 2022 \-i ~/.ssh/myidrsa\(dq\fP; these options are added first to ssh and override default ones
+can be used to give ssh options, e.g. \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
@@ -348,13 +350,13 @@ Search some files on node32 in /etc/yum.repos.d and use clush to list the matchi
 Run this Linux command to get BIOS version on nodes[3\-5,62] and show version differences (if any).
 .TP
 .B # clush \-w dc[1\-2]n[1\-2] \-\-axis=1 \-b uname \-r
-Gather output and fold the displayed nodeset header along axis 1 only, eg. show \fBdc[1\-2]n1,dc[1\-2]n2\fP rather than \fBdc[1\-2]n[1\-2]\fP in the header block. See also \fBfold_axis\fP in the Library Defaults configuration to change it permanently.
+Gather output and fold the displayed nodeset header along axis 1 only, e.g. show \fBdc[1\-2]n1,dc[1\-2]n2\fP rather than \fBdc[1\-2]n[1\-2]\fP in the header block. See also \fBfold_axis\fP in the Library Defaults configuration to change it permanently.
 .UNINDENT
 .SS All nodes
 .INDENT 0.0
 .TP
 .B # clush \-a uname \-r
-Run command \fIuname \-r\fP on all cluster nodes, see \fBgroups.conf\fP(5) to setup all cluster nodes (\fIall:\fP field).
+Run command \fIuname \-r\fP on all cluster nodes, see \fBgroups.conf\fP(5) to set up all cluster nodes (\fIall:\fP field).
 .TP
 .B # clush \-a \-x node[5,7] uname \-r
 Run command \fIuname \-r\fP on all cluster nodes except on nodes node5 and node7.
@@ -388,7 +390,7 @@ Recursively copy local directory \fI/usr/share/doc/clustershell\fP to the same
 path on remote nodes node[3\-5,62].
 .TP
 .B # clush \-w node[3\-5,62] \-\-rcopy /etc/motd \-\-dest /tmp
-Copy \fI/etc/motd\fP from remote nodes node[3\-5,62] to local \fI/tmp\fP directory, each file having their remote hostname appended, eg. \fI/tmp/motd.node3\fP\&.
+Copy \fI/etc/motd\fP from remote nodes node[3\-5,62] to local \fI/tmp\fP directory, each file having their remote hostname appended, e.g. \fI/tmp/motd.node3\fP\&.
 .UNINDENT
 .SH FILES
 .INDENT 0.0
@@ -401,11 +403,16 @@ Global clush configuration file. If $CLUSTERSHELL_CFGDIR is not defined,
 User configuration file for clush. If $XDG_CONFIG_HOME is not defined,
 \fI$HOME/.config/clustershell/clush.conf\fP is used instead.
 .TP
+.B \fI{sys.prefix}/etc/clustershell/clush.conf\fP
+Configuration file when ClusterShell is installed in a Python virtual
+environment.
+.TP
 .B \fI$HOME/.local/etc/clustershell/clush.conf\fP
 Local user configuration file for clush (default installation for pip \-\-user)
 .TP
 .B \fI~/.clush.conf\fP
-Deprecated per\-user clush configuration file.
+Deprecated per\-user clush configuration file (no longer read since
+version 1.9).
 .TP
 .B \fI~/.clush_history\fP
 File in which interactive \fBclush\fP command history is saved.
@@ -422,7 +429,7 @@ File in which interactive \fBclush\fP command history is saved.
 \fI\%https://github.com/clustershell/clustershell/issues\fP
 .UNINDENT
 .SH AUTHOR
-Stephane Thiell <sthiell@stanford.edu>
+Stephane Thiell
 .SH COPYRIGHT
 GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)
 .\" Generated by docutils manpage writer.