BPF Maps and Low Level API

BPF Maps and Low-Level API

The default pin root is /sys/fs/bpf/xdp_fw. Auto XDP owns the maps under this directory and verifies required names during load/reload. Manual writes are diagnostic only and can be overwritten by reconciliation.

Admission and runtime maps

Map	Type	Purpose
tcp_whitelist	ARRAY, 65536	Direct port-indexed TCP admission.
udp_whitelist	ARRAY, 65536	Direct port-indexed UDP admission.
sctp_whitelist	ARRAY, 65536	Configuration-managed SCTP admission.
xdp_runtime_cfg	ARRAY, 1	Hot runtime timeouts, rates, prefixes, and feature flags.
tcp_port_policies	HASH, 1024	Per-port TCP rates and connection ceilings.
udp_port_policies	HASH, 1024	Per-port UDP rates and byte ceilings.
udp_global_rl	ARRAY, 1	Shared global UDP limiter state.
udp_percpu_acc	PERCPU_ARRAY, 1	Per-CPU accumulation before global flush.

ARRAY admission maps make port lookup constant-time with a fixed valid key range. Setting value 1 admits a port; setting 0 removes it.

Connection state

Map	Type/capacity	Purpose
tcp_ct4, tcp_ct6	LRU_HASH, 196608 each	TCP tuple timestamp and pending-SYN state.
udp_ct4, udp_ct6	LRU_HASH, 196608 each	UDP return-flow tuples.
sctp_conntrack	LRU_HASH, 65536	SCTP flow state shared with its handler.
tcp_pd4	LRU_HASH, 49152	IPv4 pending port-handler dispatch.
tcp_pd6	LRU_HASH, 16384	IPv6 pending port-handler dispatch.

The XDP and tc egress programs reuse these pinned maps. Do not change key/value layouts without updating all objects and the ABI manifest.

Rate and connection accounting

Map	Type	Purpose
syn4, syn6	ARRAY_OF_MAPS, 65536 outer	One per-port LRU for per-source TCP SYN state.
udprt4, udprt6	ARRAY_OF_MAPS, 65536 outer	One per-port LRU for per-source UDP state.
synag4, synag6	LRU_HASH	Per-prefix TCP SYN state.
udpag4, udpag6	LRU_HASH	Per-prefix UDP byte state.
tsc4, tsc6	LRU_HASH	Per-source TCP connection counts.
tsc_pfx4, tsc_pfx6	LRU_HASH	Per-prefix TCP connection counts.
tsc_port	ARRAY, 65536	Total established connections per port.
icmp_tb	ARRAY, 1	Shared ICMP echo token bucket.

IPv4 rate maps use a compiled aggregate capacity of 49152 where applicable; IPv6 uses 16384. Per-port inner LRU defaults are configuration-controlled (map_entries_v4=16384, map_entries_v6=4096).

Trust, ACL, tunnel, and threat maps

Map	Type/capacity	Purpose
trusted_ipv4, trusted_ipv6	LPM_TRIE, 256	Trusted source CIDRs.
tcp_acl_v4, tcp_acl_v6	LPM_TRIE, 1024	TCP CIDR → up to 64 ports.
udp_acl_v4, udp_acl_v6	LPM_TRIE, 1024	UDP CIDR → up to 64 ports.
sit4_endpoints	HASH, 64	Allowed IPv4 outer sources for protocol 41.
abuseipdb_v4	LPM_TRIE	Active AbuseIPDB IPv4 risk networks.
hblk4, hblk6	handler block maps	Sources blocked by stateful application handlers.

LPM keys include prefix length followed by address bytes. Use the project Python wrappers or axdp; hand-encoding LPM keys with bpftool is easy to get wrong.

Program dispatch and context

Map	Type	Index
proto_handlers	PROG_ARRAY, 256	Final IP protocol number.
tcp_port_handlers	PROG_ARRAY, 65536	TCP destination port.
udp_port_handlers	PROG_ARRAY, 65536	UDP destination port.
slot_ctx_map	PERCPU_ARRAY, 1	Parsed context fallback for generic XDP.
prog	pinned program	Main XDP program used for verified reattachment.

Counters and events

Map	Type	Purpose
pkt_counters	PERCPU_ARRAY, 35	Verdict/reason packet counters.
byte_counters	PERCPU_ARRAY, 4	Total/drop packet and byte accounting.
pkt_ringbuf	RINGBUF, 4 MiB	Packet events consumed by pkt_relay.py.
sock_state_rb	RINGBUF, 64 KiB	TCP LISTEN transitions from the tracepoint program.

Inspection examples

sudo bpftool prog show pinned /sys/fs/bpf/xdp_fw/prog
sudo bpftool map show
sudo bpftool map dump pinned /sys/fs/bpf/xdp_fw/tcp_whitelist
sudo bpftool map dump pinned /sys/fs/bpf/xdp_fw/xdp_runtime_cfg
sudo bpftool map dump pinned /sys/fs/bpf/xdp_fw/pkt_counters

For an ARRAY_OF_MAPS entry, first look up the outer entry by destination port, then inspect the referenced inner map ID. axdp conntrack, axdp ports, and axdp stats already decode common data correctly.

ABI safety

auto_xdp/xdp_map_abi.txt records expected map layouts, and auto_xdp/xdp_required_maps.txt lists pins required for a healthy runtime generation. The installer validates candidate artifacts before activation. Changing capacity, key/value size, flags, or map type is a coordinated migration across XDP, tc, handlers, userspace wrappers, tests, and rollback behavior.