Configuring CML-P Breakout Tool for MacOS

Cisco has released the next iteration of VIRL, which is now named CML-P (Cisco Modeling Labs – Personal edition).

The Breakout Tool allows you to use your terminal application, such as iTerm2, to console into your lab network devices within CML-P.

Accessing the Breakout Tool

Once logged into CML-P, click on Tools and click on Breakout Tool which will open in a new window.

You’ll see text describing the Breakout Tool, how to install it, and utilize the command line interface. As described on the page:

The CML² breakout utility provides users connectivity to the device console ports that are operating in a lab environment. It acts like a a local terminal server that embeds the various serial ports/lines into an single HTTPS connection to the control server. Console access is done via Telnet and the graphics framebuffer is accessed via the VNC protocol.

The breakout utility allows for users to use their favorite external terminal emulator like Putty, Kitty, SecureCRT, etc. to devices in CML².

What is CML-P Breakout Tool

Scroll all the way to the bottom of the page where you’ll find the files you need to run the CML-P Breakout Tool. Save the file into it’s own folder.

Using the Breakout Tool

The Breakout Tool should be downloaded into it’s own folder. Once we get the Breakout Tool running, it will end up creating a YAML file.

Once the file is downloaded into it’s own directory, we need change it so it is executable. If you look at the permissions, it is not set to execute.

$ ls -l
total 27584
-rw-r--r--@ 1 cts  staff  13390936 May 31 20:09 breakout-macos-x86_amd64

Our next step is to modify the file permissions so it is executable. You may need to run this with elevated privileges:

$ chmod u+x breakout-macos-x86_amd64

We can see the permissions have changed:

$ ls -l
total 27584
-rwxr--r--@ 1 cts  staff  13390936 May 31 20:09 breakout-macos-x86_amd64

Now we can execute the file and see what options we have. Running the command requires a parameter. Without a parameter you are given some options.

$ ./breakout-macos-x86_amd64
missing parameter
breakout-macos-x86_amd64 0.2.1-build-v2.0.0-13
Build info:
  Built:      2020-04-08T19:39:15Z
  Git commit: 3a441a53a0aa549a
  Go version: go1.12.14
  Platform:   linux/amd64
  Build host: virl-rtp-jenkins-1.cisco.com 4.18.0-80.11.2.el8_0.x86_64 x86_64


Usage:
	breakout-macos-x86_amd64 [flags] COMMAND
Parameters:
	COMMAND (required), 'config', 'init', 'run' or 'ui'
	'init' takes an optional 'lab' argument
	it will look for a lab ID or label that matches
	if providing a lab title, it has to be unique
	BREAKOUT_ enviroment variables control config as well.
Workflow:
	- create a default configuration file with 'config', adapt to your needs
	- use 'init' to retrieve lab information from controller
	- enable labs or individual nodes in lab configuration file created by 'init'
	- use 'run' to start the breakout process
Alternative:
	- use 'ui' to run a web frontend.
Flags:
  -alsologtostderr
    	log to standard error as well as files
  -config string
    	global configuration filename (default "config.yaml")
  -extralf
    	send an extra LF when serial line is opened
  -labs string
    	the data file to use (default "labs.yaml")
  -listen string
    	address to listen on (default "[::1]")
  -log_backtrace_at value
    	when logging hits line file:N, emit a stack trace
  -log_dir string
    	If non-empty, write log files in this directory
  -logtostderr
    	log to standard error instead of files
  -noverify
    	disable TLS verify
  -port int
    	local port to listen on for UI mode (default 8080)
  -stderrthreshold value
    	logs at or above this threshold go to stderr
  -v value
    	log level for V logs
  -vmodule value
    	comma-separated list of pattern=N settings for file-filtered logging

The parameter options are:

• config
• init
• run
• ui

The easiest option, in my opinion, is to run the ui parameter. This starts up a web server locally on your computer. And from that user interface, we’ll be able to configure the rest of the Breakout Tool to be used with CML-P.

Issue the following command, ./breakout-macos-x86_amd64 ui

$ ./breakout-macos-x86_amd64 ui
Starting up...
W0531 20:21:08.392662   89716 run.go:238] open labs.yaml: no such file or directory
Running... Serving UI/API on http://[::1]:8080, Ctrl-C to stop.

From here we can see that we can browse to http://localhost:8080.

Configure the Breakout Tool

You’re now looking at the webpage located at http://localhost:8080. From there, click on Configuration. This is where we will set the location of our CML-P server instance with the correct credentials. You can follow the same settings below, but change your username and password to reflect your installation.

While this is all running, your terminal window will continue to show output. You can close down the server by issuing CTRL-C, but don’t do that yet.

What parameters you need to configure:

Controller address – The url to your CML-P instance
Verify TLS certificate – Disable this option
Populate all nodes – When enabled, fetches all available nodes from controller. Otherwise only ‘started’ nodes will be included.
Username – The username to log into your CML-P instance.
Password – The password for the user account above.
Leave everything else in defaults.

Click on Save and then click on the Labs tab at the top of the window.

Click on the blue Refresh button to have the Breakout Tool load your available labs.

In order to console into your network device, the Status for the lab needs to be On. Click on the button to activate the status. Then click on your lab.

With the Status set to On, we can see the URL to reach these network devices using iTerm2 and at which port. You’ll notice that it is using Telnet, which port to reach the entwork device, the status of the serial port and whether it is enabled.

I noticed that the link is hyperlinked but doesn’t do anything for me when clicked. It also appears to be in IPv6.

Console into your lab devices

Now let’s head over to iTerm2. You will notice in my example, SW1 is using serial0 on port 9000. All we have to do is telnet to our localhost on port 9000.

telnet localhost 9000

Then you’ll find that you’re able to log into your network device!

$ telnet localhost 9000
Trying ::1...
Connected to localhost.
Escape character is '^]'.

**************************************************************************
* IOSv is strictly limited to use for evaluation, demonstration and IOS  *
* education. IOSv is provided as-is and is not supported by Cisco's      *
* Technical Advisory Center. Any use or disclosure, in whole or in part, *
* of the IOSv Software or Documentation to any third party for any       *
* purposes is expressly prohibited except as otherwise authorized by     *
* Cisco in writing.                                                      *
**************************************************************************
SW1>en
SW1#show version
Cisco IOS Software, vios_l2 Software (vios_l2-ADVENTERPRISEK9-M), Version 15.2(CML_NIGHTLY_20190423)FLO_DSGS7, EARLY DEP