metalbond

README

MetalBond

MetalBond Protocol v1

Packet Format

MetalBond packets are transferred via TCP ontop of IPv6. The default TCP port is 4711.

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|    Version    |    Msg. Length (Big Endian)   |   Msg. Type   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
|               Variable-Length Protobuf Message                |
|                              ...                              |
|                       (max 1188 bytes)                        |
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

• Version must be 1.
• Msg. Length defines the length of the following Variable-Length Protobuf Message.
• Msg. Type identifies the type of the following Protobuf Message.

The metalbond protocol relies on IPv6 transport. Therefore we assume a minimum MTU of 1280 bytes. To prevent fragmentation all metalbond messages must not be larger than 1220 bytes overall (40 bytes IPv6 header, 20 bytes TCP header) - i.e. the variable-length protobuf message must not be longer than 1188 bytes.

Message Types

Type ID	Message Type
1	HELLO
2	KEEPALIVE
3	SUBSCRIBE
4	UNSUBSCRIBE
5	UPDATE

HELLO Message

KEEPALIVE Message

SUBSCRIBE Message

UNSUBSCRIBE Message

UPDATE Message

Install Routes

To install routes on a Linux system, you first need to create an IP-in-IPv6 tunnel endpoint:

ip link add overlay-tun type ip6tnl mode any external
ip link set up dev overlay-tun

and then start the metalbond client with the --install-routes command line parameter. This parameter requires a mapping between VNI and Kernel route table IDs. E.g. if you want to write all routes associated with VNI 23 to the Kernel route table 100, set --install-routes 23#100. Set the tunnel device using the tun parameter:

./metalbond client --install-routes 23#100 --tun overlay-tun

License

MetalBond is licensed under Apache v2.0 - Copyright by the MetalBond authors.

Documentation

Index

• Constants
• Variables
• type Client
• type Config
• type ConnectionDirection
• type ConnectionState
  • func (cs ConnectionState) String() string
• type Destination
  • func (d Destination) String() string
• type DummyClient
  • func NewDummyClient() *DummyClient
  • func (c DummyClient) AddRoute(vni VNI, dest Destination, nexthop NextHop) error
  • func (c DummyClient) RemoveRoute(vni VNI, dest Destination, nexthop NextHop) error
• type IPVersion
• type MESSAGE_TYPE
• type MetalBond
  • func NewMetalBond(config Config, client Client) *MetalBond
  • func (m *MetalBond) AddPeer(addr string) error
  • func (m *MetalBond) AnnounceRoute(vni VNI, dest Destination, hop NextHop) error
  • func (m *MetalBond) IsRouteAnnounced(vni VNI, dest Destination, hop NextHop) bool
  • func (m *MetalBond) IsSubscribed(vni VNI) bool
  • func (m *MetalBond) RemovePeer(addr string) error
  • func (m *MetalBond) Shutdown()
  • func (m *MetalBond) StartHTTPServer(listen string) error
  • func (m *MetalBond) StartServer(listenAddress string) error
  • func (m *MetalBond) Subscribe(vni VNI) error
  • func (m *MetalBond) Unsubscribe(vni VNI) error
  • func (m *MetalBond) WithdrawRoute(vni VNI, dest Destination, hop NextHop) error
• type NetlinkClient
  • func NewNetlinkClient(config NetlinkClientConfig) (*NetlinkClient, error)
  • func (c *NetlinkClient) AddRoute(vni VNI, dest Destination, hop NextHop) error
  • func (c *NetlinkClient) RemoveRoute(vni VNI, dest Destination, hop NextHop) error
• type NetlinkClientConfig
• type NextHop
  • func (h NextHop) String() string
• type UpdateAction
• type VNI

Constants

const METALBOND_RT_PROTO netlink.RouteProtocol = 254

Variables

var METALBOND_VERSION string

var RETRY_INTERVAL = time.Duration(5 * time.Second)

Types

type Client

type Client interface {
	AddRoute(vni VNI, dest Destination, nexthop NextHop) error
	RemoveRoute(vni VNI, dest Destination, nexthop NextHop) error
}

type Config

type Config struct {
	KeepaliveInterval uint32
}

type ConnectionDirection

type ConnectionDirection uint8

const (
	INCOMING ConnectionDirection = iota
	OUTGOING
)

type ConnectionState

type ConnectionState uint8

const (
	CONNECTING ConnectionState = iota
	HELLO_SENT
	HELLO_RECEIVED
	ESTABLISHED
	RETRY
	CLOSED
)

func (ConnectionState) String

func (cs ConnectionState) String() string

type Destination

type Destination struct {
	IPVersion IPVersion
	Prefix    netip.Prefix
}

func (Destination) String

func (d Destination) String() string

type DummyClient

type DummyClient struct{}

func NewDummyClient

func NewDummyClient() *DummyClient

func (DummyClient) AddRoute

func (c DummyClient) AddRoute(vni VNI, dest Destination, nexthop NextHop) error

func (DummyClient) RemoveRoute

func (c DummyClient) RemoveRoute(vni VNI, dest Destination, nexthop NextHop) error

type IPVersion

type IPVersion uint8

const (
	IPV4 IPVersion = 4
	IPV6 IPVersion = 6
)

type MESSAGE_TYPE

type MESSAGE_TYPE uint8

const (
	HELLO       MESSAGE_TYPE = 1
	KEEPALIVE   MESSAGE_TYPE = 2
	SUBSCRIBE   MESSAGE_TYPE = 3
	UNSUBSCRIBE MESSAGE_TYPE = 4
	UPDATE      MESSAGE_TYPE = 5
)

type MetalBond

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

func NewMetalBond

func NewMetalBond(config Config, client Client) *MetalBond

func (*MetalBond) AddPeer

func (m *MetalBond) AddPeer(addr string) error

func (*MetalBond) AnnounceRoute

func (m *MetalBond) AnnounceRoute(vni VNI, dest Destination, hop NextHop) error

func (*MetalBond) IsRouteAnnounced

func (m *MetalBond) IsRouteAnnounced(vni VNI, dest Destination, hop NextHop) bool

func (*MetalBond) IsSubscribed

func (m *MetalBond) IsSubscribed(vni VNI) bool

func (*MetalBond) RemovePeer

func (m *MetalBond) RemovePeer(addr string) error

func (*MetalBond) Shutdown

func (m *MetalBond) Shutdown()

Shutdown stops the MetalBond server.

func (*MetalBond) StartHTTPServer

func (m *MetalBond) StartHTTPServer(listen string) error

func (*MetalBond) StartServer

func (m *MetalBond) StartServer(listenAddress string) error

StartServer starts the MetalBond server asynchronously. To stop the server again, call Shutdown().

func (*MetalBond) Subscribe

func (m *MetalBond) Subscribe(vni VNI) error

func (*MetalBond) Unsubscribe

func (m *MetalBond) Unsubscribe(vni VNI) error

func (*MetalBond) WithdrawRoute

func (m *MetalBond) WithdrawRoute(vni VNI, dest Destination, hop NextHop) error

type NetlinkClient

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

func NewNetlinkClient

func NewNetlinkClient(config NetlinkClientConfig) (*NetlinkClient, error)

func (*NetlinkClient) AddRoute

func (c *NetlinkClient) AddRoute(vni VNI, dest Destination, hop NextHop) error

func (*NetlinkClient) RemoveRoute

func (c *NetlinkClient) RemoveRoute(vni VNI, dest Destination, hop NextHop) error

type NetlinkClientConfig

type NetlinkClientConfig struct {
	VNITableMap map[VNI]int
	LinkName    string
	IPv4Only    bool
}

type NextHop

type NextHop struct {
	TargetAddress    netip.Addr
	TargetVNI        uint32
	Type             pb.NextHopType
	NATPortRangeFrom uint16
	NATPortRangeTo   uint16
}

func (NextHop) String

func (h NextHop) String() string

type UpdateAction

type UpdateAction uint8

const (
	ADD UpdateAction = iota
	REMOVE
)

type VNI

type VNI uint32