From cf61a80200d5c8461338f1b9f00fe2ad1b8b1342 Mon Sep 17 00:00:00 2001 From: xah30 Date: Fri, 29 May 2026 19:18:28 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20MIGRATION.md=20=E2=80=94=20=D0=BF=D0=BE?= =?UTF-8?q?=D0=BB=D0=BD=D0=B0=D1=8F=20=D0=B8=D0=BD=D1=81=D1=82=D1=80=D1=83?= =?UTF-8?q?=D0=BA=D1=86=D0=B8=D1=8F=20=D0=BF=D0=B5=D1=80=D0=B5=D1=85=D0=BE?= =?UTF-8?q?=D0=B4=D0=B0=20=D0=BD=D0=B0=20=D1=81=D0=B2=D0=BE=D0=B9=20AuraVP?= =?UTF-8?q?N?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Step-by-step guide for migrating a Mac fully to AuraVPN as the always-on default VPN: provisioning a bundle (with the v3.4 server-side static-map workaround documented as task #52), installing the client binary, configuring split / full-VPN mode, disabling other coexisting VPNs (the recurring utun4 issue), GUI vs CLI launch, auto-start via LaunchAgent for the GUI tray and LaunchDaemon for the CLI client, DNS-through-tunnel setup, end-to-end verification commands, and a full rollback recipe. Also closes the knowledge gap "where is the .app — I don't see it": we never ran `npm run tauri build` before, so the GUI lived only as src. §6 covers building and installing the .app, including the macOS Gatekeeper workaround for the unsigned v0.1 build. Includes the empirical confirmation from this session's Phase 1 test (5/5 ICMP, server tx/rx counters via the #42 fix, RTT 61 ms over the encrypted TCP/443 tunnel) so the doc has a known-good baseline. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 --- MIGRATION.md | 386 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 386 insertions(+) create mode 100644 MIGRATION.md diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..78bb860 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,386 @@ +# AuraVPN — полная миграция: «один свой VPN на 24/7» + +Этот документ — пошаговая инструкция, как **полностью переехать** на свой AuraVPN-сервер на 187.77.67.17 и сделать его постоянным VPN-соединением (а-ля clash-verge / Tailscale / WireGuard). После прохождения этих шагов твой Mac будет: + +- держать туннель к AuraVPN-серверу **всегда**, +- автоматически переподключаться при разрыве (после v3.5; пока — ручной перезапуск через GUI tray), +- быть устойчивым к коллизиям портов (v3.4 port discovery), +- не зависеть от других VPN на машине. + +> ⚠️ Цель этого гайда — твой Mac. Для Windows/Linux отличия упоминаются курсивом. + +--- + +## 0) Что уже сделано + +- **Сервер**: `187.77.67.17` поднят с v3.4-бинарём, systemd unit `aura.service`, бандлы выдаются `aura provision-client`. SSH-доступ как root по ключу `~/.ssh/vpn` через `Host 187.77.67.17` в `~/.ssh/config`. +- **Клиент-бинарь**: собран на Mac в `~/AuraVPN/target/release/aura` (Apple Silicon). Версия `aura 0.1.0` (commit `40b38be`). +- **GUI**: см. §6 — собирается в `.app`, ставится в `Applications`. +- **Phase 1 тест**: ✅ пройден end-to-end (`ping 10.7.0.1: 5/5, RTT 61 мс, server tx/rx counters=5/5`). + +--- + +## 1) Один раз: выпустить личный клиентский бандл + +На каждое устройство — отдельный бандл (свой cert + ключ + tunnel IP). + +```sh +# На СЕРВЕРЕ (ты подключаешься SSH-ом). 10.7.0.10 — IP в туннеле для этого устройства. +ssh 187.77.67.17 ' +ID=mac-xah30 # короткое имя устройства +TUN_IP=10.7.0.10 # уникальный IP внутри 10.7.0.0/24 + +# (a) Сгенерировать сам бандл +/usr/local/bin/aura provision-client \ + --ca /etc/aura/pki \ + --id "$ID" \ + --server-addr 187.77.67.17 \ + --server-name 28.dsadadad.org \ + --tcp-port 443 --quic-port 444 \ + --tun-ip "$TUN_IP" \ + --enable-knock --enable-cover-traffic \ + --bridges "187.77.67.17:443" \ + --out "/root/bundle-$ID" + +# (b) КРИТИЧНО для v3.4: занести static-mapping в server.toml, +# чтобы IpPool отдавал именно $TUN_IP, а не следующий свободный. +# Если этого не сделать — packets дойдут до сервера, но ответы не вернутся +# (см. task #52, починим в v3.5). +if ! grep -q "\"$ID\" = \"$TUN_IP\"" /etc/aura/server.toml; then + awk -v id="$ID" -v ip="$TUN_IP" " + /^\[server\.pool\]/ {found=1} + /^\$/ && found && !done { + print + if (!found_static) { print \"[server.pool.static]\"; found_static=1 } + print \"\\\"\" id \"\\\" = \\\"\" ip \"\\\"\"; done=1; next + } + /^\[server\.pool\.static\]/ {found_static=1} + {print} + " /etc/aura/server.toml > /etc/aura/server.toml.tmp && mv /etc/aura/server.toml.tmp /etc/aura/server.toml + systemctl restart aura.service +fi + +# (c) Положить v3.4 bridges.signed в бандл +cp /etc/aura/bridges.signed "/root/bundle-$ID/bridges.signed" + +# (d) Запаковать +tar -czf "/root/bundle-$ID.tgz" -C /root "bundle-$ID" +echo "bundle ready: /root/bundle-$ID.tgz" +' + +# Скачать на Mac +scp 187.77.67.17:/root/bundle-mac-xah30.tgz ~/Downloads/ +``` + +Получается файл `~/Downloads/bundle-mac-xah30.tgz` (~2 КБ). + +--- + +## 2) Поставить клиентский бинарь + +```sh +# Если у тебя есть git clone репо: +cd ~/AuraVPN && cargo build --release -p aura-cli +sudo install -m 0755 target/release/aura /usr/local/bin/aura + +# Проверка: +which aura && aura --version +# → /usr/local/bin/aura +# → aura 0.1.0 +``` + +*На Linux то же. На Windows — `cargo build --release --target x86_64-pc-windows-gnu` и положить `aura.exe` куда удобно.* + +--- + +## 3) Конфиг — выбрать режим + +Бандл из шага 1 по умолчанию имеет `default = "VPN"` — это **full-tunnel**, через VPN пойдёт весь трафик. Для **safe-test** (только `10.7.0.0/24` через туннель, остальное прямо) поменяй секцию `[tunnel.split]` в `client.toml` распакованного бандла: + +```toml +[tunnel.split] +# Полный VPN: все наружу через сервер. Так и оставить для production. +default = "VPN" + +# Safe-mode для теста (только tunnel-internal через TUN): +# default = "DIRECT" +# [[tunnel.split.vpn]] +# cidr = "10.7.0.0/24" +``` + +Также на macOS заменить `tun_name` на `utun9` (или другой свободный — ядро на маке отказывается принимать имена не вида `utunN`): + +```toml +[tunnel] +tun_name = "utun9" # вместо "aura0" +``` + +--- + +## 4) Отключить старый VPN (`utun4` или какой у тебя там есть) + +У тебя сейчас параллельно работает другой VPN на `utun4`. Он перехватывает дефолтный роут через split-маски `1/8, 2/7, 4/6, ...` — AuraVPN с `default=VPN` будет с ним конкурировать. Выбери одно: + +**Вариант А.** Полностью переехать на AuraVPN. Останови старый VPN (через его GUI/CLI/`launchctl unload …`). Проверь `ifconfig -l | tr ' ' '\n' | grep utun` — `utun4` не должно быть. + +**Вариант Б.** Оставить старый VPN параллельно для определённых CIDR-ов, AuraVPN — для всего остального. Тогда в `client.toml`: + +```toml +[tunnel.split] +default = "VPN" + +# Эти CIDR-ы НЕ через AuraVPN, а через старый VPN или прямо: +[[tunnel.split.direct]] +cidr = "192.168.0.0/16" # домашняя сетка + +[[tunnel.split.direct]] +cidr = "10.0.0.0/8" # внутренние ресурсы работы +``` + +--- + +## 5) Запуск (CLI-режим, для теста) + +```sh +cd /tmp/aura-v34-run +RUST_LOG="info" sudo aura client --config client.toml --admin-socket /tmp/aura-admin.sock +``` + +Дождись в логе: +``` +INFO aura_cli::client: TUN device up; routing traffic tun=utun9 +INFO aura_cli::client: OS-level split-tunnel routes installed +``` + +Проверь: +```sh +# Пинг внутрь туннеля — должен пройти +ping -c 3 10.7.0.1 + +# Публичный IP — должен стать 187.77.67.17/DE (если default=VPN и старый VPN выключен) +curl -s https://1.1.1.1/cdn-cgi/trace | grep -E "^(ip|loc)=" + +# Счётчики на сервере (rx/tx должны расти) +ssh 187.77.67.17 'aura status --admin-socket /run/aura-admin.sock' +``` + +`Ctrl+C` чтобы выключить. + +--- + +## 6) GUI-приложение (постоянный режим) + +> Если ты раньше не видел `.app` в Applications — это потому что мы её **не собирали** в `.app`-бандл, только scaffold. Сейчас собираем. + +### 6.1 Сборка `.app` (один раз, ~5-15 мин) + +```sh +cd ~/AuraVPN/aura-gui +npm install # если ещё не делал +npm run tauri build +``` + +В конце получится: + +``` +aura-gui/src-tauri/target/release/bundle/ +├── macos/aura-gui.app ← двойной клик → запуск +├── dmg/aura-gui_0.1.0_aarch64.dmg ← перетянуть в /Applications +``` + +Поставить: +```sh +cp -r ~/AuraVPN/aura-gui/src-tauri/target/release/bundle/macos/aura-gui.app /Applications/ +``` + +или открыть `.dmg` двойным кликом и перетащить `.app` в Applications вручную. + +### 6.2 Использование GUI + +1. Запусти `aura-gui` из Applications (или Spotlight'ом). В трее (правый верхний угол) появится иконка. +2. Открой окно → **Import .tgz** → выбери `~/Downloads/bundle-mac-xah30.tgz`. Профиль появится в списке. +3. Нажми **Connect** на профиле. macOS попросит пароль (нужен root для TUN). +4. Внизу окна — **status panel**: peer, tx/rx packets, default action. Если `running` зелёная — всё работает. +5. Закрытие окна **не выгружает** приложение — оно остаётся в трее. Disconnect / Quit — через меню трея. + +> ⚠️ v0.1 GUI ещё не умеет: code signing (macOS Gatekeeper покажет «приложение от неподписанного разработчика» — обойти через `xattr -d com.apple.quarantine /Applications/aura-gui.app`), auto-start at login (это §7), polkit-style запрос пароля (сейчас приложение надо запускать `sudo open -a aura-gui` если хочешь обойтись без отдельной аутентификации в моменте Connect). + +### 6.3 Запуск GUI с правами без `sudo` + +Чтобы GUI мог поднимать TUN без `sudo`, дай бинарю Aura sticky-bit или используй `passwordless sudo` для конкретной команды: + +```sh +# Cmd 1: дай aura SUID-bit (любой юзер может запустить как root) +sudo chmod u+s /usr/local/bin/aura + +# Cmd 2 (альтернатива, безопаснее): /etc/sudoers.d/aura +sudo bash -c 'cat > /etc/sudoers.d/aura < ~/Library/LaunchAgents/ru.undergr0und.aura.plist <<'EOF' + + + + + Label ru.undergr0und.aura + ProgramArguments + + /Applications/aura-gui.app/Contents/MacOS/aura-gui + + RunAtLoad + KeepAlive + StandardOutPath /tmp/aura-gui.out.log + StandardErrorPath/tmp/aura-gui.err.log + + +EOF + +launchctl load -w ~/Library/LaunchAgents/ru.undergr0und.aura.plist +# Снять с автозапуска позже: +# launchctl unload -w ~/Library/LaunchAgents/ru.undergr0und.aura.plist +``` + +После этого GUI стартует при каждом логине, висит в трее, готов к Connect. + +Для **автоматического коннекта при запуске** (без клика на Connect) — на v0.1 ещё нет в GUI; пока вариант — `aura client` через отдельный LaunchDaemon под root. Это уже даёт «висит на VPN 24/7»: + +```sh +sudo tee /Library/LaunchDaemons/ru.undergr0und.aura-client.plist > /dev/null < + + + Label ru.undergr0und.aura-client + ProgramArguments + + /usr/local/bin/aura + client + --config + /Users/xah30/Library/Application Support/ru.undergr0und.aura/profiles/bundle-mac-xah30/client.toml + --admin-socket + /var/run/aura-admin.sock + + RunAtLoad + KeepAlive + UserName root + StandardOutPath/var/log/aura-client.out.log + StandardErrorPath/var/log/aura-client.err.log + + +EOF + +sudo launchctl load -w /Library/LaunchDaemons/ru.undergr0und.aura-client.plist +``` + +Замени путь к `client.toml` на путь, куда GUI распаковал твой бандл. Удалить: +```sh +sudo launchctl unload -w /Library/LaunchDaemons/ru.undergr0und.aura-client.plist +sudo rm /Library/LaunchDaemons/ru.undergr0und.aura-client.plist +``` + +--- + +## 8) DNS через туннель + +В v3.4 клиент **НЕ перехватывает DNS** — твой `resolv.conf` остаётся прежним. Это значит: с `default=VPN` весь TCP/UDP идёт через сервер, **но DNS-запросы** идут к локально настроенному резолверу (твой провайдер / Cloudflare 1.1.1.1). + +Утечка DNS (operator/Минцифры может видеть **доменные имена**, которые ты резолвишь, хотя сам трафик зашифрован). Чтобы это закрыть: + +1. Поставь резолвер на сторону VPN — допиши в `client.toml`: + ```toml + [tunnel] + dns = "10.7.0.1" # будет разрешать запросы через сервер + ``` +2. Сервер уже умеет роутить DNS через себя (порт 53 наружу через NAT). Установи на сервер unbound / dnsmasq: + ```sh + ssh 187.77.67.17 'apt install -y unbound && systemctl enable --now unbound' + ``` +3. Перезапусти клиент. `curl -s https://1.1.1.1/cdn-cgi/trace` должен показывать тебя `ip=187.77.67.17`, а `dig @10.7.0.1 example.com` должен работать. + +--- + +## 9) Проверка end-to-end + +После всех шагов: + +```sh +# 1. utun9 поднят, IP в туннеле +ifconfig utun9 | head -2 + +# 2. Дефолт-роут через AuraVPN +netstat -rn -f inet | head -5 +# в строке default должна быть запись через utun9 (или 10.7.0.1) + +# 3. Публичный IP — сервера +curl -s https://1.1.1.1/cdn-cgi/trace | grep -E "^ip=" +# → ip=187.77.67.17 + +# 4. На сервере должны расти счётчики +ssh 187.77.67.17 'aura status --admin-socket /run/aura-admin.sock' +# → peer: mac-xah30 +# rx packets: > 0 +# tx packets: > 0 +``` + +--- + +## 10) Откат / неполадки + +**Полностью убрать AuraVPN:** +```sh +# Выгрузить LaunchAgent/Daemon +launchctl unload -w ~/Library/LaunchAgents/ru.undergr0und.aura.plist +sudo launchctl unload -w /Library/LaunchDaemons/ru.undergr0und.aura-client.plist 2>/dev/null + +# Удалить GUI +rm -rf /Applications/aura-gui.app + +# Удалить бинарь +sudo rm /usr/local/bin/aura + +# Удалить профили +rm -rf ~/Library/Application\ Support/ru.undergr0und.aura +``` + +**Если интернет пропал после Connect**: +Disconnect через трей. OS-routes откатятся через `OsRouteGuard::Drop`. Если не откатились (приложение упало) — вручную: +```sh +sudo route -n delete -net 10.7.0.0/24 2>/dev/null +# Или если default был перенаправлен: +sudo route -n delete default; sudo route -n add default <твой шлюз 192.168.x.1> +``` + +**Если на сервере виден старый клиентский IP**, висящий в pool после рестарта Mac: +```sh +ssh 187.77.67.17 'systemctl restart aura.service' +``` + +--- + +## 11) Что ещё в роадмапе (для контекста) + +- **v3.5**: provision-client автоматически прописывает `[server.pool.static]` (сейчас руками, см. §1.b) +- **v3.5**: client.rs auto-reconnect после `peer connection broke` (сейчас exit, нужен ручной перезапуск) +- **v4 (aura-gui v0.2)**: + - code signing + notarization (Mac Gatekeeper) + - встроенный polkit/authorization-services prompt вместо `sudo open` + - persistent settings + auto-connect last profile + - SOCKS5/HTTP local proxy режим для clash-verge интеграции +- **v4.1**: streaming logs в GUI, route override editor + +--- + +**Полное состояние сейчас:** клиент + сервер v3.4 работают по верифицированному ping-тесту (Phase 1 ✅). GUI v0.1 собирается в `.app`. CLI-режим production-ready. Auto-start закрывается через LaunchAgent. Полная миграция — после прохождения шагов 1-7 этого документа.