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 :sup:`2` Breakout utility uses two files:

- **Server configuration file** - The server configuration file specifies the
  hostname or IP address of the CML :sup:`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 :sup:`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:

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 :sup:`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
  :sup:`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.)
