netns

README

netns - network namespaces in go

The netns package provides an ultra-simple interface for handling network namespaces in go. Changing namespaces requires elevated privileges, so in most cases this code needs to be run as root.

Local Build and Test

You can use go get command:

go get github.com/vishvananda/netns

Testing (requires root):

sudo -E go test github.com/vishvananda/netns

Example

package main

import (
    "fmt"
    "net"
    "runtime"

    "github.com/vishvananda/netns"
)

func main() {
    // Lock the OS Thread so we don't accidentally switch namespaces
    runtime.LockOSThread()
    defer runtime.UnlockOSThread()

    // Save the current network namespace
    origns, _ := netns.Get()
    defer origns.Close()

    // Create a new network namespace
    newns, _ := netns.New()
    defer newns.Close()

    // Do something with the network namespace
    ifaces, _ := net.Interfaces()
    fmt.Printf("Interfaces: %v\n", ifaces)

    // Switch back to the original namespace
    netns.Set(origns)
}

Documentation

Overview

Package netns allows ultra-simple network namespace handling. NsHandles can be retrieved and set. Note that the current namespace is thread local so actions that set and reset namespaces should use LockOSThread to make sure the namespace doesn't change due to a goroutine switch. It is best to close NsHandles when you are done with them. This can be accomplished via a `defer ns.Close()` on the handle. Changing namespaces requires elevated privileges, so in most cases this code needs to be run as root.

Index

• Constants
• func DeleteNamed(name string) error
• func Set(ns NsHandle) error
• func Setns(ns NsHandle, nstype int) error
• type NsHandle
  • func Get() (NsHandle, error)
  • func GetFromDocker(id string) (NsHandle, error)
  • func GetFromName(name string) (NsHandle, error)
  • func GetFromPath(path string) (NsHandle, error)
  • func GetFromPid(pid int) (NsHandle, error)
  • func GetFromThread(pid, tid int) (NsHandle, error)
  • func New() (NsHandle, error)
  • func NewNamed(name string) (NsHandle, error)
  • func None() NsHandle
  • func (ns *NsHandle) Close() error
  • func (ns NsHandle) Equal(other NsHandle) bool
  • func (ns NsHandle) IsOpen() bool
  • func (ns NsHandle) String() string
  • func (ns NsHandle) UniqueId() string

Constants

const (
	CLONE_NEWUTS  = unix.CLONE_NEWUTS  /* New utsname group? */
	CLONE_NEWIPC  = unix.CLONE_NEWIPC  /* New ipcs */
	CLONE_NEWUSER = unix.CLONE_NEWUSER /* New user namespace */
	CLONE_NEWPID  = unix.CLONE_NEWPID  /* New pid namespace */
	CLONE_NEWNET  = unix.CLONE_NEWNET  /* New network namespace */
	CLONE_IO      = unix.CLONE_IO      /* Get io context */
)

Deprecated: use golang.org/x/sys/unix pkg instead.

Functions

func DeleteNamed

func DeleteNamed(name string) error

DeleteNamed deletes a named network namespace

func Set

func Set(ns NsHandle) error

Set sets the current network namespace to the namespace represented by NsHandle.

func Setns

func Setns(ns NsHandle, nstype int) error

Setns sets namespace using golang.org/x/sys/unix.Setns.

Deprecated: Use golang.org/x/sys/unix.Setns instead.

Types

type NsHandle

type NsHandle int

NsHandle is a handle to a network namespace. It can be cast directly to an int and used as a file descriptor.

func Get

func Get() (NsHandle, error)

Get gets a handle to the current threads network namespace.

func GetFromDocker

func GetFromDocker(id string) (NsHandle, error)

GetFromDocker gets a handle to the network namespace of a docker container. Id is prefixed matched against the running docker containers, so a short identifier can be used as long as it isn't ambiguous.

func GetFromName

func GetFromName(name string) (NsHandle, error)

GetFromName gets a handle to a named network namespace such as one created by `ip netns add`.

func GetFromPath

func GetFromPath(path string) (NsHandle, error)

GetFromPath gets a handle to a network namespace identified by the path

func GetFromPid

func GetFromPid(pid int) (NsHandle, error)

GetFromPid gets a handle to the network namespace of a given pid.

func GetFromThread

func GetFromThread(pid, tid int) (NsHandle, error)

GetFromThread gets a handle to the network namespace of a given pid and tid.

func New

func New() (NsHandle, error)

New creates a new network namespace, sets it as current and returns a handle to it.

func NewNamed

func NewNamed(name string) (NsHandle, error)

NewNamed creates a new named network namespace, sets it as current, and returns a handle to it

func None

func None() NsHandle

None gets an empty (closed) NsHandle.

func (*NsHandle) Close

func (ns *NsHandle) Close() error

Close closes the NsHandle and resets its file descriptor to -1. It is not safe to use an NsHandle after Close() is called.

func (NsHandle) Equal

func (ns NsHandle) Equal(other NsHandle) bool

Equal determines if two network handles refer to the same network namespace. This is done by comparing the device and inode that the file descriptors point to.

func (NsHandle) IsOpen

func (ns NsHandle) IsOpen() bool

IsOpen returns true if Close() has not been called.

func (NsHandle) String

func (ns NsHandle) String() string

String shows the file descriptor number and its dev and inode.

func (NsHandle) UniqueId

func (ns NsHandle) UniqueId() string

UniqueId returns a string which uniquely identifies the namespace associated with the network handle.