Make '--instance' and '--snapshot' CLI parameters consistent

* Add '--instance' parameter to most netlab commands
* Add 'change to instance directory' processing to the 'load snapshot'
  function
* Allow '--snapshot' parameter only in read-only commands that do not
  access lab devices

Closes #1784

Author: ipspace

docs/netlab/capture.md

@@ -12,8 +12,7 @@ You cannot capture traffic on point-to-point links between *‌libvirt* virtual
 The **netlab capture** command takes two parameters: the node you want to perform packet capture on and the interface name within that node.
 
 ```text
-$ netlab capture -h
-usage: netlab capture [-h] [--snapshot [SNAPSHOT]] node [intf]
+usage: netlab capture [-h] [-i INSTANCE] node [intf]
 
 Start a packet capture on the specified node/interface
 
@@ -23,8 +22,8 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
-  --snapshot [SNAPSHOT]
-                        Transformed topology snapshot file
+  -i INSTANCE, --instance INSTANCE
+                        Specify lab instance to capture traffic in
 
 All other arguments are passed directly to the packet-capturing utility
 ```

docs/netlab/collect.md

@@ -3,22 +3,23 @@
 
 **netlab collect** command uses Ansible *device facts* modules (or an equivalent list of Ansible tasks) to collect device configurations and store them in specified output directory.
 
-A single configuration file in the output directory is created for most network devices; multiple files stored in host-specific subdirectory are collected from Cumulus VX.
+A single configuration file in the output directory is created for most network devices; multiple files are collected from FRR and Cumulus VX.
 
 After collecting the device configurations, you can save them in a tar archive with the `--tar` option and clean up the working directory with `--cleanup` option.
 
 ```{tip}
-**netlab collect** command does not need a topology file (so you don't have to specify one even if you're using a non-default topology name). It's just a thin wrapper around an Ansible playbook which uses Ansible inventory created by **netlab create** or **netlab up** command.
+* **netlab collect** command is just a thin wrapper around an Ansible playbook which uses Ansible inventory created by **netlab create** or **netlab up** command.
+* When executed with the `-i` option, **‌netlab collect** switches to the lab directory to execute the Ansible playbook, but stores the results within the directory from which it was executed.
 ```
 
 ## Usage
 
 ```text
-usage: netlab collect [-h] [-v] [-q] [-o [OUTPUT]] [--tar TAR] [--cleanup]
+usage: netlab collect [-h] [-v] [-q] [-o [OUTPUT]] [--tar TAR] [--cleanup] [-i INSTANCE]
 
 Collect device configurations
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   -v, --verbose         Verbose logging
   -q, --quiet           Run Ansible playbook and tar with minimum output
@@ -27,6 +28,8 @@ optional arguments:
   --tar TAR             Create configuration tarball
   --cleanup             Clean up config directory and modified configuration file after
                         creating tarball
+  -i INSTANCE, --instance INSTANCE
+                        Specify lab instance to collect configuration from
 
 All other arguments are passed directly to ansible-playbook
 ```

docs/netlab/config.md

@@ -5,23 +5,23 @@
 
 You have to use **netlab config** on a running lab. If you want to try out the configuration templates without starting the lab,  add the [**config** attribute](custom-config) to node data and run **netlab create** (to create the Ansible inventory) followed by **[netlab initial -c -o](netlab-initial)** to create the configuration files.
 
-```
-
 ## Usage
 
 ```text
-usage: netlab config [-h] [-r] [-v] [-q] template
+usage: netlab config [-h] [-r] [-v] [-q] [-i INSTANCE] template
 
 Deploy custom configuration template
 
 positional arguments:
-  template       Configuration template or a directory with templates
+  template              Configuration template or a directory with templates
 
 options:
