Спецификация v1. Хозяин плагинов — ядро steer: менеджер живёт в steer-core (решение В1), команды —
steer plugin … и команды сокета plugin-* (steer-api.md).
.s2p — tar (ustar, POSIX.1-1988) в одном потоке gzip. Распаковывает менеджер сам: inflate —
puff из libsteer (steer/src/lib/puff.h:32, потоковая обёртка там же, :41-50), разбор ustar —
свой. Для ручной проверки годятся busybox tar и gzip.
Правила архива (нарушение — отказ установки с именем записи):
| Правило | Почему |
|---|---|
Первые три записи — plugin.json, MANIFEST, MANIFEST.sig, в этом порядке |
подпись проверяется до распаковки остального, архив читается одним проходом |
Записи — только обычные файлы (0) и каталоги (5). Ссылки, устройства, FIFO — отказ |
ссылка выводит запись за пределы каталога плагина |
Путь — относительный, без .., без //, без ./ в начале; длина — сколько вмещает ustar (name 100 + prefix 155 байт) |
предел формата ustar, не наш выбор |
Режим файла — 0644 или 0755, каталога — 0755. setuid, setgid, sticky — отказ |
исполняемое ставится от root |
Владелец, группа, время из архива не используются: файлы ложатся root:root, время — время распаковки |
|
Каждая запись-файл кроме самих MANIFEST и MANIFEST.sig описана в MANIFEST; каждая строка MANIFEST есть в архиве; каталог в архиве нужен хотя бы одному файлу из MANIFEST |
лишний или пропавший файл — подмена. Каталоги в MANIFEST не перечисляются (см. ниже), поэтому правило относится к файлам |
gzip — один член; мусор после конца tar — отказ |
Имя файла — <id>-<версия>-<арх>.s2p (<арх> — пакетная архитектура или all); у варианта не full —
<id>-<версия>-<арх>@<вариант>.s2p, как ключ assets индекса (иначе lite и full одной версии совпали
бы по имени). Имя для человека; менеджер верит только MANIFEST. Заголовок MANIFEST варианта не несёт:
вариант читается из plugin.json.
Архив без подписи (s2p build --unsigned) тоже несёт три первые записи: MANIFEST.sig в нём пустой
файл. Так порядок архива один для всех, а steer plugin install --file x.s2p --unsigned отличает «не
подписан» от «подпись не сходится». Подписать готовый архив можно позже: s2p sign x.s2p --key k.sec
(переписывает MANIFEST.sig, остальные байты те же); --add оставляет прежние блоки и добавляет
новые — так CI подписывает двумя ключами на время ротации.
Текст UTF-8, строки через \n:
s2p 1 vless 2.1.1 aarch64_cortex-a53
9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 1834 0644 plugin.json
2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae 104544 0755 bin/vless
fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9 2210 0644 kinds/vless.schema.json
- Первая строка — заголовок:
s2p <версия формата> <id> <версия плагина> <арх>. ПодписьMANIFESTтем самым привязывает архив к id, версии и архитектуре: архивvlessнельзя выдать заfoo, аx86_64— заaarch64. Заголовок обязан совпасть сplugin.jsonи с записью индекса. - Дальше — по строке на файл:
sha256 размер режим путь, сортировка по пути (байтовая). Путь — остаток строки (может содержать пробелы, не может —\n). - Каталоги не перечисляются — они следуют из путей. В tar они записаны (режим
0755), чтобы busyboxtarсоздал их с нужными правами;s2p buildкладёт их после трёх первых записей, перед содержимым. installedв индексе — сумма размеров изMANIFEST.
Ed25519 в формате usign/signify (решение В8). Издатель подписывает обычным usign -S, человек
может проверить руками usign -V; на роутере OpenWrt утилиты есть (пакет usign, PLUGINS.md 3.4).
Менеджер проверяет подпись сам, через Ed25519 из wolfSSL, без вызова утилиты (fork/exec — техдолг
по правилам хаба). В сборке wolfSSL ядра Ed25519 сейчас нет: список
steer/build/wolfssl/build.sh:44-50 содержит ge_operations, fe_operations, sha512, но не
ed25519 — его нужно добавить (и HAVE_ED25519 в build/wolfssl/user_settings.h).
Форматы (как у usign):
- открытый ключ — файл из двух строк:
untrusted comment: <текст>и base64 от 42 байт:"Ed", номер ключа (8 байт), открытый ключ (32 байта); - подпись — файл из одного или нескольких блоков по две строки:
untrusted comment: <текст>и base64 от 74 байт:"Ed", номер ключа (8 байт), подпись Ed25519 (64 байта) над байтами файла.
Проверка: для каждого блока найти доверенный ключ с тем же номером и нужной ролью, проверить
подпись. Годится хотя бы один блок — подпись верна. Ни одного — отказ с номерами ключей: «MANIFEST
vless подписан ключом 3f1a…, такого ключа у ядра нет». Несколько блоков — для ротации: на время
перехода CI подписывает двумя ключами. usign -V проверяет только первый блок — для ручной
проверки этого достаточно.
Что подписано:
| Файл | Чем | Зачем |
|---|---|---|
index.json.sig |
ключ роли index (сторонний — ключ репозитория) |
подмена версии, откат на старую уязвимую, подмена key_role |
MANIFEST.sig |
официальный: ключ роли из key_role индекса (protocols или plugins); сторонний — ключ репозитория |
установка из файла без сети и из семени; подмена архива на зеркале |
/usr/share/steer/keys/index/<номер>.pub официальные ключи, приходят с steer-core
/usr/share/steer/keys/protocols/<номер>.pub
/usr/share/steer/keys/plugins/<номер>.pub
/usr/share/steer/keys/revoked номера отозванных ключей, по строке
/etc/steer/plugins/keys/<repo>/<номер>.pub ключи сторонних репозиториев, принятые человеком
- Роль ключа — каталог, в котором он лежит. Ключ роли
pluginsне годится дляvless, если индекс говоритkey_role: protocols. - Ротация официальных ключей — через выпуск
steer-core(решение В8): новый ключ сначала приходит вkeys/<роль>/с выпуском ядра, CI какое-то время подписывает двумя ключами, затем старый уходит вrevoked. Номер вrevokedне принимается, даже если файл ключа остался. - Закрытые ключи — секреты Actions (
S2P_KEY_INDEX,S2P_KEY_PROTOCOLS,S2P_KEY_PLUGINS); в деревьях их нет. - Ключ стороннего репозитория человек принимает при подключении: интерфейс показывает номер ключа и предупреждение «репозиторий не официальный, splify2 за него не отвечает». Новый ключ стороннего репозитория — только действием человека.
steer plugin install --file x.s2p --unsigned — только из локального файла, для разработки плагина.
Такой плагин помечен unsigned, интерфейс показывает красную плашку, автообновления у него нет.
Почему так — open.md, О-5.
/usr/lib/steer/plugins/<id>/ содержимое .s2p; после установки — только чтение
plugin.json MANIFEST MANIFEST.sig
bin/ lib/ kinds/ nft/ rpc/ ui/ i18n/ themes/ scripts/
/usr/lib/steer/plugins/.stage/<id>-<версия>/ распаковка при установке и обновлении
/usr/lib/steer/plugins/.prev/<id>/ прежняя версия — до подтверждения здоровья новой
/usr/lib/steer/plugins/.lock блокировка менеджера (flock)
/usr/share/steer/seed/ семя: .s2p протоколов, index.json и .sig (steer-core)
/usr/share/steer/keys/ официальные ключи (steer-core)
/etc/steer/plugins/state.json что стоит: id, репо, версия, включён, причина, свои системные пакеты
/etc/steer/plugins/repos.d/<имя>.json подключённые репозитории
/etc/steer/plugins/keys/<repo>/<номер>.pub ключи сторонних репозиториев
/etc/steer/plugins/conf/<id>/ настройки плагина (сохраняются всегда)
/etc/steer/plugins/alloc.json выданные ресурсы: метки, очереди, порты, таблицы
/etc/steer/plugins/cache/ кэш хуков expand и pre-apply (steer-api.md)
/var/run/steer/plugins/<repo>/index.json кэш индекса (tmpfs)
<state>/plugin/<id>/ рабочие файлы плагина и его выходов (tmpfs; <state> — /var/lib/steer)
/lib/upgrade/keep.d/steer-plugins что переживает sysupgrade (пишет steer-core)
<state> — каталог состояния ядра: на OpenWrt /var/lib/steer (steer/src/platform/openwrt.c:24-26).
Каталог спеки — /etc/steer (openwrt.c:19-21).
Пути плагина в системе (steer.links, steer-api 1.3) ставит менеджер ядра: ссылки в /usr/lib/steer/plugins/<id>/…
и копии настроек (mode: conf), steer-api-1.3.md.
Ссылки splify2 (ставит splify2 по событию plugin, а не менеджер ядра):
каталог /www/luci-static/resources/splify2/plugins/<id>/ со ссылками ui → …/<id>/ui и i18n → …/<id>/i18n (панель берёт <id>/<ui.entry> и <id>/i18n/<язык>.json; остальное в плагине наружу не раздаётся), /usr/libexec/rpcd/splify2-p-<id> →
общий диспетчер, /usr/share/rpcd/acl.d/splify2-p-<id>.json.
{
"schema": 1,
"plugins": {
"vless": {
"repo": "splify2", "version": "2.1.1", "arch": "x86_64",
"enabled": true, "state": "enabled", "why": null,
"auto_update": true, "pinned": null,
"bad_versions": { "2.1.2": "помощник не поднялся за 60 с — возвращена 2.1.1" },
"system": ["kmod-tun"],
"installed_at": "2026-11-02T10:05:00Z", "from": "network"
}
},
"system_ours": ["kmod-tun", "kmod-amneziawg"]
}state: installed (файлы на месте, ещё не включён), enabled, disabled (человеком), failed
(несовместим, упал при загрузке, не прошёл проверку здоровья — причина в why), pending (ждёт сети
или места). from: network, seed, file.
Все шаги — под одной блокировкой менеджера; параллельный запрос получает busy. Порядок:
- План. Отбор версий (index.md, «Отбор») по всему графу
requires.plugins; библиотеки — раньше зависимых. Проверка конфликтов имён (виды, подкоманды, службы). - Место.
statvfsраздела/usr/lib/steer/pluginsи/tmp:- на разделе плагинов нужно Σ
installedновых версий (.stage) — старые версии остаются в.prevдо подтверждения здоровья, их место уже занято; - в
/tmpнужно Σsize(скачанные архивы). Не хватает — отказ с числами: «нужно 1,8 МБ, свободно 0,9 МБ». Пределов на число плагинов нет (решение 5).
- на разделе плагинов нужно Σ
- Скачивание в
/tmp/steer-plugins/поmirrors/urlпо порядку. Проверкаsizeиsha256из подписанного индекса — до распаковки. - Подпись архива (
MANIFEST.sig), сверка заголовкаMANIFESTиplugin.jsonс индексом. - Системные пакеты
requires.system:apk add/opkg install(единственный вызов чужой утилиты); запись вsystem_ours; проверкаrequires.kernel. Не прошла — отказ с именем пакета или пути. - Распаковка в
.stage/<id>-<версия>/, сверка каждого файла сMANIFEST(sha256 и размер при записи),scripts/postinst --check, проба ABI библиотек (ниже). - Подмена двумя
rename(2)на одном разделе:<id>→.prev/<id>,.stage/<id>-<версия>→<id>. Между ними каталога<id>нет миллисекунды; ядро, увидевшее его отсутствие, ждёт конца блокировки. scripts/migrate(если сменился major плагина) иscripts/postinst <старая версия>.- Включение:
plugin-reloadпо сокету — ядро перечитывает реестр (виды, подкоманды, службы, хуки, nft), затемreloadспеки. Помощники выходов вида перезапускаются (их подпись включает версию плагина)..soновой версии загружается только перезапускомsteerd(musl не выгружает библиотеки, PLUGINS.md 4.1.6), поэтому плагин сsoвключается рестартом службыsteer. - Проверка здоровья — ниже. Прошла —
.prev/<id>удаляется, событиеpluginenabled. Не прошла — откат.
Снятие (remove): scripts/prerm "", удаление каталога и ссылок, plugin-reload. Настройки в
conf/<id> остаются без --purge. Плагин, вид которого есть в спеке, снимается только с --force:
отказ называет выходы («выходы nl, de — вида tunnel:vless»). Системные пакеты не снимаются.
Отключение (disable): файлы на месте, плагин выпадает из реестра. Его выходы уходят в свой on_fail
с причиной «плагин vless отключён» (spec-fields.md, unavail).
Диапазон requires.plugins говорит, какие версии библиотеки подходят, но не какой сборкой собрана программа
зависимого: та же версия net1 с другой раскладкой структур её не запускает (у net1 — код 2 со строкой
steer: библиотека net1 … собрана с другой раскладкой структур). Поэтому до подмены (шаг 7) менеджер пробует:
исполняемые файлы bin/ зависимого, в которых есть SONAME библиотеки, запускаются с LD_LIBRARY_PATH на
каталог её lib/ и STEER_LIB_PROBE=1 — сверка идёт в конструкторе до main, совместимая программа отвечает
«подходит» и выходит.
- Ставится библиотека — стоящие зависимые пробуются против её новой копии. Несовместимые, которые не
ставятся в этой же установке: из индекса и семени — берутся в ту же установку одной группой (свой
репозиторий каждого, заново и при той же версии), из файла — отказ
plugin.lib_abi_breaksс их списком. - Ставится зависимый — его программы пробуются против стоящей библиотеки (если она не ставится вместе с
ним): несовместим — отказ
plugin.lib_abi_mismatch. steer plugin install --file A.s2p --file B.s2p …ставит архивы одной группой, библиотеки первыми: так библиотека и её зависимые из файлов встают вместе.- Проверка здоровья не винит плагин в отказе перечитывания на строке ABI, если сам он с библиотеками совместим, а не запускаются соседи прежней сборки: их список — в выводе.
steer plugin migrateставит из семени заново несовместимых и библиотеки, к которым они не подходят, — и при той же версии, откуда бы они ни стояли.
Срок — health.timeout_s манифеста (умолчание 60 с). Здоров, если всё из применимого:
plugin-reloadи следующийreloadпрошли без отказа;- каждый помощник выходов вида и каждая служба прислали
helloс подходящимapi; - каждый выход вида, который был
upдо обновления, снова прислалup(выходы, лежавшие до обновления, не в счёт — их здоровье от плагина не зависит); .soзагрузился и егоinitвернул 0;scripts/postinstвернул 0.
Не здоров — <id> удаляется, .prev/<id> → <id>, plugin-reload, reload. Версия попадает в
bad_versions с причиной: автообновление её больше не берёт, ручная установка — только явно с
этой версией. Событие plugin {state: "failed", why} и строка в diag. Если откат тоже не здоров —
плагин failed, его выходы — в on_fail, остальное работает.
Решение В10: протоколы (в том числе нынешние протоколы дерева steer) обновляются отдельно от ядра и в фоне автоматически.
- Кто. Таймер в цикле
steerd(безcronи без отдельного процесса-сторожа). Само обновление — ребёнокsteer plugin update --auto, какapplyу сокета: цикл демона не ждёт. - Когда.
- проверка индекса — раз в 24 ч со случайным сдвигом в пределах часа (чтобы роутеры не шли в одну
секунду) и после подъёма WAN, если последняя проверка старше 24 ч (hotplug
ifaceуже есть вsteer-core:steer/build.sh:440-441); - установка найденного — в ночное окно (умолчание 03:00–05:00 местного времени, настройка
auto_window), потому что перезапуск помощника рвёт соединения выхода на секунды; - версия с
yanked.securityили замена отозванной стоящей — сразу, не дожидаясь окна.
- проверка индекса — раз в 24 ч со случайным сдвигом в пределах часа (чтобы роутеры не шли в одну
секунду) и после подъёма WAN, если последняя проверка старше 24 ч (hotplug
- Что. Плагины с
auto_update: true(умолчание у всех), безpinned, обновляются из своего репозитория тем же отбором; не берутся версии изbad_versions. Обновление ядра в фоне не делается — только вручную (upgrade-core). - Как. Тот же цикл установки: место, подпись,
.stage/.prev, проверка здоровья, откат. Обновления разных плагинов идут по одному, в порядке зависимостей; откат одного не трогает другие. - Чего не делает. Не ставит новые плагины, не снимает системных пакетов, не трогает плагины
unsignedи плагины в состоянииfailed. Индекс скачивается напрямую, не через выходы steer, так что упавший после обновления туннель не мешает откату. - Человек видит итог в разделе «Плагины» и событием
plugin(updated,rolled-back).
steer-core пишет /lib/upgrade/keep.d/steer-plugins:
/usr/lib/steer/plugins/
/etc/steer/plugins/
плюс пути keep всех стоящих плагинов (переписывается при каждой установке и снятии). После
загрузки с новым образом служба steer-plugins (START раньше steer):
- сверяет каждый плагин с
MANIFEST(файлы на overlay целы); - ставит заново пропавшие системные пакеты из
system_ours— kmod новой прошивки; - если ядро в образе другой версии — подбирает совместимые версии (как при обновлении ядра).
Если steer-core в новом образе нет, сохранённые плагины лежат без дела до установки ядра.
/usr/share/steer/seed/ в пакете steer-core (решение В4): подписанные .s2p всех протоколов
официального репозитория (default: true) под архитектуру пакета, плюс index.json и
index.json.sig — снимок индекса на момент выпуска ядра. Менеджер ставит из семени, если сети нет, и
при первой связи обновляет плагины из сети обычным отбором. Подробно — migration-2.1.md.