FAQ - Cisco Modeling Labs v2.x

Reference Platform and Images Questions

1. What are reference platforms?

Reference platforms are virtual instances of Cisco's operating systems. Some of these correspond to virtual products that are available on Cisco.com (e.g., CSR1000v, ASAv, and IOS-XR 9000v), while others are available only within Cisco Modeling Labs (e.g., IOSv and IOSv-L2). These virtual platforms offer software-level feature parity to physical devices that run the same operating system, with some exceptions. That is, any feature that can be done in software without underlying hardware for a given OS is generally supported in the reference platforms.

In addition to the Cisco reference platforms, Cisco Modeling Labs provides other supporting images such as Linux server VMs, desktop VMs, a traffic generator, and a "bump-on-the-wire" WAN emulator.

The Cisco Modeling Labs distribution includes an ISO image file that contains a set of default reference platforms and supporting images for use in your labs. For more details about each of the reference platforms and other VM images provided on the refplat ISO file, see VM Images for CML Labs.

2. Which reference platforms are provided by default?

3. Which third-party images are included by default?

Note: The VMs for these third-party node types do not count toward the total licensed node limit.

4. How can I add additional images to Cisco Modeling Labs?

To add images (Cisco or third-party) for existing node types, upload a VM image formatted as a .qcow2 file to your CML server. You can either upload the .qcow2 file via the CML UI or by using Secure Copy (scp). In addition to the image files themselves, you will also need to add a definition for the image that will inform libvirt and the Cisco Modeling Labs engine how to boot up the node.

Complete instructions on adding a VM image to CML can be found in the CML User Guide.

If you would like to add an image for a completely different type of node, you must first add or import a node definition.

5. I don't see a node type that was available in earlier versions of the software.  Where did it go?

Not all of the node types that were present in Cisco Modeling Labs or Virtual Internet Routing Labs v1.x are present in Cisco Modeling Labs v2.x.  For example, Ostinato and the LXC containers are no longer available. Ostinato has been replaced by the Cisco TRex traffic generator, and Docker containers can be added to and run out of instances of the CoreOS node type. The Alpine node type includes the iperf3 and RouteM tools.

6. What is the default login for the nodes?

Each node type has its own default login. See the table below for the specific node values.

^* Note: if the Design > Build Initial Bootstrap Configurations is used, the default password will be cisco for enable on IOSv, IOSvL2, CSR1000v, XRv, and XRv9000. The NX-OS nodes will have an admin / admin account (as well as cisco / cisco), and the ASAv will have a cisco / cisco account.

^** Note 2: if the Design > Build Initial Bootstrap Configurations is used, the Ubuntu node will not have any default account. You will need to restore the base cloud-init config to be able to log into this node.

7. What resources are required by each node type?

The following table lists the nominal vCPU, memory, and disk size for each node type. The resource usage of a particular node in a lab simulation depends on the node type, selected VM image, and the associated configuration. Note that CML over-provisions your system's actual hardware for virtualization, and CML uses Linux kernel same page merging to reduce the memory required to run a lab, especially when the lab has multiple nodes of the same type. Therefore, the resources required to run a simulation will generally be less than the nominal resource requirements of all of its nodes.

8. Where can I find other reference platforms?

In addition to the reference platforms included on the "refplat" ISO, there is a GitHub repository at https://github.com/CiscoDevNet/cml-community that provides a way for Cisco and external users to contribute node definitions, images, and labs for general use. This repository currently contains a number of additional Cisco and third-party node definitions. Watch the repository or come back to check it periodically for new node definitions and other Cisco Modeling Labs extras.

Installation Questions

1. Can I install Cisco Modeling Labs on a bare-metal machine?

Starting in Cisco Modeling Labs v2.1, bare metal deployments are supported. See the system requirements page for more details.

2. Can I upgrade from Cisco Modeling Labs v1.x or Virtual Internet Routing Labs to Cisco Modeling Labs v2.x?

No. There is no direct upgrade from Cisco Modeling Labs v1.x or Virtual Internet Routing Labs to Cisco Modeling Labs v2.x.  However, you can do a fresh installation of v2.x and re-import your v1.x topology files.  While not all node types exist in v2.x, many of the same node types are present and much of the same functionality is available. Upgrading from one version of Cisco Modeling Labs v2.x to another 2.x version is generally possible. See the In-place Upgrade page for details.

