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

fix28: обновлена production-документация и упаковка docs в deb

Browse Source
This commit is contained in:
Crimson
2026-05-12 16:56:36 +05:00
parent a9bac8fdad
commit 69c737bcf4
10 changed files with 488 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ACCEPTANCE_CHECKLIST.md
+2 -2
View File
@@ -4,7 +4,7 @@
- [ ] Хост — Debian 13 amd64.
- [ ] Сервер выделенный, без соседних сервисов.
- [ ] AmneziaWG/AWG 2.0 установлена официальным способом.
- [ ] AmneziaWG/AWG 2.0 или AmneziaWG/AWG 1.5 установлена официальным способом.
- [ ] Контейнер `amnezia-awg2` или `amnezia-awg` запущен.
- [ ] `docker ps` видит контейнер.
- [ ] Можно получить PID контейнера.
@@ -102,7 +102,7 @@
- [ ] Есть chain `forward_antitorrent` с hook `forward` и policy `accept`.
- [ ] Правило ограничивает `ip saddr <peer_ipv4_cidr>`, default `10.8.1.0/24`.
- [ ] Лимит считается per source VPN IP через meter/set, а не глобально по всей подсети.
- [ ] Порог совпадает с `anti_torrent.max_connections_per_peer`, default `100`.
- [ ] Порог совпадает с `anti_torrent.max_connections_per_peer`; текущий пример config использует `150`, более строгий вариант — `100`.
- [ ] Drop counter виден в `status`.
- [ ] На first-run без table `awg2-harness apply-firewall` создаёт `table inet awg2_harness`, а не падает.
- [ ] При превышении порога новые flows дропаются, established flows ниже порога не ломаются.
docs/ANTI_TORRENT.md
+4 -4
View File
@@ -65,18 +65,18 @@ table inet awg2_harness {
## 4. Threshold
Рекомендуемый default:
Рекомендуемый стартовый production baseline:
```toml
[anti_torrent]
enabled = true
max_connections_per_peer = 100
max_connections_per_peer = 150
```
Практические варианты:
- `100` — production default, более строгий режим.
- `150` — мягче, если есть жалобы на false positives.
- `100` — более строгий режим.
- `150` — текущий рекомендуемый стартовый baseline, мягче к обычному browsing/mobile traffic.
- `200/250` — ещё более permissive варианты.
- `70` — агрессивный режим только после наблюдения реального трафика.
docs/CONFIGURATION.md
+4 -4
View File
@@ -1,6 +1,6 @@
# Конфигурация AWG2 Harness
Конфиг живёт в `/etc/awg2-harness/config.toml`. Он общий для всего пакета и должен содержать только эксплуатационно значимые параметры.
AWG2 Harness разрабатывался для self-hosted AmneziaWG/AWG 2.0 и совместимого legacy-сценария AmneziaWG/AWG 1.5. Конфиг живёт в `/etc/awg2-harness/config.toml`. Он общий для всего пакета и должен содержать только эксплуатационно значимые параметры.
## Рекомендуемый `config.toml`
@@ -30,7 +30,7 @@ default_input_policy = "drop"
[anti_torrent]
enabled = true
max_connections_per_peer = 100
max_connections_per_peer = 150
peer_ipv4_cidr = "10.8.1.0/24"
apply_in_amnezia_netns = true
@@ -75,7 +75,7 @@ swappiness = 1
`host_firewall.enabled` — включает host-level INPUT firewall в отдельной AWG2-owned таблице `inet awg2_host_firewall`.
`host_firewall.ssh_port` — SSH порт хоста, который обязательно должен быть открыт. Production default: `2323`.
`host_firewall.ssh_port` — SSH порт хоста, который обязательно должен быть открыт. Production default/example: `2323`. Значение обязано совпадать с реально слушающим sshd портом до применения `apply-firewall`.
`host_firewall.amnezia_port` — внешний UDP/TCP порт Amnezia, который AWG2 открывает в host `INPUT` (в зависимости от `host_firewall.amnezia_protocols`). Значение должно совпадать с портом, указанным в панели/инсталляторе AmneziaWG. В старых инсталляциях это мог быть `44344`, в новой целевой конфигурации default — `443`.
@@ -91,7 +91,7 @@ swappiness = 1
`host_firewall.default_input_policy` — политика INPUT chain (`drop` или `accept`). Для production рекомендуется `drop`.
`anti_torrent.max_connections_per_peer` — максимум одновременных conntrack flows на один VPN peer IP. Default `100`; `250` — более мягкий вариант.
`anti_torrent.max_connections_per_peer` — максимум одновременных conntrack flows на один VPN peer IP. Текущий пример использует `150`: это мягче, чем строгий `100`, и обычно безопаснее как первый production baseline. `100` можно использовать как более жёсткий режим; `200/250` — более permissive варианты.
`anti_torrent.peer_ipv4_cidr` — подсеть, на которую распространяется правило. Обычно должна совпадать с `amnezia.peer_ipv4_cidr`.
docs/INSTALLATION.md
+131 -27
View File
@@ -1,78 +1,182 @@
# Installation
Этот документ описывает production-порядок установки AWG2 Harness. Подробный runtime-план с SSH hardening и Amnezia preflight находится в корневом [`README.md`](../README.md).
## Deployment contract
- Build выполняется на отдельной Debian 13 amd64 build-machine.
- Production-хост получает готовый Debian-пакет.
- На production-хосте не требуются Rust/cargo/source tree.
- Amnezia должна быть уже установлена и работать через Docker.
- Production-конфиг создаётся вручную; [`config.example.toml`](../config.example.toml) не копируется автоматически как боевой конфиг.
- Целевой production-хост: Debian 13 amd64.
- Amnezia ставится до AWG2 Harness официальным self-hosted способом через приложение AmneziaVPN.
- Проект рассчитан на AmneziaWG/AWG 2.0 и compatible legacy-сценарий AmneziaWG/AWG 1.5.
- SSH должен быть заранее настроен. Production-пример: порт `2323`, вход по ключу, password login disabled.
- Production-хост получает готовый Debian-пакет; Rust/cargo/source tree на нём не требуются.
- `/etc/awg2-harness/config.toml` создаётся вручную. `config.example.toml` не копируется автоматически как боевой config.
- Пакет не устанавливает Docker/Amnezia и не включает services автоматически.
## A. Build machine
### A1. Подготовка build environment
### A1. Подготовить build environment
```bash
cd awg2_harness
chmod +x tools/build.sh
./tools/build.sh --prepare-build-env --bootstrap-rust --yes
```
### A2. Build и тесты
### A2. Проверить код
```bash
cargo fmt --manifest-path Cargo.toml --all --check
cargo clippy --locked --workspace --all-targets --manifest-path Cargo.toml -- -D warnings
cargo test --locked --workspace --release --manifest-path Cargo.toml
```
То же самое выполняет build helper:
```bash
./tools/build.sh --build
```
### A3. Сборка пакета
### A3. Собрать Debian-пакет
```bash
./tools/build.sh --package
./tools/build.sh --package --version 0.1.6
sha256sum -c dist/SHA256SUMS
dpkg-deb -I dist/awg2-harness_0.1.6_amd64.deb
dpkg-deb -c dist/awg2-harness_0.1.6_amd64.deb | sort
```
## B. Transfer artifacts
`--version` можно опустить, если версия в `traffic_core/Cargo.toml` уже равна release version. Version override влияет только на metadata `.deb`.
## B. Подготовить production-хост
### B1. SSH
Production-пример:
```bash
scp dist/awg2-harness_*_amd64.deb root@vpn-host:/root/
scp config.toml root@vpn-host:/root/awg2-harness.config.toml
install -d -m 0755 /etc/ssh/sshd_config.d
cat >/etc/ssh/sshd_config.d/99-awg2-production.conf <<'EOF'
Port 2323
PermitRootLogin prohibit-password
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
EOF
sshd -t
systemctl reload ssh 2>/dev/null || systemctl reload sshd
ss -ltnp | grep ':2323'
```
## C. Production host
### C1. Install package
Обязательно проверьте вход с нового терминала:
```bash
ssh -p 2323 root@<server-ip>
```
### B2. Amnezia
Установите AmneziaWG/AWG через официальное приложение AmneziaVPN в режиме self-hosted server. Вводите в приложении тот SSH host/port/user/private key, который реально работает после B1.
Проверка после установки:
```bash
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
C="$(docker ps --format '{{.Names}}' | grep -E '^(amnezia-awg2|amnezia-awg)$' | head -n1)"
echo "container=$C"
docker port "$C"
docker exec "$C" wg show
```
Если контейнер называется иначе или интерфейс не `awg0`, отразите это в `/etc/awg2-harness/config.toml`.
## C. Transfer artifacts
```bash
scp -P 2323 dist/awg2-harness_*_amd64.deb root@<server-ip>:/root/
scp -P 2323 dist/SHA256SUMS root@<server-ip>:/root/
scp -P 2323 config.example.toml root@<server-ip>:/root/awg2-harness.config.toml
```
Перед установкой отредактируйте `/root/awg2-harness.config.toml`. Минимально проверьте:
- `[host_firewall].ssh_port` совпадает с реальным SSH-портом (`2323` в production-примере);
- `[host_firewall].amnezia_port` совпадает с published UDP port Amnezia;
- `[amnezia].peer_ipv4_cidr` совпадает с подсетью clients;
- `[anti_torrent].peer_ipv4_cidr` обычно равен `[amnezia].peer_ipv4_cidr`;
- `peer_limit` и `root_rate` отражают нужную traffic policy.
## D. Production install
```bash
cd /root
sha256sum -c SHA256SUMS
apt install ./awg2-harness_*_amd64.deb
```
### C2. Install config
```bash
install -d -m 0755 /etc/awg2-harness
install -m 0644 /root/awg2-harness.config.toml /etc/awg2-harness/config.toml
systemctl daemon-reload
```
### C3. Validate and apply
## E. Preflight before enable
```bash
awg2-harness --config /etc/awg2-harness/config.toml validate-config
awg2-harness --config /etc/awg2-harness/config.toml validate-runtime
awg2-harness --config /etc/awg2-harness/config.toml ensure-swap
awg2-harness --config /etc/awg2-harness/config.toml apply-limits
awg2-harness --config /etc/awg2-harness/config.toml apply-firewall
awg2-harness --config /etc/awg2-harness/config.toml apply-limits
awg2-harness --config /etc/awg2-harness/config.toml status
```
When `swap.enabled=true`, AWG2 Harness will disable all other active swap entries and rewrite `/etc/fstab` swap entries to a single managed swapfile.
Expected healthy result:
### C4. Enable services
```text
Traffic actual:
drift: no
Host firewall:
drift: no
Anti-torrent:
drift: no
Swap:
drift: no
```
If there are no peers yet, `apply-limits` may print `no peers found, skip tc apply`. That is healthy for an empty server.
When `swap.enabled=true`, AWG2 Harness intentionally makes swap exclusive: one managed swapfile, one fstab swap entry, configured swappiness.
## F. Enable services
```bash
systemctl enable --now awg2-harness.service
systemctl enable --now awg2-reboot-scheduler.service
systemctl status awg2-harness.service --no-pager -l
systemctl status awg2-reboot-scheduler.service --no-pager -l
journalctl -u awg2-harness.service --since '5 minutes ago' --no-pager
journalctl -u awg2-reboot-scheduler.service --since '5 minutes ago' --no-pager
```
## D. Manual source-tree install (staging/debug only)
After 30–60 seconds:
Режим [`./tools/build.sh --install`](../tools/build.sh) предназначен для staging/debug с checkout-репозиторием.
```bash
awg2-harness --config /etc/awg2-harness/config.toml status
```
Это **не** основной production deployment path.
## G. Reboot validation
```bash
reboot
```
After reconnect:
```bash
systemctl status docker --no-pager -l
systemctl status awg2-harness.service --no-pager -l
systemctl status awg2-reboot-scheduler.service --no-pager -l
awg2-harness --config /etc/awg2-harness/config.toml status
```
## H. Manual source-tree install
`./tools/build.sh --install` and `./tools/build.sh --enable` exist for staging/debug. They are not the recommended production path. Use `.deb` on production.
docs/MIGRATION.md
+1 -1
View File
@@ -199,7 +199,7 @@ default_input_policy = "drop"
[anti_torrent]
enabled = true
max_connections_per_peer = 100
max_connections_per_peer = 150
peer_ipv4_cidr = "10.8.1.0/24"
apply_in_amnezia_netns = true
docs/README.md
+15 -7
View File
@@ -2,10 +2,18 @@
Рекомендуемый порядок чтения:
1. [`OLD_BASH_BEHAVIOR.md`](OLD_BASH_BEHAVIOR.md) — что реально делает старая production bash-система.
2. [`MIGRATION.md`](MIGRATION.md) — corrected migration scope: Rust multi-orchestrator, а не механический bash port.
3. [`IMPLEMENTATION_SPEC.md`](IMPLEMENTATION_SPEC.md) — целевая архитектура и state reconciliation.
4. [`CONFIGURATION.md`](CONFIGURATION.md) — единый конфиг.
5. [`ANTI_TORRENT.md`](ANTI_TORRENT.md) — опциональный nftables guard против high-peer-count P2P.
6. [`INSTALLATION.md`](INSTALLATION.md) — установка на Debian 13 amd64.
7. [`ACCEPTANCE_CHECKLIST.md`](ACCEPTANCE_CHECKLIST.md) — критерии production-ready.
1. [`../README.md`](../README.md) — общий runtime-план: SSH, официальная Amnezia, установка пакета, preflight, reboot validation и CLI.
2. [`INSTALLATION.md`](INSTALLATION.md) — сжатый production install flow.
3. [`CONFIGURATION.md`](CONFIGURATION.md) — параметры `/etc/awg2-harness/config.toml`.
4. [`ACCEPTANCE_CHECKLIST.md`](ACCEPTANCE_CHECKLIST.md) — checklist перед production-ready статусом.
5. [`ANTI_TORRENT.md`](ANTI_TORRENT.md) — nftables connection-count guard.
6. [`IMPLEMENTATION_SPEC.md`](IMPLEMENTATION_SPEC.md) — архитектура и state reconciliation.
7. [`OLD_BASH_BEHAVIOR.md`](OLD_BASH_BEHAVIOR.md) — что делала старая bash-система.
8. [`MIGRATION.md`](MIGRATION.md) — контекст миграции с bash на Rust multi-orchestrator.
Отдельно:
- [`../tools/README.md`](../tools/README.md) — сборка и упаковка `.deb`.
- [`../reboot_module/README.md`](../reboot_module/README.md) — внешний reboot scheduler.
Практический порядок для оператора: сначала выполнить root README, затем свериться с acceptance checklist. Остальные документы нужны для понимания design intent и отладки.