guard/docs/deployment.md
loki5512344 c1a076a4a3
fix(core): close auth bypass, hangs and memory leaks found by review
Security:
- An empty API_PASSWORD passed validation (only the literal "changeme" was
  rejected) and verify_password("", "") returned true, so a login with an
  empty password minted an admin token. Require >= 16 characters and >= 32
  non-whitespace bytes for JWT_SECRET; verify rejects an empty stored secret.
- syn_challenge_enabled required a real challenge_secret_hex: the public
  placeholder from config.h is now rejected in every spelling.
- docker-compose: Redis/ClickHouse/Grafana are loopback-only and every
  password uses ${VAR:?} instead of a default. An exposed Redis was a way to
  lift bans and publish unbans to the whole fleet with one redis-cli.
- Empty CORS_ORIGIN no longer means "allow any origin".
- ban_cidr / userspace blacklist validate and mask prefixes; CIDR bans are
  stored as ranges, so a /24 or /64 ban actually covers the subnet (before,
  only the network address was blocked).

Availability:
- ClickHouse client has connect/request timeouts and no mutex held across
  await: a hung analytics backend can no longer freeze the ban path. Events
  go through a bounded buffer with a drop counter.
- Redis uses a ConnectionManager with per-command timeouts; pubsub and
  reconcile reset the backoff after success; publish cannot block shutdown.
- Ban durations from pubsub are clamped and use checked_add; the sync task
  survives panics instead of silently dying.
- Blacklist TOCTOU (remove_if) and replace_redis no longer empties the table
  during a Redis reconnect.
- RateLimiter and reputation have hard caps with incremental eviction instead
  of an unbounded DashMap and a stop-the-world retain.
- The attack detector scores before updating its baseline and needs several
  quiet windows to leave UnderAttack, so a sustained flood keeps banning new
  offenders instead of ending after one tick.
- accept() backs off on EMFILE/ENFILE, shutdown Err is treated as shutdown,
  a global semaphore bounds in-flight connections, rate limiting runs before
  PoW, whitelisted IPs are never banned, and connect/handshake/relay have
  timeouts with an idle budget.
- PoW uses the configured difficulty as a floor, the clamp is enforced, and
  nonce framing survives split segments and coalesced handshake bytes.
- Subnet tracker memory is capped (prefixes and per-prefix sources) and the
  monitor bans with the configured TTL.

CI and docs:
- CI runs the test suite with --no-default-features --features protocol-http;
  make ebpf fails on errors; the secrets gate catches weak compose defaults.
- doctor skips protected endpoints without a token and exits non-zero on
  failure; a drain timeout returns exit code 1.
- TODO §2b records the review findings, what is fixed and what is deferred;
  configuration/testing docs describe the new XDP and secret semantics.
2026-11-16 12:06:23 +01:00

148 lines
5.3 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.

# Deployment - Rampart
> Как поднять Rampart с нуля.
---
## 1. Компоненты
| Бинарь | Роль | Порт по умолчанию |
|--------|------|-------------------|
| `rampart` | Edge-нода: XDP + PoW + userspace-фильтр | 25565 (+ metrics 9090) |
| `rampart-manager` | REST API управления | 8080 |
| `rampart-cli` | Управление через Manager API | — |
## 2. Требования
### Edge
- Ubuntu 22.04+ / Debian 12, kernel 5.10+
- KVM или bare metal (OpenVZ/LXC — XDP не работает)
- Rust toolchain для сборки
Для XDP дополнительно: `libelf-dev libbpf-dev clang linux-libc-dev`.
### Manager
- Любая VDS с Docker (Redis обязателен)
## 3. Быстрый старт — Edge
```bash
# Сборка edge для Minecraft Java
git clone https://github.com/loki5512344ss/guard.git && cd guard
cargo build --release --features protocol-minecraft --bin rampart
# Установка
sudo cp target/release/rampart /usr/local/bin/
# Конфиг
sudo mkdir -p /etc/rampart
sudo cp deploy/config/edge.toml /etc/rampart/config.toml
# Отредактируй backend.upstreams под свои бэкенды
# systemd unit
cat > /etc/systemd/system/rampart.service << 'EOF'
[Unit]
Description=Rampart Edge Node
After=network.target
[Service]
Type=simple
Environment=RAMPART_CONFIG=/etc/rampart/config.toml
ExecStart=/usr/local/bin/rampart
Restart=always
RestartSec=5
LimitNOFILE=65535
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable --now rampart
# Проверка
journalctl -u rampart -f
```
Minecraft-конфиг рассчитан на один Paper backend. Если включён
`protocol.minecraft.send_proxy_protocol`, включи `proxies.proxy-protocol: true` в
Paper и закрой backend-порт firewall-ом от всех, кроме Rampart. Для подробной
схемы с домашним сервером и защищённым VDS см. [Minecraft Java guide](minecraft-java.md).
## 4. Быстрый старт — Manager
```bash
export REDIS_URL="redis://127.0.0.1:6379/0"
export JWT_SECRET="$(openssl rand -hex 32)" # минимум 32 байта без пробелов
export API_PASSWORD="$(openssl rand -base64 24)" # минимум 16 символов, дефолт запрещён
cargo run --release --bin rampart-manager
# API на 0.0.0.0:8080
```
Manager refuses to start with an empty `API_PASSWORD`, a password shorter than
16 characters, the default placeholder (which must not be `changeme`), or a
`JWT_SECRET` with fewer than 32 non-whitespace bytes.
Manager listens on all interfaces by default. Permit `8080` only from an admin
VPN or specific admin addresses; do not expose the API to the public Internet.
The same applies to Redis (`6379`) and monitoring endpoints such as Prometheus
(`9090`), ClickHouse (`8123`/`9000`) and Grafana (`3000`). The sample Compose
files bind published ClickHouse and Grafana ports to `127.0.0.1` only, so reach
them through an SSH tunnel or a local admin session, never through the public
interface. `deploy/docker-compose.yml` publishes no Redis port at all and the
root `docker-compose.yml` binds it to loopback; both refuse to start unless
`REDIS_PASSWORD` and `GRAFANA_PASSWORD` are set. Cross-origin access to the
manager API is disabled unless `CORS_ORIGIN` is set explicitly (`*` or a
comma-separated origin list).
Инфраструктура (Redis, ClickHouse, Grafana) требует пароли из окружения —
Compose не стартует без них:
```bash
export REDIS_PASSWORD="$(openssl rand -base64 24)"
export GRAFANA_PASSWORD="$(openssl rand -base64 24)"
docker compose up -d redis clickhouse grafana
```
Для нескольких edge и Manager укажи один и тот же защищённый Redis endpoint в
`store.redis_url` каждого edge и `REDIS_URL` Manager. Edge передаёт туда
локальные автобаны и восстанавливает общие bans после переподключения. Открой
Redis только через private network/VPN; при пустом `redis_url` edge остаётся
автономным, и автобаны между узлами не распространяются.
## 5. Docker
```bash
# Пароли обязательны: без REDIS_PASSWORD/GRAFANA_PASSWORD Compose падает
export REDIS_PASSWORD="$(openssl rand -base64 24)"
export GRAFANA_PASSWORD="$(openssl rand -base64 24)"
# Образ edge
docker build -f deploy/docker/Dockerfile.edge -t rampart-edge .
# Полный стек edge + инфраструктура
docker compose -f deploy/docker-compose.yml up -d
```
Edge подключается к Redis по имени сервиса. Поскольку Redis в Compose требует
пароль, впиши его в URL конфига edge (`deploy/config/edge-docker.toml`) — тот
же пароль, что в `REDIS_PASSWORD`:
```toml
[store]
redis_url = "redis://:PASSWORD@redis:6379/0"
```
## 6. Проверка после деплоя
```bash
☐ systemctl status rampart
☐ ss -tlnp | grep 25565
☐ curl http://localhost:9090/metrics | grep rampart_
☐ rampart-cli status # через Manager API
☐ rampart-cli doctor # диагностика
```
---
*Версия: 2.1 | Октябрь 2026*