README
¶
InterCloud eXpress (ICX)
ICX is a high-performance, kernel-bypass VPN solution for cloud environments.
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
Performance
2 x c7gn.2xlarge instances in the same us-west-2 availability zone with a cluster placement strategy.
Documentation
¶
Index ¶
- Constants
- func MTU(pathMTU int) int
- type Clock
- type Handler
- func (h *Handler) AddVirtualNetwork(vni uint, remoteAddr *tcpip.FullAddress, addrs []netip.Prefix) error
- func (h *Handler) GetVirtualNetwork(vni uint) (*VirtualNetwork, bool)
- func (h *Handler) ListVirtualNetworks() []*VirtualNetwork
- func (h *Handler) PhyToVirt(phyFrame, virtFrame []byte) int
- func (h *Handler) RemoveVirtualNetwork(vni uint) error
- func (h *Handler) ToPhy(phyFrame []byte) int
- 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
- func WithClock(c Clock) HandlerOption
- func WithKeepAliveInterval(interval time.Duration) HandlerOption
- func WithLayer3VirtFrames() HandlerOption
- func WithLocalAddr(a *tcpip.FullAddress) HandlerOption
- func WithSourceMAC(mac tcpip.LinkAddress) HandlerOption
- func WithSourcePortHashing() HandlerOption
- func WithVirtMAC(mac tcpip.LinkAddress) HandlerOption
- type Statistics
- type VirtualNetwork
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.
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) GetVirtualNetwork ¶ added in v0.8.0
func (h *Handler) GetVirtualNetwork(vni uint) (*VirtualNetwork, bool)
GetVirtualNetwork retrieves a virtual network by its VNI.
func (*Handler) ListVirtualNetworks ¶ added in v0.8.0
func (h *Handler) ListVirtualNetworks() []*VirtualNetwork
ListVirtualNetworks returns a snapshot of all configured 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) ToPhy ¶ added in v0.12.0
ToPhy is called periodically to allow the handler to send scheduled frames to the physical interface, e.g. keep-alive packets. Returns the length of the resulting physical frame.
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.
type HandlerOption ¶ added in v0.7.0
type HandlerOption func(*handlerOptions) error
func WithClock ¶ added in v0.12.1
func WithClock(c Clock) HandlerOption
WithClock overrides the time source used by the handler (useful for tests).
func WithKeepAliveInterval ¶ added in v0.10.0
func WithKeepAliveInterval(interval time.Duration) HandlerOption
WithKeepAliveInterval configures the handler to send keep-alive packets on each virtual network at the given interval. If nil or zero, no keep-alives are sent. A value of between 10 and 30s is recommended to keep NAT mappings alive.
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). 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 multiple addresses are provided, the best one is chosen per packet based on the remote address.
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 Statistics ¶ added in v0.12.0
type Statistics struct {
KeyEpoch atomic.Uint32
KeyRotations atomic.Uint32
// RXPackets is the number of received packets.
RXPackets atomic.Uint64
// RXBytes is the number of bytes received.
RXBytes atomic.Uint64
// RXDropsNoKey is the number of received packets dropped due to a missing key.
RXDropsNoKey atomic.Uint64
// RXDropsExpiredKey is the number of received packets dropped due to an expired key.
RXDropsExpiredKey atomic.Uint64
// RXReplayDrops is the number of received packets dropped due to a potential replay attack.
RXReplayDrops atomic.Uint64
// RXDecryptErrors is the number of received packets that failed decryption.
RXDecryptErrors atomic.Uint64
// RXInvalidSrc is the number of received packets with an invalid source address.
RXInvalidSrc atomic.Uint64
// TXPackets is the number of transmitted packets.
TXPackets atomic.Uint64
// TXBytes is the number of bytes transmitted.
TXBytes atomic.Uint64
// TXErrors is the number of transmission errors.
TXErrors atomic.Uint64
// LastRXUnixNano is the timestamp of the last received packet.
LastRXUnixNano atomic.Int64
// LastTXUnixNano is the timestamp of the last transmitted packet.
LastTXUnixNano atomic.Int64
// LastKeepAliveUnixNano is the timestamp of the last transmitted keep-alive packet.
LastKeepAliveUnixNano atomic.Int64
}
Statistics for a virtual network.
type VirtualNetwork ¶ added in v0.8.0
type VirtualNetwork struct {
// ID is the virtual network identifier.
ID uint
// RemoteAddr is the address of the remote endpoint.
RemoteAddr *tcpip.FullAddress
// Addrs is the list of local IP prefixes.
Addrs []netip.Prefix
// Statistics associated with this virtual network.
Stats Statistics
// contains filtered or unexported fields
}
The state associated with each virtual network.
Source Files
Directories