Contributing New Devices

Adding new devices to netlab shouldn’t be too hard:

Figure out the device image to use
Create device settings file including Ansible variables
Add Ansible task lists to deploy and fetch device configurations
Add initial- and module-specific configuration templates
Test and document your work

Adding support for a new virtualization provider to an existing device is even simpler.

Device Images

netlab supports three virtualization providers: Vagrant with libvirt and Virtualbox, and containerlab running Docker container images.

If you can create a Vagrant box for the network device you want to use, or get a Docker container, it makes sense to proceed. Otherwise, yell at your vendor.

In this step, you should have a repeatable build my box recipe. It’s perfectly understandable that one might have to register at a vendor web site to download a container or a Vagrant box, or the images used to build a Vagrant box. Asking the potential users to “contact the account team” is not[1].

Please publish the recipe (it’s OK to add it to netlab documentation under install directory) before proceeding. We want to have repeatable installation instructions ;)

Device Parameters (System Settings)

After building a Vagrant box or a container, you have to integrate it with netlab. Start with device name:

Device name should not be too long (up to 16 characters is still OK) and should contain alphanumeric characters, but no special characters or blanks.
Check the list of supported platforms for existing device names.

After you decided what device name to use, create <device-name>.yml file in netsim/devices directory. You’ll use that file to store device parameters.

The device parameters will have to include (more details):

Device description – a short string describing the device
Interface name template (interface_name), including {ifindex} to insert interface number.
The number of the first interface (ifindex_offset) if it’s different from 1. Sometimes the data plane interfaces start with zero, sometimes they start with 2 because the management interface is interface 1.
Name of the management interface (mgmt_if) if it cannot be generated from the interface name template (some devices use mgmt0 or similar). This is the interface Vagrant uses to connect to the device via SSH.
Optional loopback interface name (‌loopback_interface_name), including {ifindex} to insert interface number.
Image name or box name for every supported virtualization provider.

Here’s the device parameters file for the dummy device (none.yml):

interface_name: eth{ifindex}
loopback_interface_name: Loopback{ifindex}
virtualbox:
  image: none
libvirt:
  image: none
clab:
  image: none
external:
  image: none
group_vars:
  ansible_connection: paramiko_ssh
  ansible_network_os: none

Some devices use different interface names for VMs and containers. Specify provider-specific parameters in <provider>.parameter settings. For example, Arista vEOS and cEOS have different management interface names:

interface_name: Ethernet{ifindex}
description: Arista vEOS
mgmt_if: Management1
loopback_interface_name: Loopback{ifindex}
clab:
  mgmt_if: Management0

Network OS containers could also use interface names that are different from the names of the underlying Linux interfaces. For example, Arista cEOS uses EthernetX in device configuration to refer to Linux interface ethX. To deal with such a device, specify Linux (container) interface name in clab.interface.name parameter:

interface_name: Ethernet{ifindex}
description: Arista vEOS
clab:
  interface:
    name: et{ifindex}

Finally, you can specify node attributes that are copied into node data (example: default device MTU) in node dictionary. If you want to specify provider-specific node parameters, use provider.node dictionary. For example, containers requires clab.kind attribute, and Arista cEOS requires an extra environment variable:

interface_name: Ethernet{ifindex}
description: Arista vEOS
clab:
  node:
    kind: ceos
    env:
      INTFTYPE: et

Device parameters file can also include numerous features. You’ll find feature description in developer documentation for individual modules.

After creating the device parameters file, you’ll be able to use your device in network topology and use netlab create command to create detailed device data and virtualization provider configuration file.

Device Setting Inheritance

If you’re adding a new device that is very similar to another device (example: Cisco IOSv/CSR1KV or Juniper vSRX/vMX/vPTX) use device setting inheritance:

Specify new device as a subtype of an existing device with the parent: device setting.
Specify modified device parameters in the new device’s YAML configuration file.
Set parameters that exist on the parent device but do not exist on the child device to None by specifying an empty value in the YAML file.

For example, Cisco CSR 1000v supports unnumbered IPv4 interfaces (IOSv does not) but does not support all VLAN modes that can be implemented in IOSv. It also uses different interface names and supports SR-MPLS and VXLAN.

The changes between the two devices are described with the following YAML data structure:

description: Cisco CSR 1000v
parent: iosv
interface_name: GigabitEthernet{ifindex}
ifindex_offset: 2
virtualbox:
  image: cisco/csr1000v
group_vars:
  netlab_device_type: csr
node:
  min_mtu: 1500
features:
  initial:
    ipv4:
      unnumbered: true
  isis:
    unnumbered:
      ipv4: true
  sr: true
  vlan:
    model: switch
    svi_interface_name: BDI{vlan}
    mixed_trunk:
    native_routed:
    subif_name:
  vxlan: true

Vagrant Template File

If you’ll use a Vagrant box to start the network device as a VM, you have to add a template that will generate the part of Vagrantfile (or containerlab configuration file) describing your virtual machine. See netsim/templates/provider/... directories for more details.

Using Your Device with Ansible Playbooks

If you want to configure your device with netlab initial or netlab config, or connect to your device with netlab connect, you’ll have to add Ansible variables that will be copied into group_vars part of Ansible inventory. Add those variables into the group_vars part of your device parameter file.

The Ansible variables should include:

ansible_connection – use paramiko for SSH access; you wouldn’t want to be bothered with invalid SSH keys in a lab setup, and recent versions of Ansible became somewhat inconsistent in that regard.
ansible_network_os – must be specified if your device uses network_cli connection.
netlab_device_type or ansible_network_os[2] is used to select the configuration task lists and templates used by netlab initial, netlab config and netlab collect commands. Use netlab_device_type when you’re creating different devices running the same operating system (example: Juniper vSRX and vMX both run Junos).
ansible_user and ansible_ssh_pass must often be set to the default values included in the network device image.

For example, here are the group variables for Cisco IOSv:

group_vars:
  ansible_user: vagrant
  ansible_ssh_pass: vagrant
  ansible_become_method: enable
  ansible_become_password: vagrant
  ansible_network_os: ios
  ansible_connection: network_cli
  netlab_device_type: ios

If you want to use the same device with multiple virtualization providers, you might have to specify provider-specific Ansible group variables in <provider>.group_vars key. For example, cEOS uses a different administrator username/password than the vEOS Vagrant box:

group_vars:
  ansible_user: vagrant
  ansible_ssh_pass: vagrant
  ansible_network_os: eos
  ansible_connection: network_cli
clab:
  interface:
    name: et{ifindex}
  node:
    kind: ceos
    env:
      INTFTYPE: et
  mgmt_if: Management0
  image: ceos:4.31.2F
  group_vars:
    ansible_user: admin
    ansible_ssh_pass: admin
    ansible_become: yes
    ansible_become_method: enable

Configuring the Device

To configure your device (including initial device configuration), you’ll have to create an Ansible task list that deploys configuration snippets onto your device. netlab merges configuration snippets with existing device configuration (instead of building a complete configuration and replacing it).

There are two ways to configure a devices:

Configuration templates: you’ll have to create a single Ansible configuration deployment task list that will deploy configuration templates. The configuration deployment task list has to be in the netsim/ansible/tasks/deploy-config and must match the ansible_network_os or netlab_device_type Ansible variable specified in device parameters file. More details…
Ansible modules (or REST API): you’ll have to create an Ansible task list for initial configuration and any other configuration module supported by the device. The task list has to be in the device-specific subdirectory of netsim/ansible/templates/ directory; the subdirectory name must match the ansible_network_os or netlab_device_type Ansible variable specified in device parameters file. The task list name has to be initial.yml for initial configuration deployment or <module>.yml for individual configuration modules. More details…

You might want to implement configuration download to allow the lab users to save final device configurations with collect-configs.ansible playbook used by netlab collect command – add a task list collecting the device configuration into the netsim/ansible/tasks/fetch-config directory.

Initial Device Configuration

Most lab users will want to use netlab initial or netlab up command to build and deploy initial device configurations, from IP addressing to routing protocol configuration.

If decided to configure your devices with configuration templates, you have to create Jinja2 templates for initial device configuration and any configuration module you want to support.

Jinja2 templates that will generate IP addressing and LLDP configuration have to be within the netsim/ansible/templates/initial directory. The name of your template must match the netlab_device_type or ansible_network_os Ansible variable specified in device parameters file.

Jinja2 templates for individual configuration modules have to be in a subdirectory of the netsim/ansible/templates directory. The subdirectory name has to match the module name and the name of the template must match the netlab_device_type or ansible_network_os Ansible variable specified in device parameters file.

Use existing configuration templates and initial device configurations part of supported platforms document to figure out what settings your templates should support. More details…

Configuration Modules

Similar to the initial device configuration, create templates supporting individual configuration modules in module-specific subdirectories of the templates directory.

Use existing configuration templates and module description to figure out which settings your templates should support.

For every configuration module you add, update the device’s features dictionary to indicate that the configuration module is supported by the network device. When a configuration module has no extra options (or your device doesn’t support them), simply add _module_: True line. Explore existing device YAML definitions for more details. For example, this is the definition declaring that Cisco IOSv supports BFD (with no extra options) and BGP with a number BGP-specific features:

features:
  bfd: true
  bgp:
    local_as: true
    vrf_local_as: true
    local_as_ibgp: true
    activate_af: true

The list of supported devices is used by the netlab create command to ensure the final lab topology doesn’t contain unsupported/unimplemented module/device combinations.

Adding an Existing Device to a New Virtualization Provider

To add a device that is already supported by netlab to a new virtualization environment follow these steps:

Get or build a Vagrant box or container image.
Add the image/box/container name for the new virtualization provider to device parameters file.
Add device-specific virtualization provider configuration template to provider-specific subdirectory of netsim/templates/provider directory. Use existing templates to figure out what exactly needs to be done.
You might need to add provider-specific device settings to device parameters file. See the above Arista cEOS examples for more details.

Notes

The node dictionary within provider-specific device settings is copied directly into node data under provider key. For example, clab.node Arista cEOS setting (from netsim/devices/eos.yml) is copied into nodes.s1.clab assuming S1 is an EOS device and you’re using clab provider.
Other provider-specific device settings overwrite global device settings.

Test Your Changes

Create a simple topology using your new device type in the tests/integration directory.
Create Ansible inventory and Vagrantfile with netlab create
Start your virtual lab
Perform initial device configuration with netlab initial
Log into the device and verify interface state and interface IP addresses

Final Steps

Fix the documentation (at least install.md and platforms.md documents).
Make sure you created at least one test topology in tests/integration/platform directory.
Submit a pull request against the dev branch.

Implementation Notes