clush: add --maxrc as long option for -S

- test maxrc from command line and clush.conf
- doc minor changes

Author: thiell

conf/clush.conf

@@ -10,8 +10,8 @@ command_timeout: 0
 color: auto
 fd_max: 8192
 history_size: 100
-node_count: yes
 maxrc: no
+node_count: yes
 verbosity: 1
 
 # Add always all remote hosts to known_hosts without confirmation

doc/man/man1/clush.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH CLUSH 1 "2019-12-01" "1.8.3" "ClusterShell User Manual"
+.TH CLUSH 1 "2021-10-27" "1.8.3" "ClusterShell User Manual"
 .SH NAME
 clush \- execute shell commands on a cluster
 .
@@ -234,7 +234,7 @@ like \-b but including standard error
 .B \-r\fP,\fB  \-\-regroup
 fold nodeset using node groups
 .TP
-.B \-S
+.B \-S\fP,\fB  \-\-maxrc
 return the largest of command return codes
 .TP
 .BI \-\-color\fB= WHENCOLOR

doc/sphinx/config.rst

@@ -66,6 +66,10 @@ The following table describes available *clush* config file settings.
 +-----------------+----------------------------------------------------+
 | maxrc           | Should *clush* return the largest of command       |
 |                 | return codes? (yes/no)                             |
+|                 | If set to no (the default), *clush* exit status    |
+|                 | gives no information about command return codes,   |
+|                 | but rather reports on *clush* execution itself     |
+|                 | (zero indicating a successful run).                |
 +-----------------+----------------------------------------------------+
 | verbosity       | Set the verbosity level: 0 (quiet), 1 (default),   |
 |                 | 2 (verbose) or more (debug).                       |

doc/txt/clush.conf.txt

@@ -110,8 +110,8 @@ Simple configuration file.
 | history_size: 100
 | color: auto
 | fd_max: 10240
-| node_count: yes
 | maxrc: no
+| node_count: yes
 |
 
 

doc/txt/clush.txt

@@ -7,7 +7,7 @@ execute shell commands on a cluster
 -----------------------------------
 
 :Author: Stephane Thiell <sthiell@stanford.edu>
-:Date:   2019-12-01
+:Date:   2021-10-27
 :Copyright: GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)
 :Version: 1.8.3
 :Manual section: 1
@@ -159,7 +159,7 @@ Output behaviour:
   -b, --dshbak        display gathered results in a dshbak-like way (note: it will only try to aggregate the output of commands with same return codes)
   -B                  like -b but including standard error
   -r, --regroup       fold nodeset using node groups
-  -S                  return the largest of command return codes
+  -S, --maxrc         return the largest of command return codes
   --color=WHENCOLOR   whether to use ANSI colors to surround node or nodeset prefix/header with escape sequences to display them in color on the terminal. *WHENCOLOR* is ``never``, ``always`` or ``auto`` (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.
   --diff              show diff between common outputs (find the best reference output by focusing on largest nodeset and also smaller command return code)
 
@@ -183,7 +183,7 @@ Connection options:
   -u COMMAND_TIMEOUT, --command_timeout=COMMAND_TIMEOUT
                       limit time for command to run on the node
   -R WORKER, --worker=WORKER
-                      worker name to use for connection (``exec``, ``ssh``, ``rsh``, ``pdsh``), default is ``ssh``
+                      worker name to use for connection (``exec``, ``ssh``, ``rsh``, ``pdsh``, or the name of a Python worker module), default is ``ssh``
   --remote=REMOTE     whether to enable remote execution: in tree mode, 'yes' forces connections to the leaf nodes for execution, 'no' establishes connections up to the leaf parent nodes for execution (default is 'yes') 
 
 For a short explanation of these options, see ``-h, --help``.

lib/ClusterShell/CLI/OptionParser.py

@@ -172,7 +172,7 @@ def install_display_options(self,
                               help="node / line content separator string "
                                    "(default: ':')")
         else:
-            optgrp.add_option("-S", action="store_true", dest="maxrc",
+            optgrp.add_option("-S", "--maxrc", action="store_true", dest="maxrc",
                               help="return the largest of command return codes")
 
         if msgtree_mode:

tests/CLIClushTest.py

@@ -275,6 +275,7 @@ def test_017_retcodes(self):
         self._clush_t(["-w", HOSTNAME, "/bin/false"], None, b"", 0, exp_err)
         self._clush_t(["-w", HOSTNAME, "-b", "/bin/false"], None, b"", 0, exp_err)
         self._clush_t(["-S", "-w", HOSTNAME, "/bin/false"], None, b"", 1, exp_err)
+        self._clush_t(["--maxrc", "-w", HOSTNAME, "/bin/false"], None, b"", 1, exp_err)
         for i in (1, 2, 127, 128, 255):
             s = "clush: %s: exited with exit code %d\n" % (HOSTNAME, i)
             self._clush_t(["-S", "-w", HOSTNAME, "exit %d" % i], None, b"", i,

tests/CLIConfigTest.py

@@ -38,6 +38,7 @@ def testClushConfigEmpty(self):
         self.assertEqual(config.color, WHENCOLOR_CHOICES[-1])
         self.assertEqual(config.verbosity, VERB_STD)
         self.assertEqual(config.fanout, 64)
+        self.assertEqual(config.maxrc, False)
         self.assertEqual(config.node_count, True)
         self.assertEqual(config.connect_timeout, 10)
         self.assertEqual(config.command_timeout, 0)
@@ -60,6 +61,7 @@ def testClushConfigAlmostEmpty(self):
         config = ClushConfig(options, filename=f.name)
         self.assertEqual(config.color, WHENCOLOR_CHOICES[-1])
         self.assertEqual(config.verbosity, VERB_STD)
+        self.assertEqual(config.maxrc, False)
         self.assertEqual(config.node_count, True)
         self.assertEqual(config.fanout, 64)
         self.assertEqual(config.connect_timeout, 10)
@@ -96,6 +98,7 @@ def testClushConfigDefault(self):
         display.vprint(VERB_DEBUG, "shouldn't see this")
         self.assertEqual(config.color, WHENCOLOR_CHOICES[2])
         self.assertEqual(config.verbosity, VERB_STD)
+        self.assertEqual(config.maxrc, False)
         self.assertEqual(config.node_count, True)
         self.assertEqual(config.fanout, 42)
         self.assertEqual(config.connect_timeout, 14)
@@ -116,6 +119,7 @@ def testClushConfigFull(self):
             command_timeout: 0
             history_size: 100
             color: auto
+            maxrc: yes
             node_count: yes
             verbosity: 1
             ssh_user: root
@@ -132,6 +136,7 @@ def testClushConfigFull(self):
         config = ClushConfig(options, filename=f.name)
         self.assertEqual(config.color, WHENCOLOR_CHOICES[2])
         self.assertEqual(config.verbosity, VERB_STD)
+        self.assertEqual(config.maxrc, True)
         self.assertEqual(config.node_count, True)
         self.assertEqual(config.fanout, 42)
         self.assertEqual(config.connect_timeout, 14)