Creating a New Node Definition¶
Introduction
A node definition in Cisco Modeling Labs represents a type of virtual device. Each node in a CML lab has an associated node definition. For example, in the Workbench, when you drag-and-drop IOSv from the Add Nodes drawer to the lab, CML adds a node that has an associated node definition of IOSv. If you drag-and-drop CSR1000v onto the lab, CML adds another node to the lab with an associated node definition of CSR1000v. The Add Nodes drawer shows an item for each node definition that is visible.
It is important to understand that the node definition represents a family or type of virtual device, not a particular VM image. A VM image in CML has an image definition. Among other things, the image definition associates the VM image with a particular node definition. For example, if your administrator has added multiple versions of CSR1000v to your CML server, then you will have multiple image definitions, one per VM image, but each image would be associated with the same built-in CSR1000v node definition. If you do not select a specific image for a node in your lab, that node will use the default image of its associated node definition. Creating an image definition for a custom VM image is fairly straight-forward. See Custom VM Image for more information.
Creating a custom node definition for a new type of virtual device is more complicated. The node definition details all of the properties that enable Cisco Modeling Labs to start a VM that’s associated with the node definition. To create a custom node definition, you should understand the virtualization details for that type of virtual device. This guide describes the node definition properties in CML, and you should use it in conjunction with your virtual device’s installation and configuration documentation to select correct values for your custom node definition.
General Settings
Property name |
Required? |
Description |
|---|---|---|
ID |
yes |
A unique identifier for the node definition. Your CML server cannot have two node definitions with the same ID. The ID must not contain spaces. For example, “exampleco-rtr”. |
Description |
no |
A free-form description of this node type. |
Nature |
yes |
This property describes the role that nodes using this node definition play in the network. Pick the value from the drop-down that most closely matches this type of device. |
User Interface Settings
Property Name |
Required? |
Description |
|---|---|---|
Visible |
yes |
This property permits you to reduce the number of items shown in the Add Nodes drawer in the Workbench. The Add Nodes drawer shows an item for a node definition if and only if visible is true. In general, you should enable this property. |
Description |
no |
A description of the node definition that also supports Markdown mark-up for rich formatting. |
Prefix |
yes |
A prefix used to name nodes associated with this node definition. When you add a node to the lab, CML will supply a default label for the node by appending a numeric value to the prefix. For example, new IOSv nodes are named “iosv-1”, “iosv-2”, “iosv-3”, etc. The prefix value should be a sequence of letters, numbers, and dashes ending with a dash. For example, “exampleco-rtr-“. |
Icon |
yes |
The icon to assign this node. Choose from the list based on what this node most closely resembles. This choice is a matter of taste. This property only affects the visual display of your lab and has no impact on the simulation. |
Label |
yes |
The label is used for the item in the Add Nodes drawer in the Workbench. This label should be short and human-readable, such as “ExampleCo Rtr”. |
Linux Native Simulation Settings
This is the section details all of the virtualization properties. Be sure to have your virtual device’s installation and configuration documentation to help you set the correct values.
Property Name |
Required? |
Description |
|---|---|---|
Domain Driver |
yes |
The virtualization driver for this node. Always choose |
Simulation Driver |
yes |
The CML simulation driver profile. This property controls several aspects
of how CML’s behavior when working with VMs associated with this node
definition. In general, choose |
Disk Driver |
yes |
The type of disk device to add. Refer to your device’s installation and configuration documentation to choose the most appropriate type. |
Memory (MiB) |
yes |
The amount of memory (in megabytes) that CML should allocate to nodes associated with this node definition. Refer to your device’s installation and configuration documentation to choose the correct value. |
CPUs |
yes |
The number of virtual CPUs that CML should allocate to nodes associated with this node definition. Refer to your device’s installation and configuration documentation to choose the correct value. |
CPU Limit |
yes |
A percentage value that can be used to limit the amount of CPU allocated to nodes associated with this node definition. See Launch Sequence and CPU Limiting. Start with a value of 100%, and adjust later if needed. |
Network Driver |
yes |
The network driver type for nodes associated with this node definition. Refer to your device’s installation and configuration documentation to choose the correct value. |
Data Disk Size (GiB) |
no |
The size of the data disk required by nodes associated with this node definition (in gigabytes). The data disk is an additional disk that CML adds to the virtual device if a non-zero value is provided. Some devices need a second disk to store databases or other information. For example, the SD-WAN manager stores its database on the second disk. Refer to your device’s installation and configuration documentation to see whether this type of device requires a second disk and, if so, what size. |
Boot Disk Size (GiB) |
no |
The size of the boot disk required by nodes associated with this node definition (in gigabytes). The boot disk is typically the disk that holds the operating system and that is marked bootable. Refer to your device’s installation and configuration documentation to choose the correct value. |
Video Model |
no |
This property specifies the video card inserted into the virtual device. This probably can usually be left with the default value. Some devices might require a specific model to be set. Choose from the following list of identifiers: std, cirrus, vmware, qxl, xenfb, tcx, cg3, virtio, none. For typical use, either choose std or cirrus. If the device type does not require a video card, such as a router that relies on a serial console for configuration management access, you may choose none. If a node is associated with a node definition that has video card, CML will makes the VNC option available for the node. |
Video Memory (MiB) |
no |
If this device will have a graphical desktop or use a graphical console (even if that graphical console is just a text interface), you must set this property to a non-zero value. The value specified in MB, and a value of 16 or 32 is common for device types that correspond to hosts. Refer to your device’s installation and configuration documentation when choosing a value. Devices that have a heavier graphical interface require more video memory. |
Note: Disk sizes (data disk and boot disk) override the size of the disk itself. For example, a boot disk image that is associated with a specific device might have a configured disk size of 16GB, but the actual file size might be less than 16GB. It will never be larger than the specified size.
In this example, the disk image file on the CML server that corresponds to the disk associated with a particular node is not necessarily 16GB. The virtual disk inside of the disk image file is simply configured to have the specified size. An entirely empty qcow2 disk image file for a 1 TB disk might only be a few kilobytes in size.
When the boot disk size for a virtual router/server device is specified as 32GB, then the system will increase the size of the virtual disk from its initial size of 16GB to 32GB when it is first instantiated on the hypervisor. This change in size does not automatically increase file-systems or partition tables. The operating system for that particular virtual device type must take advantage of the additional space from the larger disk size.
Interfaces Settings
This section will also require you to consult your device’s system requirements or installation and configuration documentation to understand what the default interfaces and the maximum number of interfaces are. You will need the default and maximum interface counts plus the naming convention of the interfaces. If your virtual device uses a serial console, you can provide that information in this section.
Property Name |
Required? |
Description |
|---|---|---|
Has a Loopback Interface |
yes |
If this device should have a loopback interface, enable this option. Otherwise, disable it. |
Loopback Name |
no |
If the device has a loopback interface, specify its name here. For example, the loopback on a Linux hosts would be lo. |
Number of serial ports |
yes |
The total number of serial ports this type of virtual device has. Even if the device doesn’t have any serial ports, such as a console port, this property should not be 0. It must be a number between 1 and 8 (inclusive). Cisco devices typically have two serial ports: a console port and an aux port. Linux hosts may use a serial port as the text console. In general, set this property to 1 unless your virtual device’s installation and configuration documentation indicates that the device can support more than one. |
Default number of physical interfaces |
no |
The number of network interfaces to attach to the node by default. While the property is optional, you will typically specify a number here. The minimum value is 1. Allocating a few interfaces by default can be useful if nodes associated with this node definition typically have multiple connections in your labs, but you can always add additional interfaces to a node–up to its node definition’s maximum number of interfaces–after you add the node to your lab in the Workbench. See also Interfaces and Provisioning. |
Note: A loopback interface is only needed for router / device configuration generation. It does not appear as a connect-able device in the topology diagram!
Next, you should provide all of the potential interface names the device can have. This list should include the default interfaces. Enter the name of the first interface in the interface name field, such as eth0 or GigE0/0. If your device’s interface names simply have a numerical suffix, such as eth0, eth1, and eth2, you can simply enter eth0 in the interface name field and then click the Increment Last Interface, button twice to automatically add eth1 and eth2. If your device’s interface names are not incremental, use the Add Interface button to add additional empty fields and enter the interface names in those fields manually.
It is important to list all of the interfaces this type of device can have. CML will prevent you from adding more interfaces to a node than the number of interfaces in its associated node definition. The interface names are also important so that the labels shown with a lab in the Workbench match what you see in the configuration for your device’s VM. The VM’s operating system assigns names to the sequence of node interfaces following its own rules, most likely always giving them names in the same sequence. The node definition should capture the resulting list; it cannot change the OS’s rules to force any different names on the interfaces.
Boot Settings
Property Name |
Required? |
Description |
|---|---|---|
Timeout (seconds) |
yes |
The timeout in seconds that CML should wait for the node to boot fully. The value is the maximum time (in seconds) that CML will wait before the node’s in-progress status will change to booted, and the Workbench will show the node with a solid green dot. |
You can optionally click the Add Boot Line button to add additional boot lines. CML will scan the node’s console during boot, checking to see whether a line contains each boot string. Boot lines are evaluated as regular expressions. Once any of the boot lines has been seen, CML will consider the node to be fully booted. For example, IOSv nodes include “%PLATFORM-5-SIGNATURE_VERIFIED:” and “Would you like to enter the initial configuration dialog?” to indicate when the node is ready for user interaction.
pyATS Settings
pyATS is an Open Source, Python framework from Cisco for creating and running automated network tests. Using PyATS, you can write tests that execute and parse CLI output from devices and then to test the execution results, ensuring proper device operation. CML provides a pyats_testbed API that generates a testbed definition for a lab that is ready for use with pyATS tests. Enabling pyATS support and use-in-testbed for a node definition tells CML to include nodes associated with this node definition in the pyATS testbed for a lab, filling in all of the correct device-specific parameters.
Note that pyATS must be enabled if you want to use configuration extraction on nodes associated with this node definition. You can enable pyATS support but leave the Use in Testbed disabled if you’re not planning to use pyATS for anything other than configuration extraction.
Property Name |
Required? |
Description |
|---|---|---|
Enable pyATS |
yes |
If this type of device is supported by pyATS, enable this property. Otherwise, leave it disabled. |
Use in Testbed |
yes |
If enabled, nodes associated with this node definition will show up in exported testbed definitions. If disabled, this device will be omitted from the pyATS testbeds. |
Operating System |
yes |
The name of the operating system according to pyATS. For example, IOSv’s OS type is “ios”. |
Series |
no |
The series of the device. This property is not normally needed for virtual devices, but it could be something like “iosv”. |
Model |
no |
The model of the device. This property is not normally needed for virtual devices, but it could be something like “xrv9k”. |
Username |
no |
The username pyATS should use to log into the device. |
Password |
no |
The password pyATS should use to log into the device. |
Config extract command |
no |
CML uses pyATS to extract configurations from running devices. Therefore, pyATS must be enabled as a pre-requisite for configuration extraction. When you use the Extract Configuration feature of a lab to pull in a node’s current configuration, CML will use this configuration extraction command on nodes associated with this node definition. Note: Not all devices support a single configuration extract command (e.g., Linux has multiple files and subsystems that dictate overall device configuration). If there is a command to capture your device type’s current configuration, specify that command in this property. |
For a complete list of supported devices and their respective OS, series and model settings, consult the official pyATS / Unicon documentation.
Property Inheritance Settings
Property inheritance allows you to define certain properties on multiple levels. Enabling inheritance for a property will allow you to specify a value for the property in an image definition and/or on an individual node associated with this node definition. Disabling inheritance for a property will force nodes to use the value defined in the node definition.
For an inherited property, CML will look first to see whether the property was set on the node itself. If so, CML uses that value. If not, CML checks for a value on the image definition. Finally, if no value was found at the other levels, CML uses the value from the node definition.
As an example, assume that the IOSv node definition specifies RAM of 512 MiB. If you have an image for a particular version of IOSv that requires 768 MiB of RAM, you would create an image definition for that version of IOSv and set the RAM to 768 MiB in the image definition. The image definition will override the RAM setting for any IOSv nodes that use the image. You may also override the RAM value on a node. If you specify 1024MB of RAM on an IOSv node in a lab, that value will apply just for that node, not the value from the image definition or the node definition.
The properties which can use inheritance are:
RAM
CPUs
CPU Limit
Boot Disk Size
Data Disk Size
Configuration Settings
If this device uses a bootstrap configuration that is similar to an existing node definition, select that node type for them here. In the Workbench, when you click the Bootstrap Lab button in the Lab menu, prior to starting a new lab, CML will use the selected value to determine how to generate an appropriate bootstrap configuration for the node, see Bootstrap Configuration Building.
Provisioning Settings
If the device can accept a bootstrap configuration, sometimes called a Day 0 configuration, specify the details for the configuration here. Consult the installation and configuration documentation for your device to learn how its bootstrap configuration works. If enabled, CML will take the bootstrap configuration, specified either here or on the node’s Config tab in the Workbench, and convert it either to an ISO9660 (e.g., CD-ROM) or FAT volume within the node’s VM. It will then be up to the node itself to read the data from this volume and perform any initial configuration. The IOSv node type is a good example of how to define provisioning in a node definition, but the settings will be very device-specific.
You do not need to enable provisioning to take advantage of CML’s node persistence. Without bootstrap provisioning, the first time a node associated with this node definition boots, it will boot to its unconfigured state. But once you configure a node in a lab, that configuration should be preserved with the running node memory state, and/or node disk state if the node writes configuration to its disk, until the node or lab is wiped. See also Deleting Labs and Starting, Stopping, and Wiping Nodes.
Note
However, if you do not enable provisioning, you will be able to neither provide a Day 0 configuration or extract configuration from nodes created from the node definition. In other words, you will need to manually re-apply the configuration each time you import or wipe the nodes.
Next Steps
Now that the node definition is done, you can create new image definitions and tie them to this node definition. Every time you create new node definitions, you must create at least one new image definition and link it to the new node definition. You cannot copy or link image definitions from other, existing node definitions.
Configuration Extraction Customization¶
You can customize how configuration extraction works for all nodes that use this node definition. For CML to extract the configuration from a running node, the node definition must provide console-based access, and pyATS must support logging in to the running VM for the node. Most of the node definitions provided with CML support configuration extraction. For the Cisco node definitions provided as part CML, the extracted configuration usually comes from the command:
show run
You can adjust the specific command used to extract configurations by revising the node definition by using the following procedure:
Procedure
Navigate to .
Choose the node definition you intend to customize.
Specify the Config Extract Command in the pyATS field.
Press Update at the bottom of the interface to save the changes.
Synchronization from Node Definition¶
When a node is:
started,
wiped,
set,
or extracted,
unaltered configuration files will have their contents synchronized with their node’s definition.