Configuration Reference

Configuration Reference

The main configuration is /etc/auto_xdp/config.toml.

sudo axdp config show
sudo axdp config init
sudoedit /etc/auto_xdp/config.toml
sudo axdp restart

The axdp trust, acl, permanent, exclude, log-level, under-attack, slot, and port-handler commands rewrite TOML atomically and signal the daemon. Direct editor changes are not file-watched: send SIGHUP to the sync daemon or run sudo axdp restart afterward.

If a reload cannot be parsed, the daemon retains the previous in-memory configuration. Changes to the BPF pin directory, nftables family/table, or backend preference cause the backend to be reopened.

Minimal example

[firewall]
bogon_filter = true

[daemon]
log_level = "warning"
debounce_seconds = 0.4
preferred_backend = "auto"

[interfaces]
mode = "auto"
include = []
exclude = []
allow_container = false
xdp_mode = "auto"

[discovery]
exclude_loopback = true
exclude_bind_cidrs = []
exclude_ports = []

[permanent_ports]
tcp = [22, 443]
udp = []
sctp = []

[slots]
default_action = "drop"
enabled = []

[firewall]

Key	Type/default	Meaning
bogon_filter	bool / code default true	Drop clearly reserved or spoofed source ranges. Disable on ingress paths where private source ranges are legitimate.

Repository deployment samples can deliberately set this to false; a sample value and the compiled fallback are not the same thing.

[under_attack]

Key	Type/default	Meaning
enabled	bool / false	Disable XDP drop-event emission to reduce flood-path overhead. Filtering and counters remain active.

Prefer axdp under-attack on|off for live changes.

[daemon]

Key	Type/default	Meaning
log_level	`debug	info
debounce_seconds	positive number / 0.4	Coalescing window for process/socket events.
preferred_backend	`auto	xdp

Debouncing applies only to event-triggered work; periodic safety reconciliation remains independent.

[interfaces]

Key	Default	Meaning
mode	auto	Automatic selection; use include for a fixed set.
include	[]	Explicit interface names.
exclude	[]	Interfaces managed elsewhere. A name cannot be in both lists.
allow_container	false	Allow explicitly selected container/virtual interfaces. Loopback remains forbidden.
xdp_mode	auto	auto, strict native, or strict generic.

Automatic selection excludes loopback, veth/dummy/ifb, common Docker/CNI/Flannel/Calico/Podman names, and container bridges. Bonds, VLANs, and ordinary bridges remain eligible host ingress interfaces.

[ringbuf]

Key	Installed-template default	Meaning
socket_path	/var/run/auto_xdp/pkt_events.sock	Relay Unix stream socket.
retention_seconds	300	Age limit for relay history.
max_events	100000	Maximum events retained in relay memory. Older samples may use 10000.
max_history_send	5000	Maximum history items sent to a new client.
tui_max_events	500	TUI-local event scrollback.

[discovery]

Key	Default	Meaning
exclude_loopback	true	Ignore listeners bound only to 127.0.0.0/8 or ::1.
exclude_bind_cidrs	[]	Ignore listeners bound only to these local addresses/networks.
exclude_ports	[]	Never auto-discover these port numbers.

[discovery]
exclude_loopback = true
exclude_bind_cidrs = ["10.0.0.0/8", "fd00::/8"]
exclude_ports = [3306, 6379]

These settings affect discovery only. A permanent port remains admitted.

[permanent_ports]

[permanent_ports]
tcp = [22, 443]
udp = [51820]
sctp = [5060]

Ports must be 1–65535. SCTP admission comes only from this table.

[trusted_ips]

Keys are CIDRs and values are labels:

[trusted_ips]
"203.0.113.5/32" = "monitoring"
"2001:db8:1234::/48" = "office-v6"

CIDRs are normalized with non-strict network parsing. See Security Policies and Rate Limits before granting broad trust.

[[acl]]

[[acl]]
proto = "tcp"
cidr = "198.51.100.0/24"
ports = [5432, 6379]

[[acl]]
proto = "udp"
cidr = "2001:db8:5::/64"
ports = [53]

• proto is tcp or udp.
• Ports are 1–65535.
• One rule supports at most 64 ports.
• The CLI merges entries with the same protocol and CIDR.

[rate_limits]

Source grouping and inner-map capacity

Key	Code default	Range/meaning
source_cidr_v4	32	0–32 source aggregation prefix. Legacy alias: source_prefix_v4.
source_cidr_v6	128	0–128. Legacy alias: source_prefix_v6.
map_entries_v4	16384	IPv4 rate-state inner LRU capacity per enabled port.
map_entries_v6	4096	IPv6 capacity per enabled port.

[rate_limits.map_entries_by_proc] and [rate_limits.map_entries_by_service] override capacity for matching ports.

TCP policy tables

