CML 2.3 Release Notes

Cisco Modeling Labs (CML) is a network simulation platform. CML 2.3.1 is the latest release of CML, and these release notes include information for all CML 2.3.x maintenance releases.

New and Changed Information

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

Installing or Migrating to CML 2.3

Upgrading to CML 2.3.1

If you already have a CML 2.3.0 installation, you can upgrade it to CML 2.3.1. See the In-Place Upgrade page for upgrade instructions. In-place upgrades from CML version 2.2.3 or earlier are not supported.

Migrating from an Existing CML 2.2 Installation

It is not possible to upgrade a CML 2.2.x installation to CML 2.3. You must migrate to a new CML 2.3 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.3 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.3 installation.

Note: If you choose to migrate an existing, licensed CML 2.2.x installation to a new installation of CML 2.3, 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.3 (see below).
   • Since you are migrating from an existing CML 2.2.x installation, mounting the refplat ISO before running the CML 2.3 installation is optional.
   • If the reference platform ISO is mounted before starting the CML 2.3 installation, the set-up script will copy reference platform images from a mounted refplat ISO to the local disk.
   • You can skip the copying of reference platform images during installation because the migration tool will copy all of the reference platform images from your CML 2.2.x installation to the new CML 2.3 installation.
   • Only mount the new refplat 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.3 installation.
4. License your new CML 2.3 installation.

The migration tool can be found on your CML 2.3 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.3 on the same server that's 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.3. As always, make sure that you deregister your old CML 2.2.x instance before decommissioning it and starting the CML 2.3 installation.

Installing CML 2.3

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

• In CML 2.3.x, all of 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.)

Summary of Changes

This section details new and changed features in the new release. Bug fixes are listed in the subsequent section. You can see a brief demo of some of the new features in the CML 2.3 Feature Walkthrough video:

UI Changes

The CML 2.3 UI introduces new features for the lab Workbench.

The behavior of some Workbench actions have changed compared to the CML 2.2 UI. The styling of some elements has also been updated:

• Add a link is now a single click on the link button in the node action ring vs a click-and-drag in all previous versions.
• Link label styles have changed
• Badge styles have been changed
• Node positions are no longer snapped to a grid.

Canvas Actions in CML 2.3

CML 2.3 introduces new canvas actions and changes the behavior of some of the existing canvas actions in the Workbench. This table summarizes the CML 2.3 changes compared to previous versions of CML.

Toolbar Changes

This table summarizes changes to the Workbench toolbar in CML 2.3. In addition to the toolbar button changes, the toolbar is now accessible via screen readers.

LDAP Authentication

With version 2.3, a new user authentication method has been added: LDAP. Prior to version 2.3, all authentication and authorization requests to CML were checked against the local user database.

A CML admin user is created during installation. For the personal edition of the product, this is typically the one and only user account needed.

For multi-user CML-Enterprise or CML-Education instances, a CML administrator can change CML's authentication method to LDAP. You can integrate CML with your existing directory services, such as Microsoft Active Directory, as long as it provides LDAP access. With the LDAP authentication method, CML authenticates logins and authorizes users via the configured LDAP server, and the CML administrator does not create local accounts on the CML instance.

See Configuring LDAP Authentication for instructions on configuring CML to use LDAP for authentication.

API Changes

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

APIs Modified in CML 2.3

In previous versions of CML, the JSON format for many of the request bodies or responses had no defined format. In CML 2.3, the API specification now provides a JSON schema for the request and response bodies, if any. The API specification also specifies any constraints on the path parameters for the API endpoints. While defining these schemas, we normalized the object structures and made the ID handling more consistent. Therefore, the behavior of some of the existing APIs will be a little different in CML 2.3.

Lab IDs in CML 2.3 have been converted from short, unique identifiers to full, 128-bit UUIDs. The UUIDs are represented in the APIs by 36-characters strings in five hyphen-separated groups of hexadecimal digits. Note that this means that the IDs of any existing labs will be different after migration to CML 2.3.

There are some important changes in the behavior of the APIs related to users and groups. We updated these APIs as part of the changes for LDAP support, adding properties and making them more consistent. In addition to the user and group API endpoints that were added or removed in CML 2.3 (see below), the user_id parameter in the user and group APIs is now the user's UUID, not the username. The group_id in these APIs is now the group's UUID and not the group's name. This change affects both the path parameter in the API endpoints and references to users and groups in the objects returned by the APIs.

