How to implement a new network device type

This guide will explain how to extend the LNST with a new network device type.

Each device type supported by LNST is implemented as a separate class in lnst.Devices module.

User can import such device using the following code:

from lnst.Devices import VlanDevice

To implement a class for new network device type several steps need to be done.

This guide will use gre tunnel device as an example.

SoftDevice class

All virtual devices should inherit from the SoftDevice class.

from lnst.Devices.SoftDevice import SoftDevice

class GreDevice(SoftDevice):

Device name template

The new device class should define the name template for the created devices. If the template is not defined a generic one defined by the SoftDevice class will be used instead.

from lnst.Devices.SoftDevice import SoftDevice

class GreDevice(SoftDevice):
    _name_template = "t_gre"

Device type

User must also define the device type through the _link_type class attribute. The value matches the link type that is used by iproute2’s ip link utility.

For example, the gre device is created by following command:

ip link add new_gre_device type gre remote

The type gre part of the command above should be used in the _link_type.

For other link types user can check the output of the following command:

ip link help
ip -6 link help # for ipv6 specific devices

So, the device code will look like this:

from lnst.Devices.SoftDevice import SoftDevice

class GreDevice(SoftDevice):
    _name_template = "t_gre"
    _link_type = "gre"

Device parameters

The device class may define any parameters available for the network device type.

For example, the gre device uses the local and remote parameters as in the following command:

ip link add new_gre_device type gre local remote

These parameters have to be defined as class properties with their setters. They have to use SoftDevice methods to configure the device’s parameters through kernel’s netlink API:

  • _get_linkinfo_data_attr()
  • _set_linkinfo_data_attr() for the property setters

The code extended with the remote parameter would look like this:

def remote(self):
        return ipaddress(self._get_linkinfo_data_attr("IFLA_GRE_LOCAL"))
        return None

def remote(self, val):
    self._set_linkinfo_data_attr("IFLA_GRE_LOCAL", str(ipaddress(val)))

In the code above the remote property returns an IP address retrieved through the netlink by calling the _get_linkinfo_data_attr() with the netlink’s representation of the remote parameter, that is IFLA_GRE_LOCAL.

The remote.setter configures the remote device parameter by calling the _set_linkinfo_data_attr() with the netlink’s representation of the parameter IFLA_GRE_LOCAL and the IP address as the value of the parameter.

The setters must always include call of the _nl_link_sync() to commit the changes through netlink.

For the device specific IFLA_* strings refer to Finding out the IFLA_* strings

With the code above the user can now use the device class in a recipe, for example:

from lnst.Controller import Controller, HostReq, DeviceReq, BaseRecipe
from lnst.Devices.GreDevice import GreDevice

class GreRecipe(BaseRecipe):
    machine1 = HostReq()
    machine1.nic1 = DeviceReq(label="net1")

    def test(self):
        machine1.gre = GreDevice(remote="")

ctl = Controller()
recipe_instance = GreRecipe()

Mandatory device parameters

A device may require some parameters to be specified, for example a gre device requires remote parameter.

You can specify such parameters in the class attribute _mandatory_params:

class GreDevice(SoftDevice):
    _name_template = "t_gre"
    _link_type = "gre"
    _mandatory_opts = ["remote"]

LNST will automatically check if the mandatory parameters where specified in the device instance and report back a failure.

Finding out the IFLA_* strings

The device parameters are configured through the kernel’s netlink API.

In the code above we have mentioned two SoftDevice methods used for setting or retrieving the device parameters, the _get_linkinfo_data_attr() and _set_linkinfo_data_attr(). Both methods takes a name of the device parameter as an argument, these are prefixed with IFLA_ string.

What becomes challenging is to find out the corresponding IFLA_* strings for a specific network device. These are unique for each device.

Here the pyroute2 comes handy. The pyroute2 is a Python module that provides also an API for interacting with the kernel’s netlink. LNST uses this module for the device management.

To find out what parameters are needed to configure the test device simply follow the procedure below.

Save the following code to file named

from pyroute2 import IPRoute
from pprint import pprint

with IPRoute() as ipr:
    while True:
        for message in ipr.get():

Run the script in background and run an iproute command to create a gre tunnel device (or any other device of your interest).

./ &

ip link add mygre type gre local remote

The script should print the complete netlink message including the details of IFLA_LINKINFO. So simply find the message that contains ('IFLA_IFNAME', 'mygre') (mygre matches the device name used in the ip link command above).

So, inspecting the output above, the relevant IFLA_* strings are found under IFLA_LINKINFO / IFLA_INFO_DATA (in highlighted lines):

  • ('IFLA_GRE_LOCAL', '')
  • ('IFLA_GRE_REMOTE', '')