Version: v0.7.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Feb 14, 2018 License: Apache-2.0 Imports: 7 Imported by: 454


Namespaces, Threads, and Go

On Linux each OS thread can have a different network namespace. Go's thread scheduling model switches goroutines between OS threads based on OS thread load and whether the goroutine would block other goroutines. This can result in a goroutine switching network namespaces without notice and lead to errors in your code.

Namespace Switching

Switching namespaces with the ns.Set() method is not recommended without additional strategies to prevent unexpected namespace changes when your goroutines switch OS threads.

Go provides the runtime.LockOSThread() function to ensure a specific goroutine executes on its current OS thread and prevents any other goroutine from running in that thread until the locked one exits. Careful usage of LockOSThread() and goroutines can provide good control over which network namespace a given goroutine executes in.

For example, you cannot rely on the ns.Set() namespace being the current namespace after the Set() call unless you do two things. First, the goroutine calling Set() must have previously called LockOSThread(). Second, you must ensure runtime.UnlockOSThread() is not called somewhere in-between. You also cannot rely on the initial network namespace remaining the current network namespace if any other code in your program switches namespaces, unless you have already called LockOSThread() in that goroutine. Note that LockOSThread() prevents the Go scheduler from optimally scheduling goroutines for best performance, so LockOSThread() should only be used in small, isolated goroutines that release the lock quickly.

The ns.Do() method provides partial control over network namespaces for you by implementing these strategies. All code dependent on a particular network namespace (including the root namespace) should be wrapped in the ns.Do() method to ensure the correct namespace is selected for the duration of your code. For example:

targetNs, err := ns.NewNS()
if err != nil {
    return err
err = targetNs.Do(func(hostNs ns.NetNS) error {
	dummy := &netlink.Dummy{
		LinkAttrs: netlink.LinkAttrs{
			Name: "dummy0",
	return netlink.LinkAdd(dummy)

Note this requirement to wrap every network call is very onerous - any libraries you call might call out to network services such as DNS, and all such calls need to be protected after you call ns.Do(). The CNI plugins all exit very soon after calling ns.Do() which helps to minimize the problem.

Also: If the runtime spawns a new OS thread, it will inherit the network namespace of the parent thread, which may have been temporarily switched, and thus the new OS thread will be permanently "stuck in the wrong namespace".

In short, there is no safe way to change network namespaces from within a long-lived, multithreaded Go process. If your daemon process needs to be namespace aware, consider spawning a separate process (like a CNI plugin) for each namespace.

Further Reading




View Source
const (
	// https://github.com/torvalds/linux/blob/master/include/uapi/linux/magic.h
	NSFS_MAGIC   = 0x6e736673
	PROCFS_MAGIC = 0x9fa0


This section is empty.


func IsNSorErr added in v0.3.0

func IsNSorErr(nspath string) error

func WithNetNSPath

func WithNetNSPath(nspath string, toRun func(NetNS) error) error

WithNetNSPath executes the passed closure under the given network namespace, restoring the original namespace afterwards.


type NSPathNotExistErr added in v0.3.0

type NSPathNotExistErr struct {
	// contains filtered or unexported fields

func (NSPathNotExistErr) Error added in v0.3.0

func (e NSPathNotExistErr) Error() string

type NSPathNotNSErr added in v0.3.0

type NSPathNotNSErr struct {
	// contains filtered or unexported fields

func (NSPathNotNSErr) Error added in v0.3.0

func (e NSPathNotNSErr) Error() string

type NetNS added in v0.3.0

type NetNS interface {
	// Executes the passed closure in this object's network namespace,
	// attempting to restore the original namespace before returning.
	// However, since each OS thread can have a different network namespace,
	// and Go's thread scheduling is highly variable, callers cannot
	// guarantee any specific namespace is set unless operations that
	// require that namespace are wrapped with Do().  Also, no code called
	// from Do() should call runtime.UnlockOSThread(), or the risk
	// of executing code in an incorrect namespace will be greater.  See
	// https://github.com/golang/go/wiki/LockOSThread for further details.
	Do(toRun func(NetNS) error) error

	// Sets the current network namespace to this object's network namespace.
	// Note that since Go's thread scheduling is highly variable, callers
	// cannot guarantee the requested namespace will be the current namespace
	// after this function is called; to ensure this wrap operations that
	// require the namespace with Do() instead.
	Set() error

	// Returns the filesystem path representing this object's network namespace
	Path() string

	// Returns a file descriptor representing this object's network namespace
	Fd() uintptr

	// Cleans up this instance of the network namespace; if this instance
	// is the last user the namespace will be destroyed
	Close() error

func GetCurrentNS added in v0.3.0

func GetCurrentNS() (NetNS, error)

Returns an object representing the current OS thread's network namespace

func GetNS added in v0.3.0

func GetNS(nspath string) (NetNS, error)

Returns an object representing the namespace referred to by @path

func NewNS added in v0.3.0

func NewNS() (NetNS, error)

Creates a new persistent network namespace and returns an object representing that namespace, without switching to it

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL