feat(xdp): IPv6 UDP rate limit, working loader; English comments and docs

XDP behaviour:
- udp_rate_limit6 (LRU, full 128-bit source key) plus throttle_hit6, so
  udp_policy = "rate-limit" applies to native IPv6 as well.
- scripts/xdp_ipv6_smoke.sh: phase 4 patches .rodata before load and
  verifies policy=2 on a real kernel (3 pass / 3 rate-limited).

Loader (XDP could never load before this):
- .rodata is one struct rampart_config with frozen offsets enforced by
  _Static_assert; XdpGlobals is #[repr(C)] and the image is built with
  offset_of!. Before, a 96-byte image was written into a 76-byte map at
  offsets clang had reordered, so load() failed with EINVAL.
- patch_rodata fails loudly when the map size and image size diverge.
- build.rs tracks xdp/core and xdp/hooks, not just universal_filter.c.
- build_ringbuf looked for "events_map"; the map is "events_ringbuf".
- tests/xdp_object_maps.rs checks map names and .rodata size without root.

Docs and style:
- Code comments are English, JavaDoc/Rustdoc style, without emoji or
  banners (new project rule, TODO §0.8).
- README rewritten bilingual: Russian first, English below, nav buttons,
  compact TOC and copy-paste quick start.
- docs/README.md: documentation index and maintenance rules;
  configuration.md documents the whole [xdp] section and IPv4/IPv6
  coverage; testing.md covers the real-kernel smoke; stale links removed.
This commit is contained in:
Loki 2026-11-15 23:50:52 +01:00
parent b64c329125
commit a8a3057719
Signed by: boba
GPG key ID: 6CDE87BC9A778D97
104 changed files with 2155 additions and 1030 deletions

View file

