Console Server¶
CML includes a built-in console or terminal server which provides CLI based access to consoles of network nodes running in a topology. The terminal server uses SSH as the transport protocol and requires authentication using the same credentials as the web user interface.
Usage¶
To use the terminal server, a SSH client is needed. The terminal server runs on the standard SSH port on the CML controller (e.g. TCP/22). User credentials are the same as the ones used to log into the web user interface. Here’s an example:
$ ssh yourusername@some.host.lab
yourusername@some.host.lab's password:
****
CML2 Console Server
Copyright (c) 2019-2022 Cisco Systems, Inc. and/or its affiliates
****
tab completion works
list available nodes and node labels / IDs with "list"
it's also possible to do a "open /lab_1/n0/0" command
consoles>
From here, help is available via the help command:
consoles> help
Available commands:
(Note: you can do tab-completion)
all toggle all labs or only mine (needs admin permissions)
clear clear the screen
exit exit the console server
help this help
labs available lab details
list list all available consoles, including labels and lines
open open connection to a console. Example: "open /lab_1/n0/0"
quit exit the console server
refresh refresh data from controller (done after 10s automatically)
consoles>
Here’s some additional comments on a few of these commands. Most of them should be self-explanatory.
At the prompt, pressing the “tab” key completes the command, when possible… E.g. when entering the letter “o” at the prompt, followed by a “tab” will complete to the “open” command.
If a command takes additional parameters (currently only the open command does), then those parameters can also be completed by pressing the tab key.
The all command¶
This only makes sense when the logged in user has admin permissions. By default, the terminal server only lists labs and nodes which are owned and / or accessible by the user.
If the user has admin privileges, then all running labs of all users can be accessed. To make the terminal server list these labs, the all command can be used. This command toggles between listing all labs or only the labs the user owns/can access.
The list command¶
This command lists all currently running nodes with their lab and node names and the available lines (a number starting at zero).
A server / Unix type kind of node typically has one serial console. An IOSv device, on the other hand, typically has two:
0, which is the standard console port -and-
1, which is the auxilliary or aux port.
Typically, only the first port (console) is used. In specific situations, other ports than the first one can be accessed. For example, the XR 9000v devices have four consoles running from 0 to 3 which access different components of the router.
Example:
consoles> list
Lab Node Lines
-------------------------------------------------------------------------------
Lab at Wed 22:21 PM iosv-0 0,1
Lab at Wed 22:21 PM nxos9000-0 0,1
interfacemismatch66 ubuntu-0 0
consoles>
The lab command¶
The lab command lists all running labs without the nodes… This might be useful when a lot of nodes are running to get a quick overview of the available labs:
consoles> labs
Lab Nodes Links
-------------------------------------------------------------------------------
interfacemismatch66 3 2
Lab at Wed 22:21 PM 2 1
consoles>
The open command¶
The open command is used to access the actual console of the device. It uses a single, path-style parameter to define which exact console should be opened.
This path has three componets which are separated by a forward slash:
the lab name
the node name
the number of the console (typically 0)
Note Tab completion can be used to list all available nodes. A node can then be selected using the cursor keys to move the highlighted node. Return selects / opens the highlighted node.
Example:
consoles> open /
/Lab at Wed 22:21 PM/iosv-0/0 /Lab at Wed 22:21 PM/iosv-0/1
/Lab at Wed 22:21 PM/nxos9000-0/0 /Lab at Wed 22:21 PM/nxos9000-0/1
/interfacemismatch66/ubuntu-0/0
Here, five nodes are shown and after “open”, the user pressed tab twice, to show the list of those nodes.
When the correct/desired node is highlighted (or by typign the correct path) and after pressing “enter”, the terminal server connects to that particular console port of the node:
consoles> open /Lab at Wed 22:21 PM/iosv-0/0
Connecting to console for iosv-0
Connected to terminalserver.
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. *
**************************************************************************
iosv-0>
Note The first three lines up to the “Escape character” line are printed by the terminal server. If there’s no additional output (which is normal), then pressing “enter” once should result in a prompt as shown above.
The refresh command¶
By default, the terminal server refreshes the list of available labs and nodes every ten seconds. A manual refresh can be triggered by running the refresh command.
Disconnecting¶
When the terminal server session is connected to the node console, a specific escape sequence must be used to disconnect the console and get back to the terminal server prompt. This sequence is Control-]:
iosv-0>
disconnected.
consoles>
As shown above, the terminal server confirms the disconnect by printing the “disconnected.” message, issuing the “consoles>” prompt again.
Advanced Usage¶
In addition to the interactive usage of the terminal server another direct access method is possible. This bypasses the terminal server prompt and connects directly to the desired node console while still requiring authentication.
To use this, the SSH client can be given an additional parameter which indicates the command “open” and the path of the /lab/node/console to connect to (which, of course, must be known upfront).
In addition, the SSH client must be instructed to request an interactive terminal as this is not the default when a remote command is given.
Here’s an example:
ssh -t yourusername@some.host.lab "open /Lab at Wed 22:21 PM/iosv-0/0"
yourusername@some.host.lab's password:
Connecting to console for iosv-0
Connected to terminalserver.
Escape character is '^]'.
iosv-0>
Note The remote command (“open …”) has to be quoted as it contains spaces. Also note the direct connection to the node’s CLI.