Architecture and Packet Flow

Architecture and Packet Flow

Component map

Listening sockets / proc events / periodic scan
                    │
                    ▼
            xdp_port_sync.py
      discovery → policy → reconciliation
              │                │
              │                ├── pinned XDP BPF maps
              │                └── atomic nftables table
              │
              ├── AbuseIPDB background sync (XDP only)
              └── SIGHUP configuration reload

NIC ingress ─────► xdp_firewall.o ─────► Linux network stack
                         ▲
Host egress ─────► tc_flow_track.o ─────┘ shared conntrack maps

socket tracepoint ─► sock_state_rb ─► immediate reconciliation trigger
XDP pkt_ringbuf ───► pkt_relay.py ─► Unix socket ─► axdp tui / clients

Control plane

xdp_port_sync.py loads /etc/auto_xdp/config.toml, discovers listeners, builds a desired state, and asks the active backend to reconcile it. Desired state includes:

• discovered and permanent TCP/UDP/SCTP ports;
• trusted CIDRs, ACLs, and 6in4 endpoints;
• per-port TCP/UDP rate and connection policies;
• bogon, under-attack, timeout, and runtime settings;
• protocol-slot and port-handler configuration.

Events are debounced to avoid repeated policy writes during process restart bursts. A separate full reconciliation runs about every 30 seconds to repair missed events and map drift. If discovery fails, the daemon retains the last applied policy instead of reconciling to an empty port set.

XDP ingress path

The important ordering is:

1. Parse Ethernet and supported 802.1Q/QinQ depth. Excess VLAN nesting is dropped; a truncated VLAN header is passed to the kernel.
2. Pass non-IP traffic such as ARP.
3. Parse IPv4 or IPv6 and traverse supported IPv6 extension headers.
4. Drop IPv4/IPv6 fragments. If enabled, apply bogon-source filtering before transport admission.
5. Validate TCP/UDP lengths, ports, and TCP flags.
6. Evaluate trust, ACL, conntrack, port admission, rate limits, and handlers in protocol-specific order.
7. Pass required ICMP errors and IPv6 NDP; rate-limit echo requests with a global token bucket.
8. Admit IPv4 protocol 41 only from configured SIT endpoints.
9. Dispatch other protocols by final IP protocol number. A missing slot uses slots.default_action.

TCP

• Port 0, NULL/XMAS, SYN+FIN, SYN+RST, RST+FIN, and invalid/truncated TCP data offsets are dropped.
• Trusted sources and TCP ACLs can admit matching pure SYN packets.
• Established and host-originated return traffic depends on conntrack maps.
• New SYNs must use an admission path and pass five rate/connection layers.
• Port handlers can implement multi-packet validation. Pending-dispatch maps let later ACK/data packets re-enter a handler before a final conntrack-miss drop.
• FIN/RST processing, inactivity timeouts, and GC release state and connection counters.

UDP

• The destination port must first be admitted. Trust and ACLs never open a closed UDP port.
• Host-originated return tuples can pass via UDP conntrack.
• A trusted/ACL match on an admitted port bypasses UDP rate limits and the port handler.
• Other traffic is evaluated by per-source packet rate, per-prefix byte rate, global byte rate, and optional port handler.

SCTP and other protocols

SCTP ports are not automatically discovered. Enable the built-in SCTP slot handler and configure [permanent_ports].sctp; the handler uses shared whitelist and conntrack maps. GRE and ESP handlers perform basic structural validation. Custom protocols use the same tail-call ABI.

Stateful return traffic

tc_flow_track.o is attached at egress on every target interface:

• An outbound TCP SYN creates the reverse tuple required for SYN-ACK and subsequent return traffic.
• An outbound UDP datagram creates the reverse tuple required for a reply.
• The tc and XDP programs share pinned conntrack maps.

Install/reload also seeds already established TCP sessions to reduce disruption. conntrack_refresh_seconds limits timestamp write amplification; TCP, UDP, SYN, and GC timers control reclamation.

nftables backend

The fallback uses a dedicated table, normally inet auto_xdp, containing TCP/UDP/SCTP port sets, IPv4/IPv6 trusted sets, optional bogon sets, ACLs, dynamic sets, and meters. A complete candidate is committed in one nft batch, so parse or kernel-validation failure leaves the previous table intact.

nftables mirrors public policy semantics where practical, including malformed-packet checks, trust/ACL behavior, port admission, TCP/UDP limits, ICMP handling, and the default action for other protocols. These features remain XDP-specific:

• driver-level early drop and its performance benefit;
• custom BPF protocol/port handlers;
• per-packet BPF ring-buffer telemetry;
• handler-specific BPF state machines.

Transactional update and recovery

The XDP runtime uses xdp_fw_next and xdp_fw_rollback pin generations. Candidate maps, program identity, and tc attachments are verified before replacement. On failure, the previous program is restored. The runtime refuses to layer nftables fallback over an interface that still has an unresolved XDP attachment.

Installed files use immutable release generations and an atomic current symlink. An install transaction records the switch phase so startup can recover an interrupted release change.