Skip to content

Home

Jump to bottom
Kookiejarz edited this page Sep 2, 2026 · 3 revisions

Auto XDP Wiki

Auto XDP is a host-side firewall for public Linux servers. It discovers the ports the host is actually listening on and keeps the active filtering backend synchronized automatically. It uses XDP/eBPF when the host supports it and falls back to nftables when XDP cannot be used safely.

It is intended for VPSes, cloud instances, homelab servers, and other single-host deployments exposed to port scans, SYN floods, UDP amplification traffic, and malformed L3/L4 probes.

Auto XDP can only filter packets that reach the host NIC. It cannot restore bandwidth already saturated by a volumetric attack. Use upstream scrubbing or DDoS-protected hosting for that threat.

Start here

30-second walkthrough

sudo axdp backend
sudo axdp ports

python3 -m http.server 8080 &
sudo axdp ports --watch

sudo axdp tui

When the web server starts listening, port 8080 is added to the active policy. When it stops, the port is removed. TCP listener transitions produce immediate kernel events; a periodic full discovery pass repairs missed events and policy drift.

Main capabilities

  • Automatic IPv4/IPv6 TCP and UDP listener discovery. SCTP ports are configuration-managed.
  • Per-interface native XDP with generic XDP fallback, plus a full nftables backend.
  • XDP ingress filtering combined with a tc egress tracker for host-originated TCP and UDP return traffic.
  • Five default TCP protection layers: per-source SYN rate, per-prefix SYN rate, per-source connections, per-prefix connections, and per-port total connections.
  • Per-source and per-prefix UDP controls plus a global UDP byte-rate ceiling.
  • Trusted CIDRs, per-CIDR port ACLs, permanent ports, and listener-discovery exclusions.
  • Malformed TCP/UDP filtering, fragment drops, optional bogon filtering, ICMP echo rate limiting, and 6in4 endpoint validation.
  • Built-in GRE, ESP, and SCTP protocol handlers, plus custom IP-protocol and TCP/UDP-port BPF tail-call handlers.
  • Optional AbuseIPDB IPv4 threat intelligence, live counters, a terminal UI, and a line-delimited JSON event stream.
  • systemd/OpenRC services and transactional generation-based installs, updates, and rollback.

Compatibility boundaries

  • The current XDP backend probes for per-port ARRAY_OF_MAPS support and reports Linux 5.10+ when the probe fails. Older or restricted environments can use nftables.
  • Python 3.10 or newer is required.
  • Supported distribution families: Debian/Ubuntu, Fedora/RHEL, openSUSE, Arch, and Alpine.
  • Supported init systems: systemd and OpenRC.
  • Automatic interface selection excludes loopback, veth, and common container/CNI plumbing. Container interfaces require an explicit opt-in.
  • The AbuseIPDB integration is IPv4-only, disabled by default, and retains the previous map if a refresh fails.

Important paths

Purpose Default path
Main configuration /etc/auto_xdp/config.toml
Installed environment /etc/auto_xdp/auto_xdp.env
Interface selection/state /etc/auto_xdp/machine-state.json
Committed backend state /etc/auto_xdp/runtime-state.json
Install transaction /etc/auto_xdp/install-transaction.json
Active release /usr/local/lib/auto_xdp/current
Immutable releases /usr/local/lib/auto_xdp/releases/<generation>
Management command /usr/local/bin/axdp
BPF pins /sys/fs/bpf/xdp_fw
Runtime state /run/auto_xdp
Telemetry socket /var/run/auto_xdp/pkt_events.sock
Persistent custom handlers /etc/auto_xdp/handlers

Documentation baseline

This Wiki was checked against main commit a125c4e on 2026-09-02 and the complete configuration present in the working tree at that time. Where older README text conflicts with runtime probes or current code, this Wiki documents the implemented behavior.

Auto XDP documentation · Repository · Releases · MPL-2.0

Auto XDP

Clone this wiki locally