# Чистая установка версии 0.2.0

## Поддерживаемая модель

In-place upgrade 0.1.0 → 0.2.0, автоматическая миграция policy/state и запуск
старого config под новым ядром не поддерживаются. Новый package `preinst`
отклоняет upgrade. Установка выполняется через удаление старого пакета,
архивирование его данных и настройку 0.2.0 с нуля.

Повторная установка ровно 0.2.0 поверх согласованного состояния 0.2.0 не
является миграцией и поддерживается без этого runbook.

Описанные действия выполнять из console/maintenance-доступа. До успешного E2E
anti-leak guard должен оставаться в nftables.

## 1. Остановить автоматическое применение

```bash
systemctl disable --now vpn-egress-sync.path || true
systemctl stop sing-box.service
systemctl mask --runtime sing-box.service
nft list table inet vpn_egress_guard
```

Если guard отсутствует, сначала восстановить защиту. Не продолжать переход с
работающим прямым forwarding `eth1 -> eth0`.

## 2. Удалить старый package и архивировать данные

```bash
apt-get remove vpn-egressctl
install -d -m 0700 /root/vpn-egress-0.1-archive

test ! -e /etc/vpn-egress || \
  mv /etc/vpn-egress /root/vpn-egress-0.1-archive/etc-vpn-egress
test ! -e /var/lib/vpn-egress || \
  mv /var/lib/vpn-egress /root/vpn-egress-0.1-archive/var-lib-vpn-egress
test ! -e /etc/sing-box/config.json || \
  mv /etc/sing-box/config.json /root/vpn-egress-0.1-archive/config.json
```

Архив содержит secrets и должен оставаться `root:root 0700/0600`. Не копировать
старые `policy.json`, `state.json` или `last-good.json` обратно в 0.2.0.

## 3. Установить exact sing-box 1.14.0

```bash
apt-get update
apt-get install sing-box=1.14.0
sing-box version
```

Вывод должен содержать exact `1.14.0`, Linux environment, `with_quic` и
`with_gvisor`. Runtime mask не снимать: старый config уже архивирован, но новая
policy ещё не настроена.

## 4. Установить vpn-egressctl 0.2.0

```bash
dpkg -i vpn-egressctl_0.2.0_all.deb
systemctl daemon-reload
```

Если postinst сообщает о legacy state или unmanaged config, не обходить
проверку: архивировать указанный объект и повторить `dpkg --configure
vpn-egressctl`.

## 5. Настроить новую policy и URI

Редактировать новый `/etc/vpn-egress/policy.json` вручную. Из старой policy
можно перенести осознанно проверенные локальные значения, но нельзя заменять ею
новый файл целиком.

```bash
install -m 0600 -o root -g root /dev/null /etc/vpn-egress/hysteria2.uri
read -r -s URI
printf '%s\n' "$URI" > /etc/vpn-egress/hysteria2.uri
unset URI

vpn-egressctl check
vpn-egressctl diff
```

Для новой production-установки проверить, что URI содержит `obfs=gecko`.
`obfs=salamander` допускается только для явно настроенного server-side
compatibility fallback. `check` не запускает service.

## 6. Активировать защиту и config

```bash
systemctl enable --now vpn-egress-guard.service
nft list table inet vpn_egress_guard
systemctl unmask --runtime sing-box.service
vpn-egressctl sync
vpn-egressctl doctor
```

После первого успешного sync `last-good` ещё отсутствует — это ожидаемо.

## 7. Acceptance и watcher

С workload за `eth1` проверить DNS, TCP, UDP, внешний VPN IP и отсутствие
прямого WAN при остановленном sing-box. Серверный Gecko E2E выполняется отдельно
владельцем HY2XS.

```bash
systemctl enable --now vpn-egress-sync.path
vpn-egressctl status --json
vpn-egressctl doctor
```

Фактический production-прогон этой процедуры и E2E клиента за `eth1`
зафиксирован в [отчёте о финальной приёмке 0.2.0](acceptance-0.2.0.md).

## Возврат к 0.1.0

0.2.0 не выполняет downgrade. Возврат — отдельная ручная чистая установка:
удалить 0.2.0, архивировать её состояние, установить exact старые packages и
только после этого восстановить согласованный snapshot 0.1.0. Нельзя запускать
config одной версии под бинарником другой.