network

README

Docker network extension API

Go handler to create external network extensions for Docker.

Usage

This library is designed to be integrated in your program.

1. Implement the network.Driver interface.
2. Initialize a network.Handler with your implementation.
3. Call either ServeTCP, ServeUnix or ServeWindows from the network.Handler.
4. On Windows, docker daemon data dir must be provided for ServeTCP and ServeWindows functions. On Unix, this parameter is ignored.

Example using TCP sockets:

  import "github.com/docker/go-plugins-helpers/network"

  d := MyNetworkDriver{}
  h := network.NewHandler(d)
  h.ServeTCP("test_network", ":8080", "")
  // on windows:
  h.ServeTCP("test_network", ":8080", WindowsDefaultDaemonRootDir())

Example using Unix sockets:

  import "github.com/docker/go-plugins-helpers/network"

  d := MyNetworkDriver{}
  h := network.NewHandler(d)
  h.ServeUnix("test_network", 0)

Example using Windows named pipes:

import "github.com/docker/go-plugins-helpers/network"
import "github.com/docker/go-plugins-helpers/sdk"

d := MyNetworkDriver{}
h := network.NewHandler(d)

config := sdk.WindowsPipeConfig{
  // open, read, write permissions for everyone 
  // (uses Windows Security Descriptor Definition Language)
  SecurityDescriptor: AllowServiceSystemAdmin,
  InBufferSize:       4096,
  OutBufferSize:      4096,
}

h.ServeWindows("//./pipe/testpipe", "test_network", WindowsDefaultDaemonRootDir(), &config)

Full example plugins

• docker-ovs-plugin - An Open vSwitch Networking Plugin

Documentation

Index

• Constants
• type AllocateNetworkRequest
• type AllocateNetworkResponse
• type CapabilitiesResponse
• type CreateEndpointRequest
• type CreateEndpointResponse
• type CreateNetworkRequest
• type DeleteEndpointRequest
• type DeleteNetworkRequest
• type DiscoveryNotification
• type Driver
• type EndpointInterface
• type ErrorResponse
  • func NewErrorResponse(msg string) *ErrorResponse
• type FreeNetworkRequest
• type Handler
  • func NewHandler(driver Driver) *Handler
• type IPAMData
• type InfoRequest
• type InfoResponse
• type InterfaceName
• type JoinRequest
• type JoinResponse
• type LeaveRequest
• type ProgramExternalConnectivityRequest
• type RevokeExternalConnectivityRequest
• type StaticRoute

Constants

const (

	// LocalScope is the correct scope response for a local scope driver
	LocalScope = `local`
	// GlobalScope is the correct scope response for a global scope driver
	GlobalScope = `global`
)

Types

type AllocateNetworkRequest

type AllocateNetworkRequest struct {
	// A network ID that remote plugins are expected to store for future
	// reference.
	NetworkID string

	// A free form map->object interface for communication of options.
	Options map[string]string

	// IPAMData contains the address pool information for this network
	IPv4Data, IPv6Data []IPAMData
}

AllocateNetworkRequest requests allocation of new network by manager

type AllocateNetworkResponse

type AllocateNetworkResponse struct {
	// A free form plugin specific string->string object to be sent in
	// CreateNetworkRequest call in the libnetwork agents
	Options map[string]string
}

AllocateNetworkResponse is the response to the AllocateNetworkRequest.

type CapabilitiesResponse

type CapabilitiesResponse struct {
	Scope             string
	ConnectivityScope string
}

CapabilitiesResponse returns whether or not this network is global or local

type CreateEndpointRequest

type CreateEndpointRequest struct {
	NetworkID  string
	EndpointID string
	Interface  *EndpointInterface
	Options    map[string]interface{}
}

CreateEndpointRequest is sent by the daemon when an endpoint should be created

type CreateEndpointResponse

type CreateEndpointResponse struct {
	Interface *EndpointInterface
}

CreateEndpointResponse is sent as a response to a CreateEndpointRequest

type CreateNetworkRequest

type CreateNetworkRequest struct {
	NetworkID string
	Options   map[string]interface{}
	IPv4Data  []*IPAMData
	IPv6Data  []*IPAMData
}

CreateNetworkRequest is sent by the daemon when a network needs to be created

type DeleteEndpointRequest

type DeleteEndpointRequest struct {
	NetworkID  string
	EndpointID string
}

DeleteEndpointRequest is sent by the daemon when an endpoint needs to be removed

type DeleteNetworkRequest

type DeleteNetworkRequest struct {
	NetworkID string
}

DeleteNetworkRequest is sent by the daemon when a network needs to be removed

type DiscoveryNotification

type DiscoveryNotification struct {
	DiscoveryType int
	DiscoveryData interface{}
}

DiscoveryNotification is sent by the daemon when a new discovery event occurs

type Driver

type Driver interface {
	GetCapabilities() (*CapabilitiesResponse, error)
	CreateNetwork(*CreateNetworkRequest) error
	AllocateNetwork(*AllocateNetworkRequest) (*AllocateNetworkResponse, error)
	DeleteNetwork(*DeleteNetworkRequest) error
	FreeNetwork(*FreeNetworkRequest) error
	CreateEndpoint(*CreateEndpointRequest) (*CreateEndpointResponse, error)
	DeleteEndpoint(*DeleteEndpointRequest) error
	EndpointInfo(*InfoRequest) (*InfoResponse, error)
	Join(*JoinRequest) (*JoinResponse, error)
	Leave(*LeaveRequest) error
	DiscoverNew(*DiscoveryNotification) error
	DiscoverDelete(*DiscoveryNotification) error
	ProgramExternalConnectivity(*ProgramExternalConnectivityRequest) error
	RevokeExternalConnectivity(*RevokeExternalConnectivityRequest) error
}

Driver represent the interface a driver must fulfill.

type EndpointInterface

type EndpointInterface struct {
	Address     string
	AddressIPv6 string
	MacAddress  string
}

EndpointInterface contains endpoint interface information

type ErrorResponse

type ErrorResponse struct {
	Err string
}

ErrorResponse is a formatted error message that libnetwork can understand

func NewErrorResponse

func NewErrorResponse(msg string) *ErrorResponse

NewErrorResponse creates an ErrorResponse with the provided message

type FreeNetworkRequest

type FreeNetworkRequest struct {
	// The ID of the network to be freed.
	NetworkID string
}

FreeNetworkRequest is the request to free allocated network in the manager

type Handler

type Handler struct {
	sdk.Handler
	// contains filtered or unexported fields
}

Handler forwards requests and responses between the docker daemon and the plugin.

func NewHandler

func NewHandler(driver Driver) *Handler

NewHandler initializes the request handler with a driver implementation.

type IPAMData

type IPAMData struct {
	AddressSpace string
	Pool         string
	Gateway      string
	AuxAddresses map[string]interface{}
}

IPAMData contains IPv4 or IPv6 addressing information

type InfoRequest

type InfoRequest struct {
	NetworkID  string
	EndpointID string
}

InfoRequest is send by the daemon when querying endpoint information

type InfoResponse

type InfoResponse struct {
	Value map[string]string
}

InfoResponse is endpoint information sent in response to an InfoRequest

type InterfaceName

type InterfaceName struct {
	SrcName   string
	DstPrefix string
}

InterfaceName consists of the name of the interface in the global netns and the desired prefix to be appended to the interface inside the container netns

type JoinRequest

type JoinRequest struct {
	NetworkID  string
	EndpointID string
	SandboxKey string
	Options    map[string]interface{}
}

JoinRequest is sent by the Daemon when an endpoint needs be joined to a network

type JoinResponse

type JoinResponse struct {
	InterfaceName         InterfaceName
	Gateway               string
	GatewayIPv6           string
	StaticRoutes          []*StaticRoute
	DisableGatewayService bool
}

JoinResponse is sent in response to a JoinRequest

type LeaveRequest

type LeaveRequest struct {
	NetworkID  string
	EndpointID string
}

LeaveRequest is send by the daemon when a endpoint is leaving a network

type ProgramExternalConnectivityRequest

type ProgramExternalConnectivityRequest struct {
	NetworkID  string
	EndpointID string
	Options    map[string]interface{}
}

ProgramExternalConnectivityRequest specifies the L4 data and the endpoint for which programming has to be done

type RevokeExternalConnectivityRequest

type RevokeExternalConnectivityRequest struct {
	NetworkID  string
	EndpointID string
}

RevokeExternalConnectivityRequest specifies the endpoint for which the L4 programming has to be removed

type StaticRoute

type StaticRoute struct {
	Destination string
	RouteType   int
	NextHop     string
}

StaticRoute contains static route information