@ -1,17 +1,20 @@
#!/usr/bin/env bash
# Функциональный smoke XDP-банов на РЕАЛЬНОМ ядре (netns + veth + verifier).
# Functional smoke test of XDP bans on a real kernel (netns + veth + verifier).
#
# Что проверяет:
# 1. verifier принимает universal_filter.o;
# 2. native-IPv6 без бана проходит, с записью /128 в blacklist6_map — дропается;
# 3. короткая UDP-датаграмма (<20 байт L4) тоже дропается — раньше она уходила
# в XDP_PASS мимо blacklist (проверка длины была рассчитана на TCP);
# 4. то же для IPv4 (общий L4-гейт);
# 5. expiry: бан с монотонным TTL реально истекает в ядре (раньше userspace
# писал epoch-ns, а C сравнивал с bpf_ktime_get_ns() — бан жил вечно).
# What it verifies:
# 1. the verifier accepts universal_filter.o;
# 2. native IPv6 traffic passes without a ban and is dropped once a /128
# entry exists in blacklist6_map;
# 3. a short UDP datagram (under 20 bytes of L4) is dropped as well; it used
# to fall through to XDP_PASS past the blacklist because the length check
# was sized for TCP;
# 4. the same holds for IPv4, through the shared L4 gate;
# 5. expiry: a ban with a monotonic TTL really expires in the kernel; it
# used to live forever because userspace wrote epoch-ns while the C side
# compared against bpf_ktime_get_ns().
#
# Требует root/CAP_BPF+CAP_NET_ADMIN, bpftool, clang, python3.
# Запуск: sudo bash scripts/xdp_ipv6_smoke.sh
# Requires root/CAP_BPF+CAP_NET_ADMIN, bpftool, clang, python3.
# Run: sudo bash scripts/xdp_ipv6_smoke.sh
set -u
@ -30,6 +33,7 @@ PASS=1
fail() { echo "FAIL: $1"; PASS=0; }
ok() { echo "ok: $1"; }
# Detach and remove every artefact, so a rerun starts from a clean state.
cleanup() {
bpftool net detach xdp dev "$DEV0" 2>/dev/null
rm -f "$PIN" "$OBJ"
@ -41,11 +45,13 @@ trap cleanup EXIT
[ "$(id -u)" = 0 ] || { echo "нужен root (CAP_BPF+CAP_NET_ADMIN)"; exit 2; }
cd "$(dirname "$0")/.." || exit 2
# Build the object once; the same binary is reused for every phase below.
clang -O2 -g -target bpf -mcpu=v3 -c xdp/core/universal_filter.c -o "$OBJ" \
-Ixdp -Ixdp/core -Ixdp/hooks -I/usr/include/x86_64-linux-gnu \
|| { echo "clang: не собралось"; exit 1; }
ok "clang: universal_filter.c собран"
# Isolated namespace with one veth pair: host side is DEV0, peer is DEV1.
ip netns add "$NS" || { echo "не удалось создать netns"; exit 2; }
ip link add "$DEV0" type veth peer name "$DEV1" || exit 2
ip link set "$DEV1" netns "$NS"
@ -58,36 +64,43 @@ ip -n "$NS" link set "$DEV1" up
ip -n "$NS" link set lo up
ok "netns $NS + veth ($HOST6/$HOST4 <-> $NS6/$NS4)"
# Loading through the verifier is itself a check: a rejected program exits here.
bpftool prog load "$OBJ" "$PIN" type xdp || { echo "verifier отверг программу"; exit 1; }
bpftool net attach xdp pinned "$PIN" dev "$DEV0" || exit 1
ok "verifier принял программу, attach на $DEV0"
IDS=$(bpftool prog show pinned "$PIN" | grep -o 'map_ids [0-9,]*' | cut -d' ' -f2 | tr ',' ' ')
B4=""
B6=""
ST=""
for id in $IDS; do
desc=$(bpftool map show id "$id" 2>/dev/null)
case "$desc" in
*"name blacklist6_map"*) B6=$id ;;
*"name blacklist_map"*) B4=$id ;;
*"name stats_map"*) ST=$id ;;
esac
done
[ -n "$B4" ] && [ -n "$B6" ] && [ -n "$ST" ] || { echo "карты не найдены"; exit 1; }
# Resolve map ids from the pinned program; ids change on every load.
discover_maps() {
IDS=$(bpftool prog show pinned "$PIN" | grep -o 'map_ids [0-9,]*' | cut -d' ' -f2 | tr ',' ' ')
B4=""
B6=""
ST=""
for id in $IDS; do
desc=$(bpftool map show id "$id" 2>/dev/null)
case "$desc" in
*"name blacklist6_map"*) B6=$id ;;
*"name blacklist_map"*) B4=$id ;;
*"name stats_map"*) ST=$id ;;
esac
done
[ -n "$B4" ] && [ -n "$B6" ] && [ -n "$ST" ]
}
discover_maps || { echo "карты не найдены"; exit 1; }
ok "blacklist_map id=$B4, blacklist6_map id=$B6, stats_map id=$ST"
# Ключи LPM: prefixlen (u32 LE) + адрес в network order.
# LPM keys: prefixlen (u32 LE) followed by the address in network order.
KEY6="80 00 00 00 fd 00 00 00 00 00 00 00 00 00 00 00 00 00 00 02"
KEY4="20 00 00 00 0a 63 00 02"
send6() { # $1 = размер payload
# Send one IPv6 UDP datagram of $1 payload bytes from inside the namespace.
send6() {
ip netns exec "$NS" python3 -c "
import socket
s = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM)
s.sendto(b'x' * $1, ('$HOST6', $PORT))
"
}
# Same for IPv4.
send4() {
ip netns exec "$NS" python3 -c "
import socket
@ -96,7 +109,7 @@ s.sendto(b'x' * $1, ('$HOST4', $PORT))
"
}
# Суммы per-CPU счётчиков (только ненулевые).
# Sum the per-CPU counters and print only the non-zero ones.
stats() {
bpftool -j map dump id "$ST" | python3 -c "
import json, sys
@ -110,9 +123,11 @@ for e in json.load(sys.stdin):
print(' '.join(f'{k}={v}' for k, v in out.items() if v) or 'все нули')
"
}
# Read a single counter value; empty output means the counter is zero.
metric() { stats | tr ' ' '\n' | sed -n "s/^$1=//p" | head -1; }
mono_ns_hex() { # монотонные ns + $1 секунд, 8 байт little-endian
# Monotonic now + $1 seconds as 8 little-endian bytes, the kernel's ban TTL format.
mono_ns_hex() {
python3 -c "
import time
ns = time.clock_gettime_ns(time.CLOCK_MONOTONIC) + $1 * 1_000_000_000
@ -120,7 +135,7 @@ print(' '.join(f'{b:02x}' for b in ns.to_bytes(8, 'little')))
"
}
# ── Фаза 1: IPv6 ──
# Phase 1: IPv6 — traffic passes, a ban drops it, removing the ban restores it.
pass0=$(metric pass)
for _ in 1 2 3; do send6 100; done
sleep 0.5
@ -132,7 +147,7 @@ pass1=$(metric pass)
drop0=$(metric drop)
bpftool map update id "$B6" key hex $KEY6 value hex ff ff ff ff ff ff ff ff || fail "v6 map update"
for _ in 1 2 3; do send6 100; done
for _ in 1 2 3; do send6 1; done # короткая датаграмма
for _ in 1 2 3; do send6 1; done # short datagram
sleep 0.5
drop1=$(metric drop)
[ "${drop1:-0}" -ge $((${drop0:-0} + 6)) ] \
@ -148,10 +163,11 @@ pass3=$(metric pass)
&& ok "v6 после снятия бана проходит (pass $pass2 -> $pass3)" \
|| fail "v6 после снятия бана не проходит ($(stats))"
# ── Фаза 2: IPv4 (общий L4-гейт) ──
# Phase 2: IPv4 through the shared L4 gate — only short datagrams, which is
# the min_l4 regression.
drop0=$(metric drop)
bpftool map update id "$B4" key hex $KEY4 value hex ff ff ff ff ff ff ff ff || fail "v4 map update"
for _ in 1 2 3; do send4 1; done # только короткие — регрессия на min_l4
for _ in 1 2 3; do send4 1; done # short datagrams only — the min_l4 regression
sleep 0.5
drop1=$(metric drop)
[ "${drop1:-0}" -ge $((${drop0:-0} + 3)) ] \
@ -159,7 +175,8 @@ drop1=$(metric drop)
|| fail "v4 короткая датаграмма прошла мимо бана ($(stats))"
bpftool map delete id "$B4" key hex $KEY4 || fail "v4 map delete"
# ── Фаза 3: expiry бана (монотонные часы) ──
# Phase 3: ban expiry on the monotonic clock. A TTL written in epoch-ns would
# never expire against bpf_ktime_get_ns(), so this phase pins the clock choice.
TTL=2
bpftool map update id "$B6" key hex $KEY6 value hex $(mono_ns_hex $TTL) || fail "expiry update"
drop0=$(metric drop)
@ -179,5 +196,47 @@ drop3=$(metric drop); pass3=$(metric pass)
&& ok "бан истёк по монотонным часам (pass $pass2 -> $pass3, drop $drop2 -> $drop3)" \
|| fail "бан не истёк (pass $pass2 -> $pass3, drop $drop2 -> $drop3)"
[ "$PASS" = 1 ] && echo "PASS: XDP-баны (v4/v6, короткий L4, expiry) работают на живом ядре" || echo "FAIL"
[ "$PASS" = 1 ]
# Phase 4: UDP rate-limit (policy=2) for native IPv6.
# Policy is a .rodata global and libbpf freezes .rodata after load, so the
# object section is patched before loading. The offsets are pinned by the
# _Static_asserts in xdp/core/config.h: udp_policy @49, udp_hit_count @52.
POBJ="$OBJ.rl"
cp "$OBJ" "$POBJ"
if llvm-objcopy --dump-section .rodata="$POBJ.rodata" "$POBJ" \
&& python3 - "$POBJ.rodata" <<'PY' \
&& llvm-objcopy --update-section .rodata="$POBJ.rodata" "$POBJ"
import sys
path = sys.argv[1]
img = bytearray(open(path, "rb").read())
assert len(img) >= 56, f"unexpected .rodata size {len(img)}"
img[49] = 2 # G_UDP_POLICY = rate-limit
img[52:56] = (3).to_bytes(4, "little") # G_UDP_HIT_COUNT = 3 (fast trigger)
open(path, "wb").write(img)
PY
then
# Reload with the patched policy; map ids are invalidated by the reload.
ip link set "$DEV0" xdp off 2>/dev/null
rm -f "$PIN"
if bpftool prog load "$POBJ" "$PIN" type xdp \
&& bpftool net attach xdp pinned "$PIN" dev "$DEV0"; then
if discover_maps; then
rl0=$(metric rate); pass0=$(metric pass)
for _ in 1 2 3 4 5 6; do send6 100; done
sleep 0.3
rl1=$(metric rate); pass1=$(metric pass)
[ "${rl1:-0}" -gt "${rl0:-0}" ] && [ "${pass1:-0}" -gt "${pass0:-0}" ] \
&& ok "v6 UDP rate-limit policy=2 (rate $rl0 -> $rl1, pass $pass0 -> $pass1)" \
|| fail "v6 UDP rate-limit не срабатывает ($(stats))"
else
fail "карты не найдены после перезагрузки с policy=2"
fi
else
fail "объект с policy=2 не загрузился"
fi
rm -f "$POBJ" "$POBJ.rodata"
else
fail "не удалось пропатчить .rodata (policy=2)"
fi
[ "$PASS" = 1 ] && echo "PASS: XDP-баны и UDP rate-limit (v4/v6) работают на живом ядре" || echo "FAIL"
[ "$PASS" = 1 ]

View file

@ -1,18 +1,20 @@
#!/usr/bin/env bash
# netns+veth smoke-тест XDP-пути на РЕАЛЬНОМ ядре (вывод №7 конкурентного анализа).
# netns + veth smoke test of the XDP path on a real kernel (finding #7 of the
# concurrency analysis).
#
# Проверяет то, что невозможно проверить в контейнере CI без CAP_BPF:
# 1. verifier принимает universal_filter.o (загрузка через libbpf);
# 2. attach на живом интерфейсе в netns, native-режим;
# 3. легитимный HTTP проксируется;
# 4. SYN-флуд порождает ringbuf-события -> opt-in auto-ban работает;
# 5. по завершении бана трафик восстанавливается (expiry);
# 6. после SIGTERM XDP-ПРОГРАММА РЕАЛЬНО ОТВЯЗАНА (регрессия на bug fd=-1).
# Covers what cannot be checked in a CI container without CAP_BPF:
# 1. the verifier accepts universal_filter.o (loaded through libbpf);
# 2. attach on a live interface inside a netns, native mode;
# 3. legitimate HTTP is proxied;
# 4. a SYN flood produces ringbuf events, so opt-in auto-ban works;
# 5. traffic recovers once the ban expires;
# 6. after SIGTERM the XDP program is really detached (regression on the
# fd=-1 bug).
#
# Запуск: на хосте с root/CAP_BPF (VDS или VM-раннер CI), не в контейнере:
# Run: on a host with root/CAP_BPF (VDS or a VM CI runner), not in a container:
# BIN=./target/release/rampart bash scripts/xdp_netns_smoke.sh
#
# Требования: iproute2, bpftool, hping3, python3 (http.server), curl.
# Requires: iproute2, bpftool, hping3, python3 (http.server), curl.
set -u
@ -32,6 +34,7 @@ PASS=1
fail() { echo "FAIL: $1"; PASS=0; }
ok() { echo "ok: $1"; }
# Kill both processes and drop the namespace, whatever the exit path was.
cleanup() {
[ -n "$RAMPID" ] && kill -9 "$RAMPID" 2>/dev/null
[ -n "$SRVPID" ] && kill -9 "$SRVPID" 2>/dev/null
@ -43,7 +46,8 @@ trap cleanup EXIT
[ "$(id -u)" = 0 ] || { echo "нужен root (CAP_BPF+CAP_NET_ADMIN)"; exit 2; }
[ -x "$BIN" ] || { echo "бинарь не найден: $BIN"; exit 2; }
# --- 1. netns + veth: весь тест изолирован, прод-трафик не затрагивается ---
# Phase 1: netns plus veth, so the whole test is isolated and production
# traffic is never touched.
ip netns del "$NS" 2>/dev/null
ip netns add "$NS" || { echo "не удалось создать netns"; exit 2; }
ip link add rth0 type veth peer name rtap
@ -54,7 +58,8 @@ ip -n "$NS" link set rtap up
ip -n "$NS" link set lo up
ok "netns $NS + veth подняты"
# --- 2. конфиг edge: узкий защищённый диапазон, автобан включён (иначе нечего тестить) ---
# Phase 2: edge config. The protected range is a single port and auto-ban is
# on, otherwise there is nothing to observe.
cat > "$WORK/edge.toml" <<EOF
[bind]
address = "$EDGE_IP"
@ -94,13 +99,13 @@ format = "text"
enabled = false
EOF
# --- 3. origin на host-половине veth ---
# Phase 3: origin server on the host half of the veth pair.
echo "<html><body>rampart-smoke-origin</body></html>" > "$WORK/index.html"
python3 -m http.server "$ORIGIN_PORT" --bind "$HOST_IP" -d "$WORK" >/dev/null 2>&1 &
SRVPID=$!
sleep 0.5
# --- 4. старт edge внутри netns, ожидание attach ---
# Phase 4: start edge inside the namespace and wait for the attach log line.
RUST_LOG=rampart=debug RAMPART_CONFIG="$WORK/edge.toml" \
ip netns exec "$NS" "$BIN" > "$WORK/rampart.log" 2>&1 &
RAMPID=$!
@ -116,8 +121,8 @@ else
fail "XDP не аттачнулся; лог:"; sed -n '1,30p' "$WORK/rampart.log"; exit 1
fi
# Режим attach: native ожидаем на veth, но fallback на generic — штатный
# путь лестницы в load(); сверяем с честным логом режима от rampart.
# Attach mode: native is expected on veth, but generic is a normal fallback in
# the load() ladder, so compare against the mode rampart actually reports.
if ip -n "$NS" link show rtap | grep -qE "xdp( |$)"; then
ok "attach native (ip link: xdp)"
elif ip -n "$NS" link show rtap | grep -q "xdpgeneric"; then
@ -127,13 +132,13 @@ else
fi
grep -oE "mode: [a-z ()]+" "$WORK/rampart.log" | tail -1
# --- 5. легитимный HTTP проходит прокси ---
# Phase 5: a legitimate HTTP request must reach the origin through the proxy.
BODY=$(curl -s --max-time 5 "http://$EDGE_IP:$EDGE_PORT/" || true)
echo "$BODY" | grep -q "rampart-smoke-origin" \
&& ok "легитимный HTTP проксируется" \
|| fail "легитимный HTTP не дошёл до origin"
# --- 6. SYN-флуд -> throttle -> ringbuf events -> auto-ban ---
# Phase 6: SYN flood, then throttle, ringbuf events and auto-ban.
hping3 -S -p "$EDGE_PORT" -c 4000 -i u200 "$EDGE_IP" >/dev/null 2>&1 || true
sleep 3
grep -q "xdp event" "$WORK/rampart.log" \
@ -149,20 +154,21 @@ BANS=$(ip netns exec "$NS" curl -s --max-time 2 "http://127.0.0.1:$METRICS_PORT/
[ "${BANS:-0}" != "0" ] && ok "метрика rampart_xdp_autobans_total=$BANS" \
|| fail "метрика autobans пуста"
# забаненный источник отклоняется до истечения 5с
# A banned source is refused while the ban is active.
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 2 "http://$EDGE_IP:$EDGE_PORT/" || echo "err")
[ "$HTTP_CODE" = "err" ] || [ "$HTTP_CODE" = "000" ] \
&& ok "забаненный клиент отклонён (http=$HTTP_CODE)" \
|| fail "забаненный клиент получил ответ ($HTTP_CODE)"
# --- 7. expiry: через 7с (> ban 5s) трафик возвращается ---
# Phase 7: expiry. After 7s (ban is 5s) traffic must come back on its own.
sleep 7
BODY=$(curl -s --max-time 5 "http://$EDGE_IP:$EDGE_PORT/" || true)
echo "$BODY" | grep -q "rampart-smoke-origin" \
&& ok "бан истёк, легитимный трафик восстановлен" \
|| fail "после expiry трафик не восстановился"
# --- 8. ГРЕЙСФУЛ СТОП -> ПРОГРАММА ОТВЯЗАНА (регрессия на borrow_raw(-1)) ---
# Phase 8: graceful stop must leave no program behind (regression on
# borrow_raw(-1) during detach).
kill -TERM "$RAMPID"
wait "$RAMPID"; RC=$?
RAMPID=""
@ -176,7 +182,7 @@ else
ok "XDP-программа реально отвязана после SIGTERM"
fi
# --- итог ---
# Summary: exit code drives CI, the log excerpt makes a failure diagnosable.
echo
if [ "$PASS" = 1 ]; then
echo "PASS — xdp netns smoke ($(uname -r))"