Device Quirks and Device Hooks

Individual devices supported by netlab might have implementation details that are not recognized by the netlab core, configuration modules, or device feature flags. These details should be handled by device quirks modules.

The device quirks modules can also implement device hooks – device-specific methods that netlab calls at various points of the lab lifecycle (for example, to reload device configuration with netmiko).

Framework

A device quirks module must reside in the netsim/devices directory and have the same name as the device (example: eos.py for Arista EOS).

It must define a descendant of the _Quirks class (defined in netsim/devices/__init__.py) with the device_quirks method:

class EOS(_Quirks):

  @classmethod
  def device_quirks(self, node: Box, topology: Box) -> None:
  ...

Devices that share most of their quirks (for example, Cisco IOS XR and Cisco 8000v) can inherit the device class from another device module:

from .iosxr import IOSXR as _IOSXR

class Cisco8000v(_IOSXR):
  ...

netlab loads the device module the first time it needs it and caches the device object in the DEVICE_MODULE dictionary.

Device Quirks

The device_quirks method is called near the end of the data transformation, after module and plugin post-transform processing but before the provider post_transform hook. When a quirks function modifies node data, the modified data will be used to generate provider configuration files or Ansible inventory.

You should define a new function for every quirk you want to handle, and call those functions from the device_quirks method. It probably makes sense to use the node.module attribute when deciding which functions to call, for example:

class EOS(_Quirks):

  @classmethod
  def device_quirks(self, node: Box, topology: Box) -> None:
    mods = node.get('module',[])
    if 'evpn' in mods:
      if log.debug_active('quirks'):
        print(f'Arista EOS: Checking MPLS VLAN bundle for {node.name}')
      check_mlps_vlan_bundle(node)

The individual quirks functions should check the relevant node data (example: vlan.mode must be set to bridge on Arista EOS if vlan.evpn.bundle is set) and make changes to node data structure if needed (example: remove Vlan{vlan.id} interfaces on Arista EOS for VLANs in an EVPN/MPLS VLAN bundle).

Use the report_quirk function to report unsupported configurations. It reports an error (or a warning or an info message when you set the category parameter or the info flag) and tells the user how to disable the check when you specify the quirk parameter (the check is skipped when the defaults.devices.device.warnings.quirk setting is False).

The check_config_sw method is called before the initial device configuration is deployed (in netlab up and netlab initial). Use it to check whether the software needed to configure the device (for example, an Ansible collection) is installed. netlab aborts the configuration deployment if a check_config_sw method reports an error.

Device Hooks

A device hook is any method of the device class. netlab calls device hooks with the exec_device_hook function (defined in netsim/devices/__init__.py):

def exec_device_hook(node: Box, topology: Box, method: str, *, debug_flag: str = 'hooks', **kwargs: typing.Any) -> typing.Any

The exec_device_hook function:

• Loads the device module for the node device

• Checks whether the device class has the specified method. The hook methods do not have to be defined in the _Quirks class.

• Calls the method with the node and topology parameters and any extra keyword parameters specified by the caller, and returns the value returned by the method.

• Returns None when the device has no device module or when the device class does not have the specified method.

The extra parameters cannot be checked in advance, so make sure your hook method has the parameters the caller expects. The hook should return a value other than None when it did something; the caller can then skip the generic processing. For example, the configuration reload code uses this pattern:

if q_devices.exec_device_hook(n_data,topology,'netmiko_reload',conn=conn,nm_data=nm_data) is not None:
  return

The device quirks (device_quirks and check_config_sw methods) are called through the exec_device_quirk function, a wrapper around exec_device_hook that uses the quirks debugging flag.

netlab currently uses these device hooks:

Hook	Called from	Extra parameters	Meaning
device_quirks	netsim.augment.main	–	Adjust node data at the end of the data transformation
check_config_sw	netlab up, netlab initial	–	Check whether the software needed to configure the device is installed
netmiko_reload	netlab config –reload	conn, nm_data	Reload saved device configuration (see Device-Specific Reload Procedure)

Debugging

• Use the --debug quirks CLI parameter to display the device quirks calls

• Use the --debug hooks CLI parameter to display the other device hook calls. The debugging printout shows whether netlab found the device module and the hook method.