clab_terminal_launcher 0.1.0.post1

A fully-customizable automated terminal launcher designed for use with virtualized network devices in Containerlab

Terminal Launcher for Containerlab

Table of Contents

• Terminal Launcher for Containerlab
  • Table of Contents
  • Synopsis: Why?
  • Supported Features
    • Features
    • Caveats, Limitations, and Warnings
  • Installation and Usage Documentation

---

Synopsis: Why?

Let's get something out in the air right off the bat - Containerlab is awesome! If you're looking at this repository, I probably don't need to espouse the use cases and benefits of Containerlab compared to other network emulation platforms. That said, why not? Let's do it!

• Native support for containerized network operating systems (e.g., Arista cEOS, Cisco XRd, Nokia SR Linux)
• Easy sharing of labs (e.g., intrinsic Git integration)
• Lightweight/streamlined deployment model; "lab as code"

However, one annoyance of Containerlab (in its current form) is how it handles connections to the containerized network devices running inside of labs. Since the management networking is handled natively using the Docker bridge driver, it means that, by default, only the Containerlab host has access to the management IP addresses of the virtualized devices. Currently, Containerlab has no mechanism to map the management port (e.g., SSH port) of the lab devices to a port on the Containerlab host's IP address via PAT/port forwarding.

This is fine if Containerlab is running directly on your client system (e.g., your laptop), but it becomes a significant concern if you are trying to run Containerlab on a remote system (e.g., a beefier server with more resources to run more demanding VM-based devices in labs). In this model, the client doesn't have access to the management IPs of the lab devices connected to the Docker bridge. As such, how is the client machine supposed to launch an SSH session?

There are three main, recommended approaches:

• Launch an SSH session and obtain a shell on the Containerlab host. Within the remote shell, launch a second SSH session to the lab device.
  • This is the approach used by the SSH button in the Containerlab VS Code extension
• Use the ports directive in the Containerlab topology definition to map the SSH port of the lab device to a port on the IP address of the Containerlab host
• Specify the Containerlab host as an SSH jumphost (e.g., using the SecureCRT firewall option or the -J flag in the OpenSSH client) when connecting directly to the IP address/DNS hostname of the lab device

There are also some deployments that have successfully configured the underlying network to route all management traffic for Containerlab-managed lab devices to the Containerlab host using the respective Containerlab management subnet (e.g., 172.20.20.0/24 by default). However, for most deployments/networks, this presents a lot of unnecessary complexity. In most cases, this approach also prevents the use of the convenient DNS names generated by Containerlab, as those are directly stored on the hosts file of the Containerlab host. Additionally, you may also run into NAT issues with this approach, as Docker will, by default, NAT/masquerade all traffic on this management bridge.

These approaches all require a ton of manual labor; unless you are launching your connections to the lab devices using the buttons in the VS Code extension, you'll have to create each session manually, more or less.

That's where the terminal launcher for Containerlab comes into play. Could I have thought of a more inventive name? Probably. But, boring name for a boring tool, am I right? :)

Supported Features

Features

• Highly customizable, but still easy to use - lots of options to allow this utility to work with all manner of Containerlab/terminal client environments
  • Supported terminal emulators:
    • SecureCRT (preferred) - VanDyke Software
    • PuTTY (regular, windowed version) - open source by Simon Tatham
    • MTPuTTY (tabbed PuTTY-based client; Windows only) - TTYPlus
    • Native terminal + OpenSSH - OpenBSD Project, et al.
• Automated discovery of running Containerlab devices (either using the API or the output from clab inspect)
• Automated connection and launching of sessions to lab devices running in a Containerlab topology using DNS names, IPv4/IPv6 addresses, or the Containerlab host address
• Support for automated credential autofill with most connection/launch methods
• Support for defining environment variables for utility configuration to reduce time to use on subsequent occasions
• Support for Containerlab devices with custom SSH ports besides the default port 22 using a YAML file
• Comprehensive YAML-based credential definition file, complete with hierarchical specification by node name, image, kind, and default credentials (in decreasing order of precedence)
• Saves running node and lab data as a JSON file on disk, so you don't always need to retrieve the data prior to calling the launch command if the running nodes haven't changed
• Detailed console logging to display useful information during utility execution
• Complete error handling and input validation to ensure safe execution and clean/useful error messages - as far as I'm aware at least, don't take this as a challenge please! :)
• Lightweight footprint, with few external dependencies; pure Python, installation is as easy as running pip install!

Caveats, Limitations, and Warnings

• Only SSH is supported as a connection method at this time. However, the utility's codebase is architected such that it would be fairly easy to expand beyond SSH, so that could change if the need arises!
• When running launch commands on WSL 2 referencing a Windows executable, the CLI has a tendency to get messed up. In most cases, you simply need to run the reset command to fix this. You can also just run the utility directly on Windows to avoid this issue.
• WARNING: It is assumed that lab device passwords are NOT sensitive. They are stored in PLAIN TEXT inside of the credentials YAML file. Do NOT use a password that actually matters for your lab devices!!!

Installation and Usage Documentation

Check out more about how to install and use this utility by referencing the installation and usage instructions!