The members property of a group now lists the UUIDs of the users in the group, not their usernames. Similarly, the groups property on user objects is a list of group UUIDs to which the user belongs, not a list of group names. There is a new labs property in the user objects returned by the APIs. The labs property list the IDs of the labs owned (created) by the user. There is also a new groups property on the lab objects returned by the GET /labs/{lab_id} API. Similar to the groups property in the user object, this property is a list of the UUIDs of the groups to which the lab belongs.

The DELETE /groups/{group_id} and DELETE /users/{user_id} endpoints return an HTTP/204 (No Content) on success instead of an HTTP/200. In general, when a CML API endpoint completes successfully but returns no response object, it uses the return code HTTP/204 instead of HTTP/200 to indicate success.

The POST and PATCH API endpoints for /groups/{group_id} and /users/{user_id} return the group or user object that was created or updated. In CML 2.2, these API endpoints returned the object's ID or just the string "OK" on success.

Another significant change in the CML 2.3 APIs involves the structure of the node definition object. The JSON object returned by the GET /node_definitions and GET /node_definitions/{def_id} is different in CML 2.3 compared to previous releases. The JSON object for a node definition used to nest most of the details under the data property, but the extra layer of nesting was inconsistent with the YAML version of the node definition. The JSON object for a node definition in CML 2.3 no longer has the top-level data property, and the properties that it used to contain are now at the top-level of the node definition. This change makes the JSON representation of a node definition in CML 2.3 equivalent to the YAML representation. If you use the JSON response from GET /node_definitions or GET /node_definitions/{def_id} APIs, you will need to adjust your code to handle the flattened data structure.

New APIs in CML 2.3

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

APIs Removed in CML 2.3

This table summarizes the API endpoints that have been removed and are no longer available in CML 2.3.

APIs Deprecated in CML 2.3

The following APIs are now deprecated and will be removed in a future release:

Reference Platforms

The new refplat ISO file available with the CML 2.3 release includes a CAT 8000V image. To reduce the size of the refplat ISO file, only a single NX-OS 9000 VM image is included. The refplat ISO file also no longer includes the node definitions or VM images for NX-OS or IOS XRv. Both of those reference platforms are EOL and are no longer being updated. If you would like to continue using these images, the NX-OS and IOS XRv node and image definitions from CML 2.2.x still work in CML 2.3.x. If you used the migration tool to migrate your data from CML 2.2.x, then you will still have these images for use in your new CML instance. If you did not migrate data from an earlier CML release and do not have these VM images, you can get them from the CML 2.2.x refplat ISO file and add them to your new CML instance.

CML 2.3 includes the vmxnet3 NIC driver. With this driver, CML now supports subinterfaces on CSR 1000v nodes. If you migrated your data from CML 2.2.x, where CSR 1000v used the VirtIO NIC driver, CML 2.3 will automatically update the node definition to the vmxnet3 driver. Subinterfaces are also supported by the new CAT 8000V image.

The documentation on VM Images for CML Labs has been expanded to include additional information about each of the VM images on the refplat ISO file. We have also added sample labs with working configurations for each of the bundled Cisco reference platforms. Look for the sample labs with Feature Tests in the lab name in the Tools > Sample Labs page in the CML UI. These are the same labs that Cisco uses when testing the bundled Cisco reference platforms with a new CML release.

Other Changes

CML 2.3 is based on Ubuntu Linux 20.04LTS. From CML 2.0.0 to CML 2.2.3, the CML release was based on CentOS 8.x. CentOS 8 is now EOL and no longer releases security fixes. Moving CML to Ubuntu provides a stable and secure platform for the current and future CML releases.

In CML 2.3, the CML services can load the state of running VMs when the services start. Therefore, CML no longer stops any nodes or labs when you restart the CML services (without rebooting the CML server). When the CML services restart, they will scan the system to determine the state of all nodes and labs.

This table provides some details on other individual changes in CML 2.3.

Bug Fixes

Known Issues and Caveats for CML 2.3

nmcli con

check con del bridge0-p1 
nmcli con add type bridge-slave \
    con-name bridge0-p1 \
    ifname enp9s0 master bridge0 
nmcli con down enp10s0 
# verify that the set up is now correct 
nmcli con