# HY2XS production runbook

## 1. Supported target

- clean Debian 13 amd64
- single host install profile
- IPv4-only runtime model

## 2. Required prerequisites

```bash
apt-get update
apt-get install -y sudo ca-certificates curl iproute2 tar openssl nftables systemd
```

`sudo` обязателен для permission smoke-checks от имени runtime-пользователей.

`sudo` должен быть установлен до запуска `./install.sh`: preflight проверяет его до шага установки зависимостей.

## 3. Required open ports

- UDP `${HY2XS_HYSTERIA_PORT}`
- TCP `${HY2XS_UI_PORT}` (обычно localhost bind)
- TCP `${HY2XS_SSH_PORT}`
- TCP 80/443 для ACME (в зависимости от типа challenge)

## 4. Clean host assumptions

- нет legacy-конфликта по runtime-users (`hysteria`, `hy2xs-admin`)
- нет конфликтующего не-HY2XS nftables entrypoint
- install запускается от root

## 5. Install command

```bash
./install.sh --non-interactive
```

## 6. Post-install verification

```bash
systemctl status hysteria-server
systemctl status hy2xs-admin
ss -H -lun | grep ':443'
ss -H -ltn | grep ':8080'
nft list ruleset
cat /var/lib/hy2xs/install-state.json
```

## 7. Permission verification

```bash
ls -l /etc/hy2xs/hy2xs.env
ls -l /etc/hysteria/config.yaml

sudo -u hysteria test -r /etc/hysteria/config.yaml
sudo -u hy2xs-admin test -r /etc/hysteria/config.yaml
sudo -u hy2xs-admin test ! -w /etc/hysteria/config.yaml
sudo -u hy2xs-admin test ! -r /etc/hy2xs/hy2xs.env
```

## 8. Firewall recovery

Если `install`/`reconfigure` падают после firewall apply:

- rollback guard не должен отменяться до успешного smoke;
- для recovery использовать вывод оркестратора и перезапускать apply только после устранения root-cause.

## 9. Reconfigure flow

```bash
hy2xs-orchestrator reconfigure --package-dir /usr/local/lib/hy2xs/package --config /etc/hy2xs/hy2xs.env --dry-run
hy2xs-orchestrator reconfigure --package-dir /usr/local/lib/hy2xs/package --config /etc/hy2xs/hy2xs.env --apply
```

## 10. Admin bootstrap credentials

- `HY2XS_ADMIN_INITIAL_PASSWORD` и `HY2XS_ADMIN_CON_PASS` — install-only bootstrap поля.
- изменение значений в `/etc/hy2xs/hy2xs.env` после install не выполняет автоматическую ротацию существующих credentials.

## 11. IPv4/IPv6 policy

- HY2XS работает в IPv4-only режиме.
- если IPv6 включён на хосте/провайдере — это вне baseline и должно быть отдельно управляемо оператором.

## 12. Validation command

```bash
hy2xs-orchestrator doctor --package-dir /usr/local/lib/hy2xs/package --config /etc/hy2xs/hy2xs.env
```

Команда выполняет preflight + smoke как post-install/post-reboot validation.