Home Original page

libnetwork package - github.com/docker/libnetwork - Go Packages

README

libnetwork - networking for containers

Circle CI Coverage Status GoDoc

Libnetwork provides a native Go implementation for connecting containers

The goal of libnetwork is to deliver a robust Container Network Model that provides a consistent programming interface and the required network abstractions for applications.

Design

Please refer to the design for more information.

Using libnetwork

There are many networking solutions available to suit a broad range of use-cases. libnetwork uses a driver / plugin model to support all of these solutions while abstracting the complexity of the driver implementations by exposing a simple and consistent Network Model to users.

func main() {
	if reexec.Init() {
		return
	}

	// Select and configure the network driver
	networkType := "bridge"

	// Create a new controller instance
	driverOptions := options.Generic{}
	genericOption := make(map[string]interface{})
	genericOption[netlabel.GenericData] = driverOptions
	controller, err := libnetwork.New(config.OptionDriverConfig(networkType, genericOption))
	if err != nil {
		log.Fatalf("libnetwork.New: %s", err)
	}

	// Create a network for containers to join.
	// NewNetwork accepts Variadic optional arguments that libnetwork and Drivers can use.
	network, err := controller.NewNetwork(networkType, "network1")
	if err != nil {
		log.Fatalf("controller.NewNetwork: %s", err)
	}

	// For each new container: allocate IP and interfaces. The returned network
	// settings will be used for container infos (inspect and such), as well as
	// iptables rules for port publishing. This info is contained or accessible
	// from the returned endpoint.
	ep, err := network.CreateEndpoint("Endpoint1")
	if err != nil {
		log.Fatalf("network.CreateEndpoint: %s", err)
	}

	// Create the sandbox for the container.
	// NewSandbox accepts Variadic optional arguments which libnetwork can use.
	sbx, err := controller.NewSandbox("container1",
		libnetwork.OptionHostname("test"),
		libnetwork.OptionDomainname("docker.io"))
	if err != nil {
		log.Fatalf("controller.NewSandbox: %s", err)
	}

	// A sandbox can join the endpoint via the join api.
	err = ep.Join(sbx)
	if err != nil {
		log.Fatalf("ep.Join: %s", err)
	}

	// libnetwork client can check the endpoint's operational data via the Info() API
	epInfo, err := ep.DriverInfo()
	if err != nil {
		log.Fatalf("ep.DriverInfo: %s", err)
	}

	macAddress, ok := epInfo[netlabel.MacAddress]
	if !ok {
		log.Fatalf("failed to get mac address from endpoint info")
	}

	fmt.Printf("Joined endpoint %s (%s) to sandbox %s (%s)\n", ep.Name(), macAddress, sbx.ContainerID(), sbx.Key())
}

Future

Please refer to roadmap for more information.

Contributing

Want to hack on libnetwork? Docker's contributions guidelines apply.

Code and documentation copyright 2015 Docker, inc. Code released under the Apache 2.0 license. Docs released under Creative commons.

Documentation

Package libnetwork provides the basic functionality and extension points to create network namespaces and allocate interfaces for containers to use. 

networkType := "bridge"

// Create a new controller instance
driverOptions := options.Generic{}
genericOption := make(map[string]interface{})
genericOption[netlabel.GenericData] = driverOptions
controller, err := libnetwork.New(config.OptionDriverConfig(networkType, genericOption))
if err != nil {
	return
}

// Create a network for containers to join.
// NewNetwork accepts Variadic optional arguments that libnetwork and Drivers can make use of
network, err := controller.NewNetwork(networkType, "network1")
if err != nil {
	return
}

// For each new container: allocate IP and interfaces. The returned network
// settings will be used for container infos (inspect and such), as well as
// iptables rules for port publishing. This info is contained or accessible
// from the returned endpoint.
ep, err := network.CreateEndpoint("Endpoint1")
if err != nil {
	return
}