-  -h, --help     show this help message and exit
-  -r, --reload   Reload saved device configurations
-  -v, --verbose  Verbose logging (add multiple flags for increased verbosity)
-  -q, --quiet    Report only major errors
+  -h, --help            show this help message and exit
+  -r, --reload          Reload saved device configurations
+  -v, --verbose         Verbose logging (add multiple flags for increased verbosity)
+  -q, --quiet           Report only major errors
+  -i INSTANCE, --instance INSTANCE
+                        Specify lab instance to configure
 
 All other arguments are passed directly to ansible-playbook
 ```
@@ -34,6 +34,10 @@ When you specify a directory name, the **netlab config** command tries to find t
 
 See [](custom-config), [](netlab-initial-custom) and [](dev-find-custom) for more details.
 
+```{tip}
+When executed with the `-i` option, **‌netlab config** expects the configuration template file or directory to be within the lab directory.
+```
+
 ## Limiting the Scope of Configuration Deployments
 
 All unrecognized parameters are passed to the internal `config.ansible` Ansible playbook. You can use **ansible-playbook** CLI parameters to modify the configuration deployment, for example:
@@ -51,4 +55,4 @@ After that, it treats the saved device configurations as custom templates and us
 
 To display device configurations within the Ansible playbook without deploying them, use `-v --tags test` parameters after the template name. 
 
-The `-v` flag will trigger a debugging printout, and the bogus `test` flag will skip the actual configuration deployment.
+The `-v` flag triggers a debugging printout, and the bogus `test` flag skips the configuration deployment.

docs/netlab/connect.md

@@ -6,9 +6,8 @@
 ## Usage
 
 ```text
-usage: netlab connect [-h] [-v] [-q] [--dry-run] [--snapshot [SNAPSHOT]]
-                      [-s SHOW [SHOW ...]]
-                      host
+$ netlab connect -h
+usage: netlab connect [-h] [-v] [-q] [--dry-run] [-s SHOW [SHOW ...]] [-i INSTANCE] host
 
 Connect to a network device or an external tool
 
@@ -17,13 +16,14 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
-  -v, --verbose         Verbose logging
-  -q, --quiet           No logging
-  --dry-run             Print the commands that would be executed, but do not execute them
-  --snapshot [SNAPSHOT]
-                        Transformed topology snapshot file
+  -v, --verbose         Verbose logging (add multiple flags for increased verbosity)
+  -q, --quiet           Report only major errors
+  --dry-run             Print the commands that would be executed, but do not execute
+                        them
   -s SHOW [SHOW ...], --show SHOW [SHOW ...]
                         Show command to execute on the device
+  -i INSTANCE, --instance INSTANCE
+                        Specify lab instance to connect to
 
 The rest of the arguments are passed to SSH or docker exec command
 ```

docs/netlab/down.md

@@ -8,24 +8,26 @@ This command uses the lab topology or the snapshot file created by **netlab up**
 ## Usage
 
 ```
-usage: netlab down [-h] [-v] [--cleanup] [--dry-run] [-i INSTANCE] [--force] [--snapshot [SNAPSHOT]]
+$ netlab down -h
+usage: netlab down [-h] [-v] [--cleanup] [--dry-run] [--force] [-i INSTANCE]
 
 Destroy the virtual lab
 
 options:
   -h, --help            show this help message and exit
   -v, --verbose         Verbose logging (where applicable)
   --cleanup             Remove all configuration files created by netlab create
-  --dry-run             Print the commands that would be executed, but do not execute them
+  --dry-run             Print the commands that would be executed, but do not execute
+                        them
+  --force               Force shutdown or cleanup (use at your own risk)
   -i INSTANCE, --instance INSTANCE
                         Specify lab instance to shut down
-  --force               Force shutdown or cleanup (use at your own risk)
 ```
 
 Notes:
 
 * **netlab down** needs transformed topology data to find the virtualization provider and link (bridge) names.
-* **netlab down** reads the transformed topology from `netlab.snapshot.yml` file created by **netlab up** or **netlab create**. You can specify a different snapshot file name, but you really should not.
+* **netlab down** reads the transformed topology from `netlab.snapshot.yml` file created by **netlab up** or **netlab create**.
 * With the `--instance` flag, you can shut down a lab instance running in a different directory. Use the `netlab status --all` command to display all running instances.
 * Use the `--cleanup` flag to delete all Ansible-, Vagrant- or containerlab-related configuration files.
 * Use the `--force` flag with the `--cleanup` flag if you want to clean up the directory even when the virtualization provider fails during the shutdown process.

docs/netlab/exec.md

@@ -6,21 +6,22 @@
 ## Usage
 
 ```text
-usage: netlab exec [-h] [-v] [-q] [--dry-run] [--snapshot [SNAPSHOT]]                      
-                      node
+$ netlab exec -h
+usage: netlab exec [-h] [-v] [-q] [--dry-run] [-i INSTANCE] node
 
-Executes a command on one or more network devices
+Run a command on one or more network devices
 
 positional arguments:
-  node                  Device(s) to execute the command on
+  node                  Node(s) to run command on
 
 options:
   -h, --help            show this help message and exit
