New report: names of selected nodes (to be used in bash scripts) (#2420)

This is a minimally-intrusive solution for #2418:

* "netlab report nodes --node glob" prints out the names of the selected nodes
* The names of the selected nodes can be used in a bash script (see documentation
  for an example)

Closes #2418

Author: ipspace

docs/netlab/connect.md

@@ -29,7 +29,8 @@ The rest of the arguments are passed to SSH or docker exec command
 ```
 
 ```{tip}
-The [**‌--show** option](netlab-connect-show) must be used _after_ the host parameter, as the **‌--show** option consumes all arguments specified after it.
+* The [**‌--show** option](netlab-connect-show) must be used _after_ the host parameter, as the **‌--show** option consumes all arguments specified after it.
+* **‌netlab connect** connects to a single node. Use a bash script described in the [**netlab report** examples](netlab-report-examples) if you want to use a single command to connect to multiple nodes in a multi-window environment.
 ```
 
 ## Collecting Device Data
@@ -59,6 +60,10 @@ Command line parameters specified after the device name are passed to the **ssh*
 
 If you want to process the results of the command executed on a lab device, use **netlab connect -q** to remove the "_we are going to connect to device X_" message.
 
+```{tip}
+Use [**‌netlab exec**](netlab-exec) if you want to execute the same command on multiple devices
+```
+
 (netlab-connect-show)=
 ## Executing a Show Command
 

docs/netlab/report.md

@@ -29,13 +29,25 @@ options:
 The **[netlab show reports](netlab-show-reports)** command displays up-to-date list of available system reports
 ```
 
+(netlab-report-examples)=
 ## Examples
 
-* `netlab report addressing` creates lab addressing report in text format on standard output (printed to the screen)
+* `netlab report addressing` creates the lab addressing report in text format on standard output (printed to the screen)
 * `netlab report addressing.html x.html` creates an HTML addressing report (**addressing.html**) and stores it into `x.html`.
 * `netlab report bgp-neighbor.md` creates the table of BGP neighbors in Markdown format
 * `netlab report bgp-neighbor.ascii` creates the Markdown BGP neighbors report and renders it as ASCII text using the [rich.markdown](https://rich.readthedocs.io/en/stable/markdown.html) library.
 * `netlab report addressing --node r1,r2` creates addressing report for R1 and R2.
+* `netlab report nodes` lists the space-separated node names (you can use the `--node` argument to select a subset of nodes) in a format that can be used in a **bash** script. For example, the following script (when started within a **screen** session) connects to all specified devices in separate **screen** windows[^BM]:
+
+```
+#!/bin/bash
+for n in $(netlab report --node "${1:-*}" nodes); do
+  echo "Connecting to $n"
+  screen -t "$n" netlab connect $n &
+done
+```
+
+[^BM]: The **bash** magic used for the `--node` parameter uses the value of the first script parameter or '*' if the script has no parameters. The double quotes around that magic prevent **bash** filename expansion.
 
 ```{tip}
 [**netlab inspect** documentation](netlab-inspect-node) describes how to specify the nodes on which the command will be executed.

netsim/reports/nodes.j2

@@ -0,0 +1,2 @@
+{# description: List of selected (or all) nodes in the lab topology #}
+{{ nodes.keys()|join(" ") -}}