// Create the sandbox for the container.
// NewSandbox accepts Variadic optional arguments which libnetwork can use.
sbx, err := controller.NewSandbox("container1",
	libnetwork.OptionHostname("test"),
	libnetwork.OptionDomainname("docker.io"))

// A sandbox can join the endpoint via the join api.
err = ep.Join(sbx)
if err != nil {
	return
}

This section is empty.

This section is empty.

SetExternalKey provides a convenient way to set an External key to a sandbox 

type ActiveContainerError struct {
	
}

ActiveContainerError is returned when an endpoint is deleted which has active containers attached to it. 

func (ace *ActiveContainerError) Forbidden()

Forbidden denotes the type of this error 

type ActiveEndpointsError struct {
	
}

ActiveEndpointsError is returned when a network is deleted which has active endpoints in it. 

func (aee *ActiveEndpointsError) Forbidden()

Forbidden denotes the type of this error

Endpoint represents a logical connection between a network and a sandbox.

EndpointInfo provides an interface to retrieve network resources bound to the endpoint. 

type EndpointOption func(ep *endpoint)

EndpointOption is a option setter function type used to pass varios options to Network and Endpoint interfaces methods. The various setter functions of type EndpointOption are provided by libnetwork, they look like <Create|Join|Leave>Option[...](...)

CreateOptionAlias function returns an option setter for setting endpoint alias 

func CreateOptionAnonymous() EndpointOption

CreateOptionAnonymous function returns an option setter for setting this endpoint as anonymous 

func CreateOptionDisableResolution() EndpointOption

CreateOptionDisableResolution function returns an option setter to indicate this endpoint doesn't want embedded DNS server functionality

CreateOptionExposedPorts function returns an option setter for the container exposed ports option to be passed to network.CreateEndpoint() method.

CreateOptionIpam function returns an option setter for the ipam configuration for this endpoint 

func CreateOptionMyAlias(alias string) EndpointOption

CreateOptionMyAlias function returns an option setter for setting endpoint's self alias

CreateOptionPortMapping function returns an option setter for the mapping ports option to be passed to network.CreateEndpoint() method. 

func EndpointOptionGeneric(generic map[string]interface{}) EndpointOption

EndpointOptionGeneric function returns an option setter for a Generic option defined in a Dictionary of Key-Value pair 

func JoinOptionPriority(ep Endpoint, prio int) EndpointOption

JoinOptionPriority function returns an option setter for priority option to be passed to the endpoint.Join() method. 

type EndpointWalker func(ep Endpoint) bool

EndpointWalker is a client provided function which will be used to walk the Endpoints. When the function returns true, the walk will stop. 

type ErrInvalidConfigFile string

ErrInvalidConfigFile type is returned when an invalid LibNetwork config file is detected

ErrInvalidID is returned when a query-by-id method is being invoked with an empty id parameter 

func (ii ErrInvalidID) BadRequest()

BadRequest denotes the type of this error 

type ErrInvalidJoin struct{}

ErrInvalidJoin is returned if a join is attempted on an endpoint which already has a container joined. 

func (ij ErrInvalidJoin) BadRequest()

BadRequest denotes the type of this error

ErrInvalidName is returned when a query-by-name or resource create method is invoked with an empty name parameter 

func (in ErrInvalidName) BadRequest()

BadRequest denotes the type of this error 

type ErrInvalidNetworkDriver string

ErrInvalidNetworkDriver is returned if an invalid driver name is passed. 

func (ind ErrInvalidNetworkDriver) BadRequest()

BadRequest denotes the type of this error 

type ErrNoContainer struct{}

ErrNoContainer is returned when the endpoint has no container attached to it. 

func (nc ErrNoContainer) Maskable()

Maskable denotes the type of this error

ErrNoSuchEndpoint is returned when a endpoint query finds no result 

func (nse ErrNoSuchEndpoint) NotFound()

NotFound denotes the type of this error

ErrNoSuchNetwork is returned when a network query finds no result 

func (nsn ErrNoSuchNetwork) NotFound()

NotFound denotes the type of this error

InterfaceInfo provides an interface to retrieve interface addresses bound to the endpoint. 

