161 lines
5.7 KiB
Markdown
161 lines
5.7 KiB
Markdown
# 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` не требуется: на clean-host install-flow ставит его на стадии deps до выполнения smoke-checks.
|
|
|
|
## 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
|
|
```
|
|
|
|
Важно: packaged baseline использует `HY2XS_SSH_PORT=2323` по умолчанию.
|
|
На target-хосте оператор обязан выставить свой рабочий SSH-порт в `/etc/hy2xs/hy2xs.env`
|
|
и применить изменения через `reconfigure --apply`.
|
|
|
|
## 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 и должно быть отдельно управляемо оператором.
|
|
- `HY2XS_DNS_AAAA_POLICY` управляет реакцией preflight на DNS AAAA:
|
|
- `strict` (default) — install/reconfigure прекращается при наличии AAAA;
|
|
- `warn` — выводится warning и выполнение продолжается;
|
|
- `off` — AAAA-проверка игнорируется.
|
|
|
|
## 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.
|
|
|
|
## 13. Admin UI access via SSH tunnel
|
|
|
|
Production policy: UI остаётся loopback-only (`HY2XS_UI_BIND_HOST=127.0.0.1`), внешний доступ к `8080/tcp` не открывается.
|
|
Операторский доступ выполняется через SSH local forwarding.
|
|
|
|
Windows tunnel command:
|
|
|
|
```bash
|
|
ssh -p 2323 \
|
|
-i C:\Users\kirap\.ssh\id_ed25519_uk1 \
|
|
-N \
|
|
-L 127.0.0.1:8080:127.0.0.1:8080 \
|
|
root@185.156.108.141
|
|
```
|
|
|
|
Open in browser: `http://127.0.0.1:8080/#/login`.
|
|
|
|
Если туннель падает с `administratively prohibited`, проверить effective sshd-конфиг:
|
|
|
|
```bash
|
|
sshd -T | grep -E '^(port|allowtcpforwarding|permitopen|gatewayports|passwordauthentication|permitrootlogin) '
|
|
```
|
|
|
|
Recommended sshd hardening fragment:
|
|
|
|
```sshconfig
|
|
Port 2323
|
|
PubkeyAuthentication yes
|
|
PasswordAuthentication no
|
|
KbdInteractiveAuthentication no
|
|
PermitRootLogin prohibit-password
|
|
|
|
AllowTcpForwarding local
|
|
PermitOpen 127.0.0.1:8080 localhost:8080
|
|
GatewayPorts no
|
|
|
|
X11Forwarding no
|
|
AllowAgentForwarding no
|
|
MaxAuthTries 3
|
|
LoginGraceTime 20
|
|
ClientAliveInterval 300
|
|
ClientAliveCountMax 2
|
|
```
|
|
|
|
## 14. Secret-safe config sharing
|
|
|
|
Для передачи конфигов в тикеты/чаты используйте встроенную redaction-команду:
|
|
|
|
```bash
|
|
hy2xs-orchestrator redact-config --config /etc/hy2xs/hy2xs.env --out /root/hy2xs.redacted.env
|
|
hy2xs-orchestrator redact-config --config /etc/hysteria/post-install.env --out /root/post-install.redacted.env
|
|
hy2xs-orchestrator redact-config --config /etc/hysteria/config.yaml --out /root/hysteria-config.redacted.yaml --format yaml
|
|
```
|
|
|
|
Инварианты:
|
|
- команда не выводит исходные секреты в stdout;
|
|
- требуется выбрать ровно один режим: `--in-place` или `--out <path>`;
|
|
- `--format auto` пытается определить формат по имени файла, при неоднозначности используйте `--format env|yaml`.
|
|
|