Merge pull request #60 from bivlked/v5.11.2/development

v5.11.2: vpn:// QR for one-tap Amnezia VPN app import

Author: bivlked

ADVANCED.en.md

@@ -858,22 +858,34 @@ sudo bash /root/awg/manage_amneziawg.sh add guest --expires=7d
 <a id="vpnuri-adv"></a>
 ## 📱 vpn:// URI Import
 
-When a client is created, a `.vpnuri` file is automatically generated with a `vpn://` URI for quick import into Amnezia Client.
+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).
 
-**File location:** `/root/awg/<client_name>.vpnuri`
+**File locations:**
 
-**Format:** The configuration is compressed via zlib (Perl `Compress::Zlib`) and Base64-encoded, forming a URI like `vpn://...`.
+- `/root/awg/<client_name>.vpnuri` — plain-text `vpn://` URI
+- `/root/awg/<client_name>.vpnuri.png` — QR code of that URI (since v5.11.2)
 
-> 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.
+**Format:** the configuration is compressed via zlib (Perl `Compress::Zlib`) and Base64-encoded, forming a URI like `vpn://...`.
 
-**Using with Amnezia Client:**
+> 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`.
 
-1. Copy the contents of the `.vpnuri` file
-2. Open Amnezia Client
-3. "Add VPN" → "Paste from clipboard"
-4. The configuration is imported automatically
+**Option 1 — QR code (recommended for mobile):**
 
-**Permissions:** `.vpnuri` files have 600 permissions (root only).
+1. Copy `/root/awg/<name>.vpnuri.png` to your computer (`scp`) or open it locally.
+2. In the Amnezia VPN app on the phone: "Add VPN" → "Scan QR code".
+3. Point the camera at `.vpnuri.png` — the client imports automatically.
+
+**Option 2 — URI paste:**
+
+1. Copy the contents of the `.vpnuri` file.
+2. Open Amnezia VPN → "Add VPN" → "Paste from clipboard".
+3. The configuration is imported automatically.
+
+> 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.
+
+> 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.
+
+**Permissions:** `.vpnuri` and `.vpnuri.png` have 600 permissions (root only).
 
 ---
 

ADVANCED.md

@@ -856,22 +856,34 @@ sudo bash /root/awg/manage_amneziawg.sh add guest --expires=7d
 <a id="vpnuri-adv"></a>
 ## 📱 vpn:// URI импорт
 
-При создании клиента автоматически генерируется `.vpnuri` файл с `vpn://` URI для быстрого импорта в Amnezia Client.
+При создании клиента автоматически генерируется `.vpnuri` файл с `vpn://` URI и, начиная с v5.11.2, QR-код `<имя>.vpnuri.png` с тем же URI — для быстрого импорта в Amnezia VPN app (Android / iOS / Desktop).
 
-**Расположение файлов:** `/root/awg/<имя_клиента>.vpnuri`
+**Расположение файлов:**
 
-**Формат:** Конфигурация сжимается через zlib (Perl `Compress::Zlib`) и кодируется в Base64, формируя URI вида `vpn://...`.
+- `/root/awg/<имя_клиента>.vpnuri` — текстовый `vpn://` URI
+- `/root/awg/<имя_клиента>.vpnuri.png` — QR-код этого URI (с v5.11.2)
 
-> Perl с модулями `Compress::Zlib` и `MIME::Base64` должен быть на сервере. На Ubuntu и Debian они установлены по умолчанию. Если Perl отсутствует, `.vpnuri` файлы не создаются, но `.conf` файлы работают штатно.
+**Формат:** конфигурация сжимается через zlib (Perl `Compress::Zlib`) и кодируется в Base64, формируя URI вида `vpn://...`.
 
-**Использование в Amnezia Client:**
+> Perl с модулями `Compress::Zlib` и `MIME::Base64` должен быть на сервере. На Ubuntu и Debian они установлены по умолчанию. Если Perl отсутствует, `.vpnuri` / `.vpnuri.png` не создаются, но `.conf` работают штатно. `qrencode` (уже обязательный для `.conf` QR) нужен и для `.vpnuri.png`.
 
-1. Скопируйте содержимое `.vpnuri` файла
-2. Откройте Amnezia Client
-3. «Добавить VPN» → «Вставить из буфера»
-4. Конфигурация импортируется автоматически
+**Способ 1 — QR-код (рекомендую для мобильных):**
 
