Путь от пустого каталога до выпуска. Спецификации — manifest.md, s2p.md, steer-api.md, steer-abi.md, host-api.md, index.md; здесь — что делать руками и в каком порядке.
| Хотите | Берите | Шаблон | Машинный код |
|---|---|---|---|
вид выхода или протокол, службу, подкоманду steer |
программа-помощник — процесс под супервизором steer, говорит с ядром строками событий | helper |
да (C) или скрипт |
то, чему нужен горячий путь в процессе ядра: правила emit, health без fork, устройства через netlink |
.so в steerd по steer-abi |
so |
да, только C |
| свой экран в панели: карточка плагина во вкладке «Плагины», плитка, значок | интерфейс на @splify2/plugin-api |
ui |
нет |
| цвета панели | тема: только переменные --sp-* и --an-* |
theme |
нет |
| язык панели | перевод: словарь строк хоста | lang |
нет |
Начинайте с программы: она не может уронить steerd, ею можно пользоваться на любом языке, и она не
привязана к лицензии ядра. .so берите, когда программа не подходит. Один плагин может совмещать:
у recheck есть служба, правила nft, методы rpc и интерфейс.
sh build.sh # bin/s2p — один файл, Go 1.21+, без зависимостей
export PATH="$PWD/bin:$PATH" # дальше в примерах просто `s2p`
s2p versionДля C нужен zig 0.13: zig в PATH, или S2P_ZIG=<путь>, или docker с образом steer-builder:wolfssl
(S2P_BUILDER_IMAGE — другой образ). С docker s2p монтирует нужные каталоги и идёт от вашего пользователя,
файлов root не остаётся. Сборка для интерфейса — Node 20.19+ и npm. SDK OpenWrt не нужен нигде.
s2p new helper ./myplug --name "Мой плагин" # id — имя каталога: [a-z0-9][a-z0-9-]*
cd myplug
s2p keygen -o dev # dev.sec (секрет, 0600), dev.pub
s2p lint .
s2p build . --key dev.sec # dist/<id>-<версия>-<арх>.s2p, по архиву на архитектуру
s2p build . --arch x86_64 --key dev.sec # одна архитектура
s2p verify dist/myplug-0.1.0-x86_64.s2p --pub dev.pubЧто делает build: читает plugin.json, проверяет его до компиляции, запускает шаги из s2p.json
(cc — компилятор, ui — сборка интерфейса), собирает дерево, проверяет его ещё раз уже вместе с
машинным кодом, пишет MANIFEST с SHA-256, подписывает и пакует. Что попадает в архив: всё из каталога
проекта, кроме s2p.json, package*.json, tsconfig.json, vite.config.*, README*, src/, ui-src/,
build/, dist/, node_modules/ и точечных каталогов; ещё исключения — "exclude" в s2p.json. Бит x
файла становится режимом 0755, остальное — 0644; владелец, группа и время — нули.
Сборка повторяема: тот же проект и тот же zig дают те же байты архива. Расхождение на другой версии
zig или zlib не ошибка плагина, но индекс (s2p index) его заметит: см. раздел 10.
Без ключа: --unsigned (в MANIFEST.sig пустой файл). На роутере такой архив ставится только из файла и
помечается unsigned (s2p.md, «Без подписи»).
Файл SDK, в архив не попадает:
{
"cc": [
{ "kind": "helper", "out": "bin/myplug", "src": ["src/main.c"], "evline": true,
"requires": ["net1"], "link": ["vendor/libs2p-net.so.1"],
"defs": ["PLUGIN_ID=\"{id}\"", "PLUGIN_VERSION=\"{version}\""] }
],
"ui": { "dir": ".", "cmd": ["npm", "run", "build"], "out": "ui" },
"exclude": ["docs"]
}cc[].kind — helper (статическая программа musl) или so; evline добавляет библиотеку событий SDK;
requires и link — для зависимости от плагина-библиотеки (раздел 5); {id} и {version} в defs
подставляются из plugin.json, чтобы версия не жила в двух местах. ui.cmd получает каталог результата в
S2P_UI_OUT; всё, что он туда положит, ляжет в архив под ui.out.
Заготовки: helper, so, ui, theme, lang. Что получилось, проверяют s2p lint . и тест совместимости
(раздел 11): они ловят расхождение с ядром и панелью до роутера. На роутере с ядром steer 2.1 архив без подписи
ставится так: steer plugin install --file dist/myplug-0.1.0-<арх>.s2p --unsigned.
{
"schema": 1,
"id": "myplug",
"version": "0.1.0",
"name": "Мой плагин",
"license": "MIT",
"compat": { "steer-api": "^1.0" },
"arch": ["x86_64", "aarch64_cortex-a53"],
"steer": { "commands": [ { "name": "myplug-hello", "prog": "bin/myplug" } ] }
}compat— только оси, которые вы используете:steer-api(программы, хуки, подкоманды, nft),steer-abi(.so),host-api(интерфейс, темы, переводы). Диапазон в синтаксисе npm; minor добавляет, major ломает. Ядро или панель с меньшей версией плагин не поставит и назовёт числа.arch—"all"(нет машинного кода) или список пакетных архитектур OpenWrt;s2p archesпечатает десять поддерживаемых. Один.s2p— одна архитектура.permissions— что плагин делает; права сверяетs2p lint: файлы nft требуютnft,pre_applyиexpand—spec.transform,steer.so—so,requires.system—system-packages, каждый путьkeep—fs:<путь>. У официального и стороннего репозитория права одинаковы: подпись — доверие автору, а не песочница.- Имена глобальны:
id, виды, подкоманды и службы занимают одно пространство на роутере. Подкоманды ядра (apply,status,plugin…) заняты. - Версии осей. SDK 1.6.0 говорит
steer-api1.5,steer-abi1.0,host-api1.0,splify2-api1.3 (s2pдержит их в одном месте, строки — вtests/compat/matrix.json). Пишите самую раннюю ось, которой хватает:^1.0, а если нужно новое — его версию (steer.links—^1.3,splify2.luci.interface—splify2-api ^1.1). - Тексты для человека — состояние и действие, без технических пояснений. Переводы —
i18n/<язык>.json, ключиplugin.name,plugin.description,command.<имя>.help,kind.<имя>.label.
Шаблон helper. Ядро запускает программу по steer.kinds[].helper на каждый выход вида (или по
steer.services[] один раз на роутер), со словами из argv манифеста и подстановками {out}, {conf},
{mark}, {queue0} и другими (steer-api.md, раздел 1.3).
Правила:
- Первым событием —
helloсapi, версией плагина и id; иначе ядро погасит процесс. - Дальше —
up(выход готов;watch: 1— помощник сам судит о здоровье) иdownс причиной для человека. События — по одной строке JSON в дескрипторSTEER_EVENT_FD(3); для этогоlibs2p-evline(include/s2p/evline.h, ключevlineвs2p.json). - Всё, что нужно знать о выходе, лежит в файле
{conf}(ключи вида, устройство, метка, таблица, метка сокетов). Спеку помощник не читает. - Код
0— удача,2— отказ, причина — последняя непустая строка stderr; stderr идёт в журнал ядра. - На
SIGTERMвыйти; при гибелиsteerdприходитSIGTERMпоPR_SET_PDEATHSIG.
Схема ключей вида (kinds/<вид>.schema.json) — подмножество JSON Schema (manifest.md, «Ключи
вида»); x-secret: true прячет значение из status и журнала, x-path разворачивает путь.
Библиотеки. Стек туннелей и TLS живут в плагине-библиотеке net1, одной на роутер. Программа, которая
её использует, пишет "requires": {"plugins": {"net1": "^1.2"}} и собирается с requires: ["net1"] и
link: ["…/libs2p-net.so.1"] в s2p.json: загрузчик musl и RUNPATH $ORIGIN/../../net1/lib ставит
s2p cc. s2p lint проверяет связку libs2p-<имя>.so.<N> ↔ плагин <имя><N> и RUNPATH.
Шаблон so. Подключайте steer/plugin.h (он вшит в s2p) и экспортируйте ровно один символ
steer_plugin_v1_entry; всё нужное от ядра приходит таблицей steer_host_v1 в init. Следствия:
- с
libsteer*не связываться (s2p lintотвергаетDT_NEEDED); - функции не блокируют: сеть и имена — через
host->http,host->resolve, дескрипторы — через цикл демона; - падение
.soроняетsteerd: три падения за десять минут — плагин отключён; - обновление
.so— только перезапуском службыsteer(musl не выгружает библиотеки); - лицензия совместима с GPL-3.0 ядра; закрытому плагину — только программа;
- манифест:
steer.so.path,compat.steer-abi, правоso,license.
s2p cc --kind so собирает с -fPIC -fvisibility=hidden -Wl,-z,defs, файлом версий и SONAME по имени
файла. Проверка: file показывает разделяемую библиотеку нужной архитектуры, readelf --dyn-syms — один
экспорт.
Шаблон ui. Модуль ES ui/index.js панель загружает import() и зовёт activate(host); главный слот —
host.slots.pluginSettings (карточка плагина во вкладке «Плагины»). Типы — @splify2/plugin-api:
npm install -D @splify2/plugin-api preact vite typescriptvite.config.ts:
import { defineConfig } from 'vite'
import { splify2Plugin } from '@splify2/plugin-api/vite'
export default defineConfig({ plugins: [splify2Plugin()] })- Один preact на всех:
splify2Plugin()подменяетpreact,preact/hooks,preact/jsx-runtime,react,react-domпрокладкой наglobalThis.__splify2_host.preact.s2p lintне пропускает модуль с отдельнымimportизpreact. - Манифест:
ui.entryиui.css(ui/index.js,ui/style.css),compat.host-api. Стили панели живут в shadow root: CSS плагина — только черезui.cssилиhost.styles; цвета — переменные темы. - rpc: методы объявляются в
rpc.methods(access: read|write), обработчик — программа или скрипт:<prog> <метод>, параметры — JSON в stdin, ответ — JSON в stdout, код 0. Вызов —host.rpc.call. - Строки:
host.i18n.t('ключ')изi18n/<язык>.json; нет в языке человека —ru, нет и там — ключ.
s2p build запускает ui.cmd один раз и кладёт результат в каждый архив.
Тема (theme): type: theme, arch: all, файл themes/<имя>.json — {"name", "light", "dark"?} из
переменных --sp-* и --an-*. Кода нет; --sp-bleed, --sp-inset-l, --sp-inset-r ставит панель.
Перевод (lang): type: language, id — lang-<код>, словарь панели — i18n/host/<код>.json
(плоский объект «раздел.имя → строка», подстановки {0}); i18n.host.<код>.host — каким версиям словаря
панели он подходит. s2p new lang ./lang-fr --name Français переименует файлы и подставит код.
| Что | Примеры отказов |
|---|---|
схема plugin.json |
нет compat, неизвестное значение, .. в пути |
| файлы | программа из манифеста не найдена или не исполняемая; пропавший словарь, тема, схема ключей |
| права | nft, spec.transform, so, keep без нужного права |
| совместимость | диапазон не разбирается; вид без оси steer-api; .so без steer-abi; ui без host-api |
| подстановки | неизвестная {…}; {queue1} при resources.queues: 1 |
| nft | на верхнем уровне не set, map, chain <слот>; неизвестный слот |
| типы | library без libs и id без major; theme с кодом; language без i18n.host |
| тексты | предупреждение о технических словах в словарях (JSON, stderr, socket, 0x…) |
| машинный код | ELF не той архитектуры; не тот загрузчик; машинный код при arch: all; DT_NEEDED libsteer*; libs2p-* без зависимости или RUNPATH; лишний экспорт .so; лицензия .so несовместима с GPL |
| интерфейс | отдельный import preact; нет activate (предупреждение) |
| граница API | в программах плагина — пути, файлы, переменные и функции каркаса вместо служб хоста (splify2-api.md, раздел 9): предупреждение, с --official — отказ |
s2p lint понимает каталог проекта, готовый .s2p и одиночный plugin.json (только схема). --strict —
предупреждения тоже отказ; --official — плагин официального репозитория: обращение к внутренностям каркаса
(граница API) тоже отказ.
Подпись — Ed25519 в формате usign: s2p keygen пишет пару без пароля (как usign -G -N); ключи с паролем
s2p не читает. Номер ключа — 16 знаков hex. Закрытые ключи в деревьях не хранятся: в CI это секреты.
-
Ротация: на время перехода архив подписывают двумя ключами —
s2p sign x.s2p --key новый.sec --add(или--key старый.sec --key новый.secвbuild). Верна любая подпись доверенного неотозванного ключа. -
Репозиторий: подписанные архивы одной папкой, затем
s2p index dist -o repo --repo mine --name "Мои плагины" --mirror https://example.org/plugins/ \ --pub dev.pub --key index.sec --expires 30d [--meta meta.json]Индекс сливается с прежним (
repo/index.json): версии остаются, пока их не убрали (--drop id@версия); отзыв —--yank id@версия --why "…" [--security].--meta—default,key_role,tags,changelog. Разложитьrepo/на хостинг; срок индекса —--expires, переподписывать нужно раньше его конца (официальный репозиторий — раз в неделю). -
Проверка:
s2p verify repo/index.json --pub index.pub --base repo— подпись, схема, срок,sha256и размер каждого архива. -
Человек подключает репозиторий адресом и ключом (
steer plugin repo add), интерфейс говорит, что он не официальный.
Заглушки хостов повторяют проверки ядра и splify2 и запускаются на каталоге плагина (у плагина с машинным кодом —
после s2p build, на собранном дереве). Код возврата 0 — плагин подключится; иначе строки FAIL с причиной.
sh tests/compat/run.sh --steer ./myplug # ядро steer 2.1: ось steer-api, хуки видов, помощник, службы, steer.links
sh tests/compat/run.sh ./myplug 1.3 # splify2 с splify2-api 1.3: хуки, задачи, события, методы
sh tests/compat/run.sh ./myplug 1.1 # он же на хосте 1.1: хуки, задачи, события, методы, host-api
sh tests/compat/run.sh ./myplug 1.0 # он же на хосте 1.0 (плагину ^1.0 нужно, чтобы работал и там)
s2p lint --official ./myplug # граница API: плагин не лезет в внутренности каркасаОсь, которой нет у плагина, не проверяется; ось не из диапазона — FAIL compat.<ось>. Образцы — examples/:
splify2-hooks (хуки, задача, события, метод), splify2-interface (замена главного экрана) проходят всё выше;
остальные образцы — только манифест (по схеме: s2p lint examples/vless/plugin.json).
sh tests/run.sh # lint, build, sign, verify, index на шаблонах; C под 4 архитектуры
FULL=1 sh tests/run.sh # C под все 10Он же — образец: как собрать враждебный архив (tests/craft.py), как проверить .so (file, readelf),
как исполнить помощника под qemu-aarch64.
| Сообщение | Причина |
|---|---|
нужен --key … (или --unsigned) |
build без ключа |
такого ключа среди доверенных нет |
verify без --pub ключа, которым подписан архив |
…не сходится — файл изменён или подпись испорчена |
MANIFEST.sig не от этого MANIFEST |
zig не найден, а образа … нет |
нет компилятора для C: поставьте zig 0.13 или соберите образ steer-builder |
DT_NEEDED libsteer… |
.so связан с библиотекой ядра: берите всё из таблицы host_v1 |
путь …: содержит .. |
в архиве путь выводит из каталога плагина |
файла … нет в плагине |
путь в манифесте не существует (и s2p.json его не создаёт) |