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: чистая установка.

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

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.

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

• Архитектура
• Конфигурация
• Чистая установка 0.2.0
• Эксплуатация
• Безопасность
• Контракт sing-box 1.14.0
• Тестирование
• Диагностика

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

На Linux:

make check

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

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.