willfantom / neslink

Easy and safe interaction with network namespaces and links

netneslink    

NESlink is go package that allows for interaction with netlink. NESlink is simply a quality of life wrapper around these great netlink and netns packages. Not all the functionality of these packages remains in NESlink, but the interactions that are included are better suited to the NES platform implementation.

The main objective of this package is to make link interaction easier when dealing with many links across many network namespaces. This includes safe parallel operations in multiple namespaces.

---

Usage

At the core of this package are the Do functions, one for network namespaces, the other for links. These allow for low-code, go routine safe interaction with both links and namespaces (and links in namespaces).

Namespace Interaction

Any interaction with a netns should be done via a call to Do. As an example, to list the links in a network namespace, you would simply need to provide Do with a NsProvider for the target namespace, and the NsAction for listing links. So if there was a network namespace called example, then the following snippet would perform the action safely:

links := make([]netlink.Link, 0)
err := neslink.Do(neslink.NPName("example"), neslink.NALinks(&links))
if err != nil {
  ...

💡 Any number of NSActions can be provided to a single Do call, and they will be executed in order.

Here err would contain any error that occurred either in switching namespaces or within the function. If for any reason the system thread used for the action executing go routine fails to be returned to the netns of the caller, the thread is marked as dirty and can not be accessed again.

Custom NsActions can be easily created too, see this example.

Link Interaction

To manage links, any operation should be a LinkAction set in a call to Do. Do will execute a set of functions in a given netns. As an example, the below snippet will create a new bridge called br0 in a pre-existing named netns called example, then set its MAC address to 12:23:34:45:56:67 and set its state to UP:

if err := neslink.Do(
  neslink.NPName("example"),
  neslink.LANewBridge("br0"),
  neslink.LASetHw(neslink.LPName("br0"), "12:23:34:45:56:67"),
  neslink.LASetUp(neslink.LPName("br0")),
  ); err != nil {
  ...

📝 Setting a link's netns is not a LinkAction but instead a NsAction, since after moving the link to another netns, the netns of the Do goroutine should also be changed to the netns to complete any further actions on the link.

Via the LinkProviders, new links can be created, or already created links can be obtained via their name, index, or alias.

NEScript Integration

Using this package, NEScripts can be executed on any specific netns, making it easy to specify custom actions to execute via the NsAction system.

---

Motivation

Whilst the 2 packages referenced at the top of this doc for netlink and netns provide all this functionality and more, they are still somewhat low-level packages. This can result in programs that use them extensively needing a lot of wrapper code to make the provided functionality easier and safer to use. This package is that wrapper code.

---

🚧 WIP

• Add tests
• Run tests via actions