prod/AWG2_harness
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

feat: support AmneziaWG 3.1

Browse Source
This commit is contained in:
Crimson
2026-08-28 00:28:26 +05:00
parent 3912b91bc4
commit 185991504a
16 changed files with 282 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+23 -21
View File
@@ -1,8 +1,8 @@
# AWG2 Harness
`AWG2 Harness` — host-side orchestrator для выделенного Debian-хоста с self-hosted AmneziaWG. Пакет управляет инфраструктурным состоянием вокруг Amnezia: per-peer traffic shaping, IFB ingress shaping, nftables host firewall, anti-torrent connection guard, managed swap, диагностикой drift и плановым reboot.
`AWG2 Harness` — host-side orchestrator для выделенного Debian-хоста с self-hosted AmneziaWG. Основной target релиза 0.3.1 — AmneziaWG 3.1; AWG 3.0/2.x сохраняются как regression compatibility. Пакет управляет инфраструктурным состоянием вокруг Amnezia: per-peer traffic shaping, IFB ingress shaping, nftables host firewall, anti-torrent connection guard, managed swap, диагностикой drift и плановым reboot.
Проект разрабатывался и проверялся под AmneziaWG/AWG 2.0 и совместимый legacy-сценарий AmneziaWG/AWG 1.5. Он не заменяет AmneziaVPN, не генерирует ключи клиентов и не меняет продуктовую логику Amnezia. Amnezia сначала ставится официальным способом, после этого устанавливается AWG2 Harness.
Релиз source-validated по официальной документации и исходникам AWG 3.1; фактическая live-приёмка выполняется после production deployment. Harness не заменяет AmneziaVPN, не генерирует ключи клиентов и не мигрирует AWG 2.0 на 3.1. Amnezia сначала ставится официальным способом, после этого устанавливается AWG2 Harness. Точная upstream-база зафиксирована в [`docs/UPSTREAM_COMPATIBILITY.md`](docs/UPSTREAM_COMPATIBILITY.md).
## Что ставит пакет
@@ -118,37 +118,38 @@ AWG2 Harness не устанавливает Amnezia. Используйте о
1. Установите актуальное приложение AmneziaVPN на рабочую машину.
2. В приложении выберите self-hosted server.
3. Укажите публичный IPv4 сервера, SSH-порт, SSH-пользователя и приватный ключ.
4. Установите AmneziaWG/AWG. Для AWG 2.0 нужен актуальный AmneziaVPN, где протокол AmneziaWG 2.0 доступен в списке протоколов.
4. Установите AmneziaWG 3.1. Для self-hosted deployment требуется AmneziaVPN 5.0.1.5 или новее.
5. После установки убедитесь, что контейнер поднят и UDP-порт опубликован.
Проверка на сервере:
```bash
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
C="$(docker ps --format '{{.Names}}' | grep -E '^(amnezia-awg2|amnezia-awg3|amnezia-awg)$' | head -n1)"
C="$(docker ps --format '{{.Names}}' | grep -E '^(amnezia-awg2|amnezia-awg)$' | head -n1)"
echo "container=$C"
docker port "$C"
docker exec "$C" awg show
```
Ожидаемые имена контейнера по умолчанию: `amnezia-awg2` или `amnezia-awg`. `amnezia-awg3` перечислен на будущее — в AmneziaVPN 5.0 такого типа контейнера ещё нет. Ожидаемый интерфейс внутри container netns: обычно `awg0`, fallback-кандидаты описаны в `config.example.toml`.
Ожидаемые имена контейнера по умолчанию: основной `amnezia-awg2`, затем legacy fallback `amnezia-awg`. Ожидаемый интерфейс внутри container netns — `awg0`; дополнительные fallback-кандидаты описаны в `config.example.toml`. Любое другое корректное имя можно указать вручную в config.
### Совместимость с AmneziaWG 3.0
### Совместимость с AmneziaWG 3.1
Проверено по исходникам на: AmneziaVPN `5.0.0.5`, `amneziawg-tools` и `amneziawg-go` ветки `master` на момент правки. Утверждения ниже относятся к этим версиям; при более новых релизах их нужно перепроверить, а не считать бессрочными.
Канонические версии, commit SHA и официальные ссылки приведены в [`docs/UPSTREAM_COMPATIBILITY.md`](docs/UPSTREAM_COMPATIBILITY.md). Релиз 0.3.1 source-validated against AWG 3.1; до отдельной live-приёмки это не означает «протестировано на production AWG 3.1».
Обвязка не реализует AWG на уровне пакетов: `tc`, IFB и `nftables` работают с inner-IP уже после декапсуляции, поэтому header protection, content padding и рандомизация таймеров AWG 3.0 её не касаются.
Обвязка не реализует AWG на уровне пакетов: `tc`, IFB и `nftables` работают с inner-IP уже после декапсуляции, поэтому header protection, content padding, RandomTrailers и DisableCookies её не касаются.
Читается только peer state, всегда через `docker exec`. Реальный бинарь в официальном образе — `/usr/bin/awg`, `/usr/bin/wg` является symlink на него; порядок задаётся `amnezia.wg_binaries` (по умолчанию `["awg", "wg"]`). На хосте `wireguard-tools` не требуется и не проверяется в preflight: AmneziaWG — userspace-реализация, её UAPI-сокет лежит в mount namespace контейнера, и хостовый `wg` через `nsenter -n` до него не достаёт.
Peer state читается через `docker exec` официальным `awg` внутри контейнера; `/usr/bin/wg` в reference image является symlink на него. Это единая container-side точка доступа независимо от того, использован kernel `amneziawg` или fallback `amneziawg-go`, и она не привязывает harness к host-side tools. Порядок задаётся `amnezia.wg_binaries` (по умолчанию `["awg", "wg"]`); host `wireguard-tools` не требуется.
Smoke-проверка после обновления контейнера:
```bash
C="$(docker ps --format '{{.Names}}' | grep -E '^(amnezia-awg2|amnezia-awg3|amnezia-awg)$' | head -n1)"
C="$(docker ps --format '{{.Names}}' | grep -E '^(amnezia-awg2|amnezia-awg)$' | head -n1)"
docker exec "$C" readlink -f /usr/bin/wg # ожидается /usr/bin/awg
docker exec "$C" awg --version
docker exec "$C" ip -o link show awg0
docker exec "$C" ip -d link show awg0
docker exec "$C" awg show all allowed-ips
docker port "$C"
@@ -156,15 +157,15 @@ docker port "$C"
docker exec "$C" awg show all dump | awk -F '\t' '{ print "row=" NR, "fields=" NF, "interface=" $1 }'
```
Ожидаемо: `/usr/bin/wg` указывает на `/usr/bin/awg`, интерфейс `awg0` существует, peer-адреса отображаются, серверный порт опубликован по UDP. Peer-строки дают 9 полей.
Для reference tools AWG 3.1 ожидаемо: `/usr/bin/wg` указывает на `/usr/bin/awg`, интерфейс `awg0` существует, peer-адреса отображаются, серверный порт опубликован по UDP, interface-row содержит 30 полей, peer-row — 9.
Ширина interface-строки зависит от версии `amneziawg-tools`, а не от версии параметров в конфигурации: утилиты AWG 3.0 печатают расширенную строку и для туннеля, настроенного как AWG 2.0. По количеству колонок определять версию протокола нельзя, и обвязка этого не делает.
Исторически WireGuard/AWG 2.x/AWG 3.0/AWG 3.1 tools печатают interface-row шириной 5/14/28/30 полей соответственно; текущий peer-row содержит 9. Это только диагностика: ширина зависит от producer tools, а не от версии параметров туннеля. По количеству колонок harness не определяет версию и не классифицирует peer.
Полный вывод `awg show all dump` передавать нельзя: во второй колонке interface-строки находится приватный ключ устройства.
### 3.1 Установить AmneziaDNS (обязательный production-шаг)
Для production-профиля AWG2 установите AmneziaDNS из приложения AmneziaVPN после установки AmneziaWG/AWG:
Для production-профиля AWG 3.1 установите AmneziaDNS из приложения AmneziaVPN после установки AmneziaWG:
```text
AmneziaVPN:
@@ -188,13 +189,13 @@ Security note:
```bash
cd awg2_harness
./tools/build.sh --prepare-build-env --bootstrap-rust --yes
./tools/build.sh --package --version 0.3.0
./tools/build.sh --package
(cd dist && sha256sum -c SHA256SUMS)
dpkg-deb -I dist/awg2-harness_0.3.0_amd64.deb
dpkg-deb -c dist/awg2-harness_0.3.0_amd64.deb | sort
dpkg-deb -I dist/awg2-harness_0.3.1_amd64.deb
dpkg-deb -c dist/awg2-harness_0.3.1_amd64.deb | sort
```
`--version` можно не указывать, если версия в `traffic_core/Cargo.toml` уже соответствует release. Если version override указан, он меняет версию Debian-пакета, а не версию crate в `Cargo.toml`.
Release package берёт версию из `traffic_core/Cargo.toml`. `--version` предназначен только для осознанного Debian packaging override и не меняет версию crate.
### 5. Перенести `.deb` и config на production
@@ -224,7 +225,7 @@ scp -P 2323 dist/SHA256SUMS root@<server-ip>:/root/
```bash
cd /root
sha256sum -c SHA256SUMS
chmod 644 /root/awg2-harness_0.3.0_amd64.deb
chmod 644 /root/awg2-harness_0.3.1_amd64.deb
apt install ./awg2-harness_*_amd64.deb
install -d -m 0755 /etc/awg2-harness
install -m 0644 /root/awg2-harness.config.toml /etc/awg2-harness/config.toml
@@ -237,7 +238,7 @@ install -m 0644 /root/awg2-harness.config.toml /etc/awg2-harness/config.toml
```bash
cd /root
sha256sum -c SHA256SUMS
chmod 644 /root/awg2-harness_0.3.0_amd64.deb
chmod 644 /root/awg2-harness_0.3.1_amd64.deb
apt install ./awg2-harness_*_amd64.deb
install -d -m 0755 /etc/awg2-harness
cp /usr/share/doc/awg2-harness/repo/config.example.toml /etc/awg2-harness/config.toml
@@ -317,7 +318,7 @@ awg2-harness --config /etc/awg2-harness/config.toml status
Дополнительно можно проверить фактическую `tc` topology внутри network namespace Amnezia:
```bash
C="$(docker ps --format '{{.Names}}' | grep -E '^(amnezia-awg2|amnezia-awg3|amnezia-awg)$' | head -n1)"
C="$(docker ps --format '{{.Names}}' | grep -E '^(amnezia-awg2|amnezia-awg)$' | head -n1)"
PID="$(docker inspect -f '{{.State.Pid}}' "$C")"
nsenter -t "$PID" -n -- tc class show dev awg0
@@ -344,7 +345,7 @@ awg2-harness --config /etc/awg2-harness/config.toml <command>
`apply-firewall` делает два reconcile: host INPUT firewall в таблице `inet awg2_host_firewall` и anti-torrent guard в выбранном namespace. Команда не управляет Docker NAT и host `FORWARD`.
`apply-limits` находит Amnezia container, заходит в его network namespace, читает peers через `wg`, строит per-peer HTB/fq_codel классы на AWG/WG интерфейсе и IFB ingress path. Если drift не найден, пишет `traffic rules up-to-date, skip apply`.
`apply-limits` находит Amnezia container, заходит в его network namespace, читает peers через container-side `awg`/`wg`, строит per-peer HTB/fq_codel классы на AWG/WG интерфейсе и IFB ingress path. Если drift не найден, пишет `traffic rules up-to-date, skip apply`.
`status` печатает фактическую диагностику: сервис, контейнер, netns, интерфейс, peers, WireGuard runtime, traffic desired/actual, host firewall drift, Docker/Amnezia port path, anti-torrent counters, swap state, conntrack, recent events и planned reboot.
@@ -386,6 +387,7 @@ AWG2 Harness не владеет:
## Документация
- [`docs/INSTALLATION.md`](docs/INSTALLATION.md) — установка и preflight.
- [`docs/UPSTREAM_COMPATIBILITY.md`](docs/UPSTREAM_COMPATIBILITY.md) — upstream-версии и контракт AWG 3.1.
- [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) — параметры `config.toml`.
- [`docs/ACCEPTANCE_CHECKLIST.md`](docs/ACCEPTANCE_CHECKLIST.md) — production checklist.
- [`docs/ANTI_TORRENT.md`](docs/ANTI_TORRENT.md) — connection-count guard.