splify2
Ядро steer

Устройство steer#

Документ для тех, кто правит ядро steer: как устроен код и как он работает. Внешние обещания описаны отдельно: спека v1, вывод status и diag, командная строка и инварианты набора правил — docs/contract-v1.md; управляющий сокет демона — docs/ctl.md; формат спеки v2 — docs/spec-v2.md; клиент VLESS — docs/vless.md; протокол xsteer — docs/xsteer.md.

1. Сборки#

Одно дерево на C, несколько сборок. Какие файлы входят в сборку, решает профиль в build/sources.mk — единственном списке исходников: Makefile его включает, build.sh и build/build-ext.sh читают через build/sources.sh, а список в Android.bp с ним сверяет tests/buildmatch.sh.

Профиль Состав Что в сборке
base CORE_SRC ядро: модель спеки, компилятор, демон, резолвер, виды direct, interface, awg, block и группы; криптографии нет
extended ядро, XS_COMMON_SRC, EXT_ROUTER_SRC, PK_STATIC_SRC статическая полная сборка (телефон, стенды): ещё программы плагинов vless, xsteer, obfs и tgws (мост Telegram), стек туннеля, подписка, TLS на wolfSSL; на роутере те же файлы разложены по ядру и плагинам (ниже)
server ядро, XS_COMMON_SRC, EXT_SERVER_SRC хаб xsteer
android как extended та же сборка с умолчанием платформы «телефон» (-DSTEER_DEFAULT_PLATFORM=android)

Код обеих платформ, роутера и телефона, есть в каждой сборке: платформа выбирается при запуске (раздел 2, правило 2).

