Skip to content

Commit 9871f73

Browse files
author
Ivan Bondarev
committed
feat(v5.11.2): vpn:// QR for one-tap Amnezia VPN app import
Add `<name>.vpnuri.png` - a second per-client QR code rendered from the existing vpn:// URI - so users can one-tap-import clients into the flagship Amnezia VPN app (Android/iOS/Desktop). The existing `<name>.png` (scan of `.conf`) is unchanged and keeps working with WireGuard-compatible clients (AmneziaWG Windows, wireguard-apple, wg-quick). Code: - awg_common.sh + _en.sh: new generate_qr_vpnuri helper with atomic write (tmp.\$\$ in same dir -> qrencode -> chmod 600 -> mv -f) so a failed encode never leaves a truncated .vpnuri.png behind. - generate_client: hook after successful generate_vpn_uri (skipped if URI failed - no source to encode). generate_client and regenerate_client now both log_warn on URI failure for consistency. - manage_amneziawg.sh + _en.sh: regen refreshes both QR codes together; remove cleans up .vpnuri.png alongside .conf/.png/.vpnuri. - Updated lock-scope comment in regenerate_client to cover .vpnuri.png and document the known stale-artefact window against concurrent remove (peer already out of server config, user resolves on next regen/remove). Tests: - tests/test_qr_vpnuri.bats (+10 bats, 261 total, up from 251 on v5.11.1): happy path, missing .vpnuri -> error, qrencode non-zero exit -> error, atomic-write (stale PNG preserved on failure, no orphan .tmp.*), chmod 600 on Linux/Darwin, RU/EN structural parity of the helper, hooks in generate_client / regenerate_client / manage regen / remove. Docs: - ADVANCED.md + _en.md: section 'vpn:// URI import' updated with two import flows (QR scan for Amnezia VPN app + URI paste), callout about the two QR formats targeting different client families, migration note (manage regen <name> for pre-5.11.2 clients). - CHANGELOG bilingual RU+EN entry [5.11.2] - 2026-04-24. Release prep: - SCRIPT_VERSION 5.11.2 and header date 2026-04-24 across all 6 scripts. - COMMON_SCRIPT_SHA256 / MANAGE_SCRIPT_SHA256 in install_amneziawg{,_en}.sh refreshed to match the updated helpers. - README.md + README.en.md: quick-install URLs v5.11.1 -> v5.11.2 and version badge updated. Backup/restore already picks up `.vpnuri.png` via the existing *.png glob in _backup_configs_nolock and chmod 600 *.png in restore_backup - no changes needed there. Existing clients get the new .vpnuri.png after one `manage regen <name>`; downgrading to v5.11.1 is safe (stale .vpnuri.png just sits in /root/awg/ and is ignored).
1 parent 39f7e21 commit 9871f73

13 files changed

Lines changed: 434 additions & 84 deletions

‎ADVANCED.en.md‎

Lines changed: 22 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -858,22 +858,34 @@ sudo bash /root/awg/manage_amneziawg.sh add guest --expires=7d
858858
<a id="vpnuri-adv"></a>
859859
## 📱 vpn:// URI Import
860860

861-
When a client is created, a `.vpnuri` file is automatically generated with a `vpn://` URI for quick import into Amnezia Client.
861+
When a client is created, a `.vpnuri` file is automatically generated with a `vpn://` URI and, since v5.11.2, a QR code `<name>.vpnuri.png` encoding the same URI — for quick import into the Amnezia VPN app (Android / iOS / Desktop).
862862

863-
**File location:** `/root/awg/<client_name>.vpnuri`
863+
**File locations:**
864864

865-
**Format:** The configuration is compressed via zlib (Perl `Compress::Zlib`) and Base64-encoded, forming a URI like `vpn://...`.
865+
- `/root/awg/<client_name>.vpnuri` — plain-text `vpn://` URI
866+
- `/root/awg/<client_name>.vpnuri.png` — QR code of that URI (since v5.11.2)
866867

867-
> Perl with `Compress::Zlib` and `MIME::Base64` modules must be present on the server. On Ubuntu and Debian they are installed by default. If Perl is absent, `.vpnuri` files are not created, but `.conf` files work as usual.
868+
**Format:** the configuration is compressed via zlib (Perl `Compress::Zlib`) and Base64-encoded, forming a URI like `vpn://...`.
868869

869-
**Using with Amnezia Client:**
870+
> Perl with `Compress::Zlib` and `MIME::Base64` modules must be present on the server. On Ubuntu and Debian they are installed by default. If Perl is absent, neither `.vpnuri` nor `.vpnuri.png` is created, but `.conf` files work as usual. `qrencode` (already required for `.conf` QR) is also used for `.vpnuri.png`.
870871
871-
1. Copy the contents of the `.vpnuri` file
872-
2. Open Amnezia Client
873-
3. "Add VPN" → "Paste from clipboard"
874-
4. The configuration is imported automatically
872+
**Option 1 — QR code (recommended for mobile):**
875873

