- Split TODO into a thin status index plus docs/roadmap/ with one file per task (v0.4 reliability, v0.5 product, v0.6 research, icebox). - Add docs/architecture.md (current processes, packet/data path, layers, storage, metrics) and docs/development.md (rules, gates, DoD). - Add CHANGELOG.md reconstructed from history; move round details out of TODO. - Align docs with the code: config defaults and missing [detect]/ [protocol.http] sections, XDP metric names, ClickHouse table and TTL, Redis RDB restore, multiarch clang include, CLI binary name. - Add scripts/check_docs_links.sh and run it in CI. - release profile: thin LTO + one codegen unit. Binary 12.3 MB -> 9.7 MB, http parser bench 314 ns -> 278 ns; panic=abort stays off for catch_unwind in the Redis subscriber. - Drop the unused JWT role claim; fix 'rampart doctor' hints in the CLI.
8.1 KiB
8.1 KiB
Runbook - Rampart
Пошаговые инструкции для админа в критических ситуациях.
1. DDoS атака — пошагово
# ── ШАГ 1: Подтвердить атаку ──
# Метрики edge ноды
curl -s http://EDGE_IP:9090/metrics | grep -E "rampart_(connections_total|rate_limit_hits|attack_status)"
# rampart_attack_status: 0 = normal, 1 = suspicious, 2 = under_attack
# (детектор по порогу pps, см. src/traffic/intel/detector.rs)
# ── ШАГ 2: Определить тип атаки ──
# Много SYN без завершения handshake → L3/L4, смотрим kernel/XDP
ss -s
# Много установленных коннектов с малым трафиком → slow-атака (L4)
# Много коннектов/сек с одних IP → connection flood
# ── ШАГ 3: Действия через конфиг (правка + рестарт) ──
# A) Connection flood → ужесточить per-IP лимиты в /etc/rampart/config.toml:
# [limits]
# rate_limit_pps = 2.0
# rate_limit_burst = 5.0
# max_connections_per_ip = 5
systemctl restart rampart
# B) Атака с известных подсетей → внести в blacklist через Manager API или CLI:
rampart-cli blacklist add 1.2.3.4 "ddos source"
rampart-cli blacklist list
# C) Доверенные IP (мониторинг, админы) → whitelist в config.toml
# (только IP-адреса), затем systemctl restart rampart
# D) Для Minecraft Java PoW не включай: он несовместим с протоколом.
# Проверь фильтрацию трафика у upstream game-proxy и его лимиты.
# ── ШАГ 4: Если не помогает ──
# В крайнем случае — закрыть порт на firewall и разбираться:
iptables -A INPUT -p tcp --dport 25565 -j DROP
# ── ШАГ 5: После атаки ──
# События атак пишутся в ClickHouse (если настроен clickhouse_url):
clickhouse-client --query "SELECT count() FROM rampart_events WHERE event_type='attack'"
# Написать post-mortem
Честно: hot-reload конфига не реализован — изменения применяются рестартом. ASN/CIDR-баны, GeoIP-блокировки стран и выбор типов challenge через CLI не реализованы; blacklist принимает цели в том виде, в котором их хранит Manager.
2. Сигналы деградации — что смотреть
| Метрика / лог | Что значит | Что делать |
|---|---|---|
rampart_connections_total{result="overloaded"} |
исчерпан глобальный бюджет соединений (4×workers×max_connections_per_ip) | проверить, не атака ли; при легитимной нагрузке — поднять max_connections_per_ip/workers.count |
rampart_xdp_dropped растёт, rampart_xdp_passed — нет |
XDP дропает всё | проверить protected_port_start/end, баны и счётчики stats_map (список — architecture.md §6); смотреть через bpftool |
rampart_clickhouse_dropped_total > 0 |
события не успевают уходить в ClickHouse | проверить доступность/латентность ClickHouse; события потеряны, защита работает |
rampart_xdp_whitelist растёт |
трафик от whitelist-адресов | норма, но если это неожиданно — проверить whitelist в конфиге |
лог global connection budget exhausted |
то же, что overloaded |
см. выше |
лог accept error ... backing off |
кончились fd (EMFILE) или память под сокеты |
поднять ulimit -n, проверить утечки соединений |
лог XDP filter attached ... (mode: generic (skb)) |
драйвер не умеет native XDP | ожидаемо для virtio/veth; generic дороже по CPU |
лог XDP .rodata map expects N bytes |
рассинхрон config.h и XdpGlobals |
это баг сборки: не запускать, сообщить с числами из лога |
Проверить, что XDP действительно снят после остановки демона:
bpftool net show dev eth0 # не должно быть xdp-программы
ip link show eth0 | grep xdp # пусто
Если программа осталась — это регрессия загрузчика, а не норма: снимать вручную
ip link set dev eth0 xdp off и заводить баг.
Команды
emergency,drainиconfig setпока не реализованы и завершатся явной ошибкой вместо изменения состояния.
3. Edge нода не стартует
systemctl status rampart
journalctl -u rampart -n 50 --no-pager
# Типичные причины:
# A) Порт занят
ss -tlnp | grep 25565
# B) Конфиг невалиден — проверь парсингом теста:
cargo test --test config_parse
# Или запусти вручную и прочитай ошибку:
RAMPART_CONFIG=/etc/rampart/config.toml /usr/local/bin/rampart
# C) Нет ни одного protocol handler
# Для Minecraft Java пересобери edge с --features protocol-minecraft и проверь
# секцию [protocol.minecraft]. Для HTTP используй --features protocol-http.
# Если активной protocol feature нет, edge завершится с ошибкой при запуске.
# D) XDP не загрузился
journalctl -u rampart | grep -i xdp
# Временное решение: [xdp] enabled = false в config.toml
4. XDP не загружается
systemd-detect-virt # openvz/lxc → XDP не работает, нужен KVM
uname -r # нужно 5.10+
ethtool -i eth0 | grep driver
# Проверить компиляцию BPF-программы:
clang -O2 -g -target bpf -I"/usr/include/$(gcc -print-multiarch)" \
-c xdp/core/universal_filter.c -o /tmp/universal_filter.o
# Отключить XDP:
# [xdp] enabled = false → systemctl restart rampart
5. Клиенты не могут подключиться
curl -s http://EDGE_IP:9090/metrics | grep rampart_connections
nc -zv EDGE_IP 25565 # порт открыт?
iptables -L INPUT -n -v | grep 25565
dig +short your.domain # DNS указывает на edge?
# NAT: много клиентов за одним IP упираются в max_connections_per_ip — увеличь.
6. Высокая нагрузка на edge
htop -p $(pgrep -d',' rampart)
iftop -i eth0 # pps/bandwidth
# Не хватает воркеров → [workers] count = vCPU, рестарт.
# CPU > 80% от userspace → включи XDP ([xdp] enabled = true),
# чтобы дропать мусор раньше, и ужесточи rate limit.
7. ClickHouse переполнен
df -h /var/lib/clickhouse
clickhouse-client --query "ALTER TABLE rampart_events MODIFY TTL timestamp + INTERVAL 90 DAY"
# Временное отключение записи: закомментируй clickhouse_url в config.toml, рестарт.
8. Краткий справочник команд
rampart-cli status # Общее состояние системы
rampart-cli doctor # Полная диагностика
rampart-cli blacklist add <target> [reason]
rampart-cli blacklist remove <target>
rampart-cli blacklist list
Полный список: rampart-cli --help (источник — src/bin/rampart-cli.rs).
Версия: 3.0 | Ноябрь 2026