type InvalidContainerIDError string

InvalidContainerIDError is returned when an invalid container id is passed in Join/Leave 

func (id InvalidContainerIDError) BadRequest()

BadRequest denotes the type of this error

IpamConf contains all the ipam related configurations for a network

CopyTo deep copies to the destination IpamConfig

Validate checks whether the configuration is valid

IpamInfo contains all the ipam related operational info for a network

CopyTo deep copies to the destination IpamInfo

MarshalJSON encodes IpamInfo into json message

UnmarshalJSON decodes json message into PoolData

A Network represents a logical connectivity zone that containers may join using the Link method. A Network is managed by a specific driver.

NetworkController provides the interface for controller instance which manages networks.

New creates a new instance of network controller.

NetworkInfo returns some configuration and operational information about the network

NetworkNameError is returned when a network with the same name already exists. 

func (nnr NetworkNameError) Forbidden()

Forbidden denotes the type of this error 

type NetworkOption func(n *network)

NetworkOption is a option setter function type used to pass varios options to NewNetwork method. The various setter functions of type NetworkOption are provided by libnetwork, they look like NetworkOptionXXXX(...) 

func NetworkOptionDeferIPv6Alloc(enable bool) NetworkOption

NetworkOptionDeferIPv6Alloc instructs the network to defer the IPV6 address allocation until after the endpoint has been created It is being provided to support the specific docker daemon flags where user can deterministically assign an IPv6 address to a container as combination of fixed-cidr-v6 + mac-address TODO: Remove this option setter once we support endpoint ipam options

NetworkOptionDriverOpts function returns an option setter for any parameter described by a map 

func NetworkOptionGeneric(generic map[string]interface{}) NetworkOption

NetworkOptionGeneric function returns an option setter for a Generic option defined in a Dictionary of Key-Value pair 

func NetworkOptionInternalNetwork() NetworkOption

NetworkOptionInternalNetwork returns an option setter to config the network to be internal which disables default gateway service

NetworkOptionIpam function returns an option setter for the ipam configuration for this network 

func NetworkOptionPersist(persist bool) NetworkOption

NetworkOptionPersist returns an option setter to set persistence policy for a network

NetworkTypeError type is returned when the network type string is not known to libnetwork. 

func (nt NetworkTypeError) NotFound()

NotFound denotes the type of this error 

type NetworkWalker func(nw Network) bool

NetworkWalker is a client provided function which will be used to walk the Networks. When the function returns true, the walk will stop. 

type Resolver interface {
	
	Start() error
	
	
	Stop()
	
	
	SetupFunc() func()
	
	
	NameServer() string
	
	SetExtServers([]string)
	
	ResolverOptions() []string
}

Resolver represents the embedded DNS server in Docker. It operates by listening on container's loopback interface for DNS queries. 

func NewResolver(sb *sandbox) Resolver

NewResolver creates a new instance of the Resolver

type Sandbox

Sandbox provides the control over the network container entity. It is a one to one mapping with the container.

type SandboxOption 

type SandboxOption func(sb *sandbox)

SandboxOption is a option setter function type used to pass varios options to NewNetContainer method. The various setter functions of type SandboxOption are provided by libnetwork, they look like ContainerOptionXXXX(...)

OptionDNS function returns an option setter for dns entry option to be passed to container Create method. 

func OptionDNSOptions(options string) SandboxOption

OptionDNSOptions function returns an option setter for dns options entry option to be passed to container Create method.

OptionDNSSearch function returns an option setter for dns search entry option to be passed to container Create method.

func OptionDomainname

OptionDomainname function returns an option setter for domainname option to be passed to NewSandbox method.

OptionExtraHost function returns an option setter for extra /etc/hosts options which is a name and IP as strings. 

func OptionGeneric(generic map[string]interface{}) SandboxOption

OptionGeneric function returns an option setter for Generic configuration that is not managed by libNetwork but can be used by the Drivers during the call to net container creation method. Container Labels are a good example.

