diff --git a/README.md b/README.md index 5446395..1ce4e5b 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,37 @@ # Hysteria2 Ansible — ветка **Salamander** > **Ветка:** `salamander` -> **Режим:** обфускация **Salamander** (без masquerade-сайта nginx) -> **Основная ветка `main`:** masquerade под HTTPS-сайт — см. другую ветку +> **Режим:** **Salamander obfs** — запутывание пакетов для обхода DPI +> **Основная ветка:** [`main`](https://git.antropoff.ru/DevOpsTools/hysteria2/src/branch/main) — masquerade под HTTPS-сайт nginx -Ansible-роль для установки [Hysteria 2](https://v2.hysteria.network/) на Debian/Ubuntu VPS с **Salamander obfs** — запутывание пакетов для обхода DPI, когда masquerade под «обычный сайт» недостаточен. +Ansible-роль для установки [Hysteria 2](https://v2.hysteria.network/) на Debian/Ubuntu VPS с **Salamander obfs** — когда masquerade под «обычный сайт» недостаточен. --- -## Чем Salamander отличается от `main` +## Выбор ветки: `main` или `salamander` -| | **`main` (masquerade)** | **`salamander` (эта ветка)** | +| | **`main`** | **`salamander` (эта ветка)** | |---|---|---| | Маскировка | HTTPS-сайт nginx + Let's Encrypt | **Salamander obfs** — пакеты выглядят как шум | -| Порт 80/tcp | Нужен (ACME HTTP + masquerade) | **Не нужен** | +| Порт 80/tcp | **Нужен** (ACME HTTP + masquerade) | **Не нужен** | | ACME | `type: http` | `type: tls` (TLS-ALPN на 443) | -| Сайт-заглушка | `/var/www/masq` | **Нет** | +| Сайт-заглушка | `/var/www/masq` (nginx welcome) | **Нет** | | Obfs-пароль | — | **Обязателен** (один на сервер) | | URI клиента | `hysteria2://user:pass@domain:443` | + `obfs=salamander&obfs-password=...` | | Лучше когда | Нужен «легитимный» сайт в браузере | Агрессивный DPI, блокировка QUIC fingerprint | +### Когда выбирать `salamander` + +- masquerade из `main` **блокируют** или распознают по fingerprint; +- не нужен фейковый сайт в браузере; +- готовы хранить **дополнительный** obfs-пароль. + +### Когда выбирать `main` + +- нужен **нормальный HTTPS-сайт** при открытии домена; +- достаточно маскировки под nginx; +- хотите **минимум параметров** в URI клиента. + --- ## Быстрый старт @@ -43,18 +55,24 @@ make install # → output/index.html откроется в браузере | Команда | Описание | |---|---| +| `make help` | Справка | | `make init` | Создать конфиги из `.example` | | `make ping` | Проверить SSH к VPS | +| `make status` | `systemctl status hysteria-server` | | `make install` | Установка Salamander + экспорт URL/QR/HTML | | `make update` | Обновить бинарник, конфиг, перевыпустить экспорт | | `make export` | Только экспорт (URL, QR, HTML) | | `make uninstall` | Удалить Hysteria2 с VPS | | `make vault-encrypt` | Зашифровать vault | +| `make vault-edit` | Редактировать vault | ```bash make install LIMIT=vps-de -make update EXTRA_VARS='hysteria2_wait_for_acme=false' +make update LIMIT=vps-nl +make export +make uninstall LIMIT=vps-de EXTRA_VARS='hysteria2_uninstall_remove_local_output=true' make install EXTRA_VARS='hysteria2_open_browser=false' +make update EXTRA_VARS='hysteria2_wait_for_acme=false' ``` --- @@ -75,17 +93,35 @@ all: hysteria2_users: - my - friend + + vps-nl: + ansible_host: 203.0.113.20 + ansible_user: root + ansible_password: "{{ vault_ssh_passwords['vps-nl'] }}" + hysteria2_domain: vpn-nl.dynu.net + hysteria2_users: + - alice + - bob ``` ### SSH (VPS) +| Параметр | Где | Описание | +|---|---|---| +| `ansible_host` | inventory | IP VPS | +| `ansible_port` | inventory | SSH-порт (по умолчанию `22`) | +| `ansible_user` | inventory | Пользователь SSH (обычно `root`) | +| `ansible_password` | inventory + vault | Пароль из `vault_ssh_passwords` | +| `ansible_ssh_private_key_file` | inventory | Альтернатива — SSH-ключ | + ```yaml # group_vars/hysteria2_servers/vault.yml vault_ssh_passwords: - vps-de: "root-password" + vps-de: "root-password-1" + vps-nl: "root-password-2" ``` -Пароли VPN и Salamander obfs тоже можно хранить в vault — см. ниже. +Ключи в `vault_ssh_passwords` совпадают с **именами хостов** в inventory. --- @@ -139,9 +175,29 @@ hysteria2://my:password@vpn-de.example.com:443?obfs=salamander&obfs-password=OBF ### VPN-пользователи (`userpass`) -1. **Vault:** `vault_hysteria2_user_passwords` -2. **Inventory:** `hysteria2_user_passwords` -3. **Авто:** `pwgen -s 40` +1. **Vault (рекомендуется):** + +```yaml +vault_hysteria2_user_passwords: + vps-de: + friend: "Aingae0Okit1eek4eeZahFohVei4akee" +``` + +Подключается через `group_vars/hysteria2_servers/vars.yml`: + +```yaml +``` + +2. **Per-host в inventory:** + +```yaml +hysteria2_user_passwords: + friend: "custom-password" +``` + +3. **Автогенерация** — `pwgen -s 40`, если пароль не задан. + +При `make update` пароли подтягиваются из `output//server-info.yml`, если не указаны в vault/inventory. ### Salamander obfs (один на сервер) @@ -157,7 +213,7 @@ vault_hysteria2_obfs_passwords: ```yaml ``` -2. **Авто:** `pwgen -s 32` при первой установке +2. **Авто:** `pwgen -s 32` при первой установке 3. **При update:** загружается из `output//server-info.yml` > **Важно:** obfs-пароль на сервере и клиенте должен **совпадать**. При `make update` без vault пароль сохраняется из предыдущего экспорта. @@ -168,14 +224,14 @@ vault_hysteria2_obfs_passwords: **Да, Hysteria2 обновляет сертификат автоматически.** -При `acme:` в конфиге встроенный ACME-клиент Hysteria2 сам получает и **продлевает** сертификат Let's Encrypt (срок ~90 дней). Перезапуск ansible для продления **не нужен** — процесс `hysteria-server` делает это сам (подтверждено maintainer проекта). +При блоке `acme:` в конфиге встроенный ACME-клиент Hysteria2 сам получает и **продлевает** сертификат Let's Encrypt (срок ~90 дней). Повторный `make install` или certbot для продления **не нужны** — процесс `hysteria-server` делает это сам. -**Условия для авто-продления:** +**Условия для авто-продления (ветка `salamander`):** -- Сервер **запущен** и доступен из интернета -- Домен по-прежнему указывает на IP VPS -- Порт **443** открыт (для `acme type: tls` — TLS-ALPN challenge) -- Конфиг `acme` не удалён +- сервер **запущен** и доступен из интернета; +- домен указывает на IP VPS; +- порт **443/tcp** открыт (ACME TLS-ALPN challenge); +- конфиг `acme` не удалён. Проверка логов: `journalctl -u hysteria-server -f` @@ -183,7 +239,10 @@ vault_hysteria2_obfs_passwords: ## Firewall -Открываются только порты Hysteria2 (по умолчанию **443/tcp** и **443/udp**). +По умолчанию открываются только порты Hysteria2: + +- **443/tcp** +- **443/udp** **Порт 80 не используется** — в отличие от ветки `main`. @@ -197,7 +256,8 @@ output/ ├── vps-de/ │ ├── index.html ← страница сервера + obfs-пароль │ ├── my.url ← URI с obfs=salamander -│ ├── my.png ← QR +│ ├── my.png ← QR PNG +│ ├── my.qr.txt ← QR ASCII │ ├── my.txt │ └── server-info.yml ← mode, obfs_password, users └── vps-nl/ @@ -206,10 +266,26 @@ output/ HTML-страницы показывают: -- режим **Salamander** -- **obfs-password** с кнопкой копирования -- пароль и URL каждого пользователя -- QR-коды +- режим **Salamander** и **obfs-password** с кнопкой копирования; +- пароль и URL каждого пользователя; +- QR-коды; +- ссылки на файлы и страницы серверов. + +После `make install`, `make update` и `make export` **`output/index.html` автоматически открывается в браузере** (macOS: `open`, Linux: `xdg-open`). + +Отключить: `hysteria2_open_browser: false` в `group_vars/all.yml` или `EXTRA_VARS`. + +--- + +## QR-коды + +PNG генерируются средствами Ansible (без Python): + +1. `apt install qrencode` на VPS (остаётся установленным) +2. `qrencode -o user.png "hysteria2://..."` +3. `fetch` — скачивание PNG на control node + +ASCII QR — `hysteria share --qr` → `user.qr.txt`. --- @@ -221,44 +297,34 @@ HTML-страницы показывают: | `hysteria2_domain` | host | Домен для TLS/SNI/ACME | | `hysteria2_users` | host | VPN-пользователи | | `hysteria2_acme_email` | group | Email Let's Encrypt | +| `hysteria2_user_passwords` | host/vault | Свои пароли VPN | | `hysteria2_obfs_password` | host/vault | Пароль Salamander (или авто) | | `hysteria2_obfs_password_length` | group | Длина автопароля obfs (32) | +| `hysteria2_output_dir` | group | Папка экспорта (по умолчанию `./output`) | | `hysteria2_listen_port` | group | Порт (443) | -| `hysteria2_open_browser` | group | Открыть `output/index.html` | +| `hysteria2_generate_qr_png` | group | PNG QR через `qrencode` | +| `hysteria2_open_browser` | group | Открыть `output/index.html` после экспорта | +| `hysteria2_uninstall_remove_local_output` | extra-vars | Удалить `output//` при uninstall | | `vault_hysteria2_obfs_passwords` | vault | obfs-пароли по серверам | --- -## Когда выбирать эту ветку - -**Используйте `salamander`, если:** - -- masquerade из `main` блокируют или «палят» по fingerprint -- не нужен фейковый сайт в браузере -- готовы хранить **дополнительный** obfs-пароль - -**Используйте `main`, если:** - -- нужен «нормальный» HTTPS-сайт при проверке домена -- достаточно маскировки под nginx -- хотите минимум параметров в URI - ---- - ## Безопасность -- `output/` содержит пароли, obfs-ключи и URL — **не коммитить** -- `make vault-encrypt` обязателен после `make init` -- Salamander **не делает** вас невидимым: IP VPS и постоянный UDP-поток всё ещё можно анализировать +- `output/` содержит пароли, obfs-ключи и URL — **не коммитить** (в `.gitignore`) +- `inventory/hosts.yml`, `vault.yml`, `.vault_pass` — не коммитить +- После `make init` выполните `make vault-encrypt` +- Salamander **не делает** вас невидимым: IP VPS и UDP-поток всё ещё можно анализировать --- ## Требования - Ansible 2.14+ -- Debian/Ubuntu VPS +- Debian/Ubuntu VPS с sudo - Домен с A-записью на IP (для ACME TLS) - Клиент Hysteria2 с поддержкой Salamander (Shadowrocket, NekoBox, Hiddify и др.) +- Для авто-открытия браузера: macOS или Linux с `xdg-open` --- @@ -268,11 +334,13 @@ HTML-страницы показывают: roles/hysteria2/ ├── tasks/ │ ├── obfs.yml ← генерация/загрузка obfs-пароля -│ ├── configure.yml ← без masquerade, только Salamander +│ ├── configure.yml ← Salamander, без masquerade +│ ├── export.yml ← URL, QR, HTML сервера │ └── export_global.yml ← общий output/index.html └── templates/ ├── config.yaml.j2 ← acme tls + obfs salamander - └── client.yaml.j2 ← клиент с obfs + ├── client.yaml.j2 ← клиент с obfs + └── export/ ← HTML-каталоги ``` --- @@ -280,8 +348,19 @@ roles/hysteria2/ ## Переключение между ветками ```bash +git fetch origin git checkout main # masquerade + nginx -git checkout salamander # Salamander obfs +git checkout salamander # Salamander obfs (эта ветка) ``` -Конфиги на **уже установленном** сервере **не меняются** при переключении ветки в git — нужен `make install` или `make update` на целевой ветке (это **перекатит** конфиг сервера). +Конфиги на **уже установленном** сервере **не меняются** при переключении ветки в git. +Чтобы применить другой режим на VPS: + +```bash +git checkout main # или salamander +make install # перекатит конфиг сервера +# или +make update +``` + +> Переключение режима **меняет** `/etc/hysteria/config.yaml` на сервере. Клиентские URI/QR нужно **перевыпустить** (`make export` или `make update`).