ipvs

README

ipvs

Package ipvs provides programmatic access to Linux's IPVS to manage services and destinations using the netlink and genetlink packages. This package can be used in environment without the ipvsadm tool, and in programs compiled without CGO.

Usage examples can be found in the Go Reference.

Documentation

Overview

Package ipvs provides access to Linux's IPVS kernel service via netlink.

Example

package main

import (
	"log"

	"github.com/cloudflare/ipvs"
)

func main() {
	c, err := ipvs.New()
	if err != nil {
		log.Fatalf("error updating service: %v", err)
	}

	services, err := c.Services()
	if err != nil {
		log.Fatalf("error fetching services: %v", err)
	}

	for _, svc := range services {
		log.Printf("%s:%d/%s %s", svc.Address, svc.Port, svc.Protocol, svc.Scheduler)
		svc.Scheduler = "rr"

		err := c.UpdateService(svc.Service)
		if err != nil {
			log.Fatalf("error updating service: %v", err)
		}
	}
}

Index

• Constants
• type AddressFamily
  • func (i AddressFamily) String() string
• type Client
  • func New() (Client, error)
• type Destination
• type DestinationExtended
• type Flags
  • func (i Flags) String() string
• type ForwardType
  • func (i ForwardType) String() string
• type Info
• type Protocol
  • func (i Protocol) String() string
• type Service
• type ServiceExtended
• type Stats
• type TunnelFlags
  • func (i TunnelFlags) String() string
• type TunnelType
  • func (i TunnelType) String() string
• Bugs

Examples

• Package

Constants

const Masquarade = Masquerade

Deprecated: This constant is a misspelling of "Masquerade".

Types

type AddressFamily

type AddressFamily uint16

AddressFamily determines if the Service or Destination is configured to use IPv4 or IPv6 family.

const (
	INET  AddressFamily = 0x2
	INET6 AddressFamily = 0xA
)

Address families known to IPVS.

func (AddressFamily) String

func (i AddressFamily) String() string

type Client

type Client interface {
	Info() (Info, error)

	Services() ([]ServiceExtended, error)
	Service(Service) (ServiceExtended, error)
	CreateService(Service) error
	UpdateService(Service) error
	RemoveService(Service) error

	Destinations(Service) ([]DestinationExtended, error)
	CreateDestination(Service, Destination) error
	UpdateDestination(Service, Destination) error
	RemoveDestination(Service, Destination) error
}

Client represents an opaque IPVS client. This would most commonly be connected to IPVS running on the same machine, but may represent a connection to a broker on another machine.

func New

func New() (Client, error)

New returns an instance of Client.

type Destination

type Destination struct {
	Address        netip.Addr
	FwdMethod      ForwardType
	Weight         uint32
	UpperThreshold uint32
	LowerThreshold uint32
	Port           uint16
	Family         AddressFamily
	TunnelType     TunnelType
	TunnelPort     uint16
	TunnelFlags    TunnelFlags
}

Destination represents a connection to the real server.

type DestinationExtended

type DestinationExtended struct {
	Destination
	ActiveConnections     uint32
	InactiveConnections   uint32
	PersistentConnections uint32
	Stats                 Stats
	Stats64               Stats
}

DestinationExtended contains fields that are not neccesarry for comparison of the identity of a Destination.

type Flags

type Flags uint32

Flags tweak the behavior of a virtual service, and the chosen scheduler.

const (
	ServicePersistent    Flags = 0x0001
	ServiceHashed        Flags = 0x0002
	ServiceOnePacket     Flags = 0x0004
	ServiceSchedulerOpt1 Flags = 0x0008
	ServiceSchedulerOpt2 Flags = 0x0010
	ServiceSchedulerOpt3 Flags = 0x0020
)

Well-known flags.

func (Flags) String

func (i Flags) String() string

String returns a human readable representation of flags.

type ForwardType

type ForwardType uint32

ForwardType configures how IPVS forwards traffic to the real server.

const (
	Masquerade ForwardType = iota
	Local
	Tunnel
	DirectRoute
	Bypass
)

Well-known forwarding types.

func (ForwardType) String

func (i ForwardType) String() string

type Info

type Info struct {
	Version             [3]int
	ConnectionTableSize uint32
}

Info returns basic high-level information about the IPVS instance.

type Protocol

type Protocol uint16

Protocol configures how IPVS listens for connections to the virtual service.

const (
	TCP  Protocol = 0x06
	UDP  Protocol = 0x11
	SCTP Protocol = 0x84
)

The protocols IPVS is aware of.

func (Protocol) String

func (i Protocol) String() string

type Service

type Service struct {
	Address   netip.Addr
	Netmask   netmask.Mask
	Scheduler string
	Timeout   uint32
	Flags     Flags
	Port      uint16
	FWMark    uint32
	Family    AddressFamily
	Protocol  Protocol
}

Service represents a virtual server.

When referencing an existing Service, only the identifying fields (Address, Port, Family, and Protocol) are required to be set.

type ServiceExtended

type ServiceExtended struct {
	Service
	Stats   Stats
	Stats64 Stats
}

ServiceExtended contains fields that are not necessary for comparison of the identity of a Service.

type Stats

type Stats struct {
	Connections     uint64
	IncomingPackets uint64
	OutgoingPackets uint64
	IncomingBytes   uint64
	OutgoingBytes   uint64

	ConnectionRate     uint64
	IncomingPacketRate uint64 // pktbs
	OutgoingPacketRate uint64 // pktbs
	IncomingByteRate   uint64 // bps
	OutgoingByteRate   uint64 // bps
}

Stats represents the statistics of a Service as a whole, or the individual Destination connections.

type TunnelFlags

type TunnelFlags uint16

const (
	TunnelEncapNoChecksum     TunnelFlags = 0
	TunnelEncapChecksum       TunnelFlags = 0x0001
	TunnelEncapRemoteChecksum TunnelFlags = 0x0002
)

func (TunnelFlags) String

func (i TunnelFlags) String() string

type TunnelType

type TunnelType uint8

const (
	IPIP TunnelType = iota
	GUE
	GRE
)

func (TunnelType) String

func (i TunnelType) String() string

Notes

Bugs

• We might want to make the client type configurable in calls to New.