neslink

README

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

Documentation

Index

• Constants
• func Do(nsP NsProvider, actions ...Action) error
• type Action
• type LinkAction
  • func LAAddAddr(provider LinkProvider, cidr string) LinkAction
  • func LADelAddr(provider LinkProvider, cidr string) LinkAction
  • func LADelete(provider LinkProvider) LinkAction
  • func LAGeneric(actionName string, provider LinkProvider, function func() error) LinkAction
  • func LANewBridge(name string) LinkAction
  • func LANewDummy(name string) LinkAction
  • func LANewGRETap(name, localIP, remoteIP string) LinkAction
  • func LANewVeth(name, peerName string) LinkAction
  • func LANewVxlan(name, localIP, groupIP string, id, port int) LinkAction
  • func LANewWireguard(name string) LinkAction
  • func LASetAlias(provider LinkProvider, alias string) LinkAction
  • func LASetDown(provider LinkProvider) LinkAction
  • func LASetHw(provider LinkProvider, addr string) LinkAction
  • func LASetName(provider LinkProvider, name string) LinkAction
  • func LASetPromiscOff(provider LinkProvider) LinkAction
  • func LASetPromiscOn(provider LinkProvider) LinkAction
  • func LASetUp(provider LinkProvider) LinkAction
  • func (la LinkAction) ActionName() string
• type LinkProvider
  • func LPAlias(alias string) LinkProvider
  • func LPIndex(index int) LinkProvider
  • func LPName(name string) LinkProvider
  • func (lp LinkProvider) Provide() (netlink.Link, error)
• type Namespace
  • func (ns Namespace) Exists() bool
  • func (n Namespace) String() string
• type NsAction
  • func NADeleteNamed(name string) NsAction
  • func NADeleteNamedAt(mountdir, name string) NsAction
  • func NAExecNescript(script nescript.Script, subcommand []string, process *nescript.Process) NsAction
  • func NAGeneric(name string, function func() error) NsAction
  • func NAGetLink(provider LinkProvider, link *netlink.Link) NsAction
  • func NAGetNsFd(nsfd *NsFd) NsAction
  • func NALinks(links *[]netlink.Link) NsAction
  • func NANewNs(name string) NsAction
  • func NANewNsAt(mountdir, name string) NsAction
  • func NASetLinkNs(lP LinkProvider, nsP NsProvider) NsAction
• type NsFd
  • func (n NsFd) Int() int
  • func (n NsFd) Valid() bool
• type NsProvider
  • func NPGeneric(providerName string, function func() (Namespace, error)) NsProvider
  • func NPName(name string) NsProvider
  • func NPNameAt(mountdir, name string) NsProvider
  • func NPNow() NsProvider
  • func NPPath(path string) NsProvider
  • func NPProcess(pid int) NsProvider
  • func NPThread(pid, tid int) NsProvider
  • func (nsp NsProvider) Provide() (Namespace, error)

Constants

const (
	NsFdNone         NsFd   = NsFd(-1)
	DefaultMountPath string = "/run/netns"
)

Functions

func Do

func Do(nsP NsProvider, actions ...Action) error

Do executes a given set of actions in a specified network namespace. It does so in a separate OS thread in order to allow the rest of the program to continue on the current network namespace. An error is returned if any netns move fails or any provided action fails. Do note that if the spawned system thread fails to be reverted to the network namespace of the caller, the thread is considered dirty and is never unlocked (thus can not be reused).

Types

type Action

type Action interface {
	// contains filtered or unexported methods
}

Action represents an entity that has a name and some function (act) that can return an error.

type LinkAction

type LinkAction struct {
	// contains filtered or unexported fields
}

LinkAction is a singular operation that can be performed on a generic netlink link. Actions have a name as to identify individual actions when passed as a set to a LinkDo call, providing more contextual errors. They also have a function that take a link as a parameter. When called, the function will perform the operation on the provided link, returning an error if any occurred. These do support being executed outside of LinkDo calls, but using LinkDo is still recommended.

func LAAddAddr

func LAAddAddr(provider LinkProvider, cidr string) LinkAction

func LADelAddr

