General Usage

Available Versions

The following executables apply to the appropriate operating system (OS):

  • breakout-linux-x86_amd64 – Breakout utility for Linux

  • breakout-macos-x86_amd64 – Breakout utility for macOS

  • breakout-windows-x86_amd64.exe – Breakout utility for Microsoft Windows OS

For the remainder of the instructions the term breakout refers to the appropriate executable binary based upon your OS.

Configuration Files

The CML 2 Breakout utility uses two files:

  • Server configuration file - The server configuration file specifies the hostname or IP address of the CML 2 server, credentials for establishing a connection to the server, and other session options.

    There are methods to have this file generated by the Breakout utility which are explained below.

  • Lab configuration file - The lab configuration file specifies the labs and nodes that are running, and provides the ability to enable/disable the ability to connect with them with the CML 2 Breakout utility. The ports, where a node is reachable on, are defined in this file.

    There are methods to have this file generated by the Breakout utility which are explained below.

Executable Options

The Breakout utility can be executed with the following options:

breakout {config | init | ui | run}

Each of these options is explained further:

breakout config

This execution option creates a default server configuration file called config.yaml. The file can then be modified later, based on your needs (i.e., modification of the controller’s hostname or IP address).

breakout init

This execution option uses the information in the server configuration file, connects to the controller and retrieves information about running labs and creates a file called labs.yaml.

breakout ui

This execution option will start a web based UI for the creation and modification of the server configuration file.

The UI is then available by default on port TCP/8080 of the local host. Open a browser with this URL: <http://localhost:8080/>. The port and listen address can be configured via the command line or the configuration file.

The use of the UI is the easiest way to use the CML 2 utility while learning the server and lab configuration file format.

Once connectivity can be established to the server, the lab configuration file can be created / modified through the GUI. A retrieval of the active labs can be accomplished, and then the serial ports for active nodes for that lab can be enabled / disabled as needed.

Note

Any changes to the server configuration section of the GUI, will require the Breakout utility to be restarted for the changes to take effect. For example, if you change the IP address of the server in the GUI, the Breakout utility will need to be restarted so that connectivity to the new IP address can be established before any of the labs can be retrieved.

Note

Users that prefer a graphical interface can create a batch file that changes the command prompt to the directory of the Breakout executable and then launch the Breakout utility in UI mode. They can then connect to the Breakout UI via their browser for the remaining tasks to establish console connectivity.

breakout run

This execution option will start the Breakout utility and use the default server configuration file config.yaml and the default lab configuration file labs.yaml unless other configuration files are specified.

It will then display a table with the nodes and ports forwarded and listen for connections on these ports, forwarding them to the remote controller as configured.

This can be stopped by pressing Ctrl-C.

Other Command Line Options

The following is a list of additional command line parameters that can be executed to modify the behavior of what is specified in the server configuration file.

  • -noverify overrides the TLS verification setting in the server configuration file. When given, the Breakout utility does not verify the TLS certificates.

  • -listen <address> overrides the specified local host listen IP address. This can be used to set e.g. -listen 127.0.0.1 listens on the localhost IPv4 address instead of the IPv6 in the default configuration.

    Note

    If the listen_address in the server configuration file is empty, then it will listen on all interfaces. As Telnet and VNC access on the exposed ports is then available unencrypted from the outside, this should be considered carefully!

  • (init specific) when a lab ID or a unique lab name is provided as a 2 nd argument, then the Breakout utility will only retrieve the information for the specified lab and enables it by default.

  • -config file specifies the server configuration file to use.

  • -labs file specifies the lab configuration file to use.

  • -extralf send an extra LF when serial line is opened.

  • -port local port to listen on for UI mode (default 8080.)