CML 2.6 Release Notes

Cisco Modeling Labs (CML) is a network simulation platform. CML 2.6 is the latest feature release of CML and introduces a redesigned Workbench UI, a new maintenance mode for use on multi-user CML instances, and support for deployment to AWS. This release also includes further improvements for accessibility, external connectivity, cluster deployments, link conditioning, node and image definitions.

New and Changed Information

This table shows any published changes to this CML 2.6 release notes document.

Date	Changes
July 20, 2023	Initial version for the CML 2.6.0 release.
August 9, 2023	Updating Known Issues. Updating advice about upgrading to CML 2.6. Adding screenshots to the Summary of Changes and a video overview of CML 2.6 features.
October 6, 2023	Updating Bug Fixes and Known Issues for the 2.6.1 maintenance release.
October 20, 2023	Updating Known Issues for the 2.6.1 maintenance release.

Installing or Migrating to CML 2.6

Upgrading to CML 2.6

There are a few changes to the upgrade process for CML 2.6.0. Please read this section carefully before starting an upgrade to CML 2.6.0.

• We recommend reviewing the Known Issues and Caveats for CML 2.6 before upgrading to a new CML release. The latest release may include bugs that impact specific features or CML installation types. Depending on how you deploy and use CML, you may want to skip a release and wait until a specific bug is fixed in a future maintenance release.
• If your CML instance is already running CML 2.3.0 or later, you can upgrade it to CML 2.6.0.
• In most cases, you must first log in to Cockpit and install the latest software updates before upgrading to CML 2.6.0. Otherwise, the upgrade will fail due to unmet package dependencies because of a known problem in the CML 2.6.0 upgrade .pkg.zip file. Even if you are running an offline or air-gapped CML instance, you still need to install the latest software updates. If you cannot install the latest software updates before upgrading to CML 2.6.0, contact Support.
• After the upgrade completes, you must disable maintenance mode and change the state of the compute (on a cluster, at least one compute member's state) back to READY before you can start CML labs again. This post-upgrade step is new in CML 2.6.0 and is part of the maintenance mode feature, described in the Summary of Changes below.
• See the In-Place Upgrade page for detailed upgrade instructions.

In-place upgrades from CML version 2.2.3 or earlier are not supported. See migration instructions below.

Upgrading a CML Cluster to CML 2.6

If you have deployed a CML cluster, you may upgrade it to CML 2.6.0.

When upgrading from CML 2.4.0, which introduced cluster support, you must manually run the CML upgrade first on the controller and then separately on each compute member.

If you are upgrading from CML 2.5.0+, you only need to run the CML upgrade on the controller. The CML controller's upgrade automatically initiates a CML upgrade on the cluster's compute members.

Migrating from an Existing CML 2.2 Installation

It is not possible to upgrade a CML 2.2.x installation to CML 2.6. You must migrate to a new CML 2.6 installation. If you have an existing CML 2.2.x installation, the migration tool will help you migrate your data from your existing CML installation to the new CML 2.6 installation. If your existing CML installation is CML 2.0.x or 2.1.x, we recommend first following the CML 2.2.x documentation to perform an in-place upgrade to CML 2.2.3 before migrating to a new CML 2.6 installation. The following video demonstrates the migration process from CML 2.2 to CML 2.3, and you can use the same steps to migrate from CML 2.2.3 directly to CML 2.6.

Note: If you choose to migrate an existing, licensed CML 2.2.x installation to a new installation of CML 2.6, you must deregister the old CML instance before decommissioning it. See Licensing - Deregistration for instructions on deregistering a CML instance.

1. Deregister your existing CML 2.2.x instance.
2. Install CML 2.6 (see below).
   • Since you are migrating from an existing CML 2.2.x installation, mounting the reference platform ISO before running the CML 2.6 installation is optional.
   • If the reference platform ISO is mounted before starting the CML 2.6 installation, the setup script will copy reference platform images from a mounted reference platform ISO to the local disk.
   • You can skip the copying of reference platform images during installation because the migration tool will copy all the reference platform images from your CML 2.2.x installation to the new CML 2.6 installation.
   • Only mount the new reference platform ISO if you want to add the new versions of the reference platforms in addition to the existing versions from your CML 2.2.x installation.
3. Follow the instructions in the migration tool's README.md to migrate data from your existing CML 2.2 installation to your new CML 2.6 installation.
4. License your new CML 2.6 installation.

The migration tool can be found on your CML 2.6 installation at /usr/local/bin/virl2-migrate-data.sh. You can also download the latest version of the migration tool from https://github.com/CiscoDevNet/cml-community/tree/master/scripts/migration-tool.

The migration tool also supports offline migration. If you want to install CML 2.6 on the same server that is currently running CML 2.2.x, you can use the Offline Version Migration instructions to back up the data to a .tar file. That way, you can transfer the .tar file to a separate datastore temporarily while you reinstall with CML 2.6. As always, make sure that you deregister your old CML 2.2.x instance before decommissioning it and starting the CML 2.6 installation.

Installing CML 2.6

The CML Installation Guide provides detailed steps for installing your new CML 2.6 instance.

• In CML 2.6, all the reference platform VM images must be copied to the local disk of the CML instance. Be sure to provision enough disk space for your new CML instance to accommodate the reference platforms.
• Downloading the refplat ISO file is optional if you are migrating from an existing CML 2.2.x instance. The migration tool will migrate all of your existing image definitions and VM images from your old CML 2.2.x instance.
• Be sure to check the System Requirements for updated system requirements.
• Important: After the reference platforms are copied to disk during the Initial Set-Up, wait a couple of minutes for the CML services to finish restarting before clicking OK to continue. If you click OK too soon, the initial set-up can fail. (See the Known Issues below.)

Demonstration of CML 2.6 Features

You can see a brief demo of the new CML 2.6 features in the following video:

Summary of Changes

This section details new and changed features in the new release. Bug fixes are listed in the subsequent section.

UI Changes

CML 2.6 introduces a completely redesigned Workbench UI to provide a more streamlined and unified experience when working with a lab. A new onboarding tour makes all the changes easier to understand for both existing and new users. The tour is displayed to each user on your CML instance the first time they log in and visit the Workbench after the 2.6 upgrade.

For details on using the Workbench, see the Workbench section in the CML User's Guide.

Panes

The PANES panel is a versatile tool designed to give you a flexible workspace. When you open a console, VNC session, or packet capture, the Workbench opens it in a tab in the active pane of the PANES panel. You can open multiple tabs in each pane. You may also open multiple panes side-by-side in the PANES panel so that, for example, you can have a console session open in one pane and a packet capture session running in another.

For details on using panes, see the Panes section in the CML User's Guide.

Sidebar

The sidebar provides a single, consolidated hub for viewing and modifying all of your lab elements' properties. Whether you want to edit a node, link, or annotation, simply select it in the Workbench canvas, and the sidebar will display the relevant properties and editing options.

This streamlined way to manage your lab elements eliminates the need for the bottom panel to shift in response to the workbench state, which gives you a more focused experience.

With this setup, you can keep your attention on the bottom pane, while simultaneously editing properties of a lab element using the sidebar.

Right-click Context Menu

The Workbench now exposes the most common actions for each lab element in a context menu. Activate the context menu by right-clicking a single element in the canvas. This menu presents a list of actions specifically tailored to the selected element type.

In addition, you can right-click the canvas without selecting any elements to display a menu of lab actions, such as Start Lab and Stop Lab. You can also access the lab actions via the Workbench toolbar by clicking LAB in the toolbar.

Multi-select Action Menu

When you select multiple elements in the Workbench canvas and then right-click, CML shows the multi-select action menu. This context-sensitive menu shows a distinct section for each element type. Within each section, you can perform actions on all selected elements of that type. For example, you can open the console for multiple nodes at once via the multi-select action menu. Please note, however, that the UI currently does not verify whether the action is valid for the selected elements. For example, if you select multiple nodes in the STOPPED state, the multi-select action menu shows an action to open node consoles, but that action is only valid for nodes in the STARTED and BOOTED states.

In addition to the regular node actions, when you select multiple nodes, the multi-select action menu includes an Alignment section, providing options for aligning the selected nodes.

Note that the context menu for a single selected element typically provides a greater number of actions than the multi-select action menu does for elements of that type.

Adding Nodes

You can still add new nodes to your lab in the Workbench by using drag-and-drop to drop nodes onto the canvas. This interactive drag menu was previously located on the right-side menu. In CML 2.6, you can activate the menu simply by clicking the Add Nodes icon in the Workbench toolbar.

In addition to this traditional method of adding nodes, CML 2.6 introduces a brand-new Bulk Add feature. It's designed with accessibility in mind, so you can add as many nodes as you need using only your keyboard, eliminating the need to use a mouse when adding new nodes.

Keyboard Shortcuts

Keyboard Shortcut	Function
DEL	Opens a dialog to delete all selected elements
ALT + C	Opens the Connection dialog, where you to choose source and destination nodes. Your selections automatically populate the next free interface. If you select two nodes before you open the dialog, it also automatically populates the source and destination nodes.
ATL + N	Opens the Add Node dialog in the bulk mode, allowing the addition of one or more nodes to the canvas using only keyboard navigation.

Improved UX for CML Cluster Deployments

CML 2.6 improves user experience, especially in cluster deployments. Dialogs that display data for all members in a cluster are now less complex and more compact. CML 2.6 introduces scrollbars in elements that can overfill the CML UI, such as the footer bar or health status bar.

In addition, CML 2.6 introduces changes to cluster members' state handling. Expected states do not supersede the overall state of the rest of the cluster. For example, if a cluster compute member is expected to be disconnected and the remaining cluster computes are healthy, no warnings are displayed in the UI.

PATty

CML 2.6 introduces a flexible new tool for port forwarding and on-board device breakout. PATty provides an alternative approach to exposing and accessing the consoles for your labs' nodes. PATty is disabled by default, and you should understand the security implications of PATty versus the Console Server and the Breakout Tool before you enable it.

For more information, see PATty Tool.

AWS Support

CML 2.6 makes running a CML instance on AWS a supported deployment option.

For more information, see CML on Amazon Web Services.

Maintenance Mode

CML 2.6 introduces the ability to put the CML instance into maintenance mode. This feature allows CML administrators to prevent all non-administrator logins and changes on the CML instance while they perform an upgrade or performing other system maintenance. In addition, the CML administrator can control an individual compute member's lifecycle by changing its admission state. For example, the REGISTERED state is used to keep a host disconnected during maintenance.

For more information, see System Maintenance in the CML Administrator's Guide.

Notices

In addition to the maintenance mode feature, CML 2.6 introduces the ability to notify users about important upcoming or ongoing events. Administrators can configure a title and content for each notice and select which users should be shown the notice. Administrators can monitor the state of notices and see whether specific users have acknowledged a system notice.

For more information, see System Notices in the CML Administrator's Guide.

External Connectors

In the CML 2.6 Workbench, the configuration for an external connector in bridge mode now provides a dropdown list that includes bridge names or aliases on the controller. That way, you no longer have to enter the name of a bridge device manually.

CML 2.6 introduces the ability to configure bridge parameters, such as IP snooping and bridge protection, in the CML UI. CML administrators can provide a label for defined bridges to provide logical names for the bridges and to insulate your users from the specific bridge names in use. The IP snooping functionality has also been extended to all bridges instead of only the system bridge bridge0.

For more information, see External Connectors in the CML Administrator's Guide.

Persistent Link Conditioning

CML 2.6 introduces persistent link conditioning. In previous releases, you could configure link condition properties, such as link loss and bandwidth, but those properties were lost when you stopped the lab. Starting with CML 2.6, CML persists all link condition properties with the lab. The properties are also included with the exported topology: if you download the lab and import it again, the link condition properties will be preserved.

For more information, see Link Conditioning in the CML User's Guide.

Improvements to Node and Image Definitions

CML 2.6 introduces an option to make node definitions read-only or read-write, enabling you to prevent or allow changes to a node definition.

For more information, see Creating A New Node Definition in the CML Administrator's Guide.

API Changes

CML 2.6 introduces several changes to the REST-based web service APIs. For details about a specific API, log in to the CML UI and click Tools > API Documentation to view the CML API documentation page.

APIs Removed in CML 2.6

This table summarizes the API endpoints that have been removed in CML 2.6.

Removed API Endpoint	Use This API Endpoint Instead
GET /labs/{lab_id}/external_connections	GET /system/external_connectors

APIs Deprecated in CML 2.6

This table summarizes the API endpoints that have been deprecated in CML 2.6.

Deprecated API Endpoint	Use This API Endpoint Instead
POST /labs/{lab_id}/nodes/{node_id}/tags/{tag}	PATCH /labs/{lab_id}/nodes/{node_id}
DELETE /labs/{lab_id}/nodes/{node_id}/tags/{tag}	PATCH /labs/{lab_id}/nodes/{node_id}

New APIs in CML 2.6

This table summarizes the API endpoints that are new in CML 2.6.

API Endpoint	Description
GET /system/compute_hosts/configuration	Get administrative state for new compute members (REGISTERED or READY).
PATCH /system/compute_hosts/configuration	Set administrative state for new compute members (REGISTERED or READY).
GET /system/external_connectors/{connector_id}	Get an external connector configuration and state.
DELETE /system/external_connectors/{connector_id}	Remove the external connector configuration from DB (not the system).
PATCH /system/external_connectors/{connector_id}	Update and apply external connector configuration.
GET /system/maintenance_mode	Get current status of maintenance mode.
PATCH /system/maintenance_mode	Set the state of maintenance mode.
GET /system/notices	Get a list of all notices.
POST /system/notices	Add a system notice for all or specific groups of users.
GET /system/notices/{notice_id}	Get the details for the specified notice.
DELETE /system/notices/{notice_id}	Delete specified notice.
PATCH /system/notices/{notice_id}	Update attributes or acknowledgements of the specified notice.
PUT /node_definitions/{def_id}/read_only	Set specified node definition's read-only value.
PUT /image_definitions/{def_id}/read_only	Set specified image definition's read-only value.
GET /labs/{lab_id}/connector_mappings	Get list of external connector mappings for the specified lab.
PATCH /labs/{lab_id}/connector_mappings	Set partial list of external connector mappings for the specified lab.
PUT /system/external_connectors	Get a list of external connectors.

APIs Changed in CML 2.6

This table summarizes the APIs that have been changed in CML 2.6.

API Endpoint	Applies to request/response	Summary of Change
POST /authenticate POST /auth_extended POST /users PATCH /users/{user_id} GET /users/{username}/id POST /system/auth/test GET /users/{username}/id	request request request, response request, response request request response	The maxLength of username set to real limit (32).
POST /authenticate POST /auth_extended POST /users PATCH /users/{user_id} GET /users/{username}/id POST /system/auth/test	request request request, response request, response request request	Removed maxLength for password.
GET /labs/{lab_id}/annotations POST /labs/{lab_id}/annotations GET /labs/{lab_id}/annotations/{annotation_id} PATCH /labs/{lab_id}/annotations/{annotation_id} GET /labs/{lab_id}/topology POST /import	response request, response response request, response response request	Set explicit minLength for color, border_color, text_content and text_font. Set an enum for border_style property.
PATCH /labs/{lab_id}/annotations/{annotation_id}	request	Type property can't be updated.
GET /users POST /users PATCH /users/{user_id} GET /users/{user_id}	response response response response	Updated response schema by adding labs and directory_dn properties.
GET /users POST /users GET /users/{user_id} PATCH /users/{user_id}	response request, response response request, response	Added property tour_version.
PATCH /users/{user_id}	request	Property old_password is mandatory but ignored when admin is changing another user's password.
GET /groups/{group_id}/labs	response	Finalized response schema for items returned.
GET /licensing/certificate POST /licensing/certificate GET /system/auth/config PUT /system/auth/config POST /system/auth/test	response request response request request	Schema format and maxLength has been changed for licensing certificate.
GET /system/external_connectors	response	Added finalized response schema.
POST /labs GET /labs/{lab_id} PATCH /labs/{lab_id}	response response response	Added properties owner_fullname and owner_username to the response.
GET /labs/{lab_id}/topology POST /import	response request	Added/updated schema with link conditioning properties. Added new property enabled.
GET /populate_labs GET /populate_lab/{lab_id}	response response	Added topology property to the response.
GET /resource_pool_usage	response	Added local to the pattern for valid external_connectors names.
PATCH /labs/{lab_id}/interfaces/{interface_id} PUT /labs/{lab_id}/links/{link_id}	request request	Marked as Not Implemented Yet.
GET /labs/{lab_id}/links/{link_id}/condition PATCH /labs/{lab_id}/links/{link_id}/condition	response request, response	Added new query parameter operational.
GET /node_definitions POST /node_definitions PUT /node_definitions GET /node_definitions/{def_id} GET /node_definition_schema GET /simplified_node_definitions	response request, response request, response response response response	Changed enum value cat9k to cat9000v. Removed lxc as possible libvirt_domain_driver enum value for sim property. Updated enum list of possible nic_driver values.
PUT /node_definitions POST /node_definitions	request, response request, response	Removed read_only property.
GET /node_definitions/{def_id}	request	Set minLength, maxLength and pattern for valid def_id parameter.

Other Changes