OptionHostname function returns an option setter for hostname option to be passed to NewSandbox method.

OptionHostsPath function returns an option setter for hostspath option to be passed to NewSandbox method. 

func OptionOriginHostsPath(path string) SandboxOption

OptionOriginHostsPath function returns an option setter for origin hosts file path tbeo passed to NewSandbox method. 

func OptionOriginResolvConfPath(path string) SandboxOption

OptionOriginResolvConfPath function returns an option setter to set the path to the origin resolv.conf file to be passed to net container methods.

OptionParentUpdate function returns an option setter for parent container which needs to update the IP address for the linked container. 

func OptionResolvConfPath(path string) SandboxOption

OptionResolvConfPath function returns an option setter for resolvconfpath option to be passed to net container methods.

func OptionUseDefaultSandbox 

func OptionUseDefaultSandbox() SandboxOption

OptionUseDefaultSandbox function returns an option setter for using default sandbox to be passed to container Create method. 

func OptionUseExternalKey() SandboxOption

OptionUseExternalKey function returns an option setter for using provided namespace instead of creating one.

type SandboxWalker 

type SandboxWalker func(sb Sandbox) bool

SandboxWalker is a client provided function which will be used to walk the Sandboxes. When the function returns true, the walk will stop.

func SandboxContainerWalker 

func SandboxContainerWalker(out *Sandbox, containerID string) SandboxWalker

SandboxContainerWalker returns a Sandbox Walker function which looks for an existing Sandbox with the passed containerID

func SandboxKeyWalker 

func SandboxKeyWalker(out *Sandbox, key string) SandboxWalker

SandboxKeyWalker returns a Sandbox Walker function which looks for an existing Sandbox with the passed key 

type UnknownEndpointError struct {
	
}

UnknownEndpointError is returned when libnetwork could not find in it's database an endpoint with the same name and id. 

func (uee *UnknownEndpointError) NotFound()

NotFound denotes the type of this error 

type UnknownNetworkError struct {
	
}

UnknownNetworkError is returned when libnetwork could not find in it's database a network with the same name and id. 

func (une *UnknownNetworkError) NotFound()

NotFound denotes the type of this error

Source Files

Directories

Path Synopsis

Godeps

_workspace/src/github.com/boltdb/bolt

Package bolt implements a low-level key/value store in pure Go.

 Package bolt implements a low-level key/value store in pure Go.

_workspace/src/github.com/codegangsta/cli

Package cli provides a minimal framework for creating and organizing command line Go applications.

 Package cli provides a minimal framework for creating and organizing command line Go applications.

_workspace/src/github.com/coreos/etcd/client

Package client provides bindings for the etcd APIs.

 Package client provides bindings for the etcd APIs.

_workspace/src/github.com/coreos/go-systemd/dbus

Integration with the systemd D-Bus API.

 Integration with the systemd D-Bus API.

_workspace/src/github.com/coreos/go-systemd/util

Package util contains utility functions related to systemd that applications can use to check things like whether systemd is running.

 Package util contains utility functions related to systemd that applications can use to check things like whether systemd is running.

_workspace/src/github.com/deckarep/golang-set

Package mapset implements a simple and generic set collection.

 Package mapset implements a simple and generic set collection.

_workspace/src/github.com/docker/docker/pkg/listenbuffer

Package listenbuffer uses the kernel's listening backlog functionality to queue connections, allowing applications to start listening immediately and handle connections later.

 Package listenbuffer uses the kernel's listening backlog functionality to queue connections, allowing applications to start listening immediately and handle connections later.

_workspace/src/github.com/docker/docker/pkg/parsers/kernel

Package kernel provides helper function to get, parse and compare kernel versions for different platforms.

 Package kernel provides helper function to get, parse and compare kernel versions for different platforms.

_workspace/src/github.com/docker/docker/pkg/plugins

Package plugins provides structures and helper functions to manage Docker plugins.

 Package plugins provides structures and helper functions to manage Docker plugins.

