# 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
```

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` на целевой ветке (это **перекатит** конфиг сервера).