netdevsim

Documentation

Overview

Package netdevsim helps with creating transient netdevsim type virtual network interfaces for testing purposes. It leverages the Ginkgo testing framework and matching (erm, sic!) Gomega matchers.

Technically, a netdevsim in the strict sense is a device on the “netdevsim” bus. A netdevsim bus device then has a number of ports, where these ports corresponds with netdevs/network interfaces provided by the netdevsim device. For simplicity, we'll call these network interface also “netdevsim” network interfaces, like their bus devices.

The "netdevsim" network interfaces created by this package are transient because they automatically get removed at the end of the a test (spec, block/group, suite, et cetera) using Ginkgo's DeferCleanup.

Since Linux kernel 6.9+ two “port” network interfaces of netdevsims can be linked together, similar to “veth” pairs.

Caveats

On at least some Linux distributions, you might need to explicitly modprobe the “netdevsim” module. For what it's worth, the Linux kernel self-tests also modprobe the netdevsim module.

Background Information

The lifecycle management of netdevsim network interfaces can't be done through the usual NETLINK link API, as with other virtual network interfaces, such as “veth”. Instead, the following sysfs-located pseudo files must be used:

• /sys/bus/netdevsim/new_device
• /sys/bus/netdevsim/del_device

Unfortunately, when creating a new netdevsim instance via the pseudo file, we don't get the information about the names (or indices) of the newly created network interfaces. This package thus hides the complexity in mapping netdevsim instances to their particular network names and indices.

To make things worse, the only currently known way to map netdevsim ports to their network interfaces is via /sys/bus/netdevsim/devices/net/, with the associated problems around sysfs and non-adaptive network namespacing.

This package works around the situation by creating netdevsims with multiple ports piecemeal-wise, picking up the newly created ports piece by piece.

Index

• Constants
• func HasNetdevsim() bool
• func Link(dupond, dupont netlink.Link)
• func NewTransient(opts ...Opt) (id uint, links []netlink.Link)
• func Unlink(l netlink.Link)
• type Opt
  • func InNamespace(fdref int) Opt
  • func WithID(id uint) Opt
  • func WithPorts(n uint) Opt
  • func WithRxTxQueueCountEach(n uint) Opt
• type Options

Constants

const NetdevsimPrefix = "ndsi-"

MacvlanPrefix is the name prefix used for transient port network interfaces of a transient netdevsim device.

Functions

func HasNetdevsim

func HasNetdevsim() bool

HasNetdevsim returns true if netdevsims are available on this host.

func Link

func Link(dupond, dupont netlink.Link)

Link to netdevsim “port” interfaces with each other. Please note that the passed link descriptions must reference netdevsim network interfaces in the current network namespace; either by name or by index. If one or both instead refer to netdevsim network interfaces in other network namespaces than the current network namespace, then the link descriptions must have their netlink.LinkAttrs.Namespace fields properly set.

Note: requires Linux kernel 6.9+.

func NewTransient

func NewTransient(opts ...Opt) (id uint, links []netlink.Link)

NewTransient creates a transient netdevsim device as well as at least one “port” network interface. The number of port network interfaces and the amount of RX+TX queue sets can be specified through options passed in opts.

NewTransient returns the “port” links created, with the first element being port 0, the second port 1, and so on. The link objects returned have only their [LinkAttrs.Name] set, and optionally their (network) [LinkAttrs.Namespace] when configured with the option InNamespace.

func Unlink

func Unlink(l netlink.Link)

Unlink the specified “port” interface from its peer.

Note: requires Linux kernel 6.9+.

Types

type Opt

type Opt func(*Options) error

Opt is a configuration option when creating a new netdevsim network interface.

func InNamespace

func InNamespace(fdref int) Opt

InNamespace configures a new netdevsim to have its port network interface(s) to be created in the network namespace referenced by fdref, instead of creating it in the current network namespace.

func WithID

func WithID(id uint) Opt

WithID configures a new netdevsim to use the specified ID, as opposed to the lowest available ID.

func WithPorts

func WithPorts(n uint) Opt

WithPorts configures a new netdevsim to have the specified number of ports (=individual network interfaces).

func WithRxTxQueueCountEach

func WithRxTxQueueCountEach(n uint) Opt

WithRxTxQueueCountEach configures a new netdevsim to have the specified number of RX as well as TX queues. Specifying a zero queue count results in an error when trying to create a netdevsim.

type Options

type Options struct {
	HasID      bool // false means: shut up and get me the next available ID!
	ID         uint
	Ports      uint
	QueueCount uint // per RX and per TX respectively
	NetnsFd    int  // valid when >= 0
}