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.
This commit is contained in:
Loki 2026-11-16 12:36:29 +01:00
parent e456cb583f
commit da87d2a11f
Signed by: boba
GPG key ID: 6CDE87BC9A778D97
21 changed files with 600 additions and 521 deletions

View file

@ -58,6 +58,31 @@ clickhouse-client --query "SELECT count() FROM rampart.events WHERE event_type='
> Честно: 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` пока не реализованы и завершатся
> явной ошибкой вместо изменения состояния.

View file

@ -19,6 +19,31 @@ clang -O2 -g -target bpf -c xdp/core/universal_filter.c -o /tmp/uf.o
# Не помогло — отключи XDP в config.toml ([xdp] enabled = false) и рестарт.
```
### "accept error: ... backing off" / "Too many open files"
```bash
# Кончились дескрипторы: демон сам делает backoff, но сервис уже деградирует
ulimit -n # для процесса
systemctl show rampart -p LimitNOFILE
journalctl -u rampart | grep -E "accept error|EMFILE|backing off"
ss -s | head -5
```
Поднять `LimitNOFILE` (например, 65535), перезапустить, проверить утечки
соединений (`ss -tan state established | wc -l`). Backoff в списке логов — это
симптом, а не причина.
### "XDP не снимается после остановки демона"
```bash
bpftool net show dev eth0
ip link show eth0 | grep -i xdp
```
Если программа осталась — загрузчик не снял её (регрессия), снять вручную
`ip link set dev eth0 xdp off` и завести баг с режимом attach из лога
(`native (drv)` / `generic (skb)`).
### "Rate limit блокирует реальных клиентов"
```bash
@ -31,7 +56,6 @@ curl -s http://EDGE_IP:9090/metrics | grep rate_limit
```
### "Высокое CPU на edge ноде"
```bash
top -p $(pgrep rampart)
perf top -p $(pgrep rampart)
@ -63,6 +87,16 @@ export REDIS_URL="redis://127.0.0.1:6379/0" # опционально
rampart-manager
```
### "Manager не стартует: API_PASSWORD must be ..."
`API_PASSWORD` должен быть непустым и не короче 16 символов, `JWT_SECRET` —
не короче 32 непробельных байт. Пустой пароль раньше принимался как валидный,
поэтому теперь это ошибка старта, а не тихий вход без пароля.
```bash
systemctl show rampart-manager -p Environment | tr ' ' '\n' | grep -E "API_PASSWORD|JWT_SECRET" | sed 's/=.*/=<redacted>/'
```
### "Manager отдаёт 401"
Токен истёк (`JWT_EXPIRATION_SECS`, дефолт 86400) — перелогинься:
@ -108,7 +142,15 @@ df -h /var/lib/clickhouse
```
Запись настраивается `store.clickhouse_url` в config.toml. Ошибки записи не
роняют edge — они уходят в debug-лог.
роняют edge: события складываются в bounded-буфер (10 000) и при переполнении
или таймауте учитываются в `rampart_clickhouse_dropped_total`.
```bash
curl -s http://EDGE_IP:9090/metrics | grep clickhouse_dropped
```
Растущий счётчик = ClickHouse не успевает; защита при этом работает, но
аналитика теряет события.
---