_workspace/src/github.com/docker/docker/pkg/proxy

Package proxy provides a network Proxy interface and implementations for TCP and UDP.

 Package proxy provides a network Proxy interface and implementations for TCP and UDP.

_workspace/src/github.com/docker/docker/pkg/signal

Package signal provides helper functions for dealing with signals across various operating systems.

 Package signal provides helper functions for dealing with signals across various operating systems.

_workspace/src/github.com/docker/docker/pkg/sockets

Package sockets provides helper functions to create and configure Unix or TCP sockets.

 Package sockets provides helper functions to create and configure Unix or TCP sockets.

_workspace/src/github.com/docker/docker/pkg/stringid

Package stringid provides helper functions for dealing with string identifiers

 Package stringid provides helper functions for dealing with string identifiers

_workspace/src/github.com/docker/docker/pkg/term

Package term provides provides structures and helper functions to work with terminal (state, sizes).

 Package term provides provides structures and helper functions to work with terminal (state, sizes).

_workspace/src/github.com/docker/docker/pkg/tlsconfig

Package tlsconfig provides primitives to retrieve secure-enough TLS configurations for both clients and servers.

 Package tlsconfig provides primitives to retrieve secure-enough TLS configurations for both clients and servers.

_workspace/src/github.com/docker/docker/pkg/ulimit

Package ulimit provides structure and helper function to parse and represent resource limits (Rlimit and Ulimit, its human friendly version).

 Package ulimit provides structure and helper function to parse and represent resource limits (Rlimit and Ulimit, its human friendly version).

_workspace/src/github.com/docker/docker/pkg/units

Package units provides helper function to parse and print size and time units in human-readable format.

 Package units provides helper function to parse and print size and time units in human-readable format.

_workspace/src/github.com/docker/go-units

Package units provides helper function to parse and print size and time units in human-readable format.

 Package units provides helper function to parse and print size and time units in human-readable format.

_workspace/src/github.com/godbus/dbus

Package dbus implements bindings to the D-Bus message bus system.

 Package dbus implements bindings to the D-Bus message bus system.

_workspace/src/github.com/godbus/dbus/introspect

Package introspect provides some utilities for dealing with the DBus introspection format.

 Package introspect provides some utilities for dealing with the DBus introspection format.

_workspace/src/github.com/godbus/dbus/prop

Package prop provides the Properties struct which can be used to implement org.freedesktop.DBus.Properties.

 Package prop provides the Properties struct which can be used to implement org.freedesktop.DBus.Properties.

_workspace/src/github.com/golang/protobuf/proto

Package proto converts data structures to and from the wire format of protocol buffers.

 Package proto converts data structures to and from the wire format of protocol buffers.

_workspace/src/github.com/gorilla/context

Package context stores values shared during a request lifetime.

 Package context stores values shared during a request lifetime.

_workspace/src/github.com/gorilla/mux

Package gorilla/mux implements a request router and dispatcher.

 Package gorilla/mux implements a request router and dispatcher.

_workspace/src/github.com/hashicorp/go-msgpack/codec

High Performance, Feature-Rich Idiomatic Go encoding library for msgpack and binc .

 High Performance, Feature-Rich Idiomatic Go encoding library for msgpack and binc .

_workspace/src/github.com/hashicorp/memberlist

memberlist is a library that manages cluster membership and member failure detection using a gossip based protocol.

 memberlist is a library that manages cluster membership and member failure detection using a gossip based protocol.

_workspace/src/github.com/miekg/dns

Package dns implements a full featured interface to the Domain Name System.

 Package dns implements a full featured interface to the Domain Name System.

_workspace/src/github.com/miekg/dns/idn

Package idn implements encoding from and to punycode as speficied by RFC 3492.

 Package idn implements encoding from and to punycode as speficied by RFC 3492.

_workspace/src/github.com/opencontainers/runc/libcontainer

Libcontainer provides a native Go implementation for creating containers with namespaces, cgroups, capabilities, and filesystem access controls.

 Libcontainer provides a native Go implementation for creating containers with namespaces, cgroups, capabilities, and filesystem access controls.