-  -v, --verbose         Verbose logging
-  -q, --quiet           No logging
-  --dry-run             Print the commands that would be executed, but do not execute them
-  --snapshot [SNAPSHOT]
-                        Transformed topology snapshot file
+  -v, --verbose         Verbose logging (add multiple flags for increased verbosity)
+  -q, --quiet           Report only major errors
+  --dry-run             Print the hosts and the commands that would be executed on them,
+                        but do not execute them
+  -i INSTANCE, --instance INSTANCE
+                        Specify lab instance to execute commands in
 
 The rest of the arguments are passed to SSH or docker exec command
 ```

docs/netlab/graph.md

@@ -10,7 +10,9 @@ You will have to install [Graphviz](https://graphviz.org/download/) or [D2](http
 ## Usage
 
 ```text
-usage: netlab graph [-h] [--snapshot [SNAPSHOT]] [-t {topology,bgp}] [-e {graphviz,d2}] [output]
+usage: netlab graph [-h] [-t {topology,bgp}] [-e {graphviz,d2}] [-i INSTANCE]
+                    [--snapshot [SNAPSHOT]]
+                    [output]
 
 Create a graph description in Graphviz or D2 format
 
@@ -19,12 +21,18 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
-  --snapshot [SNAPSHOT]
-                        Transformed topology snapshot file
   -t {topology,bgp}, --type {topology,bgp}
                         Graph type
   -e {graphviz,d2}, --engine {graphviz,d2}
                         Graphing engine
+  -i INSTANCE, --instance INSTANCE
+                        Specify lab instance to create a graph from
+  --snapshot [SNAPSHOT]
+                        Transformed topology snapshot file
+```
+
+```{tip}
+When executed with the `--instance` option, **‌netlab graph** creates the graph description file in the lab directory.
 ```
 
 ## Examples

docs/netlab/initial.md

@@ -33,31 +33,39 @@ Jinja2 templates are used together with **_device_\_config** Ansible modules to
 ## Usage
 
 ```text
-usage: netlab initial [--log] [-q] [-v] [-i] [-m [MODULE]] [-c]  [--ready] [--fast] [-o [OUTPUT]]
+$ netlab initial -h
+usage: netlab initial [-h] [--log] [-v] [-q] [-i] [-m [MODULE]] [-c] [--ready] [--fast]
+                      [-o [OUTPUT]] [--instance INSTANCE]
 
 Initial device configurations
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   --log                 Enable basic logging
+  -v, --verbose         Verbose logging (add multiple flags for increased verbosity)
   -q, --quiet           Report only major errors
-  -v, --verbose         Verbose logging
   -i, --initial         Deploy just the initial configuration
   -m [MODULE], --module [MODULE]