Table	Value meaning
syn_by_proc	Per-source SYN/s, matched by owning process first.
syn_by_service	Per-source SYN/s fallback using /etc/services.
syn_agg_by_proc	Per-source-prefix SYN/s.
syn_agg_by_service	Prefix SYN/s fallback.
tcp_conn_by_proc	Concurrent established connections per source.
tcp_conn_by_service	Per-source connection fallback.
tcp_conn_prefix_by_proc	Established connections per source prefix.
tcp_conn_prefix_by_service	Prefix connection fallback.
tcp_conn_port_by_proc	Total established connections on the port.
tcp_conn_port_by_service	Per-port total fallback.

Process names come from the socket owner in /proc; service names come from the local /etc/services. If neither matches, the default-on tier in [xdp.runtime] applies.

UDP policy tables

Table	Value meaning
udp_by_proc	Per-source UDP packets/s.
udp_by_service	Packet-rate fallback.
udp_agg_bytes_by_proc	Per-source-prefix UDP bytes/s.
udp_agg_bytes_by_service	Prefix byte-rate fallback.

Example:

[rate_limits]
source_cidr_v4 = 24
source_cidr_v6 = 64
map_entries_v4 = 16384
map_entries_v6 = 4096

[rate_limits.syn_by_proc]
sshd = 2
caddy = 500

[rate_limits.udp_by_service]
domain = 5000
ntp = 500

[tunnel]

[tunnel]
sit4_endpoints = ["216.218.226.238"]

Entries must be IPv4 addresses. IPv4 protocol 41 from any other source is dropped.

[slots]

[slots]
default_action = "drop"
enabled = [
  "sctp",
  "gre",
  { proto = 50, path = "/etc/auto_xdp/handlers/custom_esp.o" },
]

• default_action: pass or drop on a missing protocol slot. Invalid values become drop.
• Built-ins: gre, esp, and sctp.
• Custom entries use protocol 0–255 and a .o path. The CLI can also compile .c inputs before persisting them.

[port_handlers.tcp] and [port_handlers.udp]

[port_handlers.tcp]
"25565" = "/etc/auto_xdp/handlers/minecraft_handler.o"

[port_handlers.udp]
"53" = "/etc/auto_xdp/handlers/dns_validate.o"

Keys are destination port strings. Port handlers are XDP-only.

[abuseipdb]

Key	Default	Meaning
enabled	false	Enable XDP IPv4 blocklist synchronization.
sources	["s1003d"]	100%-confidence window keys.
refresh_seconds	3600	Refresh interval; minimum 60 seconds.
base_url	borestad GitHub raw URL	Advanced source-base override.

Available source keys: s1001d, s1003d, s1007d, s10014d, s10030d, s10060d, s10090d, and s100120d.

[xdp]

Key	Default	Meaning
bpf_pin_dir	/sys/fs/bpf/xdp_fw	BPF pin root. Changing it rebuilds the backend.
conntrack_stale_reconciles	2	Consecutive missing observations before userspace cleans seeded state. Must be positive.

[xdp.runtime]

Duration values accept 0 to use the BPF program's compiled fallback.

Key	Code default	Meaning
tcp_timeout_seconds	300	Established TCP idle TTL.
udp_timeout_seconds	60	UDP return-flow TTL.
conntrack_refresh_seconds	30	Minimum timestamp refresh interval.
conntrack_gc_interval_seconds	300	Full conntrack GC interval; 0 disables.
syn_timeout_seconds	30	Pending/half-open SYN TTL. Some deployment samples use 20.
icmp_burst_packets	100	ICMP echo token-bucket burst.
icmp_rate_pps	100	Sustained ICMP echo rate.
udp_global_window_seconds	1	Global UDP accounting window.
udp_global_byte_rate_mbps	0	Aggregate UDP ceiling; 0 disables. Deployment samples may set a nonzero value.
rate_window_seconds	1	Per-source/per-prefix SYN and UDP window.
sensitive_port_threshold	5	An explicit SYN rate at or below this value selects the strict tier.
default_tcp_syn_rate_strict	5	Strict per-source SYN/s.
default_tcp_syn_rate	100	Normal per-source SYN/s.
default_tcp_syn_agg_rate_strict	50	Strict per-prefix SYN/s.
default_tcp_syn_agg_rate	1000	Normal per-prefix SYN/s.
default_tcp_established_per_src_strict	5	Strict per-source established connections.
default_tcp_established_per_src	50	Normal per-source connections.
default_tcp_established_per_prefix_strict	20	Strict per-prefix connections.
default_tcp_established_per_prefix	200	Normal per-prefix connections.
default_tcp_established_per_port_strict	200	Strict total connections per port.
default_tcp_established_per_port	5000	Normal total connections per port.

[nftables]

Key	Default	Meaning
family	inet	inet, ip, or ip6.
table	auto_xdp	Table owned exclusively by Auto XDP.

Do not place unrelated administrator rules in this table; reconciliation replaces it as one complete transaction.

Validate a configuration change

sudo axdp restart
sudo axdp backend
sudo axdp ports
sudo journalctl -u xdp-port-sync -n 100 --no-pager

Test both allowed and denied traffic from another host. Loopback, existing conntrack state, and cloud security groups can hide mistakes.