nat

package
v1.19.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 3, 2026 License: Apache-2.0 Imports: 21 Imported by: 29

Documentation

Overview

Package nat implements the BPF NAT map interaction code. +groupName=maps

Index

Constants

View Source 
const (
	// MapNameSnat4Global represents global IPv4 NAT table.
	MapNameSnat4Global = "cilium_snat_v4_external"
	// MapNameSnat6Global represents global IPv6 NAT table.
	MapNameSnat6Global = "cilium_snat_v6_external"

	// SnatCollisionRetries represents the maximum number of port allocation retries.
	SnatCollisionRetries = 32
)
View Source 
const (
	// IPv4 represents the IPv4 IP family.
	IPv4 = IPFamily(true)
	// IPv6 represents the IPv6 IP family.
	IPv6 = IPFamily(false)
)
View Source 
const SizeofNatEntry6 = int(unsafe.Sizeof(NatEntry6{}))

SizeofNatEntry6 is the size of the NatEntry6 type in bytes.

View Source 
const SizeofNatKey4 = int(unsafe.Sizeof(NatKey4{}))

SizeofNatKey4 is the size of the NatKey4 type in bytes.

View Source 
const SizeofNatKey6 = int(unsafe.Sizeof(NatKey6{}))

SizeofNatKey6 is the size of the NatKey6 type in bytes.

Variables

View Source 
var Cell = cell.Module(
	"nat-maps",
	"NAT Maps",
	cell.Provide(func(lc cell.Lifecycle, registry *metrics.Registry, cfg *option.DaemonConfig, kprCfg kpr.KPRConfig) (bpf.MapOut[NatMap4], bpf.MapOut[NatMap6]) {
		var out4 bpf.MapOut[NatMap4]
		var out6 bpf.MapOut[NatMap6]
		var ipv4Nat, ipv6Nat *Map

		if !kprCfg.KubeProxyReplacement && !cfg.EnableBPFMasquerade {
			return out4, out6
		}

		ipv4Nat, ipv6Nat = GlobalMaps(registry, cfg.EnableIPv4, cfg.EnableIPv6)
		if ipv4Nat != nil {
			out4 = bpf.NewMapOut[NatMap4](ipv4Nat)
		}
		if ipv6Nat != nil {
			out6 = bpf.NewMapOut[NatMap6](ipv6Nat)
		}

		lc.Append(cell.Hook{
			OnStart: func(hc cell.HookContext) error {
				if ipv4Nat != nil {
					if err := ipv4Nat.OpenOrCreate(); err != nil {
						return fmt.Errorf("open IPv4 nat map: %w", err)
					}
				}
				if ipv6Nat != nil {
					if err := ipv6Nat.OpenOrCreate(); err != nil {
						return fmt.Errorf("open IPv6 nat map: %w", err)
					}
				}
				return nil
			},
			OnStop: func(hc cell.HookContext) error {
				if ipv4Nat != nil {
					if err := ipv4Nat.Map.Close(); err != nil {
						return err
					}
				}
				if ipv6Nat != nil {
					if err := ipv6Nat.Map.Close(); err != nil {
						return err
					}
				}
				return nil
			},
		})

		return out4, out6
	}),
	cell.Provide(provideNATRetriesMap),
)

Cell exposes global nat maps via Hive.

View Source 
var ClusterOuterMapName = clusterOuterMapName

ClusterOuterMapName returns the name of the outer per-cluster NAT map for the given IP family. It can be overwritten for testing purposes.

View Source 
var ErrMapDisabled = fmt.Errorf("nat map is disabled")

ErrMapDisabled is the expected error will be if map was not created due to configuration.

Functions

func CleanupPerClusterNATMaps 

func CleanupPerClusterNATMaps(ipv4, ipv6 bool) error

CleanupPerClusterNATMaps deletes the per-cluster NAT maps, including the inner ones.

func ClusterInnerMapName 

func ClusterInnerMapName(family IPFamily, clusterID uint32) string

ClusterInnerMapName returns the name of the inner per-cluster NAT map for the given IP family and cluster ID.

func ClusterOuterMapNameTestOverride 