-                        Deploy module-specific configuration (optionally including a 
+                        Deploy module-specific configuration (optionally including a
                         list of modules separated by commas)
-  -c, --custom          Deploy custom configuration templates (specified in "config" 
+  -c, --custom          Deploy custom configuration templates (specified in "config"
                         group or node attribute)
   --ready               Wait for devices to become ready
-  --fast                Use "free" strategy in Ansible playbook for faster
-                        configuration deployment
+  --fast                Use "free" strategy in Ansible playbook for faster configuration
+                        deployment
   -o [OUTPUT], --output [OUTPUT]
                         Create a directory with initial configurations instead of
-                        deploying them
+                        deploying them (default output directory: config)
+  --instance INSTANCE   Specify lab instance to configure
 
 All other arguments are passed directly to ansible-playbook
 ```
 
+```{tip}
+* While most **‌netlab** commands accept the `-i` option to specify the lab instance, you have to use the `--instance` option with **‌netlab initial**.
+* When executed with the `--instance` option, **‌netlab initial -o** switches to the lab directory to execute the Ansible playbook, but stores the results within the directory from which it was executed.
+```
+
 ## Wait for Devices to Become Ready
 
 Some devices are not ready immediately after they complete the boot process. For example, Cisco Nexus OS or Juniper vPTX need another minute to realize they have data-plane interfaces.

docs/netlab/inspect.md

@@ -12,8 +12,10 @@ When selecting data from an individual node, _netlab_ adds group variables to no
 ## Usage
 
 ```text
-usage: netlab inspect [-h] [--snapshot [SNAPSHOT]] [--node NODE] 
-                      [--all] [--format {yaml,json}] [expr]
+$ netlab inspect -h
+usage: netlab inspect [-h] [--node NODE] [--all] [--format {yaml,json}] [-q]
+                      [-i INSTANCE] [--snapshot [SNAPSHOT]]
+                      [expr]
 
 Inspect data structures in transformed lab topology
 
@@ -22,11 +24,14 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
-  --snapshot [SNAPSHOT]
-                        Transformed topology snapshot file
   --node NODE           Display data for selected node(s)
   --all                 Add global Ansible variables to node data
   --format {yaml,json}  Select data presentation format
+  -q, --quiet           Report only major errors
+  -i INSTANCE, --instance INSTANCE
+                        Specify lab instance to inspect
+  --snapshot [SNAPSHOT]
+                        Transformed topology snapshot file
 ```
 
 ## Topology Inspection Examples

docs/netlab/report.md

@@ -6,7 +6,9 @@ The **netlab report** command creates a report from the transformed lab topology
 ## Usage
 
 ```text
-usage: netlab report [-h] [--snapshot [SNAPSHOT]] [--node NODE] report [output]
+$ netlab report -h
+usage: netlab report [-h] [--node NODE] [-i INSTANCE] [--snapshot [SNAPSHOT]]
+                     report [output]
 
 Create a report from the transformed lab topology data
 
@@ -16,9 +18,11 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
+  --node NODE           Limit the report to selected node(s)
+  -i INSTANCE, --instance INSTANCE
+                        Specify lab instance to report on
   --snapshot [SNAPSHOT]
                         Transformed topology snapshot file
-  --node NODE           Limit the report to selected node(s)
 ```
 
 ```{tip}

docs/netlab/restart.md

@@ -2,16 +2,18 @@
 
 **netlab restart** executes **[netlab down](down.md)** followed by **[netlab up](up.md)** to restart your lab from the transformed lab topology stored in `netlab.snapshot.yml` snapshot file.
 
-You can use **netlab restart** to restart the existing lab (use `--snapshot` keyword), or to recreate the lab configuration files in case you changed the lab topology.
+You can use **netlab restart** to restart the existing lab (use `--snapshot` keyword) or recreate the lab configuration files if you changed the lab topology.
 
 ```{warning}
-**netlab restart** does not support `-d`, `-p` or `-s` flags used by **netlab create** or **netlab up**. If you want to change lab topology settings with CLI parameters use **netlab down** and **netlab up** commands.
+* **netlab restart** does not support `-d`, `-p` or `-s` flags used by **netlab create** or **netlab up**. If you want to change lab topology settings with CLI parameters, use **netlab down** and **netlab up** commands.
+* You must execute the **‌netlab restart** command within the lab directory.
 ```
 
 ## Usage
 
 ```text
-usage: netlab [-h] [--log] [-q] [-v] [--no-config] [--fast-config]
+$ netlab restart -h
+usage: netlab [-h] [--log] [-v] [-q] [--no-config] [--fast-config]
               [--snapshot [SNAPSHOT]]
               [topology]
 
@@ -20,14 +22,13 @@ Reconfigure and restart the virtual lab
 positional arguments:
   topology              Topology file (default: topology.yml)
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   --log                 Enable basic logging
-  -q, --quiet           Report only major errors
   -v, --verbose         Verbose logging (add multiple flags for increased verbosity)
+  -q, --quiet           Report only major errors
   --no-config           Do not configure lab devices
   --fast-config         Use fast device configuration (Ansible strategy = free)
   --snapshot [SNAPSHOT]
-                        Use netlab snapshot file created by a previous lab run 
-                        to start the lab
+                        Transformed topology snapshot file
 ```

docs/netlab/status.md

@@ -9,20 +9,20 @@ This command uses the *netlab* status file (default: `~/.netlab/status.yml`) to
 
 ```
 $ netlab status -h
-usage: netlab status [-h] [-i INSTANCE] [-l] [--cleanup] [--reset] [--all] [-v] [-q]
+usage: netlab status [-h] [-l] [--cleanup] [--reset] [--all] [-v] [-q] [-i INSTANCE]
 
 Display lab status
 
 options:
   -h, --help            show this help message and exit
-  -i INSTANCE, --instance INSTANCE
-                        Display or cleanup specific lab instance(s)
   -l, --log             Display the lab instance event log
   --cleanup             Cleanup the current or specified lab instance
   --reset               Reset the lab instance tracking system
   --all                 Display an overview of all lab instance(s)
   -v, --verbose         Verbose logging (add multiple flags for increased verbosity)
   -q, --quiet           Report only major errors
+  -i INSTANCE, --instance INSTANCE
+                        Specify lab instance to inspect
 ```
 
 * **netlab status** displays the status and workload (VMs or containers) of the current or selected lab instance.