3. How many virtual network interfaces does the v2.x VM require?

Cisco Modeling Labs v2.x only requires one total virtual interface for the VM. However, you can add other virtual NICs to it to allow for external connectivity to multiple networks. See the instructions on how to add multiple interfaces in the CML Admin Guide.

4. Do I need the REFPLAT ISO image in order to deploy Cisco Modeling Labs v2.x?

While the REFPLAT ISO is not required to deploy Cisco Modeling Labs v2.x and boot it up, you will not be able to add nodes to labs until you do. If you mount the REFPLAT ISO after booting up the CML server, you will need to restart the CML services before they will recognize that the ISO is present.

If you do not wish to leave the ISO mounted to the Cisco Modeling Labs server (for example, it could prevent migration of the CML VM from working), you can copy the contents of the REFPLAT ISO to the running Cisco Modeling Labs server. Note: if you deployed CML as a VM, you will need more allocated disk space than the default CML VM configuration. The current REFPLAT ISO contents consume more than 10 GB of disk space.

To copy the REFPLAT ISO to the Cisco Modeling Labs server, follow these steps:

• Make sure the REFPLAT ISO is mounted to the VM.
• Ensure that all users have stopped all of their running labs.
• Log into Cockpit as a sysadmin.
• On the CML2 page, expand the Copy Refplat ISO sub-section.
• Click the Copy Refplat ISO button.
• Wait for the Output area at the bottom of the page to indicate that the copy process is complete.
• After the Refplat ISO contents are copied to the CML server, the ISO will be unmounted and "ejected," and the CML services will be restarted. (No reboot of the CML server is required.)

Here are some tips in case the Copy Refplat ISO process did not succeed:

• The copy process will fail if there are node VMs running, if there is no REFPLAT ISO mounted, or if you have insufficient space on the CML server for the contents of the refplat ISO.
• If the copy failed or was was interrupted, the Copy Refplat ISO action can be resumed. Just re-run it as above.

5. Can I use Cisco Modeling Labs v1.x or Virtual Internet Routing Labs topology files with Cisco Modeling Labs v2.x?

While the format of the lab export files differs between v2.x and v1.x (YAML vs. XML), you can import Cisco Modeling Labs v1.x or Virtual Internet Routing Labs .virl files into Cisco Modeling Labs v2.x just as you can with the new v2.x .yaml files.  Be aware, however, that not all node types that were present in v1.x are present in v2.x.  For example, Ostinato and LXC nodes no longer exist in v2.x.  Such nodes will not show up in the lab once imported into v2.x.

6. What keyboard layout is used during installation?

Cisco Modeling Labs uses a US English keyboard layout when performing the installation. This means that if you are using another international keyboard layout, your complex password may not be what you expect (e.g., the @ and " may be swapped). To ensure the correct password, consider a simpler password for admin and sysadmin at installation time, and then change those immediately after the system is ready in the Tools > System Administration and Cockpit > Accounts respectively as these web interfaces will respect the current international keyboard layout.

7. I was using a previous REFPLAT ISO. Do I need to upgrade my REFPLAT ISO along with Cisco Modeling Labs?

Not necessarily. In fact, if you have labs that are still using the current REFPLAT ISO (i.e., nodes that are not wiped), then replacing the current REFPLAT ISO with a new one will break those labs. If you wish to get node and image definitions from the new REFPLAT ISO, you have two choices.

1. Refer to the question "Do I need the REFPLAT ISO image in order to deploy Cisco Modeling Labs v2.x" above. Copy both REFPLAT ISOs (the current and the new one) to the Cisco Modeling Labs VM. To do this, mount the current REFPLAT ISO, run the copy script, then mount the new REFPLAT ISO, and then re-run the copy script.
2. Continue to use the current REFPLAT ISO, and import node and image definitions from the new REFPLAT ISO into Cisco Modeling Labs using the Tools > Node and Image Definitions interface. Only these imported node and image definitions will be copied to the Cisco Modeling Labs VM.

8. Can I perform an in-place upgrade if I run a CML instance that's in an air-gapped or offline environment?

Yes, you can use the pkg.zip file to perform an In-Place Upgrade on a CML instance that's in an offline environment.

9. How do I know when there's a new CML release?

You can check the CML software download page for the latest available release.

If you want to receive an e-mail notification when a new version of CML is released, click the My Notifications link next to the bell icon on the software download page. On the Add Notification dialog, configure a notification for All Releases of Cisco Modeling Labs and click Save.

System Administration

1. How can I access the Cisco Modeling Labs v2.x system administration GUI?

System administration is performed via the Linux Cockpit tool. Cockpit is available on TCP port 9090 of the Cisco Modeling Labs controller VM. It is secured with HTTPS. For example, if your Cisco Modeling Labs controller VM IP address is 192.0.2.1, Cockpit can be accessed at https://192.0.2.1:9090 using your web browser. Use the sysadmin account that you created during Cisco Modeling Labs installation, and follow the instructions for logging into Cockpit.

2. How do I download the Cisco Modeling Labs logs?

If you are experiencing issues with Cisco Modeling Labs, and you require support, it's helpful to provide the log files. Logs can be downloaded from the Cockpit main page (the CML2 tab in the left-hand pane). Under the Maintenance section in the main, right-hand pane there is a button to download the Cisco Modeling Labs logs as a TAR, gzipped bundle.

3. How do I restart the Cisco Modeling Labs services?

From the CML2 tab in Cockpit, under the Maintenance section in the main, right-hand pane, expand the Restart Controller Services sub-section and click the Restart Services button. Note that this action stops all running labs and restarts all CML background processes on the controller VM, but it will not restart the CML server itself.

4. How do I clean up all labs and start fresh with Cisco Modeling Labs?

Cisco Modeling Labs offers the ability for an administrator to stop all running labs and remove all lab data across all users. This will essentially provide each user with a clean slate in their CML accounts. To perform a cleanup, log into Cockpit, go to the CML2 tab, and expand the Clean Up sub-section in the Maintenance section of the main, right-hand pane. Click the Clean Up button. The cleanup process will restart all Cisco Modeling Labs server processes which will logout all active users.

5. How do I reset my password?

An administrator can reset the password you use to access the Cisco Modeling Labs GUI, API, or console server. If you are the administrator, and you forget your login, you can login as "sysadmin" to Cockpit and perform a Factory Reset. Factory Reset is different from Clean Up in that all user accounts will be removed and a new cml2 user will be created with the password of cml2cml2. This user can then be used to recreate other accounts, including administrative accounts. The Factory Reset is performed from the CML2 tab of the Cockpit UI under the Maintenance section of the main, right-hand pane and the Factory Reset subsection.

6. Does Cisco Modeling Labs support integration with external user databases like LDAP or Active Directory?

Currently, all users must be defined locally within Cisco Modeling Labs. External directory integration is on the roadmap for a future v2.x release. That said, the ability to manage users is all controlled by the REST API. It is possible to create automations to insert users, change passwords, and delete users.

7. How do I reboot my Cisco Modeling Labs server or VM?

In the Cockpit interface, go to the Overview tab in the left-hand pane of the window. Click the Restart button in the top right-hand corner of the window. This will prompt you for a message (optional) as well as a delay to reboot.

8. How do I install my own Certificate Authority (CA) signed certificate for Cisco Modeling Labs?

Cisco Modeling Labs includes self-signed certificates for the main web interfaces as well as Cockpit. The TLS / SSL certificate enables CML to use HTTPS and encrypt all of the traffic between the CML server and the web browser, the Breakout Tool, and other API clients. If you wish to use a trusted CA-signed certificate instead, launch the Terminal through Cockpit, and then do the following.

• Run sudo -E -s to get a root shell (you will need to enter sysadmin's password)
• Change directory to /etc/nginx with the command cd /etc/nginx
• Run: cp -a fullchain.pem fullchain.pem.bak cp -a privkey.pem privkey.pem.bak
• Copy your certificate and the full validation chain up to the CA (all in PEM-encoded format) into fullchain.pem. Be sure to overwrite all of its current contents
• Copy your private key (in PEM format) into privkey.pem. Be sure to overwrite all of its current contents. The private key MUST NOT be encrypted (i.e., cannot have a passphrase on it).
• Next, change directory to /etc/cockpit/ws-certs.d with the command cd /etc/cockpit/ws-certs.d
• Run: cp -a 0-self-signed.cert ../0-self-signed.cert.bak
• Run: cat /etc/nginx/fullchain.pem /etc/nginx/privkey.pem > 0-self-signed.cert
• Restart the CML VM from the System tab in Cockpit

Licensing

1. How do I license Cisco Modeling Labs?

Licensing for Cisco Modeling Labs v2.x uses Cisco Smart Licensing. During the initial set up of your Cisco Modeling Labs installation, you need to register the installation with your Smart Licensing Virtual Account. You will paste a registration token in the dialog on the Licensing page of the Cisco Modeling Labs UI.

CML-Personal: Smart Licensing details are mostly hidden from CML-Personal users. Since many CML-Personal customers do not have a Smart Account of their own, CML-Personal 2.x licenses are placed in a special virtual account that is owned by the CLN Store. Even if you have a Cisco Smart Account, your Smart license for CML-Personal will not be visible there. Simply visit the My Account page on the CLN Store. Find your active order and click on the View License(s) button to view and copy the registration token that corresponds to that order.

CML-Enterprise: The Cisco Smart Software Manager (CSSM) web portal for Smart Licensing is https://software.cisco.com/#module/SmartLicensing. When you purchase CML-Enterprise, one or more licenses will be deposited into a Smart Licensing Virtual Account, which is associated to a Smart Licensing Account. Depending on whether or not you are part of a larger company or organization or an individual, a given Smart Licensing Account may have many Virtual Accounts or just a single Virtual Account. Think of a Smart Licensing Account as an organization with Virtual Accounts as the users within that organization. At the Virtual Account level, you generate a registration token that will give your CML-Enterprise instance access to all of the available licenses in that Virtual Account. Copy a registration token for your virtual account for use in licensing your CML-Enterprise installation.

You must license Cisco Modeling Labs before you can start any node.

2. Does Cisco Modeling Labs support licensing an offline (or air-gapped) deployment via SLR or PLR?

Yes, starting with v2.0.1, Cisco Modeling Labs supports offline deployments with Specific License Reservation (SLR). See SLR - Specific License Reservation for detailed steps.

Cisco Modeling Labs does not support Permanent License Reservation (PLR).

3. How can I convert my Cisco Virtual Internet Routing Lab 1.x license to a Smart license?

If you have an active license for Cisco VIRL Personal Edition 1.x, then a license for CML-Personal 2.x will be auto-provisioned for you. Visit the My Account page on the CLN Store and find an order for the legacy VIRL Personal Edition product. The order will have a View License(s) button that provides a registration token that can be used to license a CML-Personal 2.x installation. Click the Download button associated with the order to download the CML-Personal 2.x OVA and ISO files.

4. How can I convert my Cisco Modeling Labs 1.x PAK license to a Smart license?

From the Cisco Smart Licensing Portal, click the Convert to Smart Licensing link at the top of the page and follow the instructions to complete the process.

5. Can Cisco Modeling Labs v1.x and v2.x be used concurrently?

Yes, Cisco Modeling Labs v1.x is authorized to run for 30 days after the PAK license has been converted to a Smart license.

6. Is there a demo for users who want to try out Cisco Modeling Labs before purchasing?

The DevNet Sandbox platform offers a Cisco Modeling Labs preview that you can reserve up to four hours at a time. This is a fully-functional Cisco Modeling Labs instance with a sample topology already setup for you to preview the tool's capabilities.

7. How do I fix an "out of compliance" license authorization status?

Check the Tools > Licensing page. This answer only applies to you if your licensing page indicates both

• Registration Status: Registered
• License Authorization Status: Out of compliance

The "out of compliance" authorization indicates that your CML instance could not authorize the specified licenses. There are a few different problems that will result in the same error message. Follow these steps to narrow down the problem and possibly fix the problem yourself.

If this license has never worked, then check the following possible problems first.

1. Did you select the correct product during the initial set-up of your CML server?
   • The license for the two products is different, and if you selected the wrong product during initial set-up, your CML installation will fail to authorize its license.
   • If you purchased CML-Personal from the CLN Store,
     • you should select CML-Personal during initial set-up, and
     • the Smart License Usage table on the Tools > Licensing page will show a single row for CML - Personal License.
   • If you purchased CML-Enterprise from the CCW or from a Cisco partner,
     • you should select CML-Enterprise during initial set-up, and
     • the Smart License Usage table on the Tools > Licensing page will include CML - Enterprise License.
   • If your instance indicates that you selected the wrong product, you must first deregister your CML instance and then change the product configuration. Follow the instructions on Changing the Licensed Product Selection.
2. Are you using the correct Smart Licensing account and registration token?
   • If you purchased a CML-Personal product offering, do not attempt to use your own Virtual Account to generate a registration token. Simply follow the instructions on Getting the Registration Token for Licensing to get the registration token to use during Licensing.
   • If you purchased CML-Enterprise from the CCW or from a Cisco partner, then you should be using your company's Smart Account and the Virtual Account assigned to you by your company's smart account administrator. See also Getting the Registration Token for Licensing.

If that didn't solve your problem, or if you successfully licensed Cisco Modeling Labs 2.x once already, and now licensing is failing, then check the following possible problems.

1. Is your license expired?
   • Check your license's expiration date in the CLN Store (for CML-Personal purchases) or in the Smart Licensing virtual account (for CML-Enterprise licenses).
   • If the license has expired, you will need to renew your license or purchase a new license first.
2. Have you already / previously used your license to successfully register a CML installation?
   • To facilitate offline usage, after the CML server successfully authorizes the license, it will not release the license even if you stop the VM. Therefore, the Cisco Smart Licensing back end will consider the license to be in use even when the CML VM is not running.
   • Only one CML server can authorize a particular license at a time.
   • Before you delete, move, or re-deploy a CML VM, you must deregister the CML server to release its license before you can use the license on a different CML installation. See the Licensing - Deregistration page for instructions on deregistering a CML installation.
   • If you successfully licensed a CML VM and then deleted the VM without without first deregistering it, you will not be able to use that license for a new CML deployment until you manually delete the old CML instance from the Smart Licensing servers.
     • (CML-Personal customers) Use the Self-Service Deregistration process in the CLN Store:
       • Log into the CLN Store - My Account page with the CCO ID associated with your CML order.
       • Find your CML order that has the license that you want to de-register.
       • Click the View License(s) button to expand the area for the Smart license associated with that order.
       • Click the De-register link next to the Smart Licensing registration token.
       • A confirmation dialog is shown.
       • Click Yes to confirm that you want to remove all CML 2.x instances registered with the order’s associated license.
       • After doing that, you will be able to re-register the new instance of CML 2.x with the registration token.
       • Note: if you had registered the new instance in the CML UI and, when the authorization failed, used the de-register link in the CLN Store, then you will need to reregister the new instance by clicking Actions > Reregister on the Tools > Licensing page in the CML UI.
     • (CML-Enterprise customers) You will need to log into CSSM with an account that is a smart account administrator or a virtual account administrator for your Smart Licensing Virtual Account.
       • Click on the Inventory link in the navigation bar.
       • Select the virtual account that holds the CML-Enterprise licenses. It's the virtual account associated with the registration token you were using.
       • Click on the Licenses tab. You should see a row in the table for a CML-Base license with Purchased > 0 but with a Balance of 0 or less.
       • Click on the Product Instances tab.
       • Find the instance that corresponds to the deleted CML VM and use Actions > Remove to remove it.
       • Once the instance has been removed in the CSSM web portal, you will be able to use your license for a new CML instance.

External Connectivity

1. How can I connect my lab to an external network?

Cisco Modeling Labs provides external connectivity in two main ways: L3 NAT and L2 bridge. In L3 NAT mode, the Cisco Modeling Labs VM will perform dynamic network address translation for traffic flowing to and from external networks. The default subnet is 192.168.255.0/24. The traffic is ultimately routed out of the VM's virtual network interface (vNIC). L3 NAT mode is useful when you only want to provide outbound connections from your topology (e.g., provide internet access).

In L2 bridge mode, the Cisco Modeling Labs VM vNIC is shared with the virtual lab. A node connected to an L2 bridge form of external connectivity will be on the same L2 subnet as the VM's vNIC. L2 bridge module is useful when you want to peer with external devices using routing protocols like OSPF or EIGRP; when you want to use your own DHCP server to provide IP addressing; or when you want to connect to your running topology directly from an external network (e.g. with network management or automation applications). CAUTION: if you connect an IOSvL2 switch to an L2 bridge external connectivity node, that switch will participate in spanning-tree and dynamic trunking protocol by default. This may cause unintended effects on your local network. Consider enabling BDPU filter and turning off dynamic trunking negotiation on the port in the switch's day 0 configuration.

To add external connectivity to a lab, drag the External Connectivity node from the palette to the topology. Go to the External Connectivity node's Edit Config tab and select between NAT or Bridge based on the desired form of external connectivity. The Custom option is discussed in more detail below.

2. How many external connectivity nodes can I have within a lab?

You can add as many as you want. You can, for example, connect each node directly to an external network if you so choose. You can also connect a switch to an external network and then connect subsequent nodes to that switch to provide common external network access. External connectivity nodes do not count toward the running node count license.

3. How can I add multiple different external networks to Cisco Modeling Labs?

The two default forms of external connectivity leverage the single vNIC of Cisco Modeling Labs to provide the connectivity. If, however, you have multiple external networks (e.g., multiple VLANs) that you wish to expose within labs, you can do that by adding additional vNICs to the Cisco Modeling Labs VM. Adding additional interfaces and bridge groups is described in the networking section of the Cisco Modeling Labs Admin Guide.

Once you have created multiple bridge groups on the CML server, go back to the CML UI. Select your External Connector nodes and then click the Edit Config tab in the lower pane. On the Edit Config pane, click Custom to set the node to use the custom connectivity type and then enter the name of the bridge interface that you want to expose in the Custom Bridge Name text field. For example, if you created a bridge1 interface in Cisco Modeling Labs, enter bridge1 in the text field.

Advanced Topics

1. Does Cisco Modeling Labs v2.x support clustering?

While Cisco Modeling Labs v1.x offered the ability to cluster multiple Cisco Modeling Labs nodes together, clustering is not yet available in Cisco Modeling Labs v2.x. It is on the roadmap for a future v2.x release.

2. How can I add custom image or node types to Cisco Modeling Labs?

It is possible to add customer images and/or node types to Cisco Modeling Labs. Images are typically different versions of an existing node type (e.g., a new version of IOS-XE for the CSR1000v node). Node types are wholly new elements you can select from your palette when building labs. These can include third party network elements or hosts. See the Cisco Modeling Labs documentation for details on adding custom VM image definitions and custom node definitions.

To add a custom node type, go to Tools > Node and Image Definitions from the main menu at the top of the Cisco Modeling Labs window. Click the Node Definitions tab at the top. Nodes are defined using libvirt properties. Consult your node's requirements to see what you will need to fill out for the various field values. What might be helpful is to download a current node type definition, modify it, and then import it as a new node type. Once a new node type has been defined, you can add images for it using the new image procedure mentioned above.

3. How does Cisco Modeling Labs allocate MAC addresses for virtual nodes?

MAC addresses in the system are automatically allocated based on the following algorithm:

• the first three bytes are 52:54:00 (this comes from the underlying libvirt layer).
• the first three bits of the fourth byte are the MAC address block that can be customized via the API call PATCH /mac_address_block/{block} where {block} is a number between 0 and 7 (inclusive). It defaults to 0. ^**
• the remaining 21 bits of the MAC address are random

There IS a potential conflict when connecting two IOSv-L2 switches together which then form a trunk between them.

IOSv-L2 uses the burnt-in-address (BIA) of the GigabitEthernet0/0 interface as the base of the address for the "pool" of Switched Virtual Interface (SVI) MAC addresses. SVIs are created when the switch creates L3 VLAN interfaces.

The conflict occurs when the first four bytes (first 32 bits) of the MAC address are not unique. That is the case when the remaining random bits of byte 4 of the MAC address are identical for both switches (ultimately, there is about a 3% chance of this happening).

If such a conflict occurs, both switches which form the trunk then use the same MAC address, which does not allow any communication between the two. A workaround is then to manually set the MAC address in the configuration of one (or both) of those switches that form the shared trunk. An alternative workaround is to wipe and restart one of the switches, which will then allocate a new MAC address. However, there is another 3% chance for the conflict to reoccur.

^** NOTE: This MAC address block must be used if multiple Cisco Modeling Labs instances are connected to the same L2 management network. If virtual nodes will be connected to an external connector in bridge mode on that network, a MAC address conflict can occur if the MAC address network block is not unique for these CML instances. Because three bits are configurable, up to 8 CML instances can be used on the same L2 management segment without creating conflicts between them. For example, if setting up a second CML instance on the same network segment as another instance, use the API call PATCH /mac_address_block/1 to set the second instance's MAC address bit pattern to be "001" (where the first instance will be "000"). IMPORTANT: Performing this API call is not persistent. Each time the CML VM restarts, this API call must be made again prior to starting any new nodes.

Troubleshooting

1. When I configure dot1q subinterfaces on a CSR1000v node, it cannot pass traffic. Why?

Due to a missing low-level ethernet driver, the CSR1000v cannot currently use dot1q subinterfaces. A workaround is to use carrier ethernet service-instances instead. That is, instead of dot1q subinterfaces to terminate VLANs 100 and 200, do the following:

Copyinterface GigabitEthernet1
 service instance 100 ethernet
  encapsulation dot1q 100
 service instance 200 ethernet
  enacapsulation dot1q 200
!
bridge-domain 100
 member GigabitEthernet1 service-instance 100
!
bridge-domain 200
 member GigabitEthernet1 service-instance 200
!
interface BDI100
 ip address ...
 encapsulation dot1q 100
!
interface BDI200
 ip address ...
 encapsulation dot1q 200

See this community thread for more details.

2. When I try to start a lab, I get the error, "Failed to start node NAME: Unable to define node (Unable to clone image)." Why is this?

The reference platform ISO has not been properly mounted. This can also result in nodes hanging in the QUEUED state. In VMware settings, make sure the ISO is configured to be connected at power on, and then reboot the Cisco Modeling Labs VM.

3. Why am I not able to send jumbo frames with NX-OS 9000 nodes?

Jumbo frames work by default in the NX-OS 9000 nodes in CML, but configuring mtu on an interface is not supported by NX-OS 9000 until version 9.3(3). To use jumbo frames, change your lab to use a NX-OS 9000 VM image version of 9.3(3) or higher.

4. Why do nodes that use my custom image definition fail to start?

• In the Workbench, click the node that is failing to start.

• Click the Simulate tab in the lower pane and check the Image Definition property for the node.

• Ensure that the node is using the image definition that you expect.

  • If the node is using the Automatic image definition, try selecting a specific image from the dropdown menu.
  • If the only value listed in the image definition dropdown menu is Automatic, then your CML server has no images for this type of node.

• If you still cannot start the node after you have selected a specific image definition for it, log into Cockpit.

• Check the output of this command:

  shell

  Copysudo journalctl virl2-lowlevel-driver | grep ERROR
  

• Check the last few errors.

• If you're seeing an error that includes this message:

  Disk resize failed: qemu-img: warning: Shrinking an image will delete all data beyond the shrunken image's end.

  the most likely problem is that the Boot Disk Size for the node's node definition or image definition is too small.

  • In the node definition (or image definition), the Boot Disk Size cannot be smaller than the VM disk's virtual size, as reported by qemu-img info.

  • If your image definition's ID was foo-1.0.0, then you can check the virtual size of the disk associated with the image definition's .qcow2 file using this command:

    shell

    Copyqemu-img info /var/lib/libvirt/images/virl-base-images/foo-1.0.0/*.qcow2 | grep -i virtual
    

    You should get output that includes a line like this:

    text

    Copyvirtual size: 21 GiB (22548579328 bytes)
    

    In this case, the Boot Disk size specified in the image definition for the custom VM image must be 21 GiB or larger. If there is no Boot Disk size set in the image definition, then the Boot Disk size in the associated node definition must be 21 GiB or larger.