# Миграция AWG2 Harness с bash-системы на Rust multi-orchestrator

## 1. Исправленный scope

AWG2 Harness не должен быть просто Rust-эквивалентом пары bash-скриптов. Цель шире: сделать единый production multi-orchestrator, который сначала приводит сервер и Amnezia network namespace к нужному состоянию, а затем постоянно следит за drift и возвращает систему в desired state.

Источник поведения — папка `Amnezia limits (old bash)/`. Всё, что там реально настроено и используется в production, должно быть явно перенесено в Rust-модель: обнаружение контейнера, обнаружение интерфейса, получение peers, `tc` rules, `ifb0`, ingress redirect, per-peer HTB classes, `fq_codel`, auto-healing, статусная диагностика и логи. Новые правила, которых не было в old bash, например anti-torrent через nftables, должны быть описаны отдельно как расширения, а не смешаны с parity contract.

Сервер выделенный. На нём нет соседних сервисов, которые надо защищать от наших сетевых правил. Поэтому бинарь может и должен владеть host/network rules, необходимыми для Amnezia. Ограничение только одно: не ломать саму Amnezia как продукт и не менять её конфиги без явной задачи. Но системные правила, созданные old bash для лимитов, становятся зоной ответственности Rust-бинаря.

## 2. Production-контекст

Целевой хост:

- Debian 13 amd64.
- SSH настроен заранее владельцем сервера.
- AmneziaWG/AWG 2.0 устанавливается официальным способом до установки AWG2 Harness.
- После Amnezia доставляется один Rust-бинарь и единый конфиг.
- Пакет ставится один раз; автообновления самого пакета не проектируются.
- Бинарь запускается от root через systemd, потому что ему нужны Docker/systemd/net-admin/swap возможности.

Система должна переживать:

- reboot хоста;
- restart Docker;
- restart контейнера Amnezia;
- update контейнера Amnezia;
- изменение имени интерфейса `awg0` / `wg0` / `amnezia0` / `tun0`;
- добавление peer;
- удаление peer;
- частично применённое или повреждённое `tc`-состояние;
- частично применённое или повреждённое AWG2-owned nftables-состояние.

## 3. Что именно делает старая bash-система

Старая система состоит из нескольких файлов, и все они важны.

`limit_peers.sh` — главный apply/reconcile-скрипт. Он:

- берёт lock через `/tmp/amnezia-tc.lock`, чтобы не было параллельных применений;
- ищет запущенный контейнер `amnezia-awg2`, затем fallback `amnezia-awg`;
- проверяет интерфейс `WG_IF`, по умолчанию `wg0`, и если его нет, авто-детектит `wg*`, `awg*`, `amnezia*`, `tun*`;
- получает client IP из `wg show all allowed-ips`, fallback — regex из `wg show`;
- фильтрует текущую production-подсеть `10.8.1.x`;
- проверяет существующие `tc filter` по hex-адресам client IP;
- если состояние не совпадает, полностью удаляет старую topology и создаёт новую;
- создаёт root HTB на WG/AWG-интерфейсе: `tc qdisc add dev <iface> root handle 1: htb`;
- создаёт root class `1:1` с `rate 1000mbit ceil 1000mbit`;
- загружает/создаёт `ifb0`;
- добавляет ingress qdisc `ffff:` на WG/AWG-интерфейс;
- добавляет ingress redirect через `mirred egress redirect dev ifb0`;
- создаёт root HTB на `ifb0`: `handle 2:`;
- создаёт root class `2:1` с `rate 1000mbit ceil 1000mbit`;
- для каждого peer создаёт egress class `1:<class_id>` с `rate LIMIT ceil LIMIT`;
- для каждого peer создаёт `fq_codel` под egress class;
- для каждого peer добавляет egress filter `match ip dst <peer_ip> flowid 1:<class_id>`;
- для каждого peer создаёт ingress class `2:<class_id>` с тем же лимитом;
- для каждого peer создаёт `fq_codel` под ingress class;
- для каждого peer добавляет ingress filter на `ifb0`: `match ip src <peer_ip> flowid 2:<class_id>`;
- начинает `class_id` с 10;
- пишет события в `/var/log/amnezia-tc.log`.

`docker_watcher.sh` слушает `docker events --filter event=start`. При старте `amnezia-awg2` или `amnezia-awg` он ждёт появления `awg0` до 20 секунд и запускает `limit_peers.sh`. В Rust это нужно исправить: watcher не должен ждать только `awg0`, он обязан использовать общий detector интерфейса.

`check-vpn-limits` — CLI-диагностика. Он показывает systemd статус, контейнер, peers из `wg show`, классы с лимитом 70 Mbit/s, filter stats и последние строки `/var/log/amnezia-tc.log`. Rust `status` должен заменить этот отчёт, но проверять шире: оба направления, `ifb0`, ingress redirect и соответствие desired state.

`amnezia-tc.service` — oneshot apply после Docker/network-online.

`amnezia-tc-watcher.service` — постоянно запущенный watcher Docker events.

`traffic_control-was.txt`, `wg-peers.txt`, `iproute2_a_core.txt`, `permissions.txt`, `Нюансы.txt` — production-снимки. Они фиксируют реальные условия: Debian 13 cloud kernel, Docker 26.1.5, iproute2 6.15.0, интерфейс `awg0`, 23 peer IP в `10.8.1.0/24`, HTB classes `1:10..1:32`, `fq_codel` leaves и enabled systemd units.

## 4. Desired state Rust-бинаря

Rust-бинарь должен иметь explicit desired state model. Нельзя ограничиться последовательным запуском команд “как в bash”. Нужно уметь сравнить expected и actual, а затем принять решение: no-op, incremental fix или full rebuild.

Базовый desired state для traffic limits:

```text
container: first running from configured names
netns: namespace of selected container
interface: detected AWG/WG interface inside that netns
peers: IPv4 /32 allowed IPs inside configured peer CIDR
root egress qdisc: <iface> root handle 1: htb
root egress class: 1:1 rate root_rate ceil root_rate
per-peer egress class: 1:<id> rate peer_limit ceil peer_limit
per-peer egress qdisc: fq_codel under 1:<id>
per-peer egress filter: dst peer_ip -> 1:<id>
ingress qdisc: <iface> handle ffff:
ingress redirect: <iface> ingress -> ifb0
ifb device: ifb0 up in the same namespace where shaping is applied
root ingress qdisc: ifb0 root handle 2: htb
root ingress class: 2:1 rate root_rate ceil root_rate
per-peer ingress class: 2:<id> rate peer_limit ceil peer_limit
per-peer ingress qdisc: fq_codel under 2:<id>
per-peer ingress filter: src peer_ip -> 2:<id>
```

Любое отклонение от этого состояния считается drift. Если drift простой, можно исправить точечно. Для v1 допустим и предпочтителен full rebuild всей AWG traffic topology, потому что он проще, предсказуемее и повторяет текущую production-модель.

## 5. Модель управления host/network state

Исправление к предыдущей версии документации: бинарь не должен рассматриваться как осторожная внешняя обёртка, которая только вызывает `docker exec` и не владеет правилами. Правильная модель — host-level orchestrator with namespace control.

Практический порядок для v1:

1. На хосте определить контейнер через Docker API или `docker inspect`.
2. Получить PID контейнера и путь к его network namespace: `/proc/<pid>/ns/net`.
3. Все операции `wg`, `ip`, `tc`, `ifb` выполнять в правильном namespace.
4. Для реализации можно выбрать один из двух путей:
   - через `nsenter -t <pid> -n ...` / `ip netns exec`-эквивалент и системные команды;
   - через netlink/native Rust libraries после входа в namespace.
5. `docker exec` допустим только как fallback или transitional adapter, но не как архитектурный центр. Причина: это делает нас зависимыми от shell/tools внутри контейнера и хуже соответствует модели “наш бинарь управляет состоянием сервера”.