876-
**Permissions:** `.vpnuri` files have 600 permissions (root only).
874+
1. Copy `/root/awg/<name>.vpnuri.png` to your computer (`scp`) or open it locally.
875+
2. In the Amnezia VPN app on the phone: "Add VPN" → "Scan QR code".
876+
3. Point the camera at `.vpnuri.png` — the client imports automatically.
877+
878+
**Option 2 — URI paste:**
879+
880+
1. Copy the contents of the `.vpnuri` file.
881+
2. Open Amnezia VPN → "Add VPN" → "Paste from clipboard".
882+
3. The configuration is imported automatically.
883+
884+
> Alongside sits `<name>.png` — the QR of `.conf` for classic WireGuard-compatible clients (AmneziaWG Windows, wireguard-apple, `wg-quick`). The two formats target different clients: Amnezia VPN app scans `.vpnuri.png`, WireGuard-compatible clients scan `<name>.png`. Do not mix them up.
885+
886+
> For existing clients created before v5.11.2, `.vpnuri.png` appears after one `manage regen <name>`. New clients get both QR codes out of the box.
887+
888+
**Permissions:** `.vpnuri` and `.vpnuri.png` have 600 permissions (root only).
877889

878890
---
879891

‎ADVANCED.md‎

Lines changed: 22 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -856,22 +856,34 @@ sudo bash /root/awg/manage_amneziawg.sh add guest --expires=7d
856856
<a id="vpnuri-adv"></a>
857857
## 📱 vpn:// URI импорт
858858

859-
При создании клиента автоматически генерируется `.vpnuri` файл с `vpn://` URI для быстрого импорта в Amnezia Client.
859+
При создании клиента автоматически генерируется `.vpnuri` файл с `vpn://` URI и, начиная с v5.11.2, QR-код `<имя>.vpnuri.png` с тем же URI — для быстрого импорта в Amnezia VPN app (Android / iOS / Desktop).
860860

861-
**Расположение файлов:** `/root/awg/<имя_клиента>.vpnuri`
861+
**Расположение файлов:**
862862

863-
**Формат:** Конфигурация сжимается через zlib (Perl `Compress::Zlib`) и кодируется в Base64, формируя URI вида `vpn://...`.
863+
- `/root/awg/<имя_клиента>.vpnuri` — текстовый `vpn://` URI
864+
- `/root/awg/<имя_клиента>.vpnuri.png` — QR-код этого URI (с v5.11.2)
864865

865-
> Perl с модулями `Compress::Zlib` и `MIME::Base64` должен быть на сервере. На Ubuntu и Debian они установлены по умолчанию. Если Perl отсутствует, `.vpnuri` файлы не создаются, но `.conf` файлы работают штатно.
866+
**Формат:** конфигурация сжимается через zlib (Perl `Compress::Zlib`) и кодируется в Base64, формируя URI вида `vpn://...`.
866867

867-
**Использование в Amnezia Client:**
868+
> Perl с модулями `Compress::Zlib` и `MIME::Base64` должен быть на сервере. На Ubuntu и Debian они установлены по умолчанию. Если Perl отсутствует, `.vpnuri` / `.vpnuri.png` не создаются, но `.conf` работают штатно. `qrencode` (уже обязательный для `.conf` QR) нужен и для `.vpnuri.png`.
868869
869-
1. Скопируйте содержимое `.vpnuri` файла
870-
2. Откройте Amnezia Client
871-
3. «Добавить VPN» → «Вставить из буфера»
872-
4. Конфигурация импортируется автоматически
870+
**Способ 1 — QR-код (рекомендую для мобильных):**
873871

874-
**Права доступа:** Файлы `.vpnuri` имеют права 600 (только root).
872+
1. Скопируйте `/root/awg/<имя>.vpnuri.png` на компьютер (`scp`) или откройте локально.
873+
2. В Amnezia VPN на телефоне: «Добавить VPN» → «Считать QR-код».
874+
3. Наведите камеру на `.vpnuri.png` — импорт произойдёт автоматически.
875+
876+
**Способ 2 — копипаст URI:**
877+
878+
1. Скопируйте содержимое `.vpnuri` файла.
879+
2. Откройте Amnezia VPN → «Добавить VPN» → «Вставить из буфера».
880+
3. Конфигурация импортируется автоматически.
881+
882+
> Рядом лежит `<имя>.png` — QR из `.conf` для классических WireGuard-совместимых клиентов (AmneziaWG Windows, wireguard-apple, `wg-quick`). Это разные форматы с разными получателями: Amnezia VPN app сканирует `.vpnuri.png`, WireGuard-совместимые — `<имя>.png`. Не путайте.
883+
884+
> Для существующих клиентов, созданных до v5.11.2, `.vpnuri.png` появится после одного `manage regen <имя>`. Новые клиенты получают оба QR-кода сразу.
885+
886+
**Права доступа:** `.vpnuri` и `.vpnuri.png` имеют права 600 (только root).
875887

