CML 2.8 Release Notes
Cisco Modeling Labs (CML) is a network simulation platform. CML 2.8 is the latest feature release of CML. This release introduces a free-tier version of the product allowing you to start up to 5 nodes without a license. Starting with this release, CML includes access to the latest FMCv and FTDv images. Other new features include the Smart Annotations, the ability to see nodes' disk usage, the ability to use LDAP groups or the ability to configure custom MAC addresses.
New and Changed Information
This table shows any published changes to this CML 2.8 release notes document.
| Date | Changes |
|---|---|
| November 21, 2024 | Initial version for CML 2.8.0 FCS release. |
Installing or Migrating to CML 2.8
Upgrading to CML 2.8
If you are still running CML 2.7.1 or older, you cannot upgrade it directly to CML 2.8.0. Your CML instance must be running CML 2.7.2 before you can upgrade it to CML 2.8.0. If you have not upgraded to CML 2.7.2 yet, see CML 2.7 Release Notes for more details about the process to upgrade to CML 2.7.2.
See the In-Place Upgrade page for detailed upgrade instructions.
- We recommend reviewing the Known Issues and Caveats 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.
- Do not forget to disable maintenance mode once the upgrade is complete.
In-place upgrades from CML version 2.2.3 or earlier are not supported. In that case, a migration is required. The migration process from CML 2.2.3 is detailed in the CML 2.6 Release Notes.
Upgrading a CML Cluster to CML 2.8
If you have deployed a CML Cluster, you may upgrade it to CML 2.8.0 provided that your CML cluster is already running CML 2.7.2.
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 host.
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 hosts.
Installing CML 2.8
The CML Installation Guide provides detailed steps for installing your new CML 2.8 instance.
- In CML 2.8, all the reference platform virtual machine (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.
- 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.
Smart Annotations
You have been able to add annotations, such as rectangles and text, to your CML labs since CML 2.5.0. If you make heavy use of annotations, you may find that it's difficult to maintain the annotations as you modify the lab. CML 2.8.0 introduces an alternate approach, called Smart Annotations.
With this feature, you do not add ellipse or rectangle annotations to group nodes manually. Instead, you add tags to your nodes. The smart annotations feature will then show visual groupings around nodes that share the same tag. That way, as you update your lab or move nodes on the canvas, CML smart annotations will automatically adjust the smart annotations to maintain the correct nodes groupings.
For more details on how to use this feature and how to customize the smart annotations, see Smart Annotations Overview.
UI Changes
Other than UI changes to support Smart Annotations and the new features mentioned below, there are some other small UI changes and bug fixes in CML 2.8.
Rotation Support for Rectangle and Ellipse Annotation Types
All annotation types other than line annotations can now be rotated. In previous releases, CML only supported rotation for the text annotation type.
Ability to paste text into VNC sessions
CML exposes a VNC connection for nodes that have a graphical console. When using this VNC connection to a node in the Panes in the Workbench for your running lab, you may now paste text into the VNC session. CML will simulate keyboard input to send text to the session.
Note: this feature only works reliably for US-ASCII characters / text. It will cause issues with other international character sets!
Node Disk Usage
We have introduced a new feature that allows you to monitor disk usage for each node's VM. The disk size for a node is also shown in the Sidebar pane when the node is selected in the Workbench. You can see the disk usage for all nodes in your lab in the Nodes pane.
CML Administrators can also monitor the disk usage for all nodes on the Node Administration tab in the System Administration page. This feature will help you identify the nodes that are consuming the most disk space when you need to free up space. If you run a CML cluster, you can use this feature to troubleshoot problems and, along with Manual Compute Assignment, optimize resource distribution across your cluster and ensure that CML is able to fully utilize your cluster's capabilities.
Ubuntu 24.04
Your CML instance is a Linux server or virtual machine (VM) that runs the CML application and services. The CML 2.7 release is based on Ubuntu Linux 20.04, which will reach its end of standard support in April 2025. CML 2.8.0 is the first release that is built on Ubuntu Linux 24.04. To continue receiving security updates for your CML server, you should plan to upgrade to CML 2.8.0 or higher before April 2025.
LDAP Group Support
This feature only applies to CML instances that are configured to use LDAP for user authentication. Since the 2.3 release, CML has supported the ability to integrate with your LDAP servers for user authentication in all non-personal offerings, such as CML-Enterprise. CML 2.8.0 expands on that feature so that you can configure CML to assign the user to CML resource groups based on their membership in specific groups in LDAP.
For information on configuring group mapping from LDAP, see the documentation for Configuring LDAP Authentication.
Note that this feature is optional: you may continue to use LDAP for user authentication without using the LDAP group support in CML.
Custom MAC Address
CML 2.8.0 permits you to configure MAC addresses for a node on a per-interface basis. The administrator of the CML server can also change the upper three bytes (the OUI) that CML uses when assigning all MAC addresses. You can use this feature to guarantee more predictable labs and functionality, which may be needed in some specialized situations:
- Consistent MAC addresses even after you wipe a lab so that you can pre-generate or reuse a license that's tied to MAC addresses on one of your nodes
- Pre-determined MAC values for sharable labs
- Known MAC addresses when teaching protocol behavior or working with features, like spanning tree, that use MAC addresses for protocol negotiation.
You can also use this feature to avoid MAC address clashes when you connect the interface via a bridged external-connector node in your lab to an L2 network outside of CML. While CML ensures that MAC addresses are unique within your lab, CML cannot avoid MAC address clashes between your running nodes' VMs and the VMs or devices that are running outside of CML.
FMCv and FTDv Support and Images
With the release of CML 2.8.0, CML provides Cisco Firepower Management Center Virtual Appliance (FMCv) and Cisco Firepower Threat Defense Virtual (FTDv) images to our users on the updated ISO file of supplemental VM images. While previous versions of CML could run the FMCv and FTDv images, a CML license did not provide access to those VM images. Therefore, only users who had access to the FMCv and FTDv images via some other entitlement could download them and add them to CML.
Note that if you were using the contributed FMCv and FTDv node definitions from the cml-community repository, the node definitions have been updated along with this new release. The CML 2.8 upgrade will not migrate labs that use the old FMCv and FTDv node definition to the new node definitions. If you want to use the new FMCv and FTDv node definitions and images, you will need to migrate your labs manually.
Free Tier
More information about CML Free Tier coming soon!
API Changes
CML 2.8 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.8
This table summarizes the API endpoints that have been removed in CML 2.8.
| API Endpoint | Alternative API Endpoint |
|---|---|
GET /mac_address_block |
None |
PATCH /mac_address_block/{block} |
None |
APIs Deprecated in CML 2.8
This table summarizes the API endpoints that have been deprecated in CML 2.8.
| API Endpoint | Alternative API Endpoint |
|---|---|
GET /licensing/features |
GET /licensing |
GET /build_configurations |
PUT /labs/{lab_id}/bootstrap |
PUT /system/auth/config |
PATCH /system/auth/config |
New APIs in CML 2.8
This table summarizes the API endpoints that are new in CML 2.8.
| API Endpoint | Description |
|---|---|
GET /labs/{lab_id}/smart_annotations |
Get a list of all smart annotations for the specified lab. |
GET /labs/{lab_id}/smart_annotations/{smart_annotation_id} |
Get the details for the specified smart annotation. |
PATCH /labs/{lab_id}/smart_annotations/{smart_annotation_id} |
Update details for the specified smart annotation. |
PUT /labs/{lab_id}/bootstrap |
Generate configurations for the nodes in the topology. |
PATCH /system/auth/config |
Set the system authentication configuration. |
GET /system/auth/groups |
Get all groups available on an LDAP server that matches the specified filter. |
PUT /system/auth/refresh |
Refreshes the membership from an LDAP server for existing users and groups in CML. Useful only when changes have been done on the LDAP server. |
APIs Changed in CML 2.8
This table summarizes the APIs that have been changed in CML 2.8.
| API Endpoint | Summary of Change |
|---|---|
POST /labs/{lab_id}/annotationsGET /labs/{lab_id}/annotationsPATCH /labs/{lab_id}/annotations/{annotation_id}GET /labs/{lab_id}/annotations/{annotation_id} |
Added new required property rotation to rectangle and ellipse annotations. |
GET /groupsPOST /groupsGET /groups/{group_id}PATCH /groups/{group_id} |
Added new optional properties directory_dn and directory_exists. |
GET /licensingGET /licensing/tech_support |
Added nested properties min, max, minEndDate and maxEndDate to features property. |
GET /system_information |
Added new property oui. |
GET /system/auth/configPOST /system/auth/test |
Removed manager_password property. Added new optional property group_display_attribute. |
POST /system/auth/test |
Added new property group-data, mutually exclusive with existing auth-data. (at least one is required, at most one is expected). |
POST /node_definitionsGET /node_definitionsGET /node_definitions/{def_id}GET /simplified_node_definitionsGET /node_definitions_schema GET /diagnostics/computes |
Added new optional properties sim.linux_native.enable_rng and sim.usage_estimations. Added new configuration.generator.driver enum values: fmcv, ftdv. |
POST /labs/{lab_id}/interfacesPATCH /labs/{lab_id}/interfaces/{interface_id} |
Added new optional property mac_address. |
GET /labs/{lab_id}/topologyPOST /import |
Added new optional property nodes.{node_id}.interfaces.{interface_id}.mac_address. Added new optional property smart_annotations. |
Other Changes
| Summary | Release Notes |
|---|---|
| Updated cat9kv node definitions | Both Catalyst 9000v UADP and Q200 now support up to 24 data interfaces. Catalyst 9000v Q200's memory requirement has been decreased to 12 GB DRAM. |
| Added network-config for ubuntu | Added a new editable network-config configuration file to Ubuntu node definition to provide an easy way for users to configure networking. |
| Added support for config drive customizer | Added an option to pre-process day-0 configuration when deploying a node for the first time. If a "cml-customizer.sh" file exists among Added an option for vfat configuration drives not to create partition tables in the configuration disk; use volume name "noparts" to achieve this. |
| Improved cockpit cluster behavior when sysadmin passwords differ | Fixed issues in cluster deployments with differing sysadmin passwords on compute hosts where some cockpit functionality was failing. |
| Added a few resource usage columns | Added new CPU/RAM/Disk usage columns to the Node Administration table (by default they are hidden). |
| Added a "help" link to the Tools menu | New links have been added to the Tools menu for the CML community forum and to open a ticket (for an administrator with an enterprise license only). |
| Added system status footer for all UI pages | Displaying the system status footer on all pages except the login page (previously it was only displayed on the workbench and dashboard pages). |
| Fixed critical a11y issues | Implemented minor UI accessibility improvements. |
| Replaced resolve.sh with native name resolution | In a cluster setup, IPv6 mDNS resolution of compute-hostname.local domains is now available to most software without special workarounds. |
| Disabled /system_admin/users/add when LDAP is enabled | Disabled and added redirect from Add User page in System Administration when LDAP is enabled. |
| Improvements for the copy refplat ISO process | Changed the process to copy reference platform images from ISO images to fix the process ignoring hard-links and copying hard-linked images multiple times. And to fix the issue where reference platform images were not cleaned from a temporary location after the copy process is complete resulting In addition, performance improvements should be observed when copying reference platform images from ISO images mounted in CD-ROM, but especially when copying from ISO images present on the disk. |
| Improved exception handling for PCL requests | Client Library: Replaced HTTPStatusError raised by calls to the API with an APIError that inherits from VirlException, and also shortened the traceback created by these errors. |
Bug Fixes
| Bug Description | Resolution |
|---|---|
| Unable to import CML 2.7.2 OVA into VMware Workstation Player 17 | Fixed an issue that prevented OVA imports in obsolete and unsupported VMWare Workstation Player. |
| Unable to delete an image definition when multiple image definitions are using the same image | Fixed a bug that prevented users from deleting an image definition if the source image of the image definition was already present in the dropfolder. Now the source image is removed, instead. |
| Unable to upload the same image twice | Corrected the message of an error raised when uploading the same file twice (still do not replace the existing file and require users to delete such file manually first). |
| Excluded columns are still considered in search result in UI | Fixed a bug in UI tables that included excluded columns in search results. |
| LVM maximize script fails when there's no disk to resize | Modified LVM Maximize feature to not report failures when there's no disk to be expanded. |
| Multi-select on annotations still shows handles | Fixed a few small rather cosmetic bugs of annotation handles. |
| LICENSE_INFO event sometimes does not report product_configuration | Fixed a bug that loaded product version late in the process. Now, it's loaded immediately on CML controller initialization. |
| Breakout Utility config file saves domain password in clear text | Fixed a bug that caused the breakout tool to require a password to be present on initialization. The password is still required and should be set via an environment variable, but if not set, the breakout tool will show a proper warning. |
| The algorithm to compute free space is not correct | Fix a bug in the algorithm that calculates used disk space. The reserved root space (5%) was not included by the algorithm leading into invalid amount of used or free space being displayed to users. |
| Accessing computes through controller cockpit dashboard is blocked when different passwords are used during installation | Fixed a bug that prevented a system administrator from orchestrating cluster members via controller's cockpit dashboard. |
| 'Non-existent' text gets appended every time a user hits Enter key for ext-conn node. | Fixed 'Non-existent' text gets appended every time user hits Enter key for ext-conn node. |
| Diagnostics -> Cluster status resolution is improper | Fixed partially hidden tables on diagnostics page for screens with a smaller resolution. |
| Bulk addition of nodes does not avoid node name conflicts | Fixed a bug in the bulk node addition feature. The feature incorrectly tried to add existing nodes and failed. Now, it correctly skips existing nodes. |
| The option to select a number of packets to display does not show an option to select all packets | Fixed displaying '-1' instead of 'All' in pagination options for packet capture table. |
| VNC sessions are not rendered after reopening PANES | Fixed missing VNC sessions after closing and reopening PANES with active VNC tabs. |
| Server returns unfriendly errors when the disk is full and starting IOL nodes | Added a wrapper around execution of system commands on computes to prevent raising of unhandled exceptions. Users should no longer get lengthy error messages. |
| Workbench does not handle deleted lab events | Fixed the missing "Lab not found" dialog if the opened topology was deleted by someone else. |
| Annotation changes are not available in preview when using CML logo for navigation | Fixed the preview in Dashboard to show recent annotation changes after using CML logo for navigation to Dashboard. |
| Topology preview in list mode is not displayed correctly | Fixed an invalid resolution of the preview in the list mode. |
| Inline edit of resource pool properties is broken | Fixed a broken inline edit for resource pool name and description. |
| The new copy-refplat script does not work with older refplats | Fixed an issue where Cockpit copy refplat ISO command failed to open the ISO device in exclusive mode in case it was mounted somewhere already |
| Bridge0 gets an unexpected IP from virbr0's subnet | Fixed a bug in Ubuntu where server interfaces including bridge0 may get IP addresses assigned from libvirt DHCP networks; such DHCP servers are now explicitly configured to ignore their host's requests. |
| NXOS9kv cannot be started in Ubuntu 24.04 | The way Nexus9000v UEFI boot is configured changed to a 'stateless' mode to work around a bug in libvirt on Ubuntu. The change to existing lab nodes is made automatically on upgrade. |
| PCAP sessions in Workbench UI do not display previously captured frames when switching pages | Fixed an issue in UI that hid already displayed packets when changing between sessions. Now, when a PCAP session is accessed all packets are always reloaded. |
Known Issues and Caveats for CML 2.8
| Bug Description | Notes |
|---|---|
| CML 2.8.0 cannot be deployed in AWS or Azure. | The scripts in cloud-cml repository do not support CML 2.8.0 yet. |
| The migration script does not work with CML 2.8.0. | The migration script to copy a CML 2.8.0 instance to another CML 2.8.0 instance does not work yet. The migration from CML 2.2.3 to CML 2.8.0 is not and will not be supported as out of scope. |
| The default CML page in Cockpit on the CML controller shows limited set of options. | There's a chance that a CML installation ends with invalid values configured in the CML configuration file (/etc/default/virl2). If RUN_CONTROLLER setting is misconfigured, the default CML page in Cockpit on the CML controller shows the limited set of options for compute instead of controller.Workaround: Navigate to the Cockpit terminal. As root, edit /etc/default/virl2, find a line starting with RUN_CONTROLLER and change it to RUN_CONTROLLER="1" and save changes. Refresh the page to apply the change. |
| The Workbench UI is locked after adding tags to multiple nodes in CML 2.8.0. | It is advised not to update tags on multiple nodes at once because it could cause the Workbench UI to break down. |
| An error is displayed on the CML login page in CML 2.8.0. | The error is annoying, but harmless and can be ignored. |
| Annotations cannot be cloned in CML 2.8.0. | Users cannot clone regular annotations in the Workbench. |
| Streams cannot be created in Alpine Trex 3.19.1 and 3.20.3 images. | A new stream cannot be created in the Trex GUI client using one of the affected images. It is recommended to use Alpine Trex 3.16.2 image in refplat-20230117-fcs.iso. |
| External connectivity does not work in CML bare metal installations. | This bug impacts CML bare metal deployments regardless of release. In some deployments, most notably on UCS bare metal servers in which the vNIC's VLAN is set to access mode, the ingress traffic is tagged with vlan 0. This VLAN is meant to carry priority information as per the 802.1p standard. Network services can normally ignore this tag and handle vlan 0 packets transparently as untagged (no VLAN), but some node types in CML do not handle it gracefully, ignoring the incoming packets. As a result, the virtual nodes connected to an external connector node may not acquire an IP address from an external DHCP server or may not be able to communicate with external devices. Workaround: Follow the instructions from the Handling 802.1p Frames in UCS section of the Cisco Modeling Labs Administrator's Guide. |
| After a restart, you cannot reach the CML UI. The console of the CML instance shows a login prompt, but it also indicates that CML does not have an IP address. | After you shut down and restart a CML instance, it sometimes loses its IP address. When that happens, you will no longer be able to reach the CML UI even though the CML services are running. Workaround: When you encounter this problem, open the CML console (e.g., the CML VM's console in VMware or the CML server's remote management console). Log in as the sysadmin user and run this command: sudo netplan apply You can verify the current/new IP address of the CML instance using this command: ip addr show bridge0 If the issue persists, follow the instructions from the Editing the Management IP address via the Console section of the Cisco Modeling Labs Administrator's Guide. |
| Cannot run simulations on a macOS system that uses Apple silicon (e.g., the Apple M1 chip). | CML and the VM Images for CML Labs are built to run on x86_64 processors. In particular, CML is not compatible with Apple silicon (e.g., the Apple M1 chip). Workaround: There are no plans to support ARM64 processors at this time. Deploy CML to a different system that meets the system requirements for running CML. |
| Even if you were able to run network simulations with CML 2.2.x on VMWare Fusion and macOS Big Sur or above, the same labs no longer start after migrating to CML 2.3.0+. | A default setting in the CML VM changed between CML 2.2.3 and CML 2.3.0. Because of the new virtualization layer in macOS 11+, this setting causes errors when running the CML VM on VMware Fusion. Workaround: follow the instructions to disable nested virtualization in the CML VM. |
| Bug in macOS Big Sur. After upgrading to Big Sur and VMware Fusion 12.x, simulations no longer start. | MacOS Big Sur introduced changes to the way macOS handles virtualization, but the problems were resolved in later versions of macOS Big Sur and VMware Fusion. Workaround 1: If you are still experiencing problems, be sure to upgrade to the latest version of VMware Fusion 12.x and the latest bug fix release of your current macOS version. Workaround 2: If you are using CML 2.3+, then follow the instructions to disable nested virtualization in the CML VM. |
| Deleting or reinstalling a CML instance without first deregistering leaves the license marked as in use. Your new CML instance indicates that the license authorization status is out of compliance. | If you have deleted or otherwise destroyed a CML instance without deregistering it, then the Cisco Smart Licensing servers will still report that instance’s licenses are in use. Workaround 1: Before you destroy a CML instance, follow the Licensing - Deregistration instructions to deregister the instance. Properly deregistering an instance before destroying it will completely avoid this problem. Workaround 2: If you have already destroyed the CML instance, see the instructions for freeing the license in the CML FAQ. |
| When the incorrect product license is selected, the SLR (Specific Licensing Reservation) can still be completed. It eventually raises an error, but the SLR reservation will be complete with no entitlements. | Workaround: If you accidentally select the wrong product license, then you will need to release the SLR reservation and then correct the product license before trying to complete the SLR licensing again. |
| If you have read-only access to a shared lab, some read/write actions are still shown in the UI. Attempting to change any properties or to invoke these actions raises error notifications in the UI. | Workaround 1: Do not attempt to invoke the read/write actions when working with a lab for which you only have read-only permissions. Workaround 2: Ask the lab owner to share the lab with read/write permissions so that you can make changes to the lab. |
| If you have read-only access to a shared lab, you will still not be able to see the current link conditioning properties in the link's Simulate pane. | Workaround: ask the lab owner to share the lab with read/write permissions if you need to access the link conditioning properties. |
| The algorithm for computing the available memory does not take into account maximal possible memory needed by all running nodes. It only checks the currently allocated memory. CML will permit you to start nodes that fit within the current available memory of the CML server. Later, if the memory footprint of the already-running nodes grows and exceeds the available memory on the CML server, those nodes will crash. | Workaround 1: Launch fewer nodes to stay within your CML server's resources. Workaround 2: Add additional memory to the CML server to permit launching additional nodes. Of course, this workaround just moves the point where the CML server will eventually hit its limit, so you must remain aware of your CML server's resource limits or ensure that the CML server has sufficient memory to accommodate all labs that will be running on your CML server simultaneously. |
When starting a CSR 1000v node for the first time or after a Wipe operation, the interfaces are all in shutdown state. |
Workaround 1: Add no shut to each interface configuration in each CSR1000v node's Edit Config field in the UI. Workaround 2: Use the EEM applet on the CSR 1000v page. |
| New nodes cannot be started when CPU usage is over 95%, when RAM is over 80%, or when disk usage is over 95%. | Workaround: Allocate additional resources to the CML server. Workaround 2: If you are hitting the disk usage limit, check the Remove Orphaned VMs function in Cockpit. Orphaned VMs can consume a significant amount of disk space even though CML is no longer using or managing those VMs. |
The journalctl output shows errors like this: cockpit-tls gnutls_handshake failed: A TLS fatal alert has been received |
This log message only occurs with Chrome browsers and has no functional impact on the use of Cockpit. No workaround needed. |
| In CML Cluster, the Cockpit Storage table for NFS mounts looks broken. | This is a display bug of the Cockpit UI when it encounters an NFS share using an IPv6 address. The single mount is split into two rows, only the first of which is indicated as mounted. Your NFS setup is probably fine, as long as the CML UI shows in its Cluster Status view that each compute host's Images indicator is green. Trying to edit or repair the NFS mount in any way in Cockpit is more likely to break the configuration. Please contact TAC if you experience networking issues with clusters which cannot be resolved by verifying basic connectivity on the cluster network or by restarting CML services. |