-**Права доступа:** Файлы `.vpnuri` имеют права 600 (только root).
+1. Скопируйте `/root/awg/<имя>.vpnuri.png` на компьютер (`scp`) или откройте локально.
+2. В Amnezia VPN на телефоне: «Добавить VPN» → «Считать QR-код».
+3. Наведите камеру на `.vpnuri.png` — импорт произойдёт автоматически.
+
+**Способ 2 — копипаст URI:**
+
+1. Скопируйте содержимое `.vpnuri` файла.
+2. Откройте Amnezia VPN → «Добавить VPN» → «Вставить из буфера».
+3. Конфигурация импортируется автоматически.
+
+> Рядом лежит `<имя>.png` — QR из `.conf` для классических WireGuard-совместимых клиентов (AmneziaWG Windows, wireguard-apple, `wg-quick`). Это разные форматы с разными получателями: Amnezia VPN app сканирует `.vpnuri.png`, WireGuard-совместимые — `<имя>.png`. Не путайте.
+
+> Для существующих клиентов, созданных до v5.11.2, `.vpnuri.png` появится после одного `manage regen <имя>`. Новые клиенты получают оба QR-кода сразу.
+
+**Права доступа:** `.vpnuri` и `.vpnuri.png` имеют права 600 (только root).
 
 ---
 

CHANGELOG.en.md

@@ -14,6 +14,36 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [5.11.2] — 2026-04-24
+
+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`).
+
+### Added
+
+- **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.
+- **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.
+- **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.
+- **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.
+
+### Why
+
+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.
+
+### Tests
+
+- **+10 new bats** (261 total, up from 251 on v5.11.1):
+  - `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.
+
+### Breaking changes
+
+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).
+
+### Dependencies
+
+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`.
+
+---
+
 ## [5.11.1] — 2026-04-23
 
 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

@@ -14,6 +14,36 @@
 
 ---
 
+## [5.11.2] — 2026-04-24
+
+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`).
+
+### Добавлено
+
+- **Новая функция `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.*` очищается.
+- **Интеграция в `generate_client` и `regenerate_client`.** После успешного `generate_vpn_uri` вызывается `generate_qr_vpnuri`. Если URI не получилось построить (нет perl-модулей / не загружены параметры), QR `vpn://` пропускается без шума. QR из `.conf` и PNG `vpn://` — независимые best-effort артефакты; отказ одного не ломает другой.
+- **Интеграция в `manage regen` и `manage remove`.** `regen` обновляет оба QR (conf и vpn://) в паре. `remove` чистит `<имя>.vpnuri.png` наряду с `<имя>.conf` / `.png` / `.vpnuri` и ключами.
+- **Backup / restore автоматически подхватывает `.vpnuri.png`** — новых путей в код не добавлял, существующий `*.png` glob в `_backup_configs_nolock` и `chmod 600 *.png` в `restore_backup` покрывают новый артефакт без изменений.
+
+### Зачем это
+
+У flagship-приложения Amnezia VPN (Android / iOS / Desktop) один-тап импорт по QR-коду с форматом `vpn://{base64url(zlib(json))}` — у меня URI давно формировался, но сохранялся только в текстовый `.vpnuri`, который надо было руками скопировать на устройство. Теперь вместо копирования файла достаточно показать второй QR-код и навести камеру телефона. Для классических WireGuard-клиентов первый QR (из `.conf`) остаётся рабочим.
+
+### Тесты
+
+- **+10 новых bats** (261 total, было 251 на v5.11.1):
+  - `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.
+
+### Breaking changes
+
+Нет. Существующие клиентские `.conf` / `.png` / `.vpnuri` остаются рабочими. Новый `.vpnuri.png` генерируется только для клиентов, созданных или пересозданных на v5.11.2 — для старых клиентов достаточно один раз запустить `manage regen <имя>`. Откат на v5.11.1 безопасен (лишние `.vpnuri.png` просто лежат в `/root/awg/` и игнорируются).
+
+### Зависимости
+
+Новых нет: `qrencode` уже был в required-списке шага 2 installer'а (использовался `generate_qr` для `.conf`), `perl` + `Compress::Zlib` + `MIME::Base64` — уже для `generate_vpn_uri`.
+
+---
+
 ## [5.11.1] — 2026-04-23
 
 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, из которого вышли все три фикса.