func LADelAddr(provider LinkProvider, cidr string) LinkAction

func LADelete

func LADelete(provider LinkProvider) LinkAction

LADelete will simply delete the link when the action is executed. For obvious reasons this should be at the end of any LinkDo call (since the link will be deleted, further actions will error).

func LAGeneric

func LAGeneric(actionName string, provider LinkProvider, function func() error) LinkAction

LAGeneric allows for a custom LinkAction to be created and then used in a LinkDo call.

func LANewBridge

func LANewBridge(name string) LinkAction

LANewBridge creates a new bridge with the given name.

func LANewDummy

func LANewDummy(name string) LinkAction

LANewDummy creates a new dummy link with the given name.

func LANewGRETap

func LANewGRETap(name, localIP, remoteIP string) LinkAction

LANewGRETap creates a new gretap device with the given name, local IP, and remoteIP.

func LANewVeth

func LANewVeth(name, peerName string) LinkAction

LANewVeth will create a new veth pair. The names for both the new interfaces (main link and peer) should be provided.

func LANewVxlan

func LANewVxlan(name, localIP, groupIP string, id, port int) LinkAction

LANewVxlan creates a new vxlan link with the given configuration.

func LANewWireguard

func LANewWireguard(name string) LinkAction

LANewWireguard creates a new wireguard link with the given name. Further setup of this link should be done in custom LinkActions with wireguard specifc code.

func LASetAlias

func LASetAlias(provider LinkProvider, alias string) LinkAction

func LASetDown

func LASetDown(provider LinkProvider) LinkAction

func LASetHw

func LASetHw(provider LinkProvider, addr string) LinkAction

func LASetName

func LASetName(provider LinkProvider, name string) LinkAction

func LASetPromiscOff

func LASetPromiscOff(provider LinkProvider) LinkAction

func LASetPromiscOn

func LASetPromiscOn(provider LinkProvider) LinkAction

func LASetUp

func LASetUp(provider LinkProvider) LinkAction

func (LinkAction) ActionName

func (la LinkAction) ActionName() string

ActionName returns the name associated with the given link action.

type LinkProvider

type LinkProvider struct {
	// contains filtered or unexported fields
}

func LPAlias

func LPAlias(alias string) LinkProvider

LPAlias creates a link provider that when called, will provide the pre-existing link with the given alias (in the namespace this is called in). If no matches are found, an error is returned.

func LPIndex

func LPIndex(index int) LinkProvider

LPIndex creates a link provider that when called, will provide the pre-existing link with the given index (in the namespace this is called in). If no matches are found, an error is returned.

func LPName

func LPName(name string) LinkProvider

LPName creates a link provider that when called, will provide the pre-existing link with the given name (in the namespace this is called in). If no matches are found, an error is returned.

func (LinkProvider) Provide

func (lp LinkProvider) Provide() (netlink.Link, error)

Provide determines the network namespace path based on the provider's conditions. Since some conditions are collected at the time of the provider's creation and others when this function is called, repeat calls are not always expected to produce the same result. Also note, the path is only returned, not opened.

type Namespace

type Namespace string

Namespace is a path to a file associated with a network namespace.

func (Namespace) Exists

func (ns Namespace) Exists() bool

Exists determines if the path used for the namespace exists. Whilst not an exhaustive check, this can help debug namespace providers.

func (Namespace) String

func (n Namespace) String() string

String returns the Namespace file path as a string.

type NsAction

type NsAction struct {
	// contains filtered or unexported fields
}

NsAction represents an action that should be executed in a namespace via NsDo. The action should have a relevant name as to give context to errors (as multiple actions are executed in a single NsDo call). Also the action itself should be a function that takes no parameters and returns an error (or nil in the event of success). Also noteworthy, if an action function executes logic in any other goroutines (either my channel interaction or spawning a new goroutine), that logic will not be executed within the expected network namespace.

func NADeleteNamed

func NADeleteNamed(name string) NsAction

NADeleteNamed when executed removes the named netns if it exists. Importantly, the netns is not removed until the tread exists (at the end of the do call).

func NADeleteNamedAt

