singbox_glue/docs/configuration.md

Конфигурация

Policy schema version 1

Production-образец находится в config/policy.json. Все секции имеют строгий набор ключей; неизвестные и отсутствующие значения являются ошибкой.

sing_box

• binary: абсолютный путь к бинарнику;
• config_path: генерируемый production JSON;
• service: имя systemd service;
• required_version: только 1.14.0.

runtime

• uri_path: защищённый desired-state URI;
• state_dir: state, last-good и backups;
• lock_path: межпроцессная блокировка;
• backup_keep: число same-release backups, от 1 до 100.

network

Policy фиксирует eth0, eth1, tun-sb0, 172.19.0.1/30, MTU 1400, таблицу 2022, rule index 9000, marks 0x2023/24/25, NFQUEUE 100 и fallback rule 32768. Публичные endpoint IP не добавляются в exclusions.

dns

• bootstrap 1.1.1.1:53, bind eth0;
• DoH 1.1.1.1:443/dns-query, SNI cloudflare-dns.com;
• DoH detour hy2-out;
• стратегия только ipv4_only.

bandwidth

up_mbps=50 и down_mbps=200 выбирают Hysteria congestion control. Поэтому renderer не задаёт bbr_profile: BBR profile применяется только когда bandwidth values не заданы.

Hysteria2 URI

Production-форма HY2XS:

hysteria2://<peer-secret>@<host>:<port>/?insecure=0&obfs=gecko&obfs-password=<secret>&sni=<domain>

Поддерживаются hysteria2:///hy2://, auth/userpass, DNS/IPv4/bracketed IPv6, IDNA, port hopping, sni, insecure=0|1, fragment, Gecko и Salamander.

Правила obfs:

нет obfs             -> допустимо для внешнего generic endpoint
obfs=gecko           -> требуется obfs-password; профиль всегда 512/1200
obfs=salamander      -> требуется obfs-password; compatibility fallback
другой obfs          -> ошибка
password без obfs    -> ошибка

Для новых HY2XS production-установок Gecko является режимом по умолчанию. Salamander полностью поддерживается как compatibility fallback, но требует явного совпадения режима и password на сервере и клиенте. Автоматического переключения между Gecko и Salamander нет.

Query parser применяет RFC percent-decoding, но не form decoding: сырой + сохраняется как +, %2B также превращается в +, а %26/%3D безопасно остаются частью значения после разбора разделителей.

pinSHA256, ech, Realm URI, client modes, неизвестные и повторяющиеся параметры отклоняются. Custom Gecko packet sizes через URI не принимаются: официальная Hysteria2 URI schema их не переносит.

Healthcheck

По умолчанию проверяется Cloudflare trace: HTTP 200 и маркер ip=. Это проверяет локальную post-activation связность шлюза, но не заменяет E2E с workload за eth1. url: null допустим только для изолированного стенда.