876888
---
877889

‎CHANGELOG.en.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,36 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
1414

1515
---
1616

17+
## [5.11.2] — 2026-04-24
18+
19+
UX patch on top of v5.11.1. A second per-client QR code — rendered from the `vpn://` URI — for one-tap import into the flagship Amnezia VPN app (Android / iOS / Desktop). The existing `<name>.png` (scan of `.conf`) is unchanged and keeps working with WireGuard-compatible clients (AmneziaWG Windows, `wireguard-apple`, `wg-quick`).
20+
21+
### Added
22+
23+
- **New `generate_qr_vpnuri` helper** in `awg_common.sh` / `awg_common_en.sh`. It reads `/root/awg/<name>.vpnuri` (the URI that `generate_vpn_uri` has been producing for a while now — full Amnezia envelope: zlib-JSON with `containers/defaultContainer/hostName/dns/mtu/protocol_version=2` plus all AWG 2.0 params), pipes it into `qrencode -t png`, writes `/root/awg/<name>.vpnuri.png` with mode 600. Writes are atomic: first into `<name>.vpnuri.png.tmp.$$` in the same directory, `chmod 600`, then `mv -f` to the target path — if `qrencode` or `chmod` fails, the old file stays intact and the orphan `.tmp.*` is cleaned up.
24+
- **Hooked into `generate_client` and `regenerate_client`.** After a successful `generate_vpn_uri`, `generate_qr_vpnuri` runs. If the URI itself cannot be built (missing perl modules, params not loaded), the vpn:// QR is silently skipped. The wg-quick QR and vpn:// QR are independent best-effort artifacts — a failure in one does not prevent the other.
25+
- **Hooked into `manage regen` and `manage remove`.** `regen` now refreshes both QR codes (conf and vpn://) together. `remove` cleans up `<name>.vpnuri.png` alongside `<name>.conf` / `.png` / `.vpnuri` and keys.
26+
- **Backup / restore picks up `.vpnuri.png` automatically** — no new code paths needed: the existing `*.png` glob in `_backup_configs_nolock` and `chmod 600 *.png` in `restore_backup` already cover the new artifact.
27+
28+
### Why
29+
30+
The flagship Amnezia VPN app (Android / iOS / Desktop) supports one-tap import by scanning a QR that encodes `vpn://{base64url(zlib(json))}`. I have been generating that URI for a while, but only as a plain text `.vpnuri` file that users had to copy over manually. Now you can point the phone camera at the second QR code instead of copying a file. The first QR (from `.conf`) remains the right one for classic WireGuard clients.
31+
32+
### Tests
33+
34+
- **+10 new bats** (261 total, up from 251 on v5.11.1):
35+
- `test_qr_vpnuri.bats` (+10) — happy path (stdin → PNG), missing `.vpnuri` → error, `qrencode` non-zero exit → error, **atomic write** (pre-existing `.vpnuri.png` is preserved on failure, no orphan `.tmp.*` left behind), `chmod 600` on Linux/Darwin, RU/EN structural parity of the helper (qrencode call + `.vpnuri.png` target + `command -v` guard), hooks in `generate_client` / `regenerate_client` / manage regen / cleanup in manage remove.
36+
37+
### Breaking changes
38+
39+
None. Existing client `.conf` / `.png` / `.vpnuri` files keep working. The new `.vpnuri.png` is only generated for clients created or regenerated on v5.11.2 — for older clients, a single `manage regen <name>` is enough. Downgrading to v5.11.1 is safe (stale `.vpnuri.png` files just sit in `/root/awg/` and are ignored).
40+
41+
### Dependencies
42+
43+
No new ones: `qrencode` was already in the installer step-2 required list (used by `generate_qr` for `.conf`), and `perl` + `Compress::Zlib` + `MIME::Base64` — already for `generate_vpn_uri`.
44+
45+
---
46+
1747
## [5.11.1] — 2026-04-23
1848

1949
UX patch. Three small improvements for `manage` on manual (non-installer) setups — e.g. `amneziawg-go` userspace in LXC. Credit to [@Akh-commits](https://github.com/Akh-commits) for the detailed live-test in [Issue #51](https://github.com/bivlked/amneziawg-installer/issues/51) on 2026-04-22, which is where all three fixes came from.

‎CHANGELOG.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,36 @@
1414

1515
---
1616

17+
## [5.11.2] — 2026-04-24
18+
19+
UX-патч к v5.11.1. Второй QR-код на клиента — из `vpn://` URI — для one-tap импорта в flagship Amnezia VPN app (Android / iOS / Desktop). Существующий `<имя>.png` (скан из `.conf`) остаётся как есть и работает с WireGuard-совместимыми клиентами (AmneziaWG Windows, `wireguard-apple`, `wg-quick`).
20+
21+
### Добавлено
22+
23+
- **Новая функция `generate_qr_vpnuri`** в `awg_common.sh` / `awg_common_en.sh`. Читает `/root/awg/<имя>.vpnuri` (тот самый URI, что уже давно генерировался через `generate_vpn_uri` и содержит полный Amnezia-envelope — zlib-JSON `containers/defaultContainer/hostName/dns/mtu/protocol_version=2` плюс все параметры AWG 2.0), скармливает его `qrencode -t png`, записывает `/root/awg/<имя>.vpnuri.png` с правами 600. Запись atomic: сначала в `<имя>.vpnuri.png.tmp.$$` в той же директории, `chmod 600`, затем `mv -f` на целевой путь — при сбое `qrencode` или `chmod` старая версия файла остаётся нетронутой, orphan `.tmp.*` очищается.
24+
- **Интеграция в `generate_client` и `regenerate_client`.** После успешного `generate_vpn_uri` вызывается `generate_qr_vpnuri`. Если URI не получилось построить (нет perl-модулей / не загружены параметры), QR `vpn://` пропускается без шума. QR из `.conf` и PNG `vpn://` — независимые best-effort артефакты; отказ одного не ломает другой.
25+
- **Интеграция в `manage regen` и `manage remove`.** `regen` обновляет оба QR (conf и vpn://) в паре. `remove` чистит `<имя>.vpnuri.png` наряду с `<имя>.conf` / `.png` / `.vpnuri` и ключами.
26+
- **Backup / restore автоматически подхватывает `.vpnuri.png`** — новых путей в код не добавлял, существующий `*.png` glob в `_backup_configs_nolock` и `chmod 600 *.png` в `restore_backup` покрывают новый артефакт без изменений.
27+
28+
### Зачем это
29+
30+
У flagship-приложения Amnezia VPN (Android / iOS / Desktop) один-тап импорт по QR-коду с форматом `vpn://{base64url(zlib(json))}` — у меня URI давно формировался, но сохранялся только в текстовый `.vpnuri`, который надо было руками скопировать на устройство. Теперь вместо копирования файла достаточно показать второй QR-код и навести камеру телефона. Для классических WireGuard-клиентов первый QR (из `.conf`) остаётся рабочим.
31+
32+
### Тесты
33+
34+
- **+10 новых bats** (261 total, было 251 на v5.11.1):
35+
- `test_qr_vpnuri.bats` (+10) — happy path (stdin → PNG), отсутствие `.vpnuri` → ошибка, non-zero exit у `qrencode` → ошибка, **atomic-write** (pre-existing `.vpnuri.png` не перезаписывается при сбое, orphan `.tmp.*` не остаётся), `chmod 600` на Linux/Darwin, RU/EN структурная parity функции (qrencode + `.vpnuri.png` + `command -v` guard), hooks в `generate_client` / `regenerate_client` / manage regen / cleanup в manage remove.
36+
37+
### Breaking changes
38+
39+
Нет. Существующие клиентские `.conf` / `.png` / `.vpnuri` остаются рабочими. Новый `.vpnuri.png` генерируется только для клиентов, созданных или пересозданных на v5.11.2 — для старых клиентов достаточно один раз запустить `manage regen <имя>`. Откат на v5.11.1 безопасен (лишние `.vpnuri.png` просто лежат в `/root/awg/` и игнорируются).
40+
41+
### Зависимости
42+
43+
Новых нет: `qrencode` уже был в required-списке шага 2 installer'а (использовался `generate_qr` для `.conf`), `perl` + `Compress::Zlib` + `MIME::Base64` — уже для `generate_vpn_uri`.
44+
45+
---
46+
1747
## [5.11.1] — 2026-04-23
1848

1949
UX-патч. Три небольших улучшения для `manage` на ручных (не-installer) установках — например, `amneziawg-go` userspace в LXC. Credit [@Akh-commits](https://github.com/Akh-commits) за детальный live-тест в [Issue #51](https://github.com/bivlked/amneziawg-installer/issues/51) 22 апр 2026, из которого вышли все три фикса.

0 commit comments

Comments
 (0)