func ClusterOuterMapNameTestOverride(prefix string)

func DeleteMapping4 added in v1.13.9 

func DeleteMapping4(m *Map, tk tuple.TupleKey) error

func DeleteMapping6 added in v1.13.9 

func DeleteMapping6(m *Map, tk tuple.TupleKey) error

func DeleteSwappedMapping4 added in v1.13.9 

func DeleteSwappedMapping4(m *Map, tk tuple.TupleKey) error

Expects ingress tuple

func DeleteSwappedMapping6 added in v1.13.9 

func DeleteSwappedMapping6(m *Map, tk tuple.TupleKey) error

Expects ingress tuple

func DoDumpEntries 

func DoDumpEntries(m NatMap) (string, error)

DoDumpEntries iterates through Map m and writes the values of the nat entries in m to a string.

func DumpEntriesWithTimeDiff added in v1.14.5 

func DumpEntriesWithTimeDiff(m NatMap, clockSource *models.ClockSource) (string, error)

DumpEntriesWithTimeDiff iterates through Map m and writes the values of the nat entries in m to a string. If clockSource is not nil, it uses it to compute the time difference of each entry from now and prints that too.

func NewPerClusterNATMaps 

func NewPerClusterNATMaps(ipv4, ipv6 bool) *perClusterNATMaps

NewPerClusterNATMaps returns a new instance of the per-cluster NAT maps manager.

Types

type IPFamily 

type IPFamily bool

IPFamily represents an IP family (i.e., either IPv4 or IPv6).

func (IPFamily) String 

func (family IPFamily) String() string

type Map 

type Map struct {
	bpf.Map
	// contains filtered or unexported fields
}

Map represents a NAT map. It also implements the NatMap interface.

func ClusterMaps 

func ClusterMaps(clusterID uint32, ipv4, ipv6 bool) (ipv4Map, ipv6Map *Map, err error)

ClusterMaps returns all NAT maps for given clusters

func GetClusterNATMap 

func GetClusterNATMap(clusterID uint32, family IPFamily) (*Map, error)

GetClusterNATMap returns the per-cluster map for the given cluster ID. The returned map needs to be opened by the caller, and it is not guaranteed to exist.

func GlobalMaps 

func GlobalMaps(registry *metrics.Registry, ipv4, ipv6 bool) (ipv4Map, ipv6Map *Map)

GlobalMaps returns all global NAT maps.

func NewMap 

func NewMap(registry *metrics.Registry, name string, family IPFamily, entries int) *Map

NewMap instantiates a Map.

func (*Map) Delete 

func (m *Map) Delete(k bpf.MapKey) (deleted bool, err error)

func (*Map) DumpBatch4 added in v1.17.0 

func (m *Map) DumpBatch4(fn func(*tuple.TupleKey4, *NatEntry4)) (count int, err error)

DumpBatch4 uses batch iteration to walk the map and applies fn for each batch of entries.

func (*Map) DumpBatch6 added in v1.17.0 

func (m *Map) DumpBatch6(fn func(*tuple.TupleKey6, *NatEntry6)) (count int, err error)

DumpBatch6 uses batch iteration to walk the map and applies fn for each batch of entries.

func (*Map) DumpEntries 

func (m *Map) DumpEntries() (string, error)

DumpEntries iterates through Map m and writes the values of the nat entries in m to a string.

func (*Map) DumpReliablyWithCallback 

func (m *Map) DumpReliablyWithCallback(cb bpf.DumpCallback, stats *bpf.DumpStats) error

func (*Map) DumpStats 

func (m *Map) DumpStats() *bpf.DumpStats

func (*Map) Flush 

func (m *Map) Flush() int

Flush deletes all NAT mappings from the given table.

type NATRetriesMap added in v1.19.0 

type NATRetriesMap any

NATRetriesMap is a marker interface for the NAT retries map. It doesn't provide any functionality to the Cilium Agent because the bpf map is only created by the Cilium Agent for the datapath. It's still provided to be picked up as dependency by the Loader and initialized at startup.

type NatEntry 

type NatEntry interface {
	bpf.MapValue

	// ToHost converts fields to host byte order.
	ToHost() NatEntry

	// Dumps the Nat entry as string.
	Dump(key NatKey, toDeltaSecs func(uint64) string) string
}

NatEntry is the interface describing values to the NAT map.

type NatEntry4 

type NatEntry4 struct {
	Created uint64     `align:"created"`
	NeedsCT uint64     `align:"needs_ct"`
	Pad1    uint64     `align:"pad1"`
	Pad2    uint64     `align:"pad2"`
	Addr    types.IPv4 `align:"to_saddr"`
	Port    uint16     `align:"to_sport"`
	// contains filtered or unexported fields
}

NatEntry4 represents an IPv4 entry in the NAT table.

func (*NatEntry4) Dump 

func (n *NatEntry4) Dump(key NatKey, toDeltaSecs func(uint64) string) string

Dump dumps NAT entry to string.

func (*NatEntry4) New 

func (n *NatEntry4) New() bpf.MapValue

func (*NatEntry4) String 

func (n *NatEntry4) String() string

String returns the readable format.

func (*NatEntry4) ToHost 

func (n *NatEntry4) ToHost() NatEntry

ToHost converts NatEntry4 ports to host byte order.

type NatEntry6 

type NatEntry6 struct {
	Created uint64     `align:"created"`
	NeedsCT uint64     `align:"needs_ct"`
	Pad1    uint64     `align:"pad1"`
	Pad2    uint64     `align:"pad2"`
	Addr    types.IPv6 `align:"to_saddr"`
	Port    uint16     `align:"to_sport"`
	// contains filtered or unexported fields
}

NatEntry6 represents an IPv6 entry in the NAT table.

func (*NatEntry6) Dump 

func (n *NatEntry6) Dump(key NatKey, toDeltaSecs func(uint64) string) string

Dump dumps NAT entry to string.

func (*NatEntry6) New 

func (n *NatEntry6) New() bpf.MapValue

func (*NatEntry6) String 

func (n *NatEntry6) String() string

String returns the readable format.

func (*NatEntry6) ToHost 

func (n *NatEntry6) ToHost() NatEntry

ToHost converts NatEntry4 ports to host byte order.

type NatKey 

type NatKey interface {
	bpf.MapKey

	// ToNetwork converts fields to network byte order.
	ToNetwork() NatKey

	// ToHost converts fields to host byte order.
	ToHost() NatKey

	// Dump contents of key to sb. Returns true if successful.
	Dump(sb *strings.Builder, reverse bool) bool

	// GetFlags flags containing the direction of the TupleKey.
	GetFlags() uint8

	// GetNextHeader returns the proto of the NatKey
	GetNextHeader() u8proto.U8proto
}

type NatKey4 

type NatKey4 struct {
	tuple.TupleKey4Global
}

NatKey4 is needed to provide NatEntry type to Lookup values

func (*NatKey4) GetNextHeader 

func (k *NatKey4) GetNextHeader() u8proto.U8proto

func (*NatKey4) New 

func (k *NatKey4) New() bpf.MapKey

func (*NatKey4) ToHost 

func (k *NatKey4) ToHost() NatKey

ToHost converts ports to host byte order.

This is necessary to prevent callers from implicitly converting the NatKey4 type here into a local key type in the nested TupleKey4Global field.

func (*NatKey4) ToNetwork 

func (k *NatKey4) ToNetwork() NatKey

ToNetwork converts ports to network byte order.

This is necessary to prevent callers from implicitly converting the NatKey4 type here into a local key type in the nested TupleKey4Global field.

type NatKey6 

type NatKey6 struct {
	tuple.TupleKey6Global
}

NatKey6 is needed to provide NatEntry type to Lookup values

func (*NatKey6) GetNextHeader 

func (k *NatKey6) GetNextHeader() u8proto.U8proto

func (*NatKey6) New 

func (k *NatKey6) New() bpf.MapKey

func (*NatKey6) ToHost 

func (k *NatKey6) ToHost() NatKey

ToHost converts ports to host byte order.

This is necessary to prevent callers from implicitly converting the NatKey6 type here into a local key type in the nested TupleKey6Global field.

func (*NatKey6) ToNetwork 

func (k *NatKey6) ToNetwork() NatKey

ToNetwork converts ports to network byte order.

This is necessary to prevent callers from implicitly converting the NatKey6 type here into a local key type in the nested TupleKey6Global field.

type NatMap 

type NatMap interface {
	DumpEntries() (string, error)
	DumpWithCallback(bpf.DumpCallback) error
	// contains filtered or unexported methods
}

NatMap interface represents a NAT map, and can be reused to implement mock maps for unit tests.

type NatMap4 added in v1.16.0 

type NatMap4 interface {
	NatMap
	DumpBatch4(func(*tuple.TupleKey4, *NatEntry4)) (count int, err error)
}

NatMap4 describes ipv4 nat map behaviors, used for providing map to hive.

type NatMap6 added in v1.16.0 

type NatMap6 interface {
	NatMap
	DumpBatch6(func(*tuple.TupleKey6, *NatEntry6)) (count int, err error)
}

NatMap6 describes ipv6 nat map behaviors, used for providing map to hive.

type NatMapRecord 

type NatMapRecord struct {
	Key   NatKey
	Value NatEntry
}

A "Record" designates a map entry (key + value), but avoid "entry" because of possible confusion with "NatEntry" (actually the value part). This type is used for JSON dump and mock maps.

type PerClusterNATMapKey 

type PerClusterNATMapKey struct {
	ClusterID uint32
}

func (*PerClusterNATMapKey) New 

func (n *PerClusterNATMapKey) New() bpf.MapKey

func (*PerClusterNATMapKey) String 

func (k *PerClusterNATMapKey) String() string

type PerClusterNATMapVal 

type PerClusterNATMapVal struct {
	Fd uint32
}

func (*PerClusterNATMapVal) New 

func (n *PerClusterNATMapVal) New() bpf.MapValue

func (*PerClusterNATMapVal) String 

func (v *PerClusterNATMapVal) String() string

type PerClusterNATMapper 

type PerClusterNATMapper interface {
	// Create enforces the presence of the outer per-cluster NAT maps.
	OpenOrCreate() error
	// Close closes the outer per-cluster NAT maps handlers.
	Close() error

	// CreateClusterNATMaps enforces the presence of the inner maps for
	// the given cluster ID. It must be called after that OpenOrCreate()
	// has returned successfully.
	CreateClusterNATMaps(clusterID uint32) error
	// DeleteClusterNATMaps deletes the inner maps for the given cluster ID.
	// It must be called after that OpenOrCreate() has returned successfully.
	DeleteClusterNATMaps(clusterID uint32) error
}

An interface to manage the per-cluster NAT maps.

type RetriesKey added in v1.18.0 

type RetriesKey struct {
	Key uint32
}

func (*RetriesKey) New added in v1.18.0 

func (k *RetriesKey) New() bpf.MapKey

func (*RetriesKey) String added in v1.18.0 

func (k *RetriesKey) String() string

type RetriesMap added in v1.18.0 

type RetriesMap interface {
	DumpPerCPUWithCallback(bpf.DumpPerCPUCallback) error
	ClearAll() error
	// contains filtered or unexported methods
}

func RetriesMaps added in v1.18.0 

func RetriesMaps(ipv4 bool, ipv6 bool) (ipv4RetriesMap, ipv6RetriesMap RetriesMap)

RetriesMaps returns the maps that contain the histograms of the number of retries. This should only be used from components which aren't capable of using hive - mainly the cilium-dbg. It needs to initialized beforehand via the Cilium Agent.

type RetriesMapRecord added in v1.18.0 

type RetriesMapRecord struct {
	Key   *RetriesKey
	Value *RetriesValue
}

type RetriesValue added in v1.18.0 

type RetriesValue struct {
	Value uint32
}

func (*RetriesValue) New added in v1.18.0 

func (k *RetriesValue) New() bpf.MapValue

func (*RetriesValue) NewSlice added in v1.18.0 

func (k *RetriesValue) NewSlice() any

func (*RetriesValue) String added in v1.18.0 

func (k *RetriesValue) String() string

type RetriesValues added in v1.18.0 

type RetriesValues []RetriesValue

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.