guard/docs/runbook.md
loki5512344 280284667f
docs: per-task roadmap, architecture and changelog
- 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.
2026-11-16 14:51:50 +01:00

175 lines
8.1 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_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](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 действительно снят после остановки демона:
```bash
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 нода не стартует
```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
```
## 4. XDP не загружается
```bash
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. Клиенты не могут подключиться
```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 — увеличь.
```
## 6. Высокая нагрузка на edge
```bash
htop -p $(pgrep -d',' rampart)
iftop -i eth0 # pps/bandwidth
# Не хватает воркеров → [workers] count = vCPU, рестарт.
# CPU > 80% от userspace → включи XDP ([xdp] enabled = true),
# чтобы дропать мусор раньше, и ужесточи rate limit.
```
## 7. ClickHouse переполнен
```bash
df -h /var/lib/clickhouse
clickhouse-client --query "ALTER TABLE rampart_events MODIFY TTL timestamp + INTERVAL 90 DAY"
# Временное отключение записи: закомментируй clickhouse_url в config.toml, рестарт.
```
## 8. Краткий справочник команд
```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).
---
*Версия: 3.0 | Ноябрь 2026*