Documentation
¶
Overview ¶
Package link helps with creating transient virtual network interfaces of various types for testing purposes. This package leverages the Ginkgo testing framework and matching (erm, sic!) Gomega matchers to assert that creation of new virtual network interfaces succeeds as expected.
The network interfaces created by this package are transient because they automatically get removed at the end of the a test – a spec, block/group, suite, et cetera – using Ginkgo's DeferCleanup.
Network Namespace Roulette ¶
Please see github.com/thediveo/notwork/netns for details on how to create and work with multiple network namespaces different from the initial/host network namespace.
First, NewTransient for creating new virtual network interfaces always acts in the “current network namespace” (but see below). This current network namespace is the one the OS-level thread executing the calling go routine is currently attached to.
Please note that github.com/thediveo/notwork/netns.EnterTransient automatically locks an OS-level thread to its go routine in order to avoid nasty surprises. In a similar way, github.com/thediveo/notwork/netns.Execute also temporarily locks the executing OS-level thread to its calling go routine for the duration of the function to be executed in a different network namespace.
Next, please note that netlink.Attrs.Namespace can be set to a netlink.NsFd wrapping the file descriptor (number) of a network namespace different from the current network namespace when calling NewTransient. In this case, the newly created virtual network interface will be created in the referenced network namespace instead of the current network namespace.
However, when creating virtual network interfaces related to existing network interfaces – such as in case of MACVLAN –, then the current network namespace defines where this “related” network interface is. For instance, netlink.LinkAttrs.ParentIndex references the parent network interface of a MACVLAN in the current namespace. Yet, the MACVLAN network interface will be created in a network namespace different from the current network namespace, if netlink.LinkAttrs.Namespace has been set.
In case of VETH pairs of network interfaces a third network namespace comes into play, courtesy of netlink.Veth.PeerNamespace. However, the current network namespace doesn't play any role here anymore, as long as both netlink.Attrs.Namespace and netlink.Veth.PeerNamespace are set. If either or both of these network namespace fields are unset (nil), then the current network namespace applies.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnsureUp ¶ added in v1.1.0
EnsureUp brings the specified network interface up and waits for it to become operationally “UP”. The maximum wait duration can be optionally specified; it defaults to 2s.
func NewTransient ¶
NewTransient creates a transient network interface of the specified type (via the type of the link value passed in) and with a name that begins with the given prefix and a random string of digits and uppercase and lowercase ASCII letters. These random network interface names will always be the maximum allowed length of 15 ASCII characters by the Linux kernel.
The newly created link is automatically scheduled for deletion using Ginko's DeferCleanup.
For typical use cases, you might want to look at these convenience functions instead:
- github.com/thediveo/notwork/dummy.CreateTransient
- github.com/thediveo/notwork/macvlan.CreateTransient
- github.com/thediveo/notwork/veth.CreateTransient
The passed-in link description is deep-copied first and thus taken as a template, but never modified. On success, the returned link description then correctly references the newly created virtual network interface (“link”).
The newly created transient link starts in down operational state, unless netlink.LinkAttrs.Flags has net.FlagUp. Alternatively, use netlink.LinkSetUp to bring the interface's operational state “up” in a guaranteed manner.
If VETH link information is passed in, NewTransient will automatically populate the netlink.Veth.PeerName with a name that also begins with the given prefix and a random string of digits and lowercase and uppercase ASCII letters filling up the remaining part up to the maximum allowed interface name length in Linux.
NewTransient remembers the network namespace the network interface was created in, so that it can correctly clean up the transient network interface later from one of Ginkgo's deferred cleanup handlers. This also covers the situation where the passed in link details reference a network namespace (in form of an open fd) different from the current network namespace.
By setting the passed-in netlink.Attrs.Namespace and/or netlink.Veth.PeerNamespace it is possible to create the new virtual network in a different network namespace than the caller's current network namespace. The current network namespace still can play a role, such as when creating a MACVLAN network interface: then, the MACVLAN's parent network interface reference (in form of an interface index) must be in the scope of the current network namespace.
Types ¶
This section is empty.
Source Files