guard/docs/runbook.md
loki5512344 da87d2a11f
test: move the last inline test modules to tests/, document new signals
- All remaining #[cfg(test)] modules left src/ (manager auth/heartbeat,
  protocol registry and HTTP parser, traffic hook/prefix/profile, TUI
  Prometheus); 41 tests moved into 10 integration suites with the same names
  and assertions, so `grep -rn '#[cfg(test)]' src/` is now empty.
- runbook.md: degradation signals (overloaded connections, ClickHouse drops,
  XDP drops, generic mode, EMFILE backoff) and how to verify XDP was detached.
- troubleshooting.md: accept backoff, orphaned XDP, password/JWT startup
  requirements, ClickHouse event loss.
- TODO: review round recorded as fixed/deferred.
2026-11-16 12:36:29 +01:00

174 lines
8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Runbook - Rampart
> Пошаговые инструкции для админа в критических ситуациях.
---
## 1. DDoS атака — пошагово
```bash
# ── ШАГ 1: Подтвердить атаку ──
# Метрики edge ноды
curl -s http://EDGE_IP:9090/metrics | grep -E "rampart_(connections|rate_limit|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_total` растёт, `passed_total` — нет | XDP дропает всё | проверить `protected_port_start/end`, баны и `xdp_feature_*`; смотреть `stats_map` через `bpftool` |
| `rampart_clickhouse_dropped_total` > 0 | события не успевают уходить в ClickHouse | проверить доступность/латентность ClickHouse; события потеряны, защита работает |
| `rampart_xdp_whitelist_total` растёт | трафик от 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 действительно снят после остановки демона:
```bash
bpftool net show dev eth0 # не должно быть xdp-программы
ip link show eth0 | grep xdp # пусто
```
Если программа осталась — это регрессия загрузчика, а не норма: снимать вручную
`ip link set dev eth0 xdp off` и заводить баг.
> Команды `emergency`, `drain` и `config set` пока не реализованы и завершатся
> явной ошибкой вместо изменения состояния.
## 2. Edge нода не стартует
```bash
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
```
## 3. XDP не загружается
```bash
systemd-detect-virt # openvz/lxc → XDP не работает, нужен KVM
uname -r # нужно 5.10+
ethtool -i eth0 | grep driver
# Проверить компиляцию BPF-программы:
clang -O2 -g -target bpf -c xdp/core/universal_filter.c -o /tmp/universal_filter.o
# Отключить XDP:
# [xdp] enabled = false → systemctl restart rampart
```
## 4. Клиенты не могут подключиться
```bash
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 — увеличь.
```
## 5. Высокая нагрузка на edge
```bash
htop -p $(pgrep -d',' rampart)
iftop -i eth0 # pps/bandwidth
# Не хватает воркеров → [workers] count = vCPU, рестарт.
# CPU > 80% от userspace → включи XDP ([xdp] enabled = true),
# чтобы дропать мусор раньше, и ужесточи rate limit.
```
## 6. ClickHouse переполнен
```bash
df -h /var/lib/clickhouse
clickhouse-client --query "ALTER TABLE rampart.events MODIFY TTL ts + INTERVAL 90 DAY"
# Временное отключение записи: закомментируй clickhouse_url в config.toml, рестарт.
```
## 7. Краткий справочник команд
```bash
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).
---
*Версия: 2.0 | Август 2026*