_workspace/src/github.com/opencontainers/runc/libcontainer/criurpc

Package criurpc is a generated protocol buffer package.

 Package criurpc is a generated protocol buffer package.

_workspace/src/github.com/opencontainers/runc/libcontainer/integration

integration is used for integration testing of libcontainer

 integration is used for integration testing of libcontainer

_workspace/src/github.com/seccomp/libseccomp-golang

Package seccomp rovides bindings for libseccomp, a library wrapping the Linux seccomp syscall.

 Package seccomp rovides bindings for libseccomp, a library wrapping the Linux seccomp syscall.

_workspace/src/github.com/stretchr/testify/assert

Package assert provides a set of comprehensive testing tools for use with the normal Go testing system.

 Package assert provides a set of comprehensive testing tools for use with the normal Go testing system.

_workspace/src/github.com/syndtr/gocapability/capability

Package capability provides utilities for manipulating POSIX capabilities.

 Package capability provides utilities for manipulating POSIX capabilities.

_workspace/src/github.com/ugorji/go/codec

High Performance, Feature-Rich Idiomatic Go codec/encoding library for binc, msgpack, cbor, json.

 High Performance, Feature-Rich Idiomatic Go codec/encoding library for binc, msgpack, cbor, json.

_workspace/src/github.com/ugorji/go/codec/codecgen command

codecgen generates codec.Selfer implementations for a set of types.

 codecgen generates codec.Selfer implementations for a set of types.

_workspace/src/github.com/vishvananda/netlink

Package netlink provides a simple library for netlink.

 Package netlink provides a simple library for netlink.

_workspace/src/github.com/vishvananda/netlink/nl

Package nl has low level primitives for making Netlink calls.

 Package nl has low level primitives for making Netlink calls.

_workspace/src/github.com/vishvananda/netns

Package netns allows ultra-simple network namespace handling.

 Package netns allows ultra-simple network namespace handling.

_workspace/src/golang.org/x/net/context

Package context defines the Context type, which carries deadlines, cancelation signals, and other request-scoped values across API boundaries and between processes.

 Package context defines the Context type, which carries deadlines, cancelation signals, and other request-scoped values across API boundaries and between processes.

Package bitseq provides a structure and utilities for representing long bitmask as sequence of run-lenght encoded blocks.

 Package bitseq provides a structure and utilities for representing long bitmask as sequence of run-lenght encoded blocks.

cmd

dnet command

ovrouter command

readme_test command

drivers

remote/api

Package api represents all requests and responses suitable for conversation with a remote driver.

 Package api represents all requests and responses suitable for conversation with a remote driver.

Package idm manages reservation/release of numerical ids from a configured set of contiguous ids

 Package idm manages reservation/release of numerical ids from a configured set of contiguous ids

Package ipamapi specifies the contract the IPAM service (built-in or remote) needs to satisfy.

 Package ipamapi specifies the contract the IPAM service (built-in or remote) needs to satisfy.

ipams

remote/api

Package api defines the data structure to be used in the request/response messages between libnetwork and the remote ipam plugin

 Package api defines the data structure to be used in the request/response messages between libnetwork and the remote ipam plugin

Package ipamutils provides utililty functions for ipam management Package ipamutils provides utililty functions for ipam management

 Package ipamutils provides utililty functions for ipam management Package ipamutils provides utililty functions for ipam management

Package options provides a way to pass unstructured sets of options to a component expecting a strongly-typed configuration structure.

 Package options provides a way to pass unstructured sets of options to a component expecting a strongly-typed configuration structure.

Package osl describes structures and interfaces which abstract os entities

 Package osl describes structures and interfaces which abstract os entities

Package resolvconf provides utility code to query and update DNS configuration in /etc/resolv.conf

 Package resolvconf provides utility code to query and update DNS configuration in /etc/resolv.conf

dns

Package types contains types that are common across libnetwork project

 Package types contains types that are common across libnetwork project