guard/docs/configuration.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

270 lines
13 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.

# Configuration — Rampart
> Единый конфиг edge-ноды (`config.toml`) и переменные окружения Manager.
> Источник правды: `src/config/mod.rs` и `src/config/sections/`. Меняешь поле —
> правь эту таблицу в том же PR.
---
## 1. Edge (`config.toml`)
Путь по умолчанию — `/etc/rampart/config.toml`, переопределяется переменной
`RAMPART_CONFIG`. Все секции опциональны; при отсутствии используются дефолты из
таблиц ниже. Валидация выполняется до bind сокета: неверное значение — отказ
старта с внятной ошибкой.
### 1.1 Корень и входящий трафик
```toml
# Корневые поля должны стоять до первой TOML-секции.
whitelist = ["127.0.0.1", "::1"]
[bind]
address = "0.0.0.0"
port = 25565
[backend]
upstreams = ["127.0.0.1:25566"]
[workers]
count = 4
[limits]
handshake_timeout_secs = 5
max_connections_per_ip = 10
rate_limit_pps = 5.0
rate_limit_burst = 10.0
relay_idle_timeout_secs = 300
[ban]
ban_duration_secs = 3600
```
| Поле | По умолчанию | Ограничения и смысл |
|------|--------------|---------------------|
| `whitelist` | `[]` | Только IP-адреса (без CIDR). Обходят все фильтры, throttle и баны; адрес из whitelist никогда не банится |
| `bind.address` | `0.0.0.0` | Адрес прослушивания (IPv4 или IPv6) |
| `bind.port` | `25565` | Защищаемый TCP-порт |
| `backend.upstreams` | `["127.0.0.1:25566"]` | `addr:port`; список не пуст, каждый адрес валиден; Minecraft требует ровно один |
| `workers.count` | `4` | Accept-loop'ы с `SO_REUSEPORT`; ≥ 1 |
| `limits.handshake_timeout_secs` | `5` | Таймаут handshake/connect (slowloris-защита) |
| `limits.max_connections_per_ip` | `10` | Одновременные соединения с одного IP; > 0 |
| `limits.rate_limit_pps` | `5.0` | Новые соединения/с с одного IP; конечно и > 0 |
| `limits.rate_limit_burst` | `10.0` | Burst token bucket; ≥ 1 |
| `limits.relay_idle_timeout_secs` | `300` | Простой relay до разрыва; `1..=86400` |
| `ban.ban_duration_secs` | `3600` | Длительность бана; `1..=31_536_000` (год) |
### 1.2 PROXY protocol и PoW
```toml
[proxy_protocol]
ingress_enabled = false
trusted_cidrs = []
ingress_timeout_ms = 750
max_header_bytes = 512
[pow]
enabled = false
difficulty = 4
```
| Поле | По умолчанию | Ограничения и смысл |
|------|--------------|---------------------|
| `proxy_protocol.ingress_enabled` | `false` | Принимать PROXY v2 от внешнего TCP-прокси; требует непустой `trusted_cidrs` и `protocol.minecraft.enabled` |
| `proxy_protocol.trusted_cidrs` | `[]` | Точные адреса/CIDR самих прокси, не «весь DC» |
| `proxy_protocol.ingress_timeout_ms` | `750` | `1..=5000` |
| `proxy_protocol.max_header_bytes` | `512` | `52..=4096` |
| `pow.enabled` | `false` | Hashcash-challenge поверх любого TCP; несовместим с `protocol.minecraft.enabled` |
| `pow.difficulty` | `4` | Стартовая и минимальная сложность; `1..=10`, растёт под нагрузкой |
`trusted_cidrs` — это адреса самих прокси, а не клиентов: IP из заголовка
используется для per-IP лимитов, репутации и банов, поэтому любой хост внутри
`trusted_cidrs` может назвать себя кем угодно. Заголовок с адресом из
`trusted_cidrs`, а также unspecified/loopback/link-local/multicast/broadcast
отклоняется: клиентом считается transport peer (событие пишется в debug один раз
на соединение). Адреса из `trusted_cidrs` не банятся локально, в Redis и XDP.
### 1.3 XDP
```toml
[xdp]
enabled = false
interface = "eth0"
protected_port_start = 1
protected_port_end = 65535
udp_policy = "pass"
udp_rate_hit_count = 100
udp_rate_window_ms = 1000
throttle_enabled = true
events_enabled = true
auto_ban_enabled = false
auto_ban_duration_secs = 60
auto_ban_conn_drop_fails = 3
syn_challenge_enabled = false
challenge_secret_hex = "" # обязателен при syn_challenge_enabled
challenge_timeout_ms = 3000
```
| Поле | По умолчанию | Что делает |
|------|--------------|------------|
| `enabled` | `false` | Загрузить и приаттачить программу; требует сборки `--features xdp` |
| `interface` | `eth0` | Интерфейс; сначала native XDP, при отказе драйвера — generic (skb) |
| `protected_port_start` / `_end` | `1` / `65535` | Порт-гейт: трафик вне диапазона не фильтруется |
| `udp_policy` | `pass` | `pass`, `drop` или `rate-limit` (окно по source-IP) |
| `udp_rate_hit_count` / `udp_rate_window_ms` | `100` / `1000` | Порог и окно для `rate-limit` |
| `throttle_enabled` | `true` | SYN-throttle и авто-бан по `connection_throttle` (IPv4) |
| `events_enabled` | `true` | Ringbuf-события в userspace (IPv4) |
| `auto_ban_enabled` | `false` | OPT-IN: баны по событиям ringbuf |
| `auto_ban_duration_secs` | `60` | Длительность авто-бана |
| `auto_ban_conn_drop_fails` | `3` | Порог `conn->fails` для бана по `EVENT_CONN_DROP` |
| `syn_challenge_enabled` | `false` | RST-challenge (Oubliette-style liveness proof), IPv4 |
| `challenge_secret_hex` | — | 128-битный hex-секрет (`openssl rand -hex 8`); placeholder запрещён |
| `challenge_timeout_ms` | `3000` | TTL pending-challenge |
Поведение фильтра:
- **Stateless-фильтр, не firewall.** Conntrack ведётся только для TCP-соединений,
начатых с SYN; пакет без состояния (non-SYN) пропускается, чтобы фильтр не рвал
ответы на исходящие соединения демона и keep-alive health-check'ов.
- **VLAN/QinQ** (802.1Q и 802.1ad, до двух тегов) разбираются; **фрагменты**
проверяются по source-IP в blacklist и пропускаются, счётчик — `fragment_bypass`.
- **Whitelist** загружается в `whitelist_map`/`whitelist6_map` при attach и
обходит state machine, throttle и баны.
- **CIDR-баны** матчатся LPM-трией; userspace — диапазонами, поэтому `/24` и `/64`
покрывают всю подсеть.
- **Оценка числа источников** в префиксе: XDP ведёт 64-битный bitmap хешей
source-адресов, userspace считает popcount (spoof-gate работает и на XDP-пути).
Счётчики префиксов сбрасываются при чтении, окно = интервал опроса монитора.
Покрытие семейств:
- **IPv4**: blacklist, SYN-throttle, conntrack, RST-challenge, ringbuf-события,
`udp_policy` (включая `rate-limit`), prefix-статистика.
- **IPv6**: blacklist, whitelist, `udp_policy` (включая `rate-limit` с 128-битным
ключом), детект TCP-bypass, prefix-статистика. Пока нет: conntrack,
SYN-throttle, RST-challenge, ringbuf-события и unban — для v6 только счётчики.
### 1.4 Детекция и алерты
```toml
[detect.prefix]
enabled = false
syn_threshold = 500
window_secs = 10
min_unique_sources = 16
[detect.autoban]
enabled = false
reputation_threshold = -50
[detect.alert]
webhook_url = ""
```
| Поле | По умолчанию | Смысл |
|------|--------------|-------|
| `detect.prefix.enabled` | `false` | Детектор атак на уровне подсети (`/24`, `/64`) |
| `detect.prefix.syn_threshold` | `500` | Порог соединений на префикс в окне; при `enabled` обязан быть > 0 |
| `detect.prefix.window_secs` | `10` | Окно детектора |
| `detect.prefix.min_unique_sources` | `16` | Минимум уникальных источников (spoof-gate) |
| `detect.autoban.enabled` | `false` | Авто-бан по score репутации |
| `detect.autoban.reputation_threshold` | `-50` | Порог score; TTL — `ban.ban_duration_secs` |
| `detect.alert.webhook_url` | — | Webhook на переход состояния атаки |
### 1.5 Протоколы, логи, метрики, хранилища
```toml
[protocol.http]
max_header_bytes = 8192
timeout_secs = 5
blocked_paths = ["/wp-login.php"]
require_user_agent = false
[protocol.minecraft]
enabled = true
max_frame_bytes = 8192
timeout_secs = 5
send_proxy_protocol = false
[logging]
level = "info"
format = "text"
[metrics]
enabled = true
port = 9090
[store]
redis_url = ""
blacklist_cache_ttl_secs = 300
clickhouse_url = ""
```
| Поле | По умолчанию | Смысл |
|------|--------------|-------|
| `protocol.http.max_header_bytes` | `8192` | Лимит request-head; > 0 |
| `protocol.http.timeout_secs` | `5` | Таймаут чтения заголовков; > 0 |
| `protocol.http.blocked_paths` | `[]` | Точные пути, которые отклоняются |
| `protocol.http.require_user_agent` | `false` | Отклонять запросы без `User-Agent` |
| `protocol.minecraft.enabled` | `true` при сборке без `protocol-http` | Активный MC-handler |
| `protocol.minecraft.max_frame_bytes` | `8192` | Лимит кадра; > 0 |
| `protocol.minecraft.timeout_secs` | `5` | Таймаут handshake; > 0 |
| `protocol.minecraft.send_proxy_protocol` | `false` | Отправлять PROXY v2 на Paper; alias — `proxy_protocol` |
| `logging.level` | `info` | `trace`, `debug`, `info`, `warn`, `error` |
| `logging.format` | `text` | `text` или `json` |
| `metrics.enabled` | `true` | Prometheus endpoint |
| `metrics.port` | `9090` | Порт метрик |
| `store.redis_url` | — | Пусто = синхронизация банов выключена |
| `store.blacklist_cache_ttl_secs` | `300` | TTL локального кеша blacklist |
| `store.clickhouse_url` | — | Пусто = запись событий выключена |
`[protocol.http]` существует только при сборке с `protocol-http`,
`[protocol.minecraft]` — только с `protocol-minecraft`; секция без
соответствующей фичи игнорируется. Для HTTP удали `[protocol.minecraft]`.
## 2. Manager (переменные окружения)
| Переменная | Обязательна | По умолчанию | Описание |
|------------|-------------|--------------|----------|
| `REDIS_URL` | нет | `redis://127.0.0.1:6379/0` | Хранилище состояния |
| `JWT_SECRET` | да | — | Минимум 32 непробельных байта |
| `JWT_AUDIENCE` | нет | `rampart` | Audience JWT |
| `JWT_EXPIRATION_SECS` | нет | `86400` | Время жизни токена |
| `API_PASSWORD` | да | — | Пароль для `/api/v1/auth/login`, минимум 16 символов; `changeme` запрещён |
| `CORS_ORIGIN` | нет | — | `*` — разрешить всё; список origin'ов через запятую; пусто — cross-origin запрещён |
| `MANAGER_TRUSTED_PROXIES` | нет | — | Сети reverse-прокси через запятую. `X-Forwarded-For` учитывается только для запросов из этих сетей; опечатка/пустая запись → отказ старта |
Manager всегда слушает `0.0.0.0:8080`.
## 3. Feature flags сборки
| Feature | По умолчанию | Что включает |
|---------|--------------|--------------|
| `store-redis` | ✅ | Redis-клиент и синхронизация blacklist |
| `geoip` | ❌ | GeoIP lookup (maxminddb; реализация — roadmap v0.5) |
| `xdp` | ❌ | Загрузка XDP-программы через libbpf-rs |
| `io-uring` | ❌ | splice/io_uring I/O (реализация — roadmap v0.6) |
| `protocol-http` | ❌ | HTTP/1.1 handler |
| `protocol-minecraft` | ❌ | Minecraft Java handshake и проксирование |
```bash
cargo build --release --features xdp,protocol-http --bin rampart
```
## 4. BPF/XDP программа
Исходник — `xdp/core/universal_filter.c`. Smoke-check компиляции:
```bash
mkdir -p target/xdp
clang -O2 -g -target bpf -I"/usr/include/$(gcc -print-multiarch)" \
-c xdp/core/universal_filter.c -o target/xdp/universal_filter.o
```
`-I` с multiarch нужен, потому что `-target bpf` не ищет
`/usr/include/<triple>` по умолчанию. Полный прогон на реальном ядре —
`scripts/xdp_ci.sh` (см. [testing.md](testing.md)).
---
*Версия: 3.0 | Ноябрь 2026*