Sergey Antropoff
8a7a4c0889
- ACME TLS challenge on 443 (no port 80 or nginx decoy) - Auto-generate and persist obfs password per server - Update client export, HTML catalog, and vault examples - Document Salamander vs main and ACME auto-renewal in README Co-authored-by: Cursor <cursoragent@cursor.com>
289 lines
9.5 KiB
Markdown
289 lines
9.5 KiB
Markdown
# Hysteria2 Ansible — ветка **Salamander**
|
||
|
||
> **Ветка:** `salamander`
|
||
> **Режим:** обфускация **Salamander** (без masquerade-сайта nginx)
|
||
> **Основная ветка `main`:** masquerade под HTTPS-сайт — см. другую ветку
|
||
|
||
Ansible-роль для установки [Hysteria 2](https://v2.hysteria.network/) на Debian/Ubuntu VPS с **Salamander obfs** — запутывание пакетов для обхода DPI, когда masquerade под «обычный сайт» недостаточен.
|
||
|
||
---
|
||
|
||
## Чем Salamander отличается от `main`
|
||
|
||
| | **`main` (masquerade)** | **`salamander` (эта ветка)** |
|
||
|---|---|---|
|
||
| Маскировка | HTTPS-сайт nginx + Let's Encrypt | **Salamander obfs** — пакеты выглядят как шум |
|
||
| Порт 80/tcp | Нужен (ACME HTTP + masquerade) | **Не нужен** |
|
||
| ACME | `type: http` | `type: tls` (TLS-ALPN на 443) |
|
||
| Сайт-заглушка | `/var/www/masq` | **Нет** |
|
||
| Obfs-пароль | — | **Обязателен** (один на сервер) |
|
||
| URI клиента | `hysteria2://user:pass@domain:443` | + `obfs=salamander&obfs-password=...` |
|
||
| Лучше когда | Нужен «легитимный» сайт в браузере | Агрессивный DPI, блокировка QUIC fingerprint |
|
||
|
||
---
|
||
|
||
## Быстрый старт
|
||
|
||
```bash
|
||
git clone https://git.antropoff.ru/DevOpsTools/hysteria2.git
|
||
cd hysteria2
|
||
git checkout salamander
|
||
|
||
make init
|
||
# отредактировать inventory/hosts.yml, group_vars/all.yml, vault
|
||
|
||
make vault-encrypt
|
||
make ping
|
||
make install # → output/index.html откроется в браузере
|
||
```
|
||
|
||
---
|
||
|
||
## Makefile
|
||
|
||
| Команда | Описание |
|
||
|---|---|
|
||
| `make init` | Создать конфиги из `.example` |
|
||
| `make ping` | Проверить SSH к VPS |
|
||
| `make install` | Установка Salamander + экспорт URL/QR/HTML |
|
||
| `make update` | Обновить бинарник, конфиг, перевыпустить экспорт |
|
||
| `make export` | Только экспорт (URL, QR, HTML) |
|
||
| `make uninstall` | Удалить Hysteria2 с VPS |
|
||
| `make vault-encrypt` | Зашифровать vault |
|
||
|
||
```bash
|
||
make install LIMIT=vps-de
|
||
make update EXTRA_VARS='hysteria2_wait_for_acme=false'
|
||
make install EXTRA_VARS='hysteria2_open_browser=false'
|
||
```
|
||
|
||
---
|
||
|
||
## Inventory
|
||
|
||
```yaml
|
||
all:
|
||
children:
|
||
hysteria2_servers:
|
||
hosts:
|
||
vps-de:
|
||
ansible_host: 203.0.113.10
|
||
ansible_port: 2222 # SSH-порт (если не 22)
|
||
ansible_user: root
|
||
ansible_password: "{{ vault_ssh_passwords['vps-de'] }}"
|
||
hysteria2_domain: vpn-de.example.com # для TLS/SNI и ACME
|
||
hysteria2_users:
|
||
- my
|
||
- friend
|
||
```
|
||
|
||
### SSH (VPS)
|
||
|
||
```yaml
|
||
# group_vars/hysteria2_servers/vault.yml
|
||
vault_ssh_passwords:
|
||
vps-de: "root-password"
|
||
```
|
||
|
||
Пароли VPN и Salamander obfs тоже можно хранить в vault — см. ниже.
|
||
|
||
---
|
||
|
||
## Как работает Salamander в этом проекте
|
||
|
||
### Сервер (`/etc/hysteria/config.yaml`)
|
||
|
||
```yaml
|
||
listen: 0.0.0.0:443
|
||
|
||
acme:
|
||
type: tls # сертификат без порта 80
|
||
domains:
|
||
- vpn-de.example.com
|
||
email: admin@example.com
|
||
|
||
auth:
|
||
type: userpass
|
||
userpass:
|
||
my: "..."
|
||
friend: "..."
|
||
|
||
obfs:
|
||
type: salamander
|
||
salamander:
|
||
password: "общий_obfs_пароль_сервера"
|
||
```
|
||
|
||
### Клиент (генерируется автоматически)
|
||
|
||
```yaml
|
||
server: vpn-de.example.com:443
|
||
auth: my:password
|
||
obfs:
|
||
type: salamander
|
||
salamander:
|
||
password: общий_obfs_пароль_сервера
|
||
```
|
||
|
||
### URI (пример)
|
||
|
||
```
|
||
hysteria2://my:password@vpn-de.example.com:443?obfs=salamander&obfs-password=OBFS_PASS#my
|
||
```
|
||
|
||
Роль вызывает `hysteria share` — URI и QR уже содержат параметры Salamander.
|
||
|
||
---
|
||
|
||
## Пароли
|
||
|
||
### VPN-пользователи (`userpass`)
|
||
|
||
1. **Vault:** `vault_hysteria2_user_passwords`
|
||
2. **Inventory:** `hysteria2_user_passwords`
|
||
3. **Авто:** `pwgen -s 40`
|
||
|
||
### Salamander obfs (один на сервер)
|
||
|
||
1. **Vault (рекомендуется):**
|
||
|
||
```yaml
|
||
vault_hysteria2_obfs_passwords:
|
||
vps-de: "cry_me_a_r1ver_salamander_obfs"
|
||
```
|
||
|
||
Подключается через `group_vars/hysteria2_servers/vars.yml`:
|
||
|
||
```yaml
|
||
hysteria2_obfs_password: "{{ (vault_hysteria2_obfs_passwords | default({}))[inventory_hostname] | default('') }}"
|
||
```
|
||
|
||
2. **Авто:** `pwgen -s 32` при первой установке
|
||
3. **При update:** загружается из `output/<server>/server-info.yml`
|
||
|
||
> **Важно:** obfs-пароль на сервере и клиенте должен **совпадать**. При `make update` без vault пароль сохраняется из предыдущего экспорта.
|
||
|
||
---
|
||
|
||
## Let's Encrypt — обновление сертификата
|
||
|
||
**Да, Hysteria2 обновляет сертификат автоматически.**
|
||
|
||
При `acme:` в конфиге встроенный ACME-клиент Hysteria2 сам получает и **продлевает** сертификат Let's Encrypt (срок ~90 дней). Перезапуск ansible для продления **не нужен** — процесс `hysteria-server` делает это сам (подтверждено maintainer проекта).
|
||
|
||
**Условия для авто-продления:**
|
||
|
||
- Сервер **запущен** и доступен из интернета
|
||
- Домен по-прежнему указывает на IP VPS
|
||
- Порт **443** открыт (для `acme type: tls` — TLS-ALPN challenge)
|
||
- Конфиг `acme` не удалён
|
||
|
||
Проверка логов: `journalctl -u hysteria-server -f`
|
||
|
||
---
|
||
|
||
## Firewall
|
||
|
||
Открываются только порты Hysteria2 (по умолчанию **443/tcp** и **443/udp**).
|
||
|
||
**Порт 80 не используется** — в отличие от ветки `main`.
|
||
|
||
---
|
||
|
||
## Результат: папка `output/`
|
||
|
||
```
|
||
output/
|
||
├── index.html ← все серверы (открывается в браузере)
|
||
├── vps-de/
|
||
│ ├── index.html ← страница сервера + obfs-пароль
|
||
│ ├── my.url ← URI с obfs=salamander
|
||
│ ├── my.png ← QR
|
||
│ ├── my.txt
|
||
│ └── server-info.yml ← mode, obfs_password, users
|
||
└── vps-nl/
|
||
└── ...
|
||
```
|
||
|
||
HTML-страницы показывают:
|
||
|
||
- режим **Salamander**
|
||
- **obfs-password** с кнопкой копирования
|
||
- пароль и URL каждого пользователя
|
||
- QR-коды
|
||
|
||
---
|
||
|
||
## Переменные
|
||
|
||
| Переменная | Где | Описание |
|
||
|---|---|---|
|
||
| `hysteria2_mode` | defaults | `salamander` (информативно) |
|
||
| `hysteria2_domain` | host | Домен для TLS/SNI/ACME |
|
||
| `hysteria2_users` | host | VPN-пользователи |
|
||
| `hysteria2_acme_email` | group | Email Let's Encrypt |
|
||
| `hysteria2_obfs_password` | host/vault | Пароль Salamander (или авто) |
|
||
| `hysteria2_obfs_password_length` | group | Длина автопароля obfs (32) |
|
||
| `hysteria2_listen_port` | group | Порт (443) |
|
||
| `hysteria2_open_browser` | group | Открыть `output/index.html` |
|
||
| `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-поток всё ещё можно анализировать
|
||
|
||
---
|
||
|
||
## Требования
|
||
|
||
- Ansible 2.14+
|
||
- Debian/Ubuntu VPS
|
||
- Домен с A-записью на IP (для ACME TLS)
|
||
- Клиент Hysteria2 с поддержкой Salamander (Shadowrocket, NekoBox, Hiddify и др.)
|
||
|
||
---
|
||
|
||
## Структура роли
|
||
|
||
```
|
||
roles/hysteria2/
|
||
├── tasks/
|
||
│ ├── obfs.yml ← генерация/загрузка obfs-пароля
|
||
│ ├── configure.yml ← без masquerade, только Salamander
|
||
│ └── export_global.yml ← общий output/index.html
|
||
└── templates/
|
||
├── config.yaml.j2 ← acme tls + obfs salamander
|
||
└── client.yaml.j2 ← клиент с obfs
|
||
```
|
||
|
||
---
|
||
|
||
## Переключение между ветками
|
||
|
||
```bash
|
||
git checkout main # masquerade + nginx
|
||
git checkout salamander # Salamander obfs
|
||
```
|
||
|
||
Конфиги на **уже установленном** сервере **не меняются** при переключении ветки в git — нужен `make install` или `make update` на целевой ветке (это **перекатит** конфиг сервера).
|