- bind.address is parsed as IpAddr (no ":::port"), the socket domain follows the family, and "::" binds dual-stack. IPv6 was impossible before. - limits.relay_idle_timeout_secs (default 300, 1..=86400) replaces the hardcoded relay constant; the deploy examples document it. - The connection budget is an Arc<Semaphore> owned by Gateway instead of a process-wide OnceLock, so tests and multiple gateways stay independent. - PROXY header identity is validated: unspecified, loopback, link-local, multicast, broadcast and addresses inside trusted_cidrs are rejected, and IPv4-mapped IPv6 is normalised first. An invalid header falls back to the transport peer. Bans targeting trusted_cidrs are suppressed, closing the ban-amplification path through a trusted load balancer. - TrustedProxyCidr::contains no longer overflows its mask for IPv6 prefixes shorter than /96.
180 lines
11 KiB
Markdown
180 lines
11 KiB
Markdown
# Configuration - Rampart
|
||
|
||
> Единый конфиг edge-ноды (`config.toml`) и переменные окружения Manager.
|
||
> Схема конфига: `src/config/sections.rs` — единственный источник правды.
|
||
|
||
## 1. Edge (`config.toml`, путь задаётся `RAMPART_CONFIG`)
|
||
|
||
```toml
|
||
# Корневые поля должны стоять до первой TOML-секции.
|
||
whitelist = ["127.0.0.1", "::1"]
|
||
|
||
[bind]
|
||
address = "0.0.0.0"
|
||
port = 25565
|
||
|
||
[backend]
|
||
# Список TCP-бэкендов (addr:port). Для Minecraft нужен ровно один backend.
|
||
upstreams = ["127.0.0.1:25566"]
|
||
|
||
[protocol.minecraft]
|
||
enabled = true
|
||
max_frame_bytes = 8192
|
||
timeout_secs = 5
|
||
send_proxy_protocol = false
|
||
|
||
[workers]
|
||
count = 4
|
||
|
||
[limits]
|
||
handshake_timeout_secs = 5 # таймаут чтения (slowloris-защита)
|
||
max_connections_per_ip = 10 # одновременные соединения с одного IP
|
||
rate_limit_pps = 5.0 # лимит коннектов/сек с одного IP
|
||
rate_limit_burst = 10.0 # burst
|
||
relay_idle_timeout_secs = 300 # простой relay до разрыва, 1..86400
|
||
|
||
[ban]
|
||
ban_duration_secs = 3600
|
||
|
||
[store]
|
||
redis_url = "" # пусто = синхронизация блэклиста выключена
|
||
blacklist_cache_ttl_secs = 300
|
||
clickhouse_url = "" # пусто = запись событий выключена
|
||
|
||
[xdp]
|
||
enabled = false # требует сборки --features xdp, kernel 5.10+
|
||
interface = "eth0"
|
||
protected_port_start = 1 # пакеты вне диапазона уходят в XDP_PASS до фильтра
|
||
protected_port_end = 65535
|
||
udp_policy = "pass" # pass | drop | rate-limit (для IPv4 и IPv6)
|
||
udp_rate_hit_count = 100 # порог пакетов в окне при rate-limit
|
||
udp_rate_window_ms = 1000 # окно rate-limit
|
||
throttle_enabled = true # SYN-throttle (только IPv4)
|
||
events_enabled = true # ringbuf-события в userspace (только IPv4)
|
||
auto_ban_enabled = false # OPT-IN: баны по событиям ringbuf
|
||
auto_ban_duration_secs = 300
|
||
auto_ban_conn_drop_fails = 3
|
||
syn_challenge_enabled = false # RST-challenge (только IPv4)
|
||
challenge_timeout_ms = 3000
|
||
|
||
[logging]
|
||
level = "info" # trace, debug, info, warn, error
|
||
format = "text" # text или json
|
||
|
||
[metrics]
|
||
enabled = true
|
||
port = 9090
|
||
|
||
[pow]
|
||
enabled = false # PoW challenge, OFF по умолчанию
|
||
difficulty = 4
|
||
|
||
# Входящий PROXY v2 от известного TCP DDoS-прокси; включай только если
|
||
# прокси действительно отправляет этот заголовок.
|
||
[proxy_protocol]
|
||
ingress_enabled = false
|
||
trusted_cidrs = []
|
||
ingress_timeout_ms = 750
|
||
max_header_bytes = 512
|
||
|
||
```
|
||
|
||
Этот пример выбирает Minecraft Java и требует сборки с `protocol-minecraft`.
|
||
Для HTTP используй сборку `protocol-http` и удали `[protocol.minecraft]`.
|
||
|
||
Все секции опциональны — при отсутствии используются дефолты из таблицы выше.
|
||
Для ingress PROXY v2 укажи сети именно прокси в `trusted_cidrs`; включение без
|
||
доверенной сети отклоняется при чтении конфига.
|
||
|
||
`trusted_cidrs` — это точные адреса/CIDR самих прокси, а не «весь DC»: IP из
|
||
заголовка используется для per-IP лимитов, репутации и банов, поэтому любой хост
|
||
внутри `trusted_cidrs` может назвать себя кем угодно. Заголовок с адресом из
|
||
`trusted_cidrs` (прокси не может быть клиентом за самим собой) или с
|
||
unspecified/loopback/link-local/multicast/broadcast адресом отклоняется, и
|
||
клиентом считается transport peer — событие пишется в debug один раз на
|
||
соединение. Адреса из `trusted_cidrs` никогда не банятся локально, в Redis и XDP;
|
||
попытка бана подавляется с предупреждением в логе.
|
||
`send_proxy_protocol` отправляет заголовок на Paper backend; прежнее имя
|
||
`proxy_protocol` внутри `[protocol.minecraft]` остаётся допустимым alias.
|
||
|
||
## 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` | нет | — (CORS выключен) | `*` — разрешить все источники; список через запятую; пусто/не задано — запретить cross-origin |
|
||
| `MANAGER_TRUSTED_PROXIES` | нет | — (никому не доверяем) | Сети reverse-прокси через запятую (`10.0.0.0/8,2001:db8::/32`). `X-Forwarded-For` учитывается только для запросов, пришедших с адреса из этих сетей; иначе клиентом считается TCP peer. Пусто/не задано — заголовок игнорируется полностью. Опечатка или пустая запись в списке не даёт менеджеру стартовать |
|
||
|
||
Manager всегда слушает `0.0.0.0:8080`.
|
||
|
||
## 3. Feature flags сборки (Cargo.toml)
|
||
|
||
| Feature | По умолчанию | Что включает |
|
||
|---------|--------------|--------------|
|
||
| `store-redis` | ✅ | Redis-клиент и синхронизация блэклиста |
|
||
| `geoip` | ❌ | GeoIP lookup (maxminddb) |
|
||
| `xdp` | ❌ | Загрузка XDP-программы через libbpf-rs |
|
||
| `io-uring` | ❌ | splice/io_uring I/O |
|
||
| `protocol-http` | ❌ | HTTP/1.1 handler; включай только для HTTP upstream |
|
||
| `protocol-minecraft` | ❌ | Minecraft Java TCP handshake и проксирование |
|
||
|
||
Пример: `cargo build --release --features xdp --bin rampart`.
|
||
|
||
## 4. BPF/XDP программа
|
||
|
||
Исходник: `xdp/core/universal_filter.c`. Smoke-check компиляции:
|
||
|
||
```bash
|
||
clang -O2 -g -target bpf -c xdp/core/universal_filter.c -o /tmp/universal_filter.o
|
||
```
|
||
|
||
Параметры `[xdp]` (значения по умолчанию — в `src/config/sections/platform.rs`):
|
||
|
||
| Поле | По умолчанию | Что делает |
|
||
|------|--------------|------------|
|
||
| `enabled` | `false` | Загрузить и приаттачить XDP-программу при старте |
|
||
| `interface` | `eth0` | Интерфейс; native XDP, при отказе драйвера — generic (skb) |
|
||
| `protected_port_start` / `_end` | `1` / `65535` | Порт-гейт: трафик вне диапазона не фильтруется |
|
||
| `udp_policy` | `pass` | `drop` — дропать весь UDP; `rate-limit` — окно на source-IP |
|
||
| `udp_rate_hit_count` / `udp_rate_window_ms` | `100` / `1000` | Порог и окно для `rate-limit` |
|
||
| `throttle_enabled` | `true` | SYN-throttle + авто-бан по `connection_throttle` |
|
||
| `events_enabled` | `true` | Ringbuf-события (rate-limit/conn-drop) в userspace |
|
||
| `auto_ban_enabled` | `false` | OPT-IN: баны по событиям ringbuf |
|
||
| `auto_ban_duration_secs` | `300` | Длительность авто-бана |
|
||
| `auto_ban_conn_drop_fails` | `3` | Порог `conn->fails` для бана по `EVENT_CONN_DROP` |
|
||
| `syn_challenge_enabled` | `false` | RST-challenge (Oubliette liveness proof) |
|
||
| `challenge_secret_hex` | — (обязателен при `syn_challenge_enabled`) | 128-битный hex-секрет, например `openssl rand -hex 8`; встроенный плейсхолдер запрещён |
|
||
| `challenge_timeout_ms` | `3000` | TTL pending-challenge |
|
||
|
||
Поведение XDP-фильтра:
|
||
|
||
- **Stateless-фильтр, не firewall.** Состояние conntrack ведётся только для TCP-соединений,
|
||
начатых с SYN. Пакет без состояния (non-SYN) пропускается: включение фильтра не рвёт
|
||
ответы на исходящие соединения самого демона и keep-alive от health-check'ов.
|
||
- **VLAN/QinQ** (802.1Q и 802.1ad, до двух тегов) разбираются; **фрагменты** проверяются по
|
||
source-IP в blacklist и пропускаются (не дропаются), счётчик — `frag` в `stats_map`.
|
||
- **Whitelist** из корневого `whitelist = [...]` загружается в XDP-карты (`whitelist_map`,
|
||
`whitelist6_map`) при attach и обходит state machine, throttle и баны.
|
||
- **CIDR-баны**: XDP матчит по LPM-трие, userspace — по диапазонам адресов, поэтому бан
|
||
`/24` или `/64` покрывает всю подсеть.
|
||
- **Оценка числа источников** в префиксе: XDP ведёт 64-битный bitmap хешей source-адресов,
|
||
userspace считает popcount. Благодаря этому spoof-gate (не банить `/24`, если в нём лишь
|
||
пара адресов) работает и на XDP-пути. Счётчики префиксов сбрасываются при каждом чтении,
|
||
то есть окно = интервал опроса монитора.
|
||
|
||
Покрытие семейств адресов:
|
||
|
||
- **IPv4**: blacklist, SYN-throttle, conntrack, RST-challenge, ringbuf-события, `udp_policy`
|
||
(включая `rate-limit`), prefix-статистика.
|
||
- **IPv6**: blacklist (`blacklist6_map`, LPM по `/128` и префиксам), `udp_policy`
|
||
(включая `rate-limit` с 128-битным ключом), детект TCP-bypass, prefix-статистика.
|
||
Пока нет: conntrack, SYN-throttle, RST-challenge, ringbuf-события и unban для v6 —
|
||
для v6 события видны только в счётчиках `stats_map`.
|
||
|
||
---
|
||
|
||
*Версия: 2.1 | Октябрь 2026*
|