func NADeleteNamedAt(mountdir, name string) NsAction

NADeleteNamedAt when executed removes the named netns if it exists. Importantly, the netns is not removed until the tread exists (at the end of the do call).

func NAExecNescript

func NAExecNescript(script nescript.Script, subcommand []string, process *nescript.Process) NsAction

NAExecNescript will execute a NEScript in the netns it is called in, most likely the netns of the wrapping NsDo. This opens up extensive custom options. Provided should be the already compiled NEScript, a subcommand to use for the script such as ["sh" "-c"] (or nil to use the nescript package's deafult), and a nescript.Process for the resulting process to be stored in.

func NAGeneric

func NAGeneric(name string, function func() error) NsAction

NAGeneric allows for a custom action (function) to be performed in a given network namespace. A name should be given to describe the custom function in a couple of words to give context to NsDo errors.

func NAGetLink

func NAGetLink(provider LinkProvider, link *netlink.Link) NsAction

NAGetLink gets a specific link from the given link provider when the action is called. The result is stored within the given link parameter. An error is returned if any occurred.

func NAGetNsFd

func NAGetNsFd(nsfd *NsFd) NsAction

NAGetNsFd provides an open file descriptor for the network namespace it is called in. This fd is separate from that of the one in the enclosing NsDo, so it is up to the user to close the fd when it is no longer needed.

func NALinks

func NALinks(links *[]netlink.Link) NsAction

NALinks returns a list of all the links in the namespace obtained via the given provider. Any errors are returned and a boolean to express if the the network namespace has returned back to the origin successfully.

func NANewNs

func NANewNs(name string) NsAction

NANewNs will create a new network namespace and bind it to a named file. Any action that is performed after this action executes successfully will be executed within the new netns.

func NANewNsAt

func NANewNsAt(mountdir, name string) NsAction

NANewNsAt will create a new network namespace and bind it to a named file in a given directory. Note that this will likely result in the netns not being visible in the iproute command line. Any action that is performed after this action executes successfully will be executed within the new netns.

func NASetLinkNs

func NASetLinkNs(lP LinkProvider, nsP NsProvider) NsAction

NASetLinkNs moves a link provided by the given link provider to the namespace provided by the ns provider. The link itself should br present in the namespace in which the wrapping NsDo is set to execute in.

type NsFd

type NsFd int

NsFd is a file descriptor for an open Namespace file.

func (NsFd) Int

func (n NsFd) Int() int

Int returns the Namespace file descriptor as an int.

func (NsFd) Valid

func (n NsFd) Valid() bool

Valid determines if the file descriptor is valid. This can be used to determine if a returned NsFd is ok regardless of the error.

type NsProvider

type NsProvider struct {
	// contains filtered or unexported fields
}

NsProvider offers a approach to obtaining network namespace paths based on given conditions.

func NPGeneric

func NPGeneric(providerName string, function func() (Namespace, error)) NsProvider

NPGeneric provides the means to create custom providers. See the docker provider for an example of this.

func NPName

func NPName(name string) NsProvider

NPName returns a netns provider that provides the netns path for a named (mounted) netns. This assumes the ns is mounted in the default location.

func NPNameAt

func NPNameAt(mountdir, name string) NsProvider

NPNameAt returns a netns provider that provides the netns path for a named (mounted) netns.

func NPNow

func NPNow() NsProvider

NPNow returns a netns provider that provides the netns path for the process/thread that calls the Provide function.

func NPPath

func NPPath(path string) NsProvider

NPPath returns a netns provider that provides the netns path based on the path given.

func NPProcess

func NPProcess(pid int) NsProvider

NPProcess returns a netns provider that provides the netns path for the process associated with the given process ID.

func NPThread

func NPThread(pid, tid int) NsProvider

NPThread returns a netns provider that provides the netns path for the process associated with the given process and thread ID.

func (NsProvider) Provide

func (nsp NsProvider) Provide() (Namespace, error)

Provide determines the network namespace path based on the provider's conditions. Since some conditions are collected at the time of the provider's creation and others when this function is called, repeat calls are not always expected to produce the same result. Also note, the path is only returned, not opened.