Для первой production-версии нормальный компромисс: Rust-бинарь владеет orchestration, locking, state comparison, retry, status и lifecycle, а низкоуровневые `tc/ip/wg` операции выполняет через команды в namespace. Нативный netlink можно вводить после стабилизации, если это даст реальный выигрыш по надёжности или нагрузке.

## 6. Обязательные функции Rust-версии

Минимум для parity со старой системой:

1. `daemon` — основной systemd-процесс.
2. `apply-limits` — ручное применение/reconcile traffic limits.
3. `status` — диагностика уровня `check-vpn-limits`, но с проверкой обоих направлений и drift.
4. `validate-config` — проверка конфига без изменения системы.
5. `apply-firewall` — ручной reconcile AWG2-owned nftables state, если anti-torrent включён.
6. `ensure-swap` — идемпотентный setup swap-файла 2 ГБ.
7. Внешний reboot scheduler `awg2-reboot-scheduler` как отдельный production service.
8. Locking, чтобы одновременно не шли два apply/reconcile.
9. Docker event watcher.
10. Периодический reconciliation loop, потому что Docker events могут быть пропущены.
11. Start-up reconciliation: при запуске daemon сразу проверить и применить лимиты и AWG2-owned firewall state.
12. Graceful behavior, если контейнер временно отсутствует: логировать и продолжать loop, а не падать насмерть.

## 7. Подкоманды

```bash
awg2-harness daemon
awg2-harness apply-limits
awg2-harness apply-firewall
awg2-harness status
awg2-harness ensure-swap
awg2-harness validate-config
awg2-harness validate-runtime
```

`daemon` — основной production-режим. Он делает initial reconcile, слушает Docker events, периодически проверяет state и пишет runtime-логи в journald. Планирование reboot выполняется отдельным сервисом `awg2-reboot-scheduler`.

`apply-limits` — немедленный reconcile traffic limits. Команда должна быть безопасной для повторного запуска.

`apply-firewall` — немедленный reconcile nftables anti-torrent rules. Команда должна менять только AWG2-owned table/chain.

`status` — отчёт о текущем состоянии: контейнер, PID/netns, интерфейс, peers, egress topology, ingress/ifb topology, drift summary, последние ошибки.

`ensure-swap` — setup-задача, не постоянный loop.

`validate-config` — синтаксическая и семантическая проверка.

## 8. Что нужно исправить относительно bash

Bash работает, но в Rust нужно убрать известные слабые места.

Первое: единый detector. Сейчас `limit_peers.sh` умеет авто-детектить интерфейс, а `docker_watcher.sh` ждёт только `awg0`. В Rust detector должен быть один и использоваться везде.

Второе: проверка полного state. Старый skip decision в основном смотрит фильтры на WG-интерфейсе. Rust должен проверять также `ifb0`, ingress redirect, classes на `ifb0`, qdisc leaves и соответствие class_id ↔ peer_ip.

Третье: парсинг peers. Текущий regex жёстко ищет `10.8.1.x`. В Rust подсеть должна быть конфигурируемой, а парсинг `wg show all allowed-ips` — структурным.

Четвёртое: наблюдаемость. Status должен отличать “container отсутствует”, “interface отсутствует”, “wg не читается”, “tc отсутствует”, “rules partial”, “rules match desired”.

Пятое: namespace ownership. Не надо полагаться на shell внутри контейнера как на единственный способ управления. Бинарь должен уметь работать от host authority и заходить в namespace контейнера.

## 9. Единый конфиг

Конфиг должен жить в `/etc/awg2-harness/config.toml` и содержать только параметры, которые реально меняются оператором.

```toml
[amnezia]
container_names = ["amnezia-awg2", "amnezia-awg"]
interface_candidates = ["awg0", "wg0", "amnezia0", "tun0"]
interface_patterns = ["awg*", "wg*", "amnezia*", "tun*"]
peer_ipv4_cidr = "10.8.1.0/24"

[traffic]
enabled = true
peer_limit = "50mbit"
root_rate = "500mbit"
reconcile_interval_secs = 15
container_ready_timeout_secs = 120
class_start_id = 10
ifb_name = "ifb0"

[host_firewall]
enabled = true
ssh_port = 22
amnezia_port = 443
amnezia_protocols = ["udp"]
allow_icmp = true
default_input_policy = "drop"

[anti_torrent]
enabled = true
max_connections_per_peer = 100
peer_ipv4_cidr = "10.8.1.0/24"
apply_in_amnezia_netns = true

[reboot]
enabled = true
window_start_utc = "01:00"
window_end_utc = "02:00"

[swap]
enabled = true
path = "/swapfile"
size_mb = 2048
priority = 1
swappiness = 1
```

`ifb_name` можно оставить в конфиге, потому что это имя системного интерфейса, которым владеет orchestrator. Handles `1:`, `2:`, `ffff:` лучше не выносить в конфиг: это implementation contract AWG traffic module, а не эксплуатационная настройка.

## 10. Anti-torrent extension

Anti-torrent не входит в старую bash-систему, но хорошо ложится в целевую модель multi-orchestrator. Бинарь уже владеет нужным network namespace и должен уметь применять, проверять и восстанавливать nftables state так же, как он восстанавливает `tc` topology.

Правильная v1-модель — не protocol detection и не strike-система, а простой per-peer connection-count guard через nftables `ct count`. Правило должно быть scoped к VPN peer CIDR и keyed by source peer IP через `meter`, иначе можно случайно получить общий лимит на всю подсеть.

Правило должно жить в отдельной AWG2-owned таблице, например `table inet awg2_harness`, и применяться в Amnezia network namespace. Нельзя делать `flush ruleset`; удалять можно только owned table/chain.

См. `docs/ANTI_TORRENT.md`.

## 11. Systemd-модель

Вместо двух старых units нужен один daemon-unit:

```ini
[Unit]
Description=AWG2 Harness multi-orchestrator
After=network-online.target docker.service
Wants=network-online.target
Requires=docker.service
StartLimitIntervalSec=60
StartLimitBurst=5

[Service]
Type=simple
User=root
ExecStartPre=/usr/sbin/awg2-harness --config /etc/awg2-harness/config.toml ensure-swap
ExecStart=/usr/sbin/awg2-harness --config /etc/awg2-harness/config.toml daemon
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
```

Сервис должен запускаться от root. На выделенном сервере не нужно искусственно ограничивать его так, чтобы он не мог управлять сетью. Hardening можно добавлять после реальной проверки, но нельзя включать `PrivateNetwork`, `PrivateDevices` или слишком жёсткий `CapabilityBoundingSet`, если они ломают `tc`, `ifb`, Docker или reboot.

## 12. Reboot и swap

Логика reboot вынесена в отдельный production-бинарь `reboot_module` (`awg2-reboot-scheduler`). Окно перезагрузки задаётся в конфиге, включая корректные окна через полночь. Механика `systemctl --no-block reboot` сохраняется.

`ensure-swap` работает как exclusive reconciler: при `swap.enabled=true` пакет полностью владеет swap-state хоста. После reconcile активен ровно один swap (`swap.path`), все прочие активные swap entries выключены (`swapoff`), а все старые swap-строки в `/etc/fstab` заменены на одну managed-запись AWG2. Для block-device swap выполняются только `swapoff` и удаление записи из `fstab`; device не удаляется.

## 13. Acceptance критерий миграции

Миграция считается корректной только если Rust-бинарь на реальном Debian 13 хосте:

- создаёт ту же traffic-control topology, что старая bash-система;
- ограничивает каждого peer в обе стороны на `traffic.peer_limit`;
- после повторного запуска не создаёт дубли и не ломает state;
- после restart контейнера сам восстанавливает rules;
- после restart Docker сам восстанавливает rules;
- после reboot хоста сам восстанавливает rules;
- после добавления peer создаёт новый class/filter;
- после удаления peer убирает устаревший class/filter через rebuild;
- `status` показывает не только “есть 70Mbit classes”, а полную картину desired vs actual;
- swap и reboot работают как части одного пакета;
- anti-torrent, если включён, применяет per-peer flow limit и не затрагивает unrelated nftables rules.