Contributing New Devices

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

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 not1.

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 ;)

System Settings

After building a Vagrant box or a container, you have to integrate it with netlab. You’ll need

  • A template that will generate the part of Vagrantfile (or containerlab configuration file) describing your virtual machine. See netsim/templates/provider/... directories for details.

  • Device parameters within the devices section of netsim/topology-defaults.yml.

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

  • Interface name template (interface_name), including %d 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.

  • Image name or box name for every supported virtualization provider.

After adding the device parameters into netsim/topology-defaults.yml, 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.

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 into the group_vars part of your device settings.

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_os2 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: ExaBGP daemon on Linux).

  • ansible_user and ansible_ssh_pass must often be set to the default values included in the network device image.

If you want to use the same device with multiple virtualization providers, you might have to specify provider-specific Ansible group variables (see providers.clab.devices.eos settings for details).

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 setting from netsim/topology-defaults.yml. 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 setting from netsim/topology-defaults.yml. The task list name has to be initial.yml for initial configuration deployment or module.yml for individual configuration modules (replace module with the module name). 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 value from netsim/topology-defaults.yml.

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 value from netsim/topology-defaults.yml.

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 module’s supported_on list in netsim/topology-defaults.yml to indicate that the configuration module is supported by the network device. 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 system settings.

  • Add device-specific virtualization provider configuration 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 system defaults (netsim/topology-defaults.yml). See devices.eos.clab settings for details.

Notes

  • The node dictionary within provider-specific device settings is copied directly into node data under provider key (example: devices.eos.clab.node system setting 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 directory.

  • Submit a pull request against the dev branch.

Implementation Notes

1

That was one of the reasons ArcOS was taken off the list of supported platforms.

2

netlab_device_type takes precedence over ansible_network_is.