internal

Documentation

Index

• Variables
• func ParsePrefix(prefix string) (netaddr.IPPrefix, error)
• func UnloadDispatcher(netnsPath, bpfFsPath string) error
• func UpgradeDispatcher(netnsPath, bpfFsPath string) (ebpf.ProgramID, error)
• type Binding
  • func NewBinding(label string, proto Protocol, prefix string, port uint16) (*Binding, error)
  • func (b *Binding) String() string
• type Bindings
  • func (sb Bindings) Len() int
  • func (sb Bindings) Less(i, j int) bool
  • func (sb Bindings) Swap(i, j int)
• type Collector
  • func NewCollector(logger log.Logger, netnsPath, bpfFsPath string) *Collector
  • func (c *Collector) Collect(ch chan<- prometheus.Metric)
  • func (c *Collector) Describe(ch chan<- *prometheus.Desc)
• type Destination
  • func (dest *Destination) String() string
• type DestinationMetrics
  • func (dm *DestinationMetrics) TotalErrors() uint64
• type Dispatcher
  • func CreateDispatcher(netnsPath, bpfFsPath string) (_ *Dispatcher, err error)
  • func OpenDispatcher(netnsPath, bpfFsPath string, readOnly bool) (_ *Dispatcher, err error)
  • func (d *Dispatcher) AddBinding(bind *Binding) error
  • func (d *Dispatcher) Bindings() (Bindings, error)
  • func (d *Dispatcher) Close() error
  • func (d *Dispatcher) Destinations() ([]Destination, map[Destination]SocketCookie, error)
  • func (d *Dispatcher) Metrics() (*Metrics, error)
  • func (dp *Dispatcher) Program() (*ebpf.Program, error)
  • func (d *Dispatcher) RegisterSocket(label string, conn syscall.Conn) (dest *Destination, created bool, _ error)
  • func (d *Dispatcher) RemoveBinding(bind *Binding) error
  • func (d *Dispatcher) ReplaceBindings(bindings Bindings) (added, removed Bindings, _ error)
  • func (d *Dispatcher) UnregisterSocket(label string, domain Domain, proto Protocol) error
• type Domain
  • func (d Domain) String() string
  • func (d *Domain) UnmarshalText(text []byte) error
• type Metrics
• type Protocol
  • func (p Protocol) String() string
  • func (p *Protocol) UnmarshalText(text []byte) error
• type SocketCookie
  • func (c SocketCookie) String() string

Variables

var (
	ErrLoaded            = errors.New("dispatcher already loaded")
	ErrNotLoaded         = errors.New("dispatcher not loaded")
	ErrNotSocket         = syscall.ENOTSOCK
	ErrBadSocketDomain   = syscall.EPFNOSUPPORT
	ErrBadSocketType     = syscall.ESOCKTNOSUPPORT
	ErrBadSocketProtocol = syscall.EPROTONOSUPPORT
	ErrBadSocketState    = syscall.EBADFD
)

Errors returned by the Dispatcher.

var CreateCapabilities = []cap.Value{cap.SYS_ADMIN, cap.NET_ADMIN}

CreateCapabilities are required to create a new dispatcher.

Functions

func ParsePrefix

func ParsePrefix(prefix string) (netaddr.IPPrefix, error)

ParsePrefix parses a prefix with an optional mask into an IPPrefix.

A missing prefix is interpreted as a /128 or /32.

func UnloadDispatcher

func UnloadDispatcher(netnsPath, bpfFsPath string) error

UnloadDispatcher removes a dispatcher and its associated state.

Returns ErrNotLoaded if the dispatcher state directory doesn't exist.

func UpgradeDispatcher

func UpgradeDispatcher(netnsPath, bpfFsPath string) (ebpf.ProgramID, error)

UpgradeDispatcher updates the datapath program for the given dispatcher.

It doesn't remove old unused state.

Returns the program ID of the new dispatcher or an error.

Types

type Binding

type Binding struct {
	Label    string
	Protocol Protocol
	Prefix   netaddr.IPPrefix
	Port     uint16
}

A Binding selects which packets to redirect.

You have to add a Binding to a Dispatcher for it to take effect.

func NewBinding

func NewBinding(label string, proto Protocol, prefix string, port uint16) (*Binding, error)

NewBinding creates a new binding.

prefix may either be in CIDR notation (::1/128) or a plain IP address. Specifying ::1 is equivalent to passing ::1/128.

func (*Binding) String

func (b *Binding) String() string

type Bindings

type Bindings []*Binding

Bindings is a list of bindings.

They may be sorted using sort.Sort in the order of precedence used by the data plane, with the most specific binding at the start of the list.

func (Bindings) Len

func (sb Bindings) Len() int

func (Bindings) Less

func (sb Bindings) Less(i, j int) bool

func (Bindings) Swap

func (sb Bindings) Swap(i, j int)

type Collector

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

Collector exposes metrics from a Dispatcher in the Prometheus format.

func NewCollector

func NewCollector(logger log.Logger, netnsPath, bpfFsPath string) *Collector

func (*Collector) Collect

func (c *Collector) Collect(ch chan<- prometheus.Metric)

Collect implements prometheus.Collector.

func (*Collector) Describe

func (c *Collector) Describe(ch chan<- *prometheus.Desc)

Describe implements prometheus.Collector.

type Destination

type Destination struct {
	Label    string
	Domain   Domain
	Protocol Protocol
}

A Destination receives traffic from a Binding.

It is implicitly created when registering a socket with a Dispatcher.

func (*Destination) String

func (dest *Destination) String() string

type DestinationMetrics

type DestinationMetrics struct {
	// Total number of times traffic matched a destination.
	Lookups uint64
	// Total number of failed lookups since no socket was registered.
	Misses uint64
	// Total number of failed lookups since the socket was incompatible
	// with the incoming traffic.
	ErrorBadSocket uint64
}

func (*DestinationMetrics) TotalErrors

func (dm *DestinationMetrics) TotalErrors() uint64

TotalErrors sums all errors.

type Dispatcher

type Dispatcher struct {
	Path string
	// contains filtered or unexported fields
}

Dispatcher manipulates the socket dispatch data plane.

func CreateDispatcher

func CreateDispatcher(netnsPath, bpfFsPath string) (_ *Dispatcher, err error)

CreateDispatcher loads the dispatcher into a network namespace.

Returns ErrLoaded if the namespace already has the dispatcher enabled.

func OpenDispatcher

func OpenDispatcher(netnsPath, bpfFsPath string, readOnly bool) (_ *Dispatcher, err error)

OpenDispatcher loads an existing dispatcher from a namespace.

Returns ErrNotLoaded if the dispatcher is not loaded yet.

func (*Dispatcher) AddBinding

func (d *Dispatcher) AddBinding(bind *Binding) error

AddBinding redirects traffic for a given protocol, prefix and port to a label.

Traffic for the binding is dropped by the data plane if no matching destination exists.

func (*Dispatcher) Bindings

func (d *Dispatcher) Bindings() (Bindings, error)

Bindings lists known bindings.

func (*Dispatcher) Close

func (d *Dispatcher) Close() error

Close frees associated resources.

It does not remove the dispatcher, see UnloadDispatcher.

func (*Dispatcher) Destinations

func (d *Dispatcher) Destinations() ([]Destination, map[Destination]SocketCookie, error)

Destinations returns a set of existing destinations, i.e. sockets and labels.

func (*Dispatcher) Metrics

func (d *Dispatcher) Metrics() (*Metrics, error)

Metrics returns current counters from the data plane.

func (*Dispatcher) Program

func (dp *Dispatcher) Program() (*ebpf.Program, error)

Program returns the active dispatcher program.

The caller must call Program.Close().

func (*Dispatcher) RegisterSocket

func (d *Dispatcher) RegisterSocket(label string, conn syscall.Conn) (dest *Destination, created bool, _ error)

Returns the Destination with which the socket was registered, and a boolean indicating whether the Destination was created or updated, or an error.

func (*Dispatcher) RemoveBinding

func (d *Dispatcher) RemoveBinding(bind *Binding) error

RemoveBinding stops redirecting traffic for a given protocol, prefix and port.

Returns an error if the binding doesn't exist.

func (*Dispatcher) ReplaceBindings

func (d *Dispatcher) ReplaceBindings(bindings Bindings) (added, removed Bindings, _ error)

ReplaceBindings changes the currently active bindings to a new set.

It is conceptually identical to repeatedly calling AddBinding and RemoveBinding and therefore not atomic: the function may return without applying all changes.

Returns a boolean indicating whether any changes were made.

func (*Dispatcher) UnregisterSocket

func (d *Dispatcher) UnregisterSocket(label string, domain Domain, proto Protocol) error

type Domain

type Domain uint8

const (
	AF_INET  Domain = unix.AF_INET
	AF_INET6 Domain = unix.AF_INET6
)

func (Domain) String

func (d Domain) String() string

func (*Domain) UnmarshalText

func (d *Domain) UnmarshalText(text []byte) error

type Metrics

type Metrics struct {
	Destinations map[Destination]DestinationMetrics
	Bindings     map[Destination]uint64
	Sockets      map[Destination]uint8
}

Metrics contain counters generated by the data plane.

type Protocol

type Protocol uint8

const (
	TCP Protocol = unix.IPPROTO_TCP
	UDP Protocol = unix.IPPROTO_UDP
)

Valid protocols.

func (Protocol) String

func (p Protocol) String() string

func (*Protocol) UnmarshalText

func (p *Protocol) UnmarshalText(text []byte) error

type SocketCookie

type SocketCookie uint64

func (SocketCookie) String

func (c SocketCookie) String() string