# singbox_glue / vpn-egressctl

`vpn-egressctl` — локальный декларативный control plane для Linux-шлюза
`vpn-egress-gw`. Он получает реквизиты подключения из защищённого Hysteria2 URI,
объединяет их с локальной инфраструктурной policy и полностью генерирует
конфигурацию sing-box.

## Контракт релиза 0.2.0

- строго `sing-box 1.14.0`, Linux build с `with_quic` и `with_gvisor`;
- HY2XS/Hysteria 2.12.2 использует Gecko как единственный production obfs;
- Gecko packet profile фиксирован: `512/1200`;
- Salamander принимается только как явно заданный compatibility fallback;
- TUN DNS сохраняет прежнюю архитектуру через `dns_mode=disabled` и явное
  route action `hijack-dns`;
- лицензия исходного кода — Mozilla Public License 2.0.

Salamander не является автоматическим fallback: клиент не может согласовать тип
obfs с сервером. Production URI HY2XS обязан содержать `obfs=gecko`.

## Что обеспечивает проект

- endpoint остаётся DNS hostname и не закрепляется как публичный `/32`;
- bootstrap DNS привязан к `eth0`, remote DoH идёт через `hy2-out`;
- неизвестные URI и policy-параметры отклоняются;
- candidate проходит настоящий `sing-box check` до установки;
- запись атомарна, после неуспешного restart/healthcheck выполняется
  same-release rollback;
- legacy `last-good` без версии и checksum не используется;
- nftables guard блокирует прямой forwarding `eth1 -> eth0`;
- systemd path unit применяет изменение URI без постоянного Python-процесса.

## Только чистая установка

Переход с 0.1.0 на 0.2.0 через `apt upgrade` или `dpkg -i` поверх старого пакета
не поддерживается и блокируется `preinst`. Старые policy, config, state и backups
не мигрируют и не активируются.

Правильная последовательность: остановить сервисы, оставить anti-leak guard,
удалить пакет 0.1.0, архивировать его данные, установить sing-box 1.14.0 и пакет
0.2.0, настроить новую policy и применить новый Gecko URI. Полный runbook:
[чистая установка](docs/migration.md).

## Основные команды

```bash
sudo vpn-egressctl import --stdin
sudo vpn-egressctl check
sudo vpn-egressctl diff
sudo vpn-egressctl sync
sudo vpn-egressctl status --json
sudo vpn-egressctl doctor
sudo vpn-egressctl rollback
```

URI нельзя передавать позиционным аргументом: secret не должен попадать в argv и
shell history.

## Документация

- [Архитектура](docs/architecture.md)
- [Конфигурация](docs/configuration.md)
- [Чистая установка 0.2.0](docs/migration.md)
- [Эксплуатация](docs/operations.md)
- [Безопасность](docs/security.md)
- [Контракт sing-box 1.14.0](docs/sing-box-1.14.md)
- [Тестирование](docs/testing.md)
- [Диагностика](docs/troubleshooting.md)

## Локальная проверка

На Linux:

```bash
make check
```

Указанный embedded Python для Windows работает в isolated mode, поэтому пути
добавляются явно:

```powershell
E:\python-31312\python.exe -c "import sys,unittest; sys.path[:0]=[r'F:\projects\singbox_glue',r'F:\projects\singbox_glue\src']; s=unittest.defaultTestLoader.discover('tests',top_level_dir='.'); r=unittest.TextTestRunner(verbosity=2).run(s); raise SystemExit(not r.wasSuccessful())"
```

## Лицензия

Версия 0.2.0 распространяется по [Mozilla Public License 2.0](LICENSE).