Пакет роутера — разделяемая раскладка, а не один статический файл. Профили выше остаются для статических сборок (телефон, стенды, хаб на VPS); роутер получает те же файлы, разложенные по бинарникам и библиотекам (списки — те же build/sources.mk, рецепт — build/build-libs.sh), — раскладка 2.1 ниже. Видов протоколов в ядре нет: виды tunnel:<протокол> и xsteer приходят манифестами плагинов (src/kinds/plugin.c). Без плагина выход такого вида при запуске демона и reload — unavail с причиной «нужен плагин X — поставить»: он живёт по своему on_fail, остальная спека применяется (план стартового применения и reload — apply-plan --start, не строгий), а при apply из интерфейса — отказ с той же причиной. Кто даёт вид, ядро узнаёт из provides.kinds индекса семени /usr/share/steer/seed, а для официальных плагинов вне семени — из таблицы src/kinds/offkinds.h, которую build/offkinds.sh порождает из манифестов plugins/*/plugin.json (сверяет tests/buildmatch.sh); вид, которого нет ни там, ни там, — «неизвестный kind». Команды протоколов без плагина — «нет такой команды». Модулей ядра нет: мост Telegram — тоже плагин (tgws, вид tgws, исходник — plugins/tgws, src/modules/main_tgws.c, src/proto/tgws; выпускает его репозиторий splify2-extended-plugins). В семени его нет, вид tgws ядро знает по таблице и без плагина ведёт себя так же, как tunnel:vless без плагина vless.

Экспорт libsteer.so — version-script build/libsteer.map (только то, что берёт steerd; порождён из кода build/libs-exports.sh, проверка — make libs-test), SONAME libsteer.so.<версия ядра steer>. Экспорт libsteer-wolfssl.so — build/wolfssl/libsteer-wolfssl.map, libsteer-ngtcp2.so — build/ngtcp2/libsteer-ngtcp2.map (оба порождает тот же build/libs-exports.sh). Ядро и libsteer собираются -fPIC и -ftls-model=initial-exec; net1 — без него (модель global-dynamic): её загружают и dlopen'ом, вслед за .so-плагином steerd, а места в статическом блоке TLS процесса для неё нет. Видимость задаёт version-script. Загрузчик musl задаётся на каждую архитектуру (interp_of в build/arches.sh).

Раскладка 2.1: ядро, net1 и протоколы-плагины#

С 2.1 протоколы — плагины, обновляются отдельно от ядра, а общий для них сетевой стек — один плагин-библиотека net1 (plugin-sdk: docs/steer-abi.md, «Сервисы протоколам»). Раскладка 2.1 — единственная у build/build-libs.sh.

Файл Список Что в нём
libsteer.so.<версия> PROFILE_libsteer модель, виды, разбор команд, линия событий, слой примитивов, TLS 1.3, REALITY, HTTP/2, ECH, корни, HTTP-клиент (httpc.c, wbhttps.c), подпись и распаковка плагинов, обёртка QUIC и DoQ. Стека TUN (src/tunnel), транспортов (src/proto/transport), разбора ссылок узлов (sublink.c) и обфускатора (obfs.c) нет
libsteer-wolfssl.so.<версия wolfSSL> build/wolfssl/build.sh wolfSSL с нашими опциями и отпечаток сборки steer_wolfssl_abi; одна на ядро, net1 и мост tgws
libsteer-ngtcp2.so.<версия>-<серия> build/ngtcp2/build.sh ngtcp2 с патчами Brutal и криптобэкендом wolfSSL (2.1.4); одна на резолвер ядра и net1
plugins/net1/lib/libs2p-net.so.1 PROFILE_net1 стек TUN, пул узлов, гео, транспорты, разбор ссылок, вторая копия TLS/REALITY/HTTP/2 и обёртки QUIC, основа стека (платформа, профиль, линия событий, run, JSON, err); wolfSSL и ngtcp2 — общие библиотеки ядра (DT_NEEDED, ось compat.steer-crypto, ниже)
plugins/<id>/bin/<id> PROFILE_plug_<id> vless, hysteria2, proxy, xsteer, warpbox — код протокола на src/plugkit (сторона плагина в API: {conf}, точка входа, файл состояния; модели спеки ядра нет) и DT_NEEDED libs2p-net.so.1 с RUNPATH $ORIGIN/../../net1/lib; obfs стека не берёт и с библиотеками steer не связан; tgws (мост Telegram, PLUGINS_TLS) — свой TLS 1.3/1.2 статически, wolfSSL — libsteer-wolfssl.so ядра (ось steer-crypto): net1 не отдаёт TLS-соединение, а стек туннелей мосту не нужен
steerd PROFILE_steerd демон, компилятор, резолвер, менеджер плагинов на libsteer
sing-box плагина box-connector EXT_TLS_SRC + исходники коннектора (build/ext-build.sh --static) sing-box для podkop и forkop (репозиторий steer-box-connector): статически со своей копией TLS 1.3, REALITY, HTTP/2, корней, разбора .srs и wolfSSL, без libsteer.so.<версия> — плагину нельзя быть привязанным к версии ядра

Что ядро держит само и почему. TLS/QUIC и wolfSSL у ядра свои: резолвер ходит по DoH, DoH3 и DoQ, замер групп — по HTTPS (urltls.c), менеджер плагинов качает индекс и архивы (httpc.c, wbhttps.c) и проверяет подпись (sigverify.c). Всё это должно работать без единого плагина и не падать, когда net1 обновляется в фоне. Исходник у TLS один, собирается он дважды: в ядро — со своими именами, в net1 — с приставкой.

Общие библиотеки криптографии (2.1.4). Сами wolfSSL и ngtcp2 с 2.1.4 — по одной копии на роутер: libsteer-wolfssl.so.<версия wolfSSL> и libsteer-ngtcp2.so.<версия ngtcp2>-<серия патчей> лежат в steer-core, а net1 и мост tgws связаны с ними (DT_NEEDED; до 2.1.4 у каждого была своя скрытая копия — 0,64 МБ wolfSSL и 0,3 МБ ngtcp2 в net1 на mipsel). Их имена — не версия ядра, а версия сборки библиотеки, и меняются они редко; какую сборку ждёт плагин, он объявляет осью compat.steer-crypto ("^1.0"), а ядро называет свою (steer version --json, поле crypto; CLI_STEER_CRYPTO в src/cli/cli.h). Мажор оси — смена SONAME любой из библиотек или раскладки структур слоя, минор — новое имя в экспорте; записанные значения — build/wolfssl/crypto.lst, сверяет tests/buildmatch.sh (изменилась сборка, а ось та же — отказ). Менеджер плагинов не ставит плагин, чья ось не сходится («net1 1.5.0 требует steer-crypto ^2.0, у ядра 1.0»), а ядро до 2.1.4 оси не знает («неизвестная ось совместимости steer-crypto — обновите ядро») и остаётся на net1 1.4.x со своей копией. Сверка размеров структур при загрузке (sc_abi_check в scrypto.c) работает и в net1, и в tgws: строка отказа начинается с «steer: библиотека», и её узнаёт проба ABI менеджера (STEER_LIB_PROBE, src/pluginmgr/pminst.c). Новое ядро с другой сборкой библиотек приносит в семени net1 под неё (версия net1 обязана расти, build/net1/abi.lst), и steer plugin migrate в postinst ставит её до перезапуска службы. Откат ядра на 2.1.3 и раньше net1 1.5 сам не снимет — steer plugin install net1 1.4.3.

Имена net1. Наружу — только s2p_* (build/net1/libs2p-net.map, узел LIBS2P_NET_1, порождает build/libs-exports.sh из нужд плагинов). Исходники стека не переименованы: сборка порождает из карты заголовок #define имя s2p_имя и подключает его ключом -include к net1 и к плагинам на ней. Так ни одно имя net1 не совпадает с libsteer в процессе steerd — musl версий символов не различает; wolfSSL и ngtcp2 в этом процессе — одни и те же библиотеки ядра у обоих. На границе net1 и плагина — структуры исходников (struct output, pool_cfg, platform_ops, транспорт, QUIC), поэтому у net1 есть отпечаток их раскладки (src/net1/s2pnet.h): плагин сверяет его и minor ABI при запуске (src/net1/s2pcheck.c) и отказывает строкой, а не портит память. Смена раскладки структуры границы — major (net2).

Где ядро ищет протокол. Только в манифесте плагина: вид (steer.kinds[], ключи — по схеме вида), помощник выхода (helper), хуки check и expand, подкоманды и команды сокета (steer.commands[]). Программа плагина <каталог плагинов>/<id>/bin/<id> (STEER_PLUGINS_ROOT, иначе /usr/lib/steer/plugins) о выходе знает только {conf} — файл, который пишет ядро (plugin_conf_json: ключи вида, устройство, метка, таблица, метка сокетов, подложка, члены развёрнутой группы, каталоги); спеку человека она не читает (--spec у команд протоколов нет). Подкоманда с conf: true получает {conf} названного выхода через memfd. Состояние программа пишет в <state>/plugin/<id>/<выход>.status.json (событие state), ядро печатает его в status полем plugin.state (и прежним полем протокола, "vless": {…}), а строки diag из него — в steer diag. Таблица подкоманд программы — PK_PROGRAM в src/modules/main_<id>.c; её же вкомпилированный вариант — в бинарнике телефона вместе с манифестом (src/plugkit/pkembed.c).

Упаковка. Манифесты и схемы ключей — plugins/<id>/ дерева; build/pack-s2p.sh собирает .s2p под архитектуру (s2p build, подпись — ключ S2P_KEY, без него тестовый) и семя /usr/share/steer/seed/ в steer-core (s2p index): net1, awg (без файлов, --arch all) и плагины PLUGINS_NET1 и PLUGINS_STATIC — vless, hysteria2, proxy, xsteer, warpbox, obfs. tgws (PLUGINS_EXTENDED) это дерево собирает, но в семя он не входит: архив собирает и подписывает репозиторий splify2-extended-plugins.

Семя после установки (2.1.4). Архив семени нужен, пока плагина нет. После install, update, ensure и migrate менеджер снимает архивы тех плагинов, что стоят версией не ниже семени (seed_prune, src/pluginmgr/pmmain.c): из них плагин никогда не ставится, а на флеше net1 лежала дважды. index.json и подпись остаются — по provides.kinds семени ядро узнаёт, кто даёт вид. Архив не стоящего, не вставшего (failed) или стоящего ниже версии плагина остаётся: откат после неудачной проверки здоровья возвращает прежнюю версию, и семя для повтора на месте. Файлы принадлежат пакету: apk и opkg при обновлении и снятии отсутствующий файл пропускают, новый пакет кладёт семя заново, и migrate в postinst снова его чистит. Снятый потом плагин без сети из семени уже не встанет — только из сети. steer-core 2.1 берёт на себя имена прежних пакетов steer-vless, -hysteria2, -proxy, -xsteer, -obfs, -warpbox, -tgws и steer-extended (apk — provides и replaces, opkg — Conflicts, Replaces и Provides) и зависит от kmod-tun, так что установка ядра снимает их в той же транзакции.

Размер пакета и скорость (2.1.4)#

Жалоба 2.1.3: пакет почти вдвое больше 2.0.5 и на роутерах с 12–16 МБ флеша не встаёт. Что сделано (build/build-libs.sh, «РАЗМЕР И СКОРОСТЬ»), и замер тем же ./build.sh STEER_ARCH=…:

mipsel_24kc 2.1.3 → 2.1.4 aarch64_cortex-a53 2.1.3 → 2.1.4
steer-core .apk / .ipk 2555 / 2560 КБ → 1801 / 1807 КБ 2369 / 2370 КБ → 1661 / 1662 КБ
файлы пакета (из них семя) 4440 (1243) КБ → 3317 (562) КБ 3696 (1071) КБ → 2767 (523) КБ
флеш после установки со всеми протоколами 7216 КБ → 3896 КБ 5646 КБ → 3188 КБ
net1 распакованная 1494 КБ → 386 КБ 1241 КБ → 323 КБ
  • Одна копия wolfSSL и ngtcp2 (раздел 1, «Общие библиотеки криптографии»): −0,94 МБ из net1 на mipsel, −0,75 МБ из tgws.
  • Семя после установки снимается (раздел 1, «Семя после установки»).
  • -O2 только горячему пути (HOT_SRC в build/sources.mk: шифры, TLS-запись, QUIC, стек, транспорты, данные протоколов, резолвер), остальное -Os; STEER_OPT=O2 собирает всё как прежде — для сравнительного замера.
  • Мусор в файлах: .pdr MIPS (0,64 МБ на mipsel, build/nopdr.ld), таблицы раскрутки .eh_frame (0,38 МБ на aarch64), выравнивание сегментов под 64 КБ (по 66 КБ нулей в libsteer и tgws на mipsel; теперь страница 4 КБ).
  • compiler_rt zig — один объект: в программы под mipsel он приносил экспортированные sin, cos, log, fma… (60–90 КБ на программу; лечит повторная компоновка с --exclude-libs ALL, link_exe), а его побайтовые memcpy, memmove и memset побеждали memcpy из libc.so во всех файлах под mipsel. Теперь в каждый файл собираются memcpy, memmove и memset из исходников musl, которые zig несёт с собой (на aarch64, arm и x86_64 — ассемблер musl). Замер под qemu-mipsel: копирование 1500 байт — 268 → 1091 МБ/с, 16 КБ — 271 → 1178 МБ/с (невыровненный источник — до 2003 МБ/с).
  • Не взято: LTO (-flto) под MIPS не компонуется (R_MIPS_HI16 … _gp_disp), под aarch64 — на 6 % БОЛЬШЕ; --icf=safe у программ — 80 байт на steerd.

Скорость (регресса нет): стенд tests/bench-tunnel.sh 1024 (VLESS без TLS, x86_64, процессор туннеля) — 0,72 → 0,68 с на ГБ, 7,3 → 7,8 Гбит/с (по три прогона); hysteria2 на ВМ OpenWrt 25.12 x86_64 (KVM, сервер tobyxdd/hysteria, 200 МБ через туннель) — 24,4 → 24,7 мс процессора помощника на МБ (по три прогона, разброс ±0,5), 267 Мбит/с (упор — slirp стенда). SUnreclaim до и после подъёма туннеля и закачки — в пределах 0,1–0,4 МБ у обеих сборок.

Что ещё общее у ядра и net1 — TLS 1.3, REALITY, HTTP-клиент, обёртка QUIC, слой scrypto.c: в libsteer 86 КБ (mipsel) и 57 КБ (aarch64), в net1 то же семейство с HTTP/2 и ECH — 135 и 82 КБ. Убрать копию ядра нельзя (менеджер плагинов и резолвер работают без плагинов), а вынос в общую библиотеку ядра привязал бы исправления TLS и REALITY к выпускам ядра: net1 перестала бы обновляться отдельно. Решение — за владельцем.

2. Устройство#

Ядро — компилятор. Спека превращается в дерево набора правил (src/lib/ir.h), дерево — в текст, а текст применяется одной транзакцией nft -f. Поэтому генератор проверяется без роутера: tests/gen.sh и снимок генератора (раздел 4).

Ядерная форма. Выход выбирают метки nftables, policy routing и наборы адресов; доменные правила идут через свой резолвер (fake-IP или real-ip); туннели — устройства TUN или устройства ядра. tproxy, перехвата потоков в пользовательский процесс и сниффинга нет. Пользовательский процесс стоит только там, где без него нельзя: туннели с протоколами и DNS как плоскость управления.

Чем ближе к L2, тем лучше — когда это даёт пользу. Пакет классифицируется и получает выход как можно ниже по стеку и как можно раньше на своём пути, если это даёт хотя бы одно из следующего: - меньше обработки трафика; - выше скорость, меньше задержки и расход ресурсов; - меньше возможности другому софту вмешаться в наш трафик без нашего ведома; - удобнее.

Перенос ниже, который ничего из этого не даёт или стоит памяти (например, вторая копия наборов в таблице netdev), не делается. По этому правилу правила каналов раздачи стоят на хуке ingress («Набор правил» ниже).

Чужие пакеты — настройка человека. dnsmasq, https-dns-proxy, netifd, odhcpd и зоны fw4 ядро не настраивает: оно маршрутизирует само и говорит в diag, чего не хватает. Исключение одно — подмена адреса в своей таблице: masquerade IPv4 у устройств выходов, которые адреса клиентов сами не завершают (interface, awg, члены WARP; цепочка postrouting_nat4), и masquerade IPv6 по ключу ipv6: nat у выхода (раздел 4б).

Один разбор спеки. Спеку читает одна функция load_spec (src/model/parse.c), а таблицу доменных каналов для резолвера строит код модели (dch_build, src/dnsd/table.c); имя набора у компилятора и резолвера считает одна функция (docs/contract-v1.md, §7).

Правила устройства#

  1. Вид выхода — файл. Всё, что знает о виде, лежит в src/kinds/<вид>.c и отдаётся одной таблицей struct kind_ops («Вид выхода» ниже). Общий код спрашивает свойства и функции вида, а не сравнивает, какой он: сравнение вида вне src/kinds ловит tests/buildmatch.sh.
  2. Платформа — таблица, выбираемая при запуске. Отличия телефона от роутера лежат в src/platform/openwrt.c и src/platform/android.c за таблицей struct platform_ops (platform.h): пути, поле метки, NAT, цепочки на сам телефон. Порядок выбора (platform.c): --platform или STEER_PLATFORM, затем умолчание сборки (-DSTEER_DEFAULT_PLATFORM), затем признаки среды, последним — роутер. Условной компиляции по STEER_ANDROID нет (buildmatch).
  3. Сборка — набор файлов, а не набор макросов. Профиль в build/sources.mk — это список файлов, и больше ничего. То, чего в сборке может не быть (хаб xsteer, менеджер плагинов, вкомпилированные программы плагинов телефона), — слабые ссылки в src/daemon/main.c, виды ядра — слабые ссылки реестра src/kinds/kind.c: файла нет в профиле — на его месте штатный отказ («хаб xsteer в этой сборке отсутствует — он ставится на VPS из архива steer-hub», «менеджера плагинов в этой сборке нет»). Команды протоколов приходят только из манифестов плагинов: нет плагина — «нет такой команды». То, что файлом не выражается, лежит в файле профиля src/profile/<профиль>.c (profile.h): имя варианта сборки и признак полного статического бинарника. У base своего файла нет, действуют умолчания src/profile/profile.c. Макросов STEER_EXTENDED, STEER_SERVER, STEER_TGWS нет ни в src, ни в путях сборки (buildmatch).
  4. Слои зависят только вниз. buildmatch проверяет это частями: сборочные списки замкнуты по #include, ядро не включает заголовков протоколов, а src/tunnel и src/proto не зовут маршрутизацию демона.
  5. Ошибки возвращаются. Модели и компилятору die() не нужен: они возвращают код и заполняют struct err (src/lib/err.h), а процесс завершает только точка входа бинарника (err_die). В src/model, src/compile и src/lib, кроме err.c, нет ни die(), ни exit() (buildmatch).
  6. Спека — значение, а не глобалы. Всё прочитанное лежит в struct spec (src/model/spec.h), и функции получают её параметром. Прежних глобалов спеки (g_out, g_ch, g_lan_dev и соседних) в src нет (buildmatch).

Процессы#

На роутере:

procd
  └─ steerd daemon --watch --supervise --apply    один экземпляр, respawn
       ├─ сокет управления, протокол v1            <каталог спеки>/steer.sock
       ├─ apply-сверка                             дети apply-plan, apply-commit на команду
       ├─ сторож                                   на цикле событий, без fork на проход
       ├─ супервизор детей
       ├─ steer dnsd --table-fd 3                  ребёнок: файл steerd, argv[0] «…/steer»
       ├─ <id> <выход> --conf {conf}               ребёнок: программа плагина
       │                                            (plugins/<id>/bin/<id>: vless, xsteer, obfs, tgws…)
steer <команда>          клиент: команды демона — в сокет; остальное и всё без демона — execv steerd
steer-tools <команда>    ссылка на steerd: отвечает только на инструменты
  • Три имени в пакете. steerd — всё ядро одной программой (на libsteer.so и libsteer-wolfssl.so): демон, компилятор, apply, резолвер, менеджер плагинов, инструменты; steerd <подкоманда> — то же, что подкоманда ядра. steer — отдельный маленький клиент сокета (src/client/main.c). steer-tools — ссылка на steerd, под этим именем ядро отвечает только на инструменты (раздел 4а, «Бинарники»).
  • Помощники: резолвер — подкоманда steerd, протоколы и мост Telegram — программы плагинов. Резолвер демон запускает тем же файлом steerd, помощников выходов видов плагинов — программой плагина по манифесту (helper: <id> <выход> --conf {conf}; plugin_kind_helper в src/kinds/plugin.c). Окружение — STEER_EVENT_FD, STEER_SUPD и переменные steer-api (STEER_PLUGIN_ID, STEER_PLUGIN_STATE…). Первое сообщение программы — hello с её steer-api и id: чужой major или minor новее ядра, чужое имя или не hello — процесс гасится, причина — в last_down. В статической сборке телефона программы плагинов слинкованы в сам бинарник (PK_PROGRAM), а манифесты — в src/plugkit/pkembed.c: ядро запускает тот же бинарник с STEER_PK_BUILTIN=<id>. Помощник, который не подкоманда ядра, а своя программа (программа плагина, внешний модуль DPI recheck), — kind_helper.prog.
  • Версия плагина с версией ядра не сверяется: плагины обновляются отдельно. Сверяется steer-api из hello (major — как у ядра, minor — не новее); программу, начавшую не с hello, демон гасит (SIGTERM) и не верит ни одному её событию, причина — в журнале и в last_down ответа helper (поле rejected). Программы плагина нет — «нет программы плагина X — переставить плагин» в журнале и в last_down, повтор запуска — по обычной паузе.
  • У программ плагинов SIGPIPE выключен (pk_main). Запись в сокет узла, который узел уже закрыл, — ошибка EPIPE, как ECONNRESET: стек закрывает ровно это соединение (RST клиенту) и освобождает его, а процесс продолжает нести остальные; с SIGPIPE по умолчанию такая запись убивала бы помощника со всеми соединениями. Закрытая труба событий гасит помощника через EPIPE и SIGTERM (evline_emit).
  • Службу держит /etc/init.d/steer: один экземпляр procd с respawn. reload, reload_dnsd, reload_zapret и reapply — запрос reload демону клиентом (без демона reapply применяет спеку сам, steerd apply; reload_dnsd поднимает службу, если автозапуск не снят); stop ждёт выхода демона и зовёт steerd down; restart (его зовут и скрипты пакета при обновлении) — свой, а не stop и start rc.common: steerd down не зовётся, набор правил, правила fwmark и таблицы выходов остаются в ядре, а демону перед SIGTERM оставлен файл <каталог состояния>/restart — по нему он не гасит резолвер, и тот достаётся новому демону; hotplug (files/etc/hotplug.d/iface/95-steer) шлёт экземпляру SIGHUP. На телефоне демона держит init (init/steerd.rc в дереве прошивки vendor/der, вне этого репозитория).

Слои и каталоги#

Каталоги слоёв — INC_DIRS в build/sources.mk; их же ровно перечисляет Android.bp, и сверяет это tests/buildmatch.sh. Имена заголовков в дереве уникальны: заголовки подключаются по имени из любого слоя.

src/
  lib/        общие кирпичи: run.c (run, run_quiet), err.c, tmpfile.c (шаблон временного файла),
              jsonw.c, jsonr.c, ynode.c (обёртка libyaml), nlbuf.h, nftnl.c (nf_tables по
              netlink), nftdump.c, nftvmap.c, ctnl.c (conntrack), rtnl.c, procscan.c, sindex.c,
              puff.c и gz.c (распаковка gzip), ir.c (дерево набора правил: его строят и compile, и
              виды через emit), evline.c (линия событий помощник → демон, hello), ctlcall.c (вызов
              сокета демона), module.c (версия ядра этой сборки), scrypto.c (слой криптографических
              примитивов — только в сборках с TLS), sigverify.c и untar.c (подпись и распаковка
              архивов плагинов)
  model/      spec.h (struct spec, struct output с union видов, правила, клиенты, списки),
              parse.c (выбор формата), v2.c и v2print.c (спека v2), v2keys.c (таблицы ключей спеки v2:
              их берут разбор и схема), v2schema.c (`steer spec-schema`), v1.c (перевод спеки v1),
              check.c (сквозные проверки), registry.c (реестр меток и таблиц), marks.h, probe.c,
              plugprep.c (хуки плагинов check, expand, pre_apply и выдача ресурсов), srs.c, srsplan.c
              (наборы sing-box)
  kinds/      kind.h и kind.c (struct kind_ops, биты свойств, реестр),
              direct.c interface.c awg.c awgdev.c (устройство AmneziaWG: его же берёт плагин warpbox)
              block.c group.c grpurl.c, plugin.c и plugalloc.c (реестр плагинов: виды, команды и хуки из
              манифестов; выдача ресурсов плагинам — порты, очереди, биты метки)
  platform/   platform.h, platform.c, openwrt.c, android.c
  profile/    profile.h, profile.c (умолчания), extended.c, server.c — данные профиля
  compile/    groups.c, balance.c, torrent.c, generate.c, print.c,
              nftcompat.c (что умеет nft этого ядра)
  daemon/     main.c, ctl.c (сокет, протокол), apply.c, recon.c (сверка), watch.c и watchd.c
              (сторож), supervise.c и supd.c (супервизор), helpers.c, status.c, diag.c,
              explain.c, fwcheck.c, failover.c, fogroup.c, folat.c, foprobe.c, urltest.c, gaiw.c,
              conns.c, loop.c, state.c, rulewd.c, nftquery.c, wandev.c, plugso.c (плагины-библиотеки
              в процессе демона)
  dnsd/       main.c, proxy.c, wire.c, rules.c, fakeip.c, realip.c, origdst.c, table.c, tabfmt.c,
              fpseed.c, adopt.c, dlog.c, dcache.c, dup.c, dupgrp.c, dupdial.c, doh2.c, doh3.c, doq.c,
              dprobe.c (`steer dns-probe`)
  client/     main.c — steer, клиент сокета
  cli/        cli.c — таблица команд и разбор командной строки; modcmd.c — флаг --platform
  pluginmgr/  менеджер плагинов (`steer plugin`, команды сокета `plugin-*`): pmmain.c (действия),
              pminst.c (установка, снятие, откат), pmindex.c (индексы репозиториев и семени),
              pmstate.c (state.json), pmkind.c (какой плагин нужен виду), pmver.c (semver), pmutil.c
  plugkit/    сторона плагина в API ядра (steer-api): plugkit.c — {conf} выхода, точка входа
              программы (pk_main, PK_PROGRAM), файл состояния и событие state; pkmain.c — main
              программы плагина; pktun.c — ключи туннеля по подписке; pkjson.c — разбор JSON;
              pkembed.c — манифесты плагинов, вкомпилированных в бинарник телефона (порождает
              build/pkembed.sh). Модели спеки ядра в программах плагинов нет
  modules/    main_vless.c, main_xsteer.c, main_obfs.c, main_hysteria2.c, main_proxy.c, main_warpbox.c,
              main_tgws.c — таблицы подкоманд программ плагинов (PK_PROGRAM); мост tgws выпускает
              репозиторий splify2-extended-plugins, его исходник здесь (plugins/tgws)
  net1/       s2pnet.c и s2pnet.h (версия ABI и отпечаток раскладки библиотеки net1), s2pcheck.c (сверка
              в программе плагина при запуске)
  tools/      aggregate.c (fit), srsread.c, hwid.c
  tunnel/     стек туннеля без протокола: tun.c (TUN: очереди, разгрузка, запись пакетов),
              rtx.c (кольцо недописанного клиенту), stack.c и stack.h (соединения TCP от слушателя и
              датаграммы UDP из TUN ↔ потоки к узлу, рабочие потоки, таблица соединений, пул
              установщиков, запасные сессии, доли клиента и бюджет памяти), dialer.h (struct dialer_ops),
              pool.c и pool.h (пул узлов выхода: N активных узлов, раздача соединений, слежка
              за каждым и замена мёртвого без перезапуска — обёртка дайлера), geo.c (страна выхода)
  proto/      tls/ (tls13, certverify, reality, chello, h2, ech, roots — корни проверки сертификата,
              httpc и plughttp — HTTP-клиент, tlsprobe, urltls)
              transport/ (transport.h — struct transport_ops и security_ops; transport.c —
              сборка ярусов и транспорт tcp; trdial.c — сокет до узла; trsec.c — none, tls,
              reality; trgrpc.c; trxhttp.c; trupgrade.c — запрос Upgrade по HTTP/1.1 и
              httpupgrade; trws.c — кадры WebSocket; trpath.c — путь запроса Upgrade; trvenc.c —
              VLESS encryption)
              vless/ (vlmain.c — подкоманды vless*, vldial.c — дайлер стека, client.c —
              vless_connect и проверка узла, vless_proto, vision, sub,
              subfetch; sublink.c — ссылка узла и поля транспорта, общие с плагином proxy)
              proxy/ (trojan, shadowsocks, socks, http, vmess: pxwire, pxsub, pxdial, pxtrojan,
              pxss, pxsocks, pxhttp, pxvmess, pxmain — плагин proxy, docs/proxy.md)
              hysteria2/ (клиент hysteria2 на QUIC — плагин hysteria2, docs/hysteria2.md)
              quic/ (quic.c, qcssl.c — обёртка над ngtcp2; qcdoq.c — шов DoQ резолвера)
              warp/ (регистрация, подбор точек, MASQUE — плагин warpbox, docs/warp.md; wbhttps.c и
              wbjson.c — HTTPS и JSON, общие с ядром)
              xsteer/ (xswire, xshake, xsepoch, xsconf, xslink, xsconn, xsroute, xsstream,
              xsclient, xshook, xshub, xsadmin)   tgws/   obfs/ (WG поверх поддельного TCP:
              obfs.c — обфускатор, obfsmain.c — помощник и obfs-server)
  third_party/libyaml (разбор YAML; файлы не правятся — суммы в UPSTREAM сверяет buildmatch)

Отдельной точки входа туннеля в src/tunnel нет: она у программы плагина (src/proto/vless/vlmain.c и соседи), а стек — библиотека, которую программа зовёт (stack_run).

Куда файлы уходят в разделяемой раскладке (раздел 1, списки — build/sources.mk): модель, виды, платформа, cli/cli.c, tools/hwid.c, TLS, HTTP-клиент, подпись и распаковка плагинов, QUIC — в libsteer.so; src/daemon, src/dnsd, src/compile, src/pluginmgr, tools/aggregate.c, tools/srsread.c, tls/urltls.c — в steerd; src/tunnel, src/proto/transport, sublink.c и вторая копия TLS и QUIC — в net1; код протоколов (proto/vless с tls/tlsprobe.c, proto/hysteria2, proto/proxy, proto/xsteer без xshub.c, proto/warp, proto/obfs, proto/tgws) — в программы плагинов; xshub.c — только в хаб на VPS.

Файлы reality.c, tls13.c, vision.c, vless_proto.c, xswire.c, xshake.c, xsepoch.c, certverify.c держат байты на проводе: ошибка в них не ломается явно, поэтому их правка проверяется make ext-test и стендами протокола (раздел 4).

Вид выхода#

Вид выхода — файл src/kinds/<вид>.c с записью struct kind_ops (src/kinds/kind.h, полностью и с доводами — там же):

enum kind_cap {
    KC_DEVICE = 1 << 0,  KC_MARK = 1 << 1,        KC_CTMARK = 1 << 2,   KC_ENGINE_OWNED = 1 << 3,
    KC_SELF_NAT = 1 << 4, KC_OVER = 1 << 5,       KC_SKIP_ZAPRET = 1 << 6,
    KC_TCP_PROBE = 1 << 7, KC_FLOW_UDP = 1 << 8,  KC_IPV6 = 1 << 9,
    KC_TCP_REDIR = 1 << 10,
};

struct kind_ops {
    const char *name;           /* как пишется в спеке */
    unsigned caps;              /* enum kind_cap */
    unsigned keys;              /* enum kind_key: чьи ключи спеки */
    const char *absent;         /* не NULL — вида в этой сборке нет, строка отказа */
    unsigned (*caps_of)(const struct output *);        /* свойства, зависящие от настройки */
    const char *novia, *selfnat_why, *lan_only;       /* тексты о виде для общего кода */

    int  (*parse)(struct output *, const struct out_keys *, struct err *);  /* один разбор на v1 и v2 */
    void (*keys_of)(const struct output *, struct out_keys *);             /* обратное parse */
    int  (*check)(const struct spec *, const struct output *, struct err *);
    void (*emit)(struct nft_rs *, const struct spec *, const struct output *);
    int  (*health)(const struct spec *, const struct output *, const char *dev);
    int  (*revive)(const struct spec *, const struct output *, const char *dev,
                   const struct kind_name *names, size_t n);
    size_t (*revive_names)(const struct spec *, const struct output *, struct kind_name *, size_t);
    int  (*latency)(const struct spec *, const struct output *, const char *dev);
    void (*status)(FILE *, const struct spec *, const struct output *);
    void (*diag)(kind_diag_fn *, const struct spec *, const struct output *);
    int  (*helper)(const struct spec *, const struct output *, struct kind_helper *);
    void (*conf_keys)(FILE *, const struct output *);  /* ключи вида в {conf} помощника плагина */
};
  • Свойства — биты caps. Предикаты out_* в spec.h (out_has_device, out_needs_mark, out_engine_managed, out_self_natting и соседи) — тонкие обёртки над битами, и у каждого записано, чем он отличается от соседнего.
  • Любая функция может быть NULL: общий код проверяет это явно и идёт общим путём (общая проба ICMP или TCP по KC_TCP_PROBE, общий замер соединением TCP, правила по свойствам).
  • Настройки видов — union внутри struct output: у каждого вида ядра своя структура (struct iface_cfg, struct awg_cfg, struct group_cfg, …), и заполняет её только разбор его файла; вид плагина держит ключи по схеме манифеста (struct plugin_out). Помощники видов плагинов знают о выходе только свой {conf}.
  • Реестр (kind.c): виды ядра direct, interface, awg, block — в этом порядке идут правила видов в дереве (kind_emit_all) и проверки diag; за ними — виды плагинов по id плагина и порядку манифеста, так что порядок не зависит от порядка установки. На месте вида ядра, файла которого в сборке нет, стоит запись отказа с absent.
  • Группа (kind: group, src/kinds/group.c) — вид модели v2 и в реестр не входит: спека v1 её не знает, разбор v2 находит её через kind_by_name_v2, а пул devices спеки v1 собирает в группу перевод v1 (раздел 4в).

Набор правил#

Всё, что ставит ядро steer, лежит в своих таблицах (table inet steer), и каждая замена идёт одной транзакцией: файл начинается со снятия таблицы, за ним новая, поэтому момента без таблицы нет (docs/contract-v1.md, §7). Раскладка одна — nat в семействе inet (Linux 5.2 и новее); что умеет nft этой машины (составной набор, хук ingress), проверяет src/compile/nftcompat.c. Базовые цепочки (src/compile/generate.c; хуки и приоритеты печатает steer nft-map, для плагинов это часть steer-api):

Цепочка Хук, приоритет Что делает
ingress_mark ingress устройств раздачи, filter + 10 правила каналов раздачи: метка выхода пакету до conntrack и до чужих цепочек prerouting
prerouting_raw prerouting, raw traceroute для доменных каналов (traceroute_hops)
prerouting_mark prerouting, mangle + 1 метка соединения и выбор члена balance по готовой метке; те же правила каналов — запасные, для пакета, который ingress не разобрал
prerouting_failopen prerouting, mangle + 2 снимает бит обхода DPI с трафика выхода, пущенного сторожем напрямую
forward_v6 forward, mangle отвергает IPv6 правил, ведущих в выход без IPv6, и адрес из префикса хоста мимо донора (раздел 4б)
prerouting_dns nat prerouting, dstnat - 2 заворот DNS клиентов на порт резолвера
prerouting_tcp_redir, output_tcp_redir nat, dstnat - 1 перенаправление TCP клиентов выходов с KC_TCP_REDIR к слушателю программы плагина по метке (раздел 2, «Туннели: стек, дайлер, транспорт»)
prerouting_dnat nat prerouting, dstnat подмена поддельного адреса fake-IP на настоящий по карте; поддельный адрес без подмены отбрасывает правило steer-fakeip-nomap
prerouting_restore prerouting, dstnat + 10 возврат решения из метки соединения после чужой перезаписи метки (только при STEER_MARK_RESTORE=1 — его просит коннектор через steer.platform)
output_mark, output_dns output каналы на сам телефон и заворот его DNS
postrouting_guard postrouting, filter пакет с меткой выхода с устройством уходит только в устройства этого выхода — или отбрасывается
postrouting_fakeguard postrouting, filter пакет к пулу fake-IP не уходит в устройства клиентов и в mesh-VPN (tailscale*, zt*)
postrouting_nat4 nat postrouting, srcnat masquerade IPv4 на устройстве выхода, которому нужна подмена (interface, awg, члены WARP)
postrouting_nat6 nat postrouting, srcnat masquerade IPv6 у выхода с ipv6: nat
postrouting_down, input_down postrouting srcnat + 10, input filter + 10 счётчики скачанного трафика каналов (input_down — каналов на сам телефон)
plugin_<слот>, plugin_<id>_<слот> слот правила плагинов: файлы nft и шаблоны видов (перехват моста tgws — слот prerouting-dnat)

Разметка на ingress. Цепочка ingress_mark стоит на тех устройствах из lan_devices, что есть при apply, с приоритетом filter + 10 — после flowtable fw4 на том же хуке. Первое правило даёт пакету с пустым полем метки значение «разобран, выхода нет» (STEER_INGRESS_SEEN, 0x0f000000, src/model/marks.h), дальше идут правила каналов с меткой пакета. Записи conntrack на ingress ещё нет, поэтому метку соединения и выбор члена balance ставит первое правило prerouting_mark (цепочки ingress_seen и ingress_ct). Остальные правила prerouting_mark ловят пакет, который ingress не разбирал: устройство без хука, клиент с другого устройства, метка, переписанная чужой цепочкой между ingress и нами. Цепочку ingress ядро принимает только на существующие устройства и вынимает из неё исчезнувшее; устройство, созданное заново, возвращает в неё следующая замена набора правил (демон со --watch ставит её сам, раздел 4а). Разметка остаётся целиком в prerouting на ядре без inet ingress (проба nft -c), на телефоне, у спеки без правил раздачи и при STEER_NFT_INGRESS=0 в окружении apply.

Порядок применения (docs/ctl.md, «Порядок применения»): устройства awg и привязка выходов — раньше набора правил, чтобы метка ни мгновения не жила без своего правила fwmark; набор правил — одной транзакцией, с картой fake-IP и наборами каналов fake-IP, засеянными из файла состояния резолвера (src/dnsd/fpseed.c, print_elements в src/compile/print.c); сразу после загрузки — возврат элементов real-ip резолвером, отметки «пущен напрямую», карта balance к живым членам; снятие прежних меток — только после удачной загрузки.

Туннели: стек, дайлер, транспорт#

Туннель с протоколом поверх потоков — три слоя (раскладка по файлам — «Слои и каталоги»):

  • стек (src/tunnel): соединения TCP и датаграммы UDP клиента ↔ потоки к узлу — таблица соединений, ранние данные, сборка фрагментов UDP, пул установщиков, запасные сессии. Про протокол он не знает ничего: на каждое соединение у него непрозрачная сессия дайлера; вход — stack_run(выход, дайлер, ready, arg) (stack.h), а обратный вызов ready получает имя поднятого устройства. Стек несёт оба семейства: ключ потока (flow_key) хранит адреса IPv4 (4 байта) или IPv6 (16). TCP клиентов (IPv4 и IPv6) у выходов vless, hysteria2 и прокси (KC_TCP_REDIR) завершает ядро Linux: правило nat на dstnat - 1 — раньше подмены fake-IP — перенаправляет соединение по метке выхода к слушателю программы плагина (порт 9480 плюс место выхода в реестре, out_tcp_port), стек берёт назначение из SO_ORIGINAL_DST (поддельный адрес — по fakeip.state) и гонит поток дайлером; соединения раздаются рабочим по кругу. Карту «метка → порт» ведёт демон вместе с привязкой таблицы выхода: элемент есть, пока таблица смотрит в устройство живого помощника (у группы — порт члена, на котором она стоит), и снимается, когда помощник вышел. Вход fw4 для таких соединений (гостевая зона с input REJECT) открывает файл пакета /usr/share/nftables.d/chain-pre/input/30-steer.nft. Слушатель — сокет IPv6 с IPV6_V6ONLY=0: он принимает и IPv6 (исходное назначение — IP6T_SO_ORIGINAL_DST, поддельный IPv6 из fdfe:dcba:9876::/96 разворачивается картой fakeip6), и IPv4 (адрес вида ::ffff:a.b.c.d, назначение — SO_ORIGINAL_DST); на ядре без IPv6 слушатель остаётся IPv4. Для IPv6 правило nat своё (meta nfproto ipv6, тот же порт и та же карта), в таблице IPv6 выхода — маршрут в TUN, на устройстве — адрес ULA fd73:7465:6572::<N>/128 (источник для пакетов самого роутера). Через TUN идёт только UDP, в обоих семействах: разбор IPv6 принимает за фиксированным заголовком TCP, UDP или заголовок фрагментации (прочие расширения — hop-by-hop, маршрутизация, параметры получателя — не разбираются), датаграмма крупнее MTU уходит клиенту фрагментами с заголовком фрагментации, клиентские фрагменты стек собирает (ключ — адреса и 32-битный номер, как у IPv4 с 16-битным); раздача по рабочим, программа ядра и хэш считают IPv6 по свёртке адресов исключением. TCP, попавший в устройство (перенаправления нет), получает сброс. Своего TCP-стека поверх TUN у туннеля нет. Рабочих потоков столько, сколько ядер доступно процессу (STEER_TUN_THREADS задаёт число руками, 1 — один поток без отдельного читателя TUN); у каждого своя таблица соединений, а пакеты из TUN раздаёт рабочим читатель без замков. Установщиков связи с узлом — до 64 (STEER_TUN_CONNECTORS), по 16 заявок на установщика отдельно для TCP и UDP; одному клиенту (адрес IPv4 или /64 IPv6) — не больше четверти заявок рода, рукопожатие с узлом целиком — не дольше 16 с. Памяти, которую соединения держат в куче (сессии, кольца недописанного, ранние данные), — бюджет: половина MemAvailable при запуске, не меньше 16 МиБ, или STEER_TUN_MEM_MB; одному клиенту — половина бюджета. Новое соединение принимается, пока занято не больше трёх четвертей бюджета (и доли клиента), последняя четверть — запас уже открытым; на пределе TCP получает RST, UDP — ICMP «порт недоступен», а медленный читатель перестаёт читать у узла, пока его клиент не заберёт своё;
  • дайлер — протокол поверх транспорта: заголовок запроса, обёртки, разбор ответа, обрамление датаграмм. Дайлеры — VLESS (src/proto/vless/vldial.c: заголовок VLESS, Vision, UDP командой 2) и протоколы прокси (src/proto/proxy: trojan, shadowsocks, socks, http, vmess — по файлу на протокол; docs/proxy.md), а hysteria2 ходит своим путём (QUIC, src/proto/hysteria2). Подкоманды steer vless* / steer proxy* и выбор первого узла — в программе плагина (vlmain.c/pxmain.c), а N активных узлов, раздача соединений и слежка — у пула узлов (src/tunnel/pool.c): он обёртка дайлера, ctx протокола у него по-прежнему узел, только узел свой у каждого соединения;
  • транспорт (src/proto/transport): как поток дайлера едет до узла — сокет по всем адресам имени с меткой over (trdial.c), безопасность security= — none, tls, reality (trsec.c) — и транспорт type= — tcp, grpc, xhttp, ws, httpupgrade (transport.c, trgrpc.c, trxhttp.c, trws.c, trupgrade.c).

Интерфейсы — сокращённо, полностью с доводами в заголовках:

struct dialer_ops {              /* src/tunnel/dialer.h */
    const char *name;
    unsigned caps;               /* DC_PRECONNECT: связь открывается до адреса — пул запасных */
    size_t sess_size;            /* сессия на соединение клиента; память выделяет стек */
    int  (*connect)(const void *ctx, void *sess, int timeout_s);   /* в потоке установщика */
    void (*take)(void *dst, void *src);      /* связь из запасной сессии — в сессию соединения */
    int  (*flow_open)(const void *ctx, void *sess, const struct flow_key *k, int udp);
    int  (*send)(const void *ctx, void *sess, const struct flow_key *k, int udp,
                 const unsigned char *d, size_t n);
    size_t (*dgram_frame)(const unsigned char *p, size_t n, unsigned char *out, size_t cap);
    int  (*read)(void *sess, unsigned char *buf, size_t cap,
                 const unsigned char **data, size_t *got);
    int  (*deliver)(const void *ctx, void *sess, int udp, const unsigned char *d, size_t n,
                    dialer_emit_fn emit, void *arg);   /* кусками потока или датаграммами */
    /* служебные: peer, describe, strerror, close, clear, fd, has_data */
    /* вторая связь (NULL — нет): aux_fd — дескриптор, который стек ставит в epoll, aux_drain — слить
     * пришедшее; у xhttp это связь выгрузки, ответы на которую освобождают место (room) */
    /* узлов несколько (пул, pool.c; NULL — узел один): peer_of, match — годится ли запасная,
     * stale — узел соединения больше не активен (RST), lost — связь оборвана ядром или узлом */
};

struct transport_ops {           /* src/proto/transport/transport.h — tcp, grpc, xhttp, ws, httpupgrade */
    const char *name;
    const char *alpn;            /* что просить в ALPN; NULL у tcp, http/1.1 у ws и httpupgrade */
    int zc;                      /* данные лежат в записях TLS как есть — чтение без копии */
    int  (*open)(struct transport *, const struct tr_node *, int timeout_s);
    int  (*write)(struct transport *, const unsigned char *, size_t);
    int  (*read)(struct transport *, unsigned char *, size_t cap, size_t *got);
    void (*moved)(struct transport *);       /* структура переехала — поправить самоуказатели */
    void (*close)(struct transport *);       /* своё сверх основной связи: вторая связь xhttp */
    int  (*pending)(const struct transport *); /* своё непрочитанное: остаток за ответом 101 */
    int  (*aux_fd)(const struct transport *);  /* вторая связь для epoll цикла (xhttp: выгрузка), -1 — нет */
    int  (*aux_drain)(struct transport *);     /* слить её по событию; не 0 — слушать больше нечего */
};
struct security_ops {            /* none, tls, reality */
    const char *name;
    int (*handshake)(struct tr_link *, const struct tr_node *, const char *alpn);
};
  • Безопасность и транспорт — две таблицы, а не одна цепочка. В ссылке узла это два независимых поля, security= и type=, и сочетаются они любые. Слои безопасности различаются только рукопожатием — после него у tls и reality одни и те же записи TLS 1.3, — поэтому у security_ops одна функция, а поток после рукопожатия общий. Вторая связь xhttp (stream-up, packet-up) поднимается тем же tr_link_open, что и основная.
  • У дайлера нет своих open_tcp/open_udp. Узел у протокола один на соединение (у пула узлов — свой у каждого соединения, без пула — один на процесс), связь — одна на поток клиента, и открывает её установщик стека (connect); TCP и UDP различаются флагом в flow_open, send и deliver — у VLESS это одна связь с другой командой в заголовке. Датаграммы едут байтами потока (dgram_frame).
  • Сессия одна на соединение клиента — и связь, и состояние потока. Граница между ними — дело дайлера: take переселяет из запасной сессии только связь, не затирая UUID и Vision потока.
  • Таблицы потока — в куче, а не в __thread. У потока цикла одно отображение (mmap) под таблицу соединений, списки, корзины и сессии; страницы берутся по факту обращения, а установщики и поток слежки этого адресного пространства не получают. Статический TLS разделяемой библиотеки заводился бы каждому потоку каждого слинкованного с ней процесса.
  • Буферы на поток остаются __thread (рукопожатие TLS, записи, кадры gRPC, xhttp и HTTP/2). У libsteer.so, которую процесс получает при запуске (DT_NEEDED), модель -ftls-model=initial-exec: обращение — одна загрузка из GOT. У net1 модель по умолчанию (global-dynamic): её загружают и dlopen'ом, а места в статическом блоке TLS процесса для её буферов нет. Размер сегмента TLS файла показывает readelf -l (TLS). На musl TLS потока лежит в его же отображении, нулевые страницы не трогаются, пока буфер не использован; резидентной остаётся только используемая часть.

Новый протокол поверх потоков — это файл дайлера, стек не трогается (так добавлены trojan, vmess и http плагина proxy). UDP самим протоколом по датаграммам (shadowsocks, socks5 UDP ASSOCIATE) ложится в ту же таблицу без правки стека: бит DC_UDP_OWN говорит, что у потока UDP своя связь — сокет UDP к узлу, а не поток, и стек не берёт для него запасную связь пула (dialer.h). Бит DC_INLOOP — у дайлера, чья связь с узлом не дескриптор на соединение клиента, а состояние рабочего потока (hysteria2: QUIC): стек сам зовёт connect в потоке рабочего, исход дайлер сообщает stack_sess_ready, события потока — stack_sess_rx и stack_sess_room, а сокет и сроки дайлера встают в цикл рабочего (loop_start, loop_poll, loop_wait, loop_stop; сокет — stack_loop_watch). Окно клиента такого дайлера — место у узла (dialer_ops.room), и оно растёт по подтверждениям узла. Новый транспорт — таблица transport_ops без правки дайлера и стека (так устроены ws и httpupgrade: tr_ws в trws.c, tr_httpupgrade в trupgrade.c).

xsteer на этот стек не ложится: он везёт IP-пакеты, а не потоки — TUN ↔ записи своего протокола (Noise IK в облике TLS, xshake.c) поверх UDP или своего TCP (xsstream.c), без терминатора TCP/UDP, окон и повтора. Транспорты src/proto/transport ему тоже ни к чему: его рукопожатие — не TLS-клиент к серверу, а своё. Общее со стеком у него — слой TUN (tun.c: очереди, чтение, склейка сегментов при записи); подъём устройства и потоки — свои.

Криптография#

Криптобиблиотека — wolfSSL, собранная из исходников выпуска со своими опциями: версия и сумма архива — build/wolfssl/fetch.sh, опции — build/wolfssl/user_settings.h, список файлов — build/wolfssl/build.sh (с ним сверяется build/wolfssl/Android.bp). Код протоколов и транспортов библиотеку не зовёт: между ними тонкий слой примитивов src/lib/scrypto.h — хэши, HMAC, HKDF, AES-GCM, ChaCha20-Poly1305, AES-CTR, X25519, проверка подписей и цепочки X.509. В заголовке слоя нет ни одного типа wolfSSL, контексты — непрозрачные буферы фиксированного размера, а заголовки wolfSSL включает один src/lib/scrypto.c (buildmatch). Свои TLS 1.3 и REALITY (src/proto/tls), рукопожатие и ратчет xsteer и мост tgws стоят на этом слое. В статической базовой сборке криптографии нет.

Постквантовая часть. Слой отдаёт ML-KEM-768 (sc_mlkem768_*: ключ и закрытый ключ — байтами, не контекстами; случайность даёт вызывающий), проверку ML-DSA-65 (sc_mldsa65_verify, пустой контекст FIPS 204) и BLAKE3 (sc_blake3_*). Первые два стоят на wolfSSL (WOLFSSL_WC_MLKEM, WOLFSSL_WC_MLDSA в режиме VERIFY_ONLY, SHA-3 — все три в user_settings.h; ключи wolfSSL создаются в куче на время вызова, поэтому их размер не входит в ABI между libsteer и libsteer-wolfssl). BLAKE3 в wolfSSL нет: это src/lib/blake3.h, переносимый C без библиотеки, включаемый в scrypto.c. Потребители: гибрид X25519MLKEM768 в TLS 1.3 и REALITY (src/proto/tls), подпись ML-DSA-65 у REALITY (certverify.c) и VLESS encryption (src/proto/transport/trvenc.c), см. vless.md.

ChaCha20-Poly1305 на 32-битном MIPS. На роутерах без AES и SIMD (MT7621, mipsel_24kc и mips_24kc) это шифр туннеля, а поставляемая wolfSSL без ассемблера считает его медленно: Poly1305 — 26-битными ветвями с побайтовой сборкой слов, а гамма ChaCha20 накладывается по байту, когда данные не выровнены так же, как блок гаммы (запись с 5-байтным заголовком TLS невыровнена, как правило). Поэтому на __mips__ без 64 битов слой scrypto.c собирает AEAD сам по RFC 8439 (ветка SC_CP_OWN): Poly1305 на 32-битных словах и multu/maddu — src/lib/poly1305_32.h, ChaCha20 — из wolfSSL, но невыровненные данные идут через выровненный буфер на 256 байт. На остальных целях слой зовёт wc_ChaCha20Poly1305_*_ex как прежде (на aarch64 у wolfSSL свой ассемблер — NEON для ChaCha20 и Poly1305, расширение Crypto для AES). Ветку сверяет с wolfSSL tests/cpmatch.c: на хосте с переносимой арифметикой — в make ext-test, с настоящими командами MIPS — tests/cpmips.sh под qemu-user (в make test не входит).

В пакете роутера библиотека — libsteer-wolfssl.so.<версия wolfSSL>, слой scrypto.c — в libsteer.so, и libsteer.so зависит от неё (DT_NEEDED). Наружу из libsteer-wolfssl.so выходят символы wc_* и wolfSSL_*, которые зовёт слой (build/wolfssl/libsteer-wolfssl.map), и steer_wolfssl_abi; остальное код wolfSSL — включая TLS-стек и QUIC, включённые опциями, — в файл попадает, только если достижим от экспорта (--gc-sections). Размеры SC_HASH_CTX_SIZE, SC_AEAD_CTX_SIZE, SC_AESCTR_CTX_SIZE слоя — часть ABI между двумя файлами: контексты размещает libsteer, а заполняет libsteer-wolfssl. Их держат две проверки: при сборке библиотеки (build/wolfssl/abi.c: те же _Static_assert, что в scrypto.c) и при загрузке (sc_abi_check в scrypto.c сверяет версию wolfSSL, размеры структур и смещение поля cm хранилища корней с массивом steer_wolfssl_abi загруженной библиотеки; расхождение — строка в stderr и выход с кодом 3). С 2.1.4 net1 и tgws связаны с той же libsteer-wolfssl.so (раздел 1, «Общие библиотеки криптографии») и сверяют её так же; коннектор несёт свою копию статически. На роутере wolfSSL пакета libwolfssl не используется: в нём нет QUIC, а его SONAME несёт хеш опций.

QUIC как слой. QUIC-соединение для DoQ и hysteria2 даёт src/proto/quic — тонкая обёртка над ngtcp2: в libsteer.so — для DoQ и DoH3 резолвера, вторым экземпляром обёртки в net1 — для плагинов (сама ngtcp2 с 2.1.4 — одна, libsteer-ngtcp2.so) (hysteria2, MASQUE у warpbox). Сама ngtcp2 — выпуск с закреплёнными версией и суммой (build/ngtcp2/fetch.sh, лицензия MIT), в дереве не лежит: скрипт скачивает архив, сверяет sha256 и накладывает наши патчи (build/ngtcp2/patches). Собирается она своим рецептом build/ngtcp2/build.sh (все файлы lib/ и криптобэкенд crypto/wolfssl, build/ngtcp2/config.h вместо порождаемого configure) в статический архив с -fPIC; nghttp3 не берётся. Криптобэкенд зовёт TLS-стек и wolfSSL_quic_* из libsteer-wolfssl.so, поэтому опции wolfSSL включают QUIC, слой EVP и AES-ECB (защита заголовка пакета). Заголовки wolfSSL видят два файла: scrypto.c и src/proto/quic/qcssl.c (ngtcp2 нужен сам TLS-стек, а не примитивы); quic.c держит сокет, потоки, датаграммы RFC 9221 и таймер и wolfSSL не видит. Модель выполнения — внешняя линия событий: соединение отдаёт дескриптор UDP-сокета и срок таймера (qc_fd, qc_timeout_ms), потребитель зовёт qc_on_readable и qc_on_timer. Перегрузка по умолчанию — CUBIC; при bbr — BBR; при brutal_bps — Brutal из hysteria2, патч к ngtcp2: заданная скорость в байтах в секунду, окно bps × RTT × 2 / доля подтверждённых пакетов, без снижения при потерях. Второй патч (0002) даёт смену перегрузки на установленном соединении (qc_set_cc: Brutal с другой скоростью или BBR).

Швы для hysteria2, не меняющие остальное поведение слоя: фильтр датаграмм сокета (qc_filter, Salamander; tx_multi — один пакет в несколько датаграмм, Gecko), прыжки по портам сервера (hop_*: отправка на порт диапазона, приём с любого порта диапазона, для ngtcp2 путь остаётся один), метка сокета (sock_mark), проверка отпечатка сертификата (pin_sha256, вместо цепочки), однонаправленный поток (qc_stream_open_uni — управляющий поток HTTP/3), PING по молчанию (keepalive_ms) и ручное продление окон приёма (flow_manual, qc_stream_consumed) — обратное давление на сервер. Длина идентификатора соединения — четыре байта. Потребители — резолвер, плагины hysteria2 и warpbox и стенд tests/qcbench.c (build/libs-exports.sh).

Клиент hysteria2 в стеке туннеля. Стек (stack.c) рассчитан на связь с узлом на каждое соединение клиента, а QUIC-соединение у hysteria2 одно на рабочего. Поэтому QUIC живёт в цикле рабочего потока стека (hy2conn.c, hy2dial.c, caps = DC_INLOOP, без пула запасных сессий): сокет QUIC стоит в epoll рабочего, таймеры ngtcp2 — в его ожидании, а сессия дайлера — сам поток клиента: колбэки QUIC кладут нагрузку в очередь сессии, стек забирает указатель на неё без копии (dialer_ops.read), вверх send — это qc_stream_send. Отдельного потока QUIC нет (сверх рабочих у программы остаются поток файла состояния и слежка за узлом), пар сокетов и побудок между потоками нет. У каждого рабочего своё соединение QUIC к узлу со своими рукопожатием и авторизацией: соединение клиента живёт у одного рабочего всю жизнь (хэш пятёрки), так что поток QUIC открывает тот же рабочий. Узел видит столько соединений одного пароля, сколько рабочих; окна приёма соединений делятся поровну (но не ниже 4 МиБ на рабочего), а Brutal у каждого соединения со своей полной скоростью.

Обратное давление идёт в обе стороны. Вниз (скачивание): окно приёма QUIC продлевается только за байты, которые стек забрал из очереди сессии (qc_stream_consumed в hy2c_read; пакет с обновлением окна уходит одним на виток из loop_wait — qc_flush_credit), а очередь к медленному клиенту — цепочка блоков по 16 КиБ, память которых возвращается по мере отдачи, и не больше окна потока: 8 МиБ на поток и 16 МиБ на соединение при одном рабочем (RX_STREAM_WIN, RX_CONN_WIN в hy2conn.c; окно обязано вмещать «скорость × задержка» с запасом вдвое, а при медленном клиенте оно же — наихудший расход памяти на очереди туннеля; у каждого из N рабочих — доля 1/N, не ниже 4 МиБ на соединение). Вверх (выгрузка): окно, которое стек объявляет клиенту, — место в буфере потока QUIC (send_buf, 1 МиБ минус неподтверждённое узлом; dialer_ops.room), и освободившееся по ACK узла место возвращается клиенту обновлением окна (stack_sess_room, room_watch): клиент идёт со скоростью QUIC без подтверждений, привязанных к очереди. Остаток, который буфер всё же не принял (клиент вышел за объявленное окно), ждёт в сессии и досылается по ACK.

DNS#

Резолвер steer dnsd (src/dnsd) — ребёнок демона. Он слушает порт 5300 (DNS_PORT), и набор правил заворачивает на него DNS клиентов (prerouting_dns). Спеку резолвер под демоном не читает: таблицу доменных каналов — набор, режим, семейства, файлы списков (src/dnsd/tabfmt.h) — демон пишет ему в трубу (--table-fd) при старте и после каждого изменения, и резолвер меняет её без перезапуска. Без трубы резолвер читает спеку сам.

  • Имя вне правил уходит к апстриму как есть: на роутере — 127.0.0.1:53 (dnsmasq), на телефоне — туда, куда шёл запрос клиента (адрес из conntrack, --upstream-origdst). С dns.other — к его серверу или группе тем же dup_ask, что у канала; имена своей сети (name_local в src/dnsd/proxy.c: без точки, lan, local, home.arpa, обратные зоны …) остаются на прежнем пути. Нет ответа или SERVFAIL/REFUSED — вопрос уходит прежним путём (forward_old, тот же код, что у обычного имени вне правил); отказ без ответа ставит паузу (struct dpause, src/dnsd/dup.h), и на её время имена вне правил идут прежним путём сразу.
  • Имя под правилом в режиме fake-IP получает поддельный адрес из 198.18.0.0/15 (IPv6 — fdfe:dcba:9876::/96, раздел 4б); подмена ставится в карту ядра раньше ответа клиенту, а адрес — в набор канала. Раздача хранится в <каталог состояния>/fakeip.state: файл пишет фоновый поток через секунду после изменения; строки с негодным именем, с поддельным адресом, уже выданным другому имени, или с адресом пула на месте настоящего при загрузке отбрасываются, и файл переписывается без них. Пул не растёт и не берётся из спеки: диапазон зашит в правила nft и в пару IPv6. Когда выдача доходит до края (131070 адресов), имена, которых не спрашивали дольше 1800 с (--fakeip-idle) и на чей адрес нет живых соединений в conntrack, возвращают адрес (fakeip_reclaim, src/dnsd/fakeip.c): он снимается из наборов и карт, файл состояния переписывается, свободные адреса идут по кругу. Нет conntrack — решает один срок простоя. Пул кончается, лишь когда все адреса заняты недавно спрошенными или держащими соединения именами, — об этом строка в журнале с числом адресов, а новое имя под правилом получает SERVFAIL, не настоящий адрес мимо выхода. За одним клиентом (адрес IPv4 или /64 IPv6; петля — без предела: за ней пересыльщики всей сети) не больше восьмой части пула, 16384 адресов: у предела он сначала возвращает свои простоявшие имена, а если нечего — его новые имена под правилами получают SERVFAIL, у остальных клиентов всё как прежде. Имя вопроса с байтом 0, точкой, пробелом или управляющим символом внутри метки не матчится правилами, не кэшируется и поддельного адреса не получает: вопрос уходит наверх как есть, ответ — клиенту без изменений. Таблица ожиданий резолвера (1024 вопроса по 5 с) делится так же: у клиента не больше 128 мест (петля — тоже без доли), и его новый вопрос сверх них вытесняет его же самый давний. Настоящий адрес под поддельным не меняется, пока именем пользуются (fakeip_real_pick): если его нет в свежем ответе (сети доставки ротируют ответы), он остаётся — замена увела бы сеанс QUIC, молчавший дольше записи conntrack о потоке UDP, на другой сервер. Заменяется он, когда имя спросили после десяти минут простоя или когда его нет в ответах полчаса; от conntrack правило не зависит. Ответ апстрима из одних пустых адресов (0.0.0.0, :: — имя заблокировано фильтрующим сервером) клиенту уходит пустым адресом, поддельный не выдаётся, а стоявшее под именем снимается (fakeip_entry_blocked). В режиме real-ip клиент получает настоящий ответ, а адрес ложится в набор канала со сроком ответа; эти элементы резолвер помнит в памяти (src/dnsd/realip.c) и возвращает после каждой замены набора правил.
  • Сокеты резолвера в каталоге состояния: dnsd.sock — журнал имён для dns-log; dnsd-ctl.sock — просьбы демона и загрузчика набора правил: подхват нового демона, down, reassert (вернуть элементы real-ip), flush (записать fakeip.state перед засевом) (src/dnsd/adopt.c).
  • Апстрим канала (dns.upstreams, dns у правила, dns.upstream, dns.other; ключи — docs/spec-v2.md). Канал — это набор nft, режим и апстрим; демон кладёт апстримы, которыми пользуются каналы и dns.other, в ту же таблицу: заголовок N U кэш min max neg [other], после строк каналов U строк имя|адрес|выход|метка|адреса|bootstrap[|frag] (frag — fragment: true, поле есть только у включённых), у канала последнее поле dns:<номер>; седьмое число заголовка — номер строки апстрима dns.other (только когда он задан). Группа серверов — строка имя|group:race|-|0|1,2,3|- (или group:failover): члены — номера строк апстримов, они стоят в таблице раньше группы. Без апстримов и кэша таблица — прежняя, N и строки каналов, байт в байт.
  • Группа серверов (src/dnsd/dupgrp.c) — для резолвера один апстрим: dup_ask по её номеру даёт ровно один обратный вызов — первый годный ответ члена (не SERVFAIL и не REFUSED) или отказ. race спрашивает сразу всех без паузы; failover — по порядку, с паузой отказавшего члена и вопросом следующему по отказу или через 1,5 с молчания (350 мс, когда у члена нет готового соединения — dup_warm); вместе с членом, не ответившим годно после паузы, сразу спрашивается следующий. Пауза отказавшего — у обоих режимов; когда на паузе все, вопрос уходит одному, наименее плохому. Следующий член спрашивается из dup_tick, а не из обратного вызова прежнего: тот приходит изнутри разбора соединения. Вопрос группы живёт в куче, пока не вернутся все принятые вопросы членов. Имя под правилом с апстримом уходит только туда (src/dnsd/dup.c): UDP, TCP, DoT (кадры с длиной в два байта по одному соединению, вопросы вперемешку, номер транзакции свой на апстрим), DoH (POST application/dns-message; в ALPN «h2, http/1.1», протокол выбирает сервер. HTTP/2: одно соединение на апстрим, вопрос — поток, число одновременных потоков — то, что объявил сервер (SETTINGS_MAX_CONCURRENT_STREAMS, до его SETTINGS — 100), ответ на GOAWAY — потоки за last_stream_id уходят на новое соединение; кадры и HPACK — src/dnsd/doh2.c, таблица заголовков у сервера нулевая. HTTP/1.1: keep-alive, соединение на каждый ожидающий вопрос, пока хватает дескрипторов — четверть RLIMIT_NOFILE, на каждом один вопрос за раз; ALPS из ClientHello DoH убран) и DoQ (RFC 9250, quic://: одно соединение QUIC на апстрим, вопрос — свой двунаправленный поток с кадром «длина, сообщение с номером 0» и FIN, ответ сопоставляется по потоку; кадры и коды — src/dnsd/doq.c). Сокеты — в epoll резолвера, неблокирующие, срок вопроса 4 с, простаивающее соединение закрывается через 5 минут; обрыв соединения под вопросом — один повтор на новом, дальше SERVFAIL; после неудачи следующая попытка — через 1, 2, 4 … 30 с, всё это время вопросы получают SERVFAIL сразу. Рукопожатие TLS блокирующее, поэтому соединение устанавливает короткий поток (dupdial.c: bootstrap, connect, tls13_handshake_auth) и отдаёт циклу готовый сокет; поток заводится на соединение, не на вопрос. Рукопожатие QUIC неблокирующее: поток dupdial.c только находит адреса сервера, а qc_open, события сокета и таймер обёртки src/proto/quic ведёт цикл резолвера (dup_wait_ms учитывает qc_timeout_ms); контекст TLS с корнями — один на процесс. Соединение DoQ, не подавшее ни пакета за 1,5 с после отправленного вопроса, считается мёртвым: оно пересоздаётся, вопрос уходит на новом. Соединение QUIC держится с PING раз в 15 с (keepalive_ms шва dupq.h); молчавшее дольше 17 с до вопроса ждёт ответа 400 мс, молчащее 20 с без вопросов закрывается. За соединениями TCP следит ядро (conn_tcp_watch: TCP_USER_TIMEOUT 1,5 с и SO_KEEPALIVE с пробой через 15 с), обрыв приходит событием сокета. Билеты сессии (кэш qc_tls в src/proto/quic/quic.c, по записи на сервер, память процесса) дают рукопожатие по PSK и 0-RTT: пока рукопожатие идёт, pick_conn берёт соединение с dupq_early_ready и вопрос уходит в early data; отвергнутый 0-RTT (on_early_rejected) возвращает вопросы в очередь, попытка не тратится; счётчики early и early_rejected — в dns-log. TLS и обёртка QUIC берутся из библиотек ядра слабыми ссылками: сборка без них работает, а DoT/DoH (без TLS) и DoQ (без QUIC) в ней отказывают. DoH по HTTP/3 (h3://, RFC 9114) идёт тем же соединением и тем же швом dupq.h (ALPN h3, нового кода QUIC нет, ngtcp2 в ядро не добавляется): вопрос — двунаправленный поток с запросом HEADERS + DATA, ответ собирается по FIN; кадры, целые переменной длины и QPACK по статической таблице (своя динамическая — 0, потоки кодировщика и декодировщика не открываются) — src/dnsd/doh3.c; поток управления с SETTINGS открывается по завершении рукопожатия (quic_after), 0-RTT не берётся.
  • Путь запроса. Сокет апстрима «через выход» метится меткой выхода (та же, что у сокета туннеля over, marks.h, плюс на телефоне бит собственного трафика туннеля), «напрямую» — без метки на роутере и меткой «само ядро steer» на телефоне. Метку в таблицу кладёт демон из реестра; у резолвера без демона её нет, и апстрим «через выход» не используется. Правило ip rule ведёт помеченный пакет в таблицу выхода, postrouting_guard (в него попадают и выходы, названные в dns) не пускает его в другое устройство. Bootstrap идёт с той же меткой.
  • Кэш (dns.cache, src/dnsd/dcache.c): только ответы на имена под правилами и, с dns.other, на имена вне правил (ответы его сервера), NOERROR и NXDOMAIN, ключ — апстрим, имя без регистра, тип. Срок — наименьший TTL, зажатый пределами cache_ttl; TTL в самом ответе зажат так же и уменьшается на возраст, поэтому адрес real-ip в наборе и у клиента кончается одновременно. Ответ из кэша идёт через тот же upstream_answer, что ответ по сети: подмена fake-IP ставится в ядро раньше ответа клиенту, ответа «из пула сразу» нет. Кэш сбрасывается при каждой новой таблице.
  • steer dns-log кроме имён (у каждого — сервер, которым оно спрашивается, dns) отдаёт upstreams (состояние, счётчики, последняя ошибка; у группы — режим, члены и их паузы), cache и other (docs/ctl.md).

Команды и файлы состояния#

Команда описана строкой таблицы CMDS[] в src/cli/cli.c (флаги, справка, проверка аргументов), а вызывается цепочкой сравнений в main() (src/daemon/main.c). То, чего в сборке может не быть, объявлено там же слабыми ссылками и отвечает штатным отказом (правило 3); команды плагинов (steer.commands[] манифеста) ищет реестр плагинов (plugin_cmd_find). Инструменты, на которые отвечает steer-tools, — TOOLS[] в src/daemon/main.c (fit, srs-read, sub-hwid, dev-id, xsteer-hub, dnsd-table) и команды плагинов.

Файлы ядра (пути платформы — src/platform/openwrt.c и android.c):

Где Файл Что
каталог спеки (/etc/steer, телефон — /data/misc/steer) spec.json или spec.yaml спека
select выбор групп pick: manual; пишется только при смене выбора
steer.sock управляющий сокет демона
каталог состояния (/var/lib/steer, на роутере tmpfs; телефон — /data/misc/steer/state) registry реестр меток и таблиц выходов
fakeip.state раздача fake-IP резолвера
active, latency, restart-* память сторожа между проходами у steer failover; демон держит её в памяти, active пишет при изменении
status.json снимок status для status --fast
probe-<выход>, xsteer-<имя>.json ход перебора узлов и состояние клиента xsteer — только у помощника без трубы событий демона
awg-devices, awg-<устройство>.hs, awg-<устройство>.sig, dnsd.sig устройства awg, которые завело ядро; замер awg одиночного прохода; подписи, по которым решается, перенастроить ли устройство awg и хватит ли резолверу SIGHUP
dnsd.sock, dnsd-ctl.sock сокеты резолвера
plugin/<id>/<выход>.status.json состояние выхода, которое пишет программа плагина (plugin.state в status)
restart просьба init-скрипта на время restart: резолвер оставить новому демону
временный каталог (/tmp, телефон — /data/misc/steer/tmp) steer-ruleset.rejected последний набор правил, который отверг nft, — для разбора; следующий отказ его перезаписывает
каталог плагинов (/usr/lib/steer/plugins) <id>/ установленные плагины: plugin.json, программы, схемы, файлы nft
/etc/steer/plugins state.json, repos.d/, keys/, platform.env состояние менеджера (что стоит, включено ли, автообновление), добавленные репозитории и их ключи, просьбы плагинов к службе ядра (steer.platform)
/usr/share/steer seed/, keys/ семя (подписанный индекс и архивы плагинов из пакета ядра; архивы стоящих плагинов снимаются после установки) и открытые ключи официальных репозиториев

Что переживает sysupgrade, перечисляют files/lib/upgrade/keep.d/steer (спека, выбор групп, подписки, свои списки, файлы awg и xsteer) и files/lib/upgrade/keep.d/steer-plugins (каталог плагинов и /etc/steer/plugins).

3. Спека v2#

Свой формат под ядерную модель steer, а не разделы sing-box. YAML читается через libyaml из дерева (src/third_party/libyaml); JSON — тоже YAML, и спеку v2 можно записать JSON-объектом с "version": 2. Ключ version: 2 отличает формат от спеки v1 — JSON со schema: 1 или schema: 2 (docs/contract-v1.md), которую переводит src/model/v1.c.

Полная форма формата — ниже. Всё, что в ней есть, разбор принимает и проверяет; то, чего ядро ещё не выполняет (здесь — app клиента, встроенные domains/prefixes списка), отвергается отказом «ещё не поддерживается в этой версии ядра steer: …» после всех настоящих проверок. Что ядро принимает целиком, показывает пример docs/spec-v2.md; там же все ключи, умолчания и отказы.

version: 2

lan: { devices: [br-lan] }            # кто наши клиенты по умолчанию

clients:                              # именованные группы клиентов
  kids: { mac: [aa:bb:cc:dd:ee:01] }
  tv:   { addr: [192.168.1.50] }
  tg:   { app: [org.telegram.messenger] }      # только на телефоне

lists:                                # что: назначения
  youtube: { srs: lists/youtube.srs }
  work:    { domains: [corp.example], prefixes: [10.20.0.0/16] }
  voice:   { prefixes_file: lists/dc.lst, proto: udp, ports: [50000-65535] }

outputs:                              # куда
  wg0:  { kind: interface, device: wg0 }
  wg1:  { kind: interface, device: wg1 }
  nl:   { kind: tunnel, protocol: vless, subscription: sub/nl, nodes: [3, 5],
          transport: ws, over: wg0 }
  dpi:  { kind: block }
  res:  { kind: group, pick: order,   members: [wg0, wg1], on_fail: drop }
  eu:   { kind: group, pick: manual,  members: [nl, res], default: nl }
  bal:  { kind: group, pick: balance, members: [nl, wg1] }

dns:
  mode: fakeip                        # умолчание
  cache: 2048
  upstreams:
    nl-doh: { url: https://1.1.1.1/dns-query, out: nl }

rules:                                # сверху вниз, выше — сильнее
  - { name: yt,   for: [kids, tv], to: [youtube], out: dpi, resolve: realip }
  - { name: work, to: [work, voice], out: eu, dns: nl-doh }
  • Правило только ссылается на имена: for — клиенты (по умолчанию lan), to — списки, out — выход или группа. При пересечении правил побеждает то, что выше, а нижнее не отбрасывается.
  • over — подложка туннеля, выход, через который идёт трафик самого туннеля (в спеке v1 — via).
  • У interface в v2 одно устройство: резерв из нескольких устройств — группа pick: order.
  • Формат — по содержимому, а не по имени файла. Текст с { — JSON: version наверху — v2, иначе v1 с отказами v1; остальное — YAML, то есть v2. Файл по умолчанию — {etc}/spec.json или {etc}/spec.yaml; лежат оба — отказ «две спеки».
  • Неизвестный ключ и ключ чужого вида — отказ, каждый отказ — файл:строка:столбец. Ссылки по именам проверяются, круг в группах и в over — отказ.
  • Ключи видов ядра разбирает сам вид (kind_ops.parse над struct out_keys — один разбор на оба формата): conf у awg; obfs: { mode, server, listen } у interface; strategy у вида DPI recheck (v1 opts_file); ipv6 и prefix у выходов с IPv6 (раздел 4б). Ключи видов плагинов проверяются по схеме вида из манифеста (steer.kinds[].keys, например plugins/vless/kinds/vless.schema.json): у kind: tunnel, protocol: vless — subscription (v1 sub_file), nodes, transport; у xsteer — conf, stream, stream_port; у tgws — domain. kind: vless в спеке v2 — отказ с подсказкой «пишется kind: tunnel, protocol: vless»; kind: zapret — отказ с заменой (модуль DPI recheck или kind: direct).
  • Относительный путь — от каталога файла спеки (lists/youtube.srs рядом со спекой в {etc}), а не от рабочего каталога процесса.
  • steer spec convert печатает спеку v2 из спеки v1 (src/model/v2print.c); напечатанное даёт тот же набор правил до байта.
  • steer spec-schema [--json] печатает схему спеки v2 (src/model/v2schema.c) по таблицам ключей разбора (src/model/v2keys.c), реестру видов и реестру плагинов — spec-schema.md.

Во что спека разбирается — раздел 4в.

4. Проверка изменений#

  • Юнит-стенды. Модуль линкуется со стендом сам, без #include чужого .c и setjmp; общий каркас — tests/unit.h. Стенды не включают .c из src/model, src/compile, src/lib, src/daemon, src/dnsd; число стендов, которые включают исходники из src (протоколы, туннель, awgmatch), не растёт — это держит храповик tests/buildmatch.sh.
  • Снимок генератора (tests/snapshot.sh, tests/golden/ruleset, входит в make test) — вывод apply --dry-run со stderr и кодом выхода по всем спекам стендов tests/gen.sh, tests/androidmatch.sh и tests/tgwsmatch.sh, для обеих платформ. Изменение, которое не должно менять набор правил, обязано совпасть с ним байт в байт; перезапись — make snapshot-record, только вместе с намеренным изменением набора правил. Спека v1 и её перевод в v2 дают один набор правил (tests/v2match.sh).
  • Интеграция в сетевых пространствах (стенды *.sh с root): демон, резолвер, туннель и сторож на хосте, пакет клиента реально уходит в нужный выход, упавший выход переключается.
  • make ext-test — стенды расширенной части на настоящем wolfSSL той же версии и с теми же опциями, что в сборке (tests/ext-test.sh).
  • tests/buildmatch.sh — согласие сборочных списков, правила раздела 2, контракт журнала, упаковка, keep.d и идентификаторы проверок diag против docs/contract-v1.md.
  • Стенд роутера в QEMU — поведение на настоящих procd, fw4 и netifd.

4а. Демон steerd#

Демон — хозяин состояния ядра: спека и группы в памяти, сторож выходов, дети-помощники и резолвер, сокет управления с событиями. Флаги: --watch (сторож), --supervise (дети), --apply (применить спеку при старте). Устройство сокета, команд и событий — docs/ctl.md.

Сокет и протокол. Протокол управляющего сокета v1: строка запроса с телом по длине, ответ — один объект JSON одной строкой; subscribe оставляет соединение открытым и шлёт события строками JSON (src/daemon/ctl.c). status, diag, explain, conns, dns-log демон отвечает из памяти и по ядру в своём процессе: nf_tables и маршруты — по netlink (src/lib/nftdump.c, src/lib/rtnl.c), резолвер и обфускатор — обходом /proc (src/lib/procscan.c). Изменяющие команды (apply, check, reload, rm-file) идут по одной, в очереди; проверка и компиляция — в детях демона, поэтому остальные команды отвечают и во время apply. Неудавшееся применение спеки при старте демон повторяет сам — через 5 с, с удвоением паузы до 5 минут.

Цикл событий (src/daemon/loop.c). Один epoll: слушающий сокет и соединения, signalfd (SIGCHLD, SIGHUP, SIGTERM), таймеры (timerfd, CLOCK_MONOTONIC), сокет rtnetlink событий сети (ссылки и адреса) — они будят сторожа, сокет стража правил и трубы событий от детей. Опроса по кругу нет.

Абсолютные монотонные миллисекунды цикла, супервизора помощников, проб и окон защиты от повторных сверок хранятся в int64_t, включая deadline/cache поля потребителей. Это устраняет переполнение 32-битного long после примерно 24,9 дня uptime. Относительный API loop_timer_set(long) сохранён; сложение внутреннего срока насыщается. tests/clock64match.c проверяет переходы через INT32_MAX/UINT32_MAX с подставленными часами без изменения системного времени; эта проверка должна запускаться и настоящей ILP32-сборкой, не только на LP64.

Проход без fork. Проход сторожа (src/daemon/failover.c) — конечный автомат на цикле событий: пробы (неблокирующий TCP connect и эхо ICMP, привязанные к устройству), ожидание подъёма устройства (таймер шага и события netlink), команды оживления (ifdown/ifup, ubus — ребёнок на действие) и разрешение имён (рабочий поток src/daemon/gaiw.c) ждутся шагами автомата, а не синхронно. Тот же автомат крутят демон (watchd.c) и одиночный steer failover. Молчание устройства, которое несёт трафик выхода, — приговор не одного прохода: серия из трёх проходов, счётчик принятого устройством и путь наружу у самого роутера (failover.c, «СОМНЕНИЕ»; расписание — docs/ctl.md, «Сторож выходов»). Сверка маршрутизации читает ядро по rtnetlink, поэтому проход по исправной спеке не запускает ни одного процесса; процесс появляется только на действие. Во время прохода демон отвечает на запросы.

Состояние в памяти (src/daemon/state.c, watchd.c): спека и группы, отпечатки применённого, по выходу — активное устройство, серия, серия молчания устройства, задержка, здоровье, время оживления; дети; подписчики. Где та же память лежит файлами (у steer failover и помощников без демона), — «Команды и файлы состояния» в разделе 2; шов между файлами и памятью — src/daemon/fostate.h.

Дети и здоровье (src/daemon/supd.c, helpers.c). Помощник получает дескриптор трубы (STEER_EVENT_FD) и пишет в неё события строками JSON (src/lib/evline.h): up (с полем dev — устройство, которое поднял этот процесс), down с причиной, node, health. Без дескриптора (ручной запуск, стенды) помощник работает сам по себе и пишет свои файлы состояния. Порядок подъёма по over, перезапуск с растущей паузой, подпись параметров «надо ли перезапускать» — одним кодом для демона и steer supervise. Маршрут выхода к устройству помощника ставит демон: по первому up с dev за жизнь процесса он привязывает таблицу выхода к устройству (bind_device) в своём процессе; следующие up маршрут не трогают, после down и выхода процесса решает сторож (on_fail). Без демона маршрут выхода к устройству помощника не привязывает никто. Клиент VLESS (и протоколов прокси) сам следит за своими активными узлами (src/tunnel/pool.c), и сторож принимает его up и down без своей пробы.

Apply-сверка (src/daemon/recon.c). apply и reload строят план новой спеки в ребёнке (apply-plan: проверки dry-run и отпечатки частей) и применяют только изменившиеся части (apply-commit): набор правил, маршрутизацию выходов, помощников, таблицу резолвера. Отпечаток набора правил считается по тексту без засева из файла состояния резолвера. Неизменная спека не запускает ни nft, ни ip.

Сверка с ядром. То же apply и reload сверяют с ядром и применённое: номер и отпечаток наших таблиц (nfd_table_fp: цепочки, правила по порядку, заголовки наборов — без счётчиков и элементов), сводку элементов статических наборов (сумма перемешанных хэшей, снимает ребёнок-план), правило fwmark и таблицу каждого выхода. Ожидаемое снимает сам ребёнок apply-commit сразу после своего nft -f. Демон с --watch сверяет номер и отпечаток таблиц ещё и перед каждым проходом сторожа — без процессов и без элементов; расхождение ставит в очередь reload, не больше трёх за пять минут (docs/ctl.md, «Сверка с ядром»).

Страж правил (src/daemon/rulewd.c, с --watch). Правила fwmark выходов живут вне нашей таблицы, и их снимают чужие (netifd на своём старте, netd на телефоне, ip rule flush). Страж слушает снятие правил IPv4 и IPv6 и запасного запрета в таблицах IPv6 выходов и возвращает их сам, одним сообщением rtnetlink; своё снятие он отличает по таблице IPv4 выхода. Сторож ещё и замечает пересозданное устройство раздачи и ставит сверку набора правил, возвращая на него цепочку ingress_mark (docs/ctl.md, «Страж правил выходов»). Пока правила нет, помеченный пакет не уйдёт в чужое устройство: его отбросит postrouting_guard.

dnsd — ребёнок демона на таблице от него (раздел 2, «DNS»). Демона резолвер переживает: закрытая труба — «демона нет», он отвечает по последней таблице и ждёт нового демона (--orphan-timeout, по умолчанию 60 с); новый демон на том же каталоге состояния забирает его через dnsd-ctl.sock новой трубой (src/dnsd/adopt.c). Резолвер другой сборки (после обновления пакета его бинарник заменён) новый демон не забирает, а гасит и поднимает свой. steerd down без демона просит его выйти тем же сокетом. Если stderr резолвера сломан (читателя нет), строки журнала уходят в /dev/log с заголовком syslog.

Бинарники. steerd — всё ядро одним файлом. steer (src/client/main.c, CLIENT_SRC в build/sources.mk) — клиент: команды демона (status, diag, explain, conns, dns-log, select, apply без --dry-run, reload, subscribe) шлёт в сокет и печатает stdout, stderr и код из ответа; всё остальное — и любую команду, когда демона нет или он обслуживает другую спеку (сверка по version), — отдаёт steerd через execv с теми же аргументами. steerd клиент берёт из STEER_ENGINE или рядом с собой. steer-tools — ссылка на steerd: под этим именем (argv[0]) ядро отвечает только на инструменты. Подробно — docs/ctl.md, «Клиент steer».

Выключенное ядро (телефон, свойство persist.der.steer.enabled): ни таймеров сторожа и стража правил, ни снимка status, ни сокетов событий сети — демон не просыпается сам. Положение выключателя ему сообщают apply, reload и SIGHUP. wakelock демон не берёт.

4б. IPv6#

Семейство — свойство строки списка и адреса клиента; у выхода и группы — бит KC_IPV6. Его несут interface, awg и туннели ядра с протоколом (vless, hysteria2, прокси: стек src/tunnel несёт IPv6 и по TCP, и по UDP) и группа, все члены которой его несут; у xsteer и tgws его нет.

  • Списки. Строка списка классифицируется по семейству (spec_line_family: 4, 6 или 0 — имя). Строки IPv6 из файлов и подсети IPv6 из .srs идут в парный набор группы <имя>6 (ipv6_addr; у составной группы — ipv6_addr . inet_proto . inet_service). Набор заводится, только когда у группы есть элементы IPv6 или у доменной группы есть половина IPv6 (dom6). steer fit пропускает строки IPv6 как есть: не сливает и в бюджет не считает.
  • Правила. У правила группы — v6-двойник в той же цепочке: то же «кто», сужение, поиск в <имя>6 (или «весь трафик»), та же метка и тот же комментарий, поэтому счётчик канала остаётся одним числом (counters_load складывает правила с одним именем). «Кто» по устройству и по MAC — одно выражение на оба семейства; адреса — ip saddr для записей IPv4 и ip6 saddr для записей IPv6. Клиенты по умолчанию из одних подсетей IPv4 узнаются для IPv6 по устройствам. Клиент правила из одних адресов IPv4 по IPv6 не узнаётся (diag: ipv6_clients).
  • Маршрутизация. Выход с устройством и KC_IPV6 получает ip -6 rule fwmark <метка>/<маска> table <таблица> с той же меткой и тем же номером таблицы и маршрут в устройство в таблице IPv6. В таблице IPv6 всегда лежит запасной запрет prohibit (table_bh_type, src/daemon/failover.c): ядро сразу отвечает клиенту «administratively prohibited», и клиент переходит на IPv4, а не ждёт таймаута; у IPv4 запрет — blackhole. Сторож и страж правил сверяют и возвращают оба семейства. masquerade IPv6 на роутере — дело зоны fw4 (masq6), на телефоне его ставит ядро steer (ip6tables).
  • Проба сторожа — по IPv4: здоровье туннеля — здоровье его транспорта и пира, у семейств оно общее.
  • Выход без IPv6. IPv6 его правил метится, но правила ip -6 rule у метки нет, и цепочка forward_v6 отвергает такой пакет (reject with icmpx type admin-prohibited): клиент с двумя стеками сразу переходит на IPv4. В prerouting reject ядро не принимает, а drop задел бы трафик к самому роутеру. На телефоне для каналов на само устройство — reject в output_mark. diag: ipv6_output.

Резолвер. - Есть ли у доменного правила IPv6 — одно решение на компилятор и резолвер, dom6_ok (src/model/parse.c): выход несёт IPv6 или метки не ставит (direct), «кто» выражается для IPv6 (клиенты — устройства, MAC, адреса IPv6 или клиенты по умолчанию). Резолвер получает решение полем семейства в таблице каналов. - Ответ на AAAA. Имя под правилом получает адрес, только если IPv6 есть у всех совпавших каналов (dch_all_v6); иначе — пустой ответ. Спека v1 после перевода в модель отвечает так же, как v2. HTTPS и SVCB для имён под правилом гасятся. - fake-IP v6. Пул fdfe:dcba:9876::/96 (FAKEIP6_NET); поддельный IPv6 — пара поддельного IPv4 той же записи в младших 32 битах (fakeip6_of), поэтому выдача одна на оба семейства и хранить поддельный IPv6 не нужно. Карта fakeip6 и правило dnat ip6 to ip6 daddr map @fakeip6 в prerouting_dnat; отказ карты — пустой AAAA. - real-ip v6. Настоящие AAAA — в <имя>6 каналов real-ip со сроком ответа. - fakeip.state — строка «домен, поддельный, настоящий, настоящий IPv6»; на месте настоящего IPv4 — «-», если его нет; запись без IPv6 пишется формой из трёх полей. - explain принимает адрес IPv6 и у поддельного адреса обоих семейств называет имя.

IPv6 от хоста (ключ ipv6: routed | nat | off у выхода спеки v2, docs/spec-v2.md). Хост — сервер на том конце туннеля WireGuard, у которого IPv6 есть; роутер получает IPv6 внутри туннеля. - Модель. enum out_ipv6, struct v6pfx и v6_denied у struct output (spec.h). Кому снять IPv6, решает spec_v6_resolve один раз после разбора: off и все выходы рядом с донором, кроме донора и nat; у них снимается KC_IPV6, и всё, что спрашивает «несёт ли выход IPv6», видит один ответ. На телефоне routed и nat действуют как отсутствие ключа (out_ipv6_mode), off действует. - Набор правил. Набор v6donor с префиксом хоста; последнее правило разметки — всё несовпавшее из префикса, кроме назначений в самом префиксе, ULA, link-local и multicast, — в донора; в forward_v6 — запрет источника из префикса мимо устройств донора и раздачи и ULA-источника в донора; донор — и в postrouting_guard. nat — цепочка postrouting_nat6 с masquerade IPv6 на устройство выхода. - Префикс без prefix: (v6donor_derive, failover.c) выводится по ядру: нуль-маршрут unreachable P, который netifd ставит на раздаваемый префикс, над глобальным адресом устройства раздачи; префикс провайдера отличает маршрут default from P через чужое устройство. Кандидат ровно один — префикс донора, иначе не угадывается. Сторож в конце каждого прохода сверяет набор v6donor с ядром и переписывает элементы одной транзакцией (nfv_ranges6_write, src/lib/nftvmap.c). - diag (ipv6_host): чего не хватает в /etc/config/network и /etc/config/dhcp (только чтение) и проба эхом ICMPv6 через выход.

4в. Модель v2 и группы#

Одна внутренняя модель — модель v2 (src/model/spec.h). Компилятор, резолвер, сторож и status работают с ней. Спека v2 разбирается в неё напрямую (src/model/v2.c), спека v1 — переводчиком src/model/v1.c; load_spec (parse.c) выбирает формат по содержимому, сквозные проверки обоих форматов — src/model/check.c. Сущности: - struct spec_client — кто: адреса, MAC, self/uid на телефоне; sp->lan — клиенты по умолчанию; - struct spec_list — что: файлы префиксов и доменов, .srs, сужение proto/ports, all — весь трафик; - выходы — struct output с видами из src/kinds, в том числе group; - struct spec_rule — «кто → что → куда»: клиенты и списки номерами, выход по номеру, режим DNS, область device, выключенность. Порядок правил — приоритет.

Несколько клиентов или списков у правила разбор сводит в одного клиента или один список, когда смысл не меняется: компилятор берёт у правила одного клиента и один список.

Перевод v1. Канал становится правилом с безымянными клиентом и списком; выход interface с devices из нескольких устройств — группой pick: order (или latency) из безымянных членов-интерфейсов по одному на устройство. Безымянные члены лежат в sp->out за именованными, поэтому реестр, status, помощники и правила видов их не видят; группа видна снаружи прежним видом и именем, с прежними меткой и таблицей. via становится over. У steer spec convert члены пула получают имена <пул>.<устройство> и становятся обычными выходами со своими метками и таблицами.

Группы (src/kinds/group.c, struct group_cfg): у группы свои метка и таблица, члены — любые выходы с устройством, в том числе группы. Ключи и умолчания — docs/spec-v2.md. - Члены спеки v2 — выходы со своим приговором. Группа своих устройств не пробует: жив ли член — приговор его прохода в том же обходе, лист — выбранное им устройство. Обход — по зависимостям (over и члены раньше группы, fog_order в src/daemon/fogroup.c). Безымянные члены пула v1 пробуются, как устройства пула. - До первого прохода (после старта и перезагрузки) apply и status решают за группу так же, как решил бы проход, только без проб: fog_pick_known — последний приговор члена и наличие устройства. - order — первый живой член; возврат на предпочтительный — после нескольких проходов подряд. - latency — замер как urltest sing-box (src/daemon/urltest.c): GET к url через члена, время до первого байта ответа 204 или 200. Через именованного члена — сокет с его меткой (SO_MARK), то есть ровно путь трафика группы; безымянному члену пула — SO_BINDTODEVICE. HTTP — неблокирующий сокет в цикле демона, HTTPS — рабочим потоком src/proto/tls/urltls.c: он есть в steerd пакета роутера и в полном статическом бинарнике (профили extended и android); в базовой сборке https:// отвергает разбор. Замер — по IPv4, а у группы спеки v2, все живые члены которой несут IPv6, ещё и по IPv6; выбор один на оба семейства — по худшему из двух (src/daemon/folat.c). У демона замер идёт своим таймером группы на её interval и зовёт внеочередной проход, только если выбор меняется. Без трафика через группу дольше idle_timeout (по счётчикам правил каналов) запросов нет. Выбор — group_latency_pick: самый быстрый из ЖИВЫХ, а из не хуже него на tolerance — первый по порядку (допуск 0 — настоящий ноль, group_tolerance_ms); у члена, которого нет в живых, замер в счёт не идёт. Замер, не давший ответа ни у кого, оставляет группу «по порядку» — ядро говорит это строкой в журнале и в status (why), а повтор замера у члена без ответа идёт раньше срока (FOLAT_RETRY_S). - manual — член, выбранный командой select <группа> <член> без apply: маршрут таблицы группы сразу на лист члена. Выбор хранится в файле select рядом со спекой (steer_keep_dir). Выбранный член не работает — on_fail группы, другой член не берётся. - balance (src/compile/balance.c) — правило канала переходит в цепочку bal_<таблица>: там восстановление по метке соединения (соединение остаётся на своём члене), затем numgen random mod 120 vmap @balmap_<таблица> и запасной переход в метку самой группы. 120 слотов (GROUP_BAL_SLOTS), а не mod <живых>: уход члена меняет только элементы карты, которые сторож переписывает одной транзакцией nf_tables (src/lib/nftvmap.c); веса — доли слотов. numgen random, а не jhash по кортежу: постоянство соединения держит метка соединения, а хэш по кортежу при смене карты переносил бы установленные соединения. Если хоть один член не несёт IPv6, IPv6 группы уходит в метку самой группы, и forward_v6 его отвергает. - balance с by: site / site_client — вместо numgen по правилу на семейство: meta nfproto ipv4 jhash ip daddr mod 120 seed 0x<таблица> vmap @balmap_<таблица> и то же с ip6 daddr (у site_client — ip saddr . ip daddr). Карта, метка соединения и сторож — те же; хеш выбирает слот, то есть член, для сайта, а не для соединения. Семя — номер таблицы группы: без семени ядро берёт случайное на каждое правило (сайты тасовались бы с каждым apply), и у каждой группы оно своё (вложенная balance с тем же семенем получала бы только «свои» слоты внешней и отдавала бы их одному члену). Раскладка слотов (group_balance_slots) — основная при всех живых; когда член лёг, живые сохраняют свои слоты основной раскладки и добирают долю только слотами ушедших, поэтому сайты живых не переезжают от чужого отказа, а вернувшийся получает свои назад. - Закрепление у order и latency (группа с именованными членами, group_carded) — та же цепочка bal_<таблица> с восстановлением по метке соединения, но карта из одного слота (numgen inc mod 1 vmap @balmap_<таблица>) — текущий член. Сторож при смене члена переписывает только этот слот (fog_balance_sync): новые соединения идут на выбранный член, установленные доживают на своём, пока тот жив; записи conntrack снимаются только у умершего члена (его проход, on_fail члена). Таблица самой группы по-прежнему ведёт в текущий лист: её метку несут сокеты роутера (over, апстримы DNS) и запасной путь цепочки. manual не закрепляет (выбор человека переводит всё), пул v1 — тоже (у безымянных членов нет своих меток). - Вложенность. order, latency и manual разворачивают выбор до листа; у balance вложенная группа — один член со своей меткой и весом, а вложенная balance — переход в её цепочку. balance членом группы order, latency или manual — отказ разбора. - status — объект group у выхода-группы спеки v2 и умение groups (docs/contract-v1.md, §2); события switched у групп — с полем member (docs/ctl.md).