Installation and Upgrade

Installation, Upgrade, and Compatibility

Requirements

Item	Requirement
Operating system	Linux
Python	3.10+
XDP kernel capability	Per-port map-in-map support; normally Linux 5.10+
Fallback backend	nftables
Init system	systemd or OpenRC
Privileges	Start as a normal user; the installer invokes sudo only when needed

Supported package managers are apt-get, dnf/yum, zypper, pacman, and apk. The installer checks or installs clang/LLVM, libbpf headers, bpftool, iproute2 and tc, nftables, Python, psutil, curses, curl, tar, and build tools.

Older README text says kernel 5.8+, based on BPF ring-buffer availability. The current implementation also requires per-port ARRAY_OF_MAPS inner maps and explicitly reports 5.10+ when its runtime capability probe fails. Use 5.10+ as the current XDP baseline.

Install the latest release

Check GitHub Releases first. This example uses the latest release when this page was written, v26.8.13a:

(
  set -e
  AUTO_XDP_VERSION=v26.8.13a
  auto_xdp_tmp=$(mktemp -d)
  trap 'rm -rf "$auto_xdp_tmp"' EXIT
  curl --proto '=https' --proto-redir '=https' --tlsv1.2 -sSfL \
    "https://github.com/Kookiejarz/Auto_XDP/archive/refs/tags/${AUTO_XDP_VERSION}.tar.gz" \
    | tar -xz -C "$auto_xdp_tmp" --strip-components=1
  cd "$auto_xdp_tmp"
  bash setup_xdp.sh
)

The project deliberately rejects an unqualified direct curl | bash path. Downloading a tagged archive lets the complete source tree be staged and validated before privilege escalation.

Install from source

git clone https://github.com/Kookiejarz/Auto_XDP.git
cd Auto_XDP

# Automatically select active host ingress interfaces
bash setup_xdp.sh

# Protect explicit interfaces
bash setup_xdp.sh eth0
bash setup_xdp.sh eth0 eth1

# Protect all active non-loopback host interfaces
bash setup_xdp.sh --all-interfaces

# Inspect without changing the host
bash setup_xdp.sh --check-env
bash setup_xdp.sh --dry-run

To select a container/veth interface explicitly, add --allow-container-interfaces or set interfaces.allow_container = true. Loopback is never attachable.

Installer options

Option	Meaning
--check-update	Compare installed/local files with GitHub by SHA-256 and offer an update.
--force	Skip replacement/update confirmations.
--check-env	Print detected distro, package manager, and init system, then exit.
--dry-run	Print planned actions without changing the host.
--all-interfaces / -a	Select all active non-loopback, non-container host interfaces.
--allow-container-interfaces	Permit explicitly included container-classified interfaces.

What installation does

1. Acquires /run/auto_xdp/install.lock and repairs an interrupted transaction when possible.
2. Detects the distribution, package manager, init system, and target interfaces.
3. Preserves an existing /etc/auto_xdp/config.toml, or creates it on first install.
4. Compiles XDP, tc, socket-state tracepoint, and built-in handler objects in staging.
5. Builds an immutable /usr/local/lib/auto_xdp/releases/<generation> and validates shell, Python, and BPF map ABI contracts.
6. Creates a candidate BPF pin generation, pre-seeds allowed ports and active TCP state, then switches XDP and tc attachments.
7. If XDP is unavailable, builds and atomically validates an nftables policy before switching.
8. Installs and starts xdp-port-sync and auto-xdp-relay under systemd or OpenRC.
9. Commits the generation only after backend and policy checks pass; otherwise it preserves or restores the previous protection.

Interface and XDP mode selection

The [interfaces] table controls persistent selection:

• mode = "auto": choose UP host ingress interfaces.
• include = ["eth0", "eth1"]: use an explicit stable list.
• exclude = ["eth1"]: omit interfaces managed elsewhere.
• allow_container = false: reject veth and common Docker/CNI/Podman interfaces.
• xdp_mode = "auto": retry the last verified mode first, then the other mode.
• xdp_mode = "native" or "generic": require that mode on every selected interface.

Per-interface mode, program ID, and tc egress state are stored in machine-state.json. The active backend, overall mode, generation, fallback reason, and health are stored in runtime-state.json.

Backend selection

[daemon].preferred_backend accepts:

• auto: retain a healthy committed backend; otherwise try XDP and then nftables.
• xdp: request XDP. Always verify the actual result with axdp backend because attachment or safety checks can still force a fallback path.
• nftables: use nftables directly.

XDP availability checks privileges, bpffs, required objects/maps, map-in-map support, and attachment health. During a change to nftables, the complete candidate table is installed and verified before XDP is detached. If cutover fails, the current protection is retained.

Verify installation

sudo axdp status
sudo axdp backend
sudo axdp ports
sudo axdp stats

systemd:

systemctl status xdp-port-sync auto-xdp-relay
journalctl -u xdp-port-sync -u auto-xdp-relay --since today

OpenRC:

rc-service xdp-port-sync status
rc-service auto-xdp-relay status

Upgrade

sudo axdp check-update
sudo axdp check-update --force

Or reinstall from a new checkout:

bash setup_xdp.sh --force

Updates use immutable generations and an atomic current symlink. The install transaction records the previous generation, candidate generation, and switch phase. If startup detects an interrupted switch, it attempts to restore the previous current target.

Existing config.toml is preserved. New keys omitted from an older configuration use code defaults, so compare your configuration with the current repository sample after upgrading.

Inspect the installed generation

readlink -f /usr/local/lib/auto_xdp/current
sudo axdp backend
sudo cat /etc/auto_xdp/runtime-state.json
sudo cat /etc/auto_xdp/machine-state.json