README
¶
InterCloud eXpress (ICX)
Notes
On Debian you might need to create this symlink to fix bpf compilation issues:
sudo ln -sf /usr/include/$(uname -m)-linux-gnu/asm /usr/include/asm
Documentation
¶
Index ¶
- Constants
- func MTU(pathMTU int) int
- type Handler
- func (h *Handler) AddVirtualNetwork(vni uint, remoteAddr *tcpip.FullAddress, addrs []netip.Prefix) error
- func (h *Handler) AllStats() []VirtualNetworkStats
- func (h *Handler) PhyToVirt(phyFrame, virtFrame []byte) int
- func (h *Handler) RemoveVirtualNetwork(vni uint) error
- func (h *Handler) StatsForVNI(vni uint) (VirtualNetworkStats, bool)
- func (h *Handler) UpdateVirtualNetworkAddrs(vni uint, addrs []netip.Prefix) error
- func (h *Handler) UpdateVirtualNetworkKeys(vni uint, epoch uint32, rxKey, txKey [16]byte, expiresAt time.Time) error
- func (h *Handler) VirtToPhy(virtFrame, phyFrame []byte) (int, bool)
- type HandlerOption
- type VirtualNetworkStats
Constants ¶
const (
// The size of the GENEVE header with icx options.
HeaderSize = 32
)
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler processes encapsulated GENEVE traffic for one or more virtual networks. It performs encryption/decryption, replay protection, address validation, and translation between physical and virtual frame formats.
A Handler tracks virtual networks by VNI and allowed address prefixes, supports both L2 and L3 operation, and is safe for concurrent use.
func NewHandler ¶
func NewHandler(opts ...HandlerOption) (*Handler, error)
NewHandler returns a new Handler configured with the given options. It validates required parameters and allocates internal state for managing virtual networks and packet processing.
func (*Handler) AddVirtualNetwork ¶
func (h *Handler) AddVirtualNetwork(vni uint, remoteAddr *tcpip.FullAddress, addrs []netip.Prefix) error
AddVirtualNetwork adds a new network with the given VNI and remote address.
func (*Handler) AllStats ¶ added in v0.6.0
func (h *Handler) AllStats() []VirtualNetworkStats
AllStats returns snapshots for all currently registered virtual networks.
func (*Handler) PhyToVirt ¶
PhyToVirt converts a physical frame to a virtual frame typically by performing decapsulation. Returns the length of the resulting virtual frame.
func (*Handler) RemoveVirtualNetwork ¶
RemoveVirtualNetwork removes a network by its VNI.
func (*Handler) StatsForVNI ¶ added in v0.6.0
func (h *Handler) StatsForVNI(vni uint) (VirtualNetworkStats, bool)
StatsForVNI returns a snapshot for a single virtual network.
func (*Handler) UpdateVirtualNetworkAddrs ¶ added in v0.7.2
UpdateVirtualNetworkAddrs updates the allowed address prefixes for a virtual network.
func (*Handler) UpdateVirtualNetworkKeys ¶ added in v0.5.0
func (h *Handler) UpdateVirtualNetworkKeys(vni uint, epoch uint32, rxKey, txKey [16]byte, expiresAt time.Time) error
UpdateVirtualNetworkKeys sets/rotates the encryption keys for a virtual network. This must be called atleast once every 24 hours or after `replay.RekeyAfterMessages` messages.
func (*Handler) VirtToPhy ¶
VirtToPhy converts a virtual frame to a physical frame typically by performing encapsulation. Returns the length of the resulting physical frame. VirtToPhy converts a virtual frame to a physical frame typically by performing encapsulation. Returns the length of the resulting physical frame.
type HandlerOption ¶ added in v0.7.0
type HandlerOption func(*handlerOptions) error
func WithLayer3VirtFrames ¶ added in v0.7.0
func WithLayer3VirtFrames() HandlerOption
WithLayer3VirtFrames configures the handler for L3 mode, where virtual frames are raw IP packets (no Ethernet header). In this mode:
- VirtToPhy expects an IP packet as input.
- PhyToVirt returns a decrypted IP packet.
- WithVirtMAC and WithSourceMAC are ignored.
Default is L2 mode (Ethernet frames).
func WithLocalAddr ¶ added in v0.7.0
func WithLocalAddr(a *tcpip.FullAddress) HandlerOption
WithLocalAddr sets the local UDP endpoint used as the source for encapsulated packets. This option is required.
If WithSourcePortHashing is enabled, the Port field of this address is overridden per packet with a hash of the inner flow. Otherwise, the Port specified here is used as-is.
func WithSourceMAC ¶ added in v0.7.0
func WithSourceMAC(mac tcpip.LinkAddress) HandlerOption
WithSourceMAC overrides the synthetic source MAC used for L2 frames and for ProxyARP replies. By default, a random MAC is generated at handler creation. Ignored when L3 mode is enabled.
func WithSourcePortHashing ¶ added in v0.7.0
func WithSourcePortHashing() HandlerOption
WithSourcePortHashing enables per-packet UDP source-port selection based on a hash of the inner IP flow. This improves ECMP distribution in the underlay. When enabled, it overrides the Port from WithLocalAddr for each packet.
func WithVirtMAC ¶ added in v0.7.0
func WithVirtMAC(mac tcpip.LinkAddress) HandlerOption
WithVirtMAC sets the MAC address used for the virtual interface in L2 mode. This is required when not running in L3 mode (see WithLayer3VirtFrames). Ignored when L3 mode is enabled.
type VirtualNetworkStats ¶ added in v0.6.0
type VirtualNetworkStats struct {
// VNI is the virtual network identifier.
VNI uint
// KeyEpoch is the current key epoch.
KeyEpoch uint32
// KeyRotations is the number of key rotations that have occurred.
KeyRotations uint32
// RXPackets is the number of received packets.
RXPackets uint64
// RXBytes is the number of bytes received.
RXBytes uint64
// RXDropsNoKey is the number of received packets dropped due to a missing key.
RXDropsNoKey uint64
// RXDropsExpiredKey is the number of received packets dropped due to an expired key.
RXDropsExpiredKey uint64
// RXReplayDrops is the number of received packets dropped due to a potential replay attack.
RXReplayDrops uint64
// RXDecryptErrors is the number of received packets that failed decryption.
RXDecryptErrors uint64
// RXInvalidSrc is the number of received packets with an invalid source address.
RXInvalidSrc uint64
// TXPackets is the number of transmitted packets.
TXPackets uint64
// TXBytes is the number of bytes transmitted.
TXBytes uint64
// TXErrors is the number of transmission errors.
TXErrors uint64
// LastRX is the timestamp of the last received packet.
LastRX time.Time
// LastTX is the timestamp of the last transmitted packet.
LastTX time.Time
}
VirtualNetwork is a statistics snapshot for a virtual network.
Source Files
Directories