Skip to content

Latest commit

 

History

History
290 lines (235 loc) · 25.5 KB

s2p.md

File metadata and controls

290 lines (235 loc) · 25.5 KB

Архив .s2p, подпись, раскладка на диске и жизненный цикл

Спецификация 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 подписывает двумя ключами на время ротации.

MANIFEST

Текст 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), чтобы busybox tar создал их с нужными правами; 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.

state.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. Порядок:

  1. План. Отбор версий (index.md, «Отбор») по всему графу requires.plugins; библиотеки — раньше зависимых. Проверка конфликтов имён (виды, подкоманды, службы).
  2. Место. statvfs раздела /usr/lib/steer/plugins и /tmp:
    • на разделе плагинов нужно Σinstalled новых версий (.stage) — старые версии остаются в .prev до подтверждения здоровья, их место уже занято;
    • в /tmp нужно Σsize (скачанные архивы). Не хватает — отказ с числами: «нужно 1,8 МБ, свободно 0,9 МБ». Пределов на число плагинов нет (решение 5).
  3. Скачивание в /tmp/steer-plugins/ по mirrors/url по порядку. Проверка size и sha256 из подписанного индекса — до распаковки.
  4. Подпись архива (MANIFEST.sig), сверка заголовка MANIFEST и plugin.json с индексом.
  5. Системные пакеты requires.system: apk add / opkg install (единственный вызов чужой утилиты); запись в system_ours; проверка requires.kernel. Не прошла — отказ с именем пакета или пути.
  6. Распаковка в .stage/<id>-<версия>/, сверка каждого файла с MANIFEST (sha256 и размер при записи), scripts/postinst --check, проба ABI библиотек (ниже).
  7. Подмена двумя rename(2) на одном разделе: <id> → .prev/<id>, .stage/<id>-<версия> → <id>. Между ними каталога <id> нет миллисекунды; ядро, увидевшее его отсутствие, ждёт конца блокировки.
  8. scripts/migrate (если сменился major плагина) и scripts/postinst <старая версия>.
  9. Включение: plugin-reload по сокету — ядро перечитывает реестр (виды, подкоманды, службы, хуки, nft), затем reload спеки. Помощники выходов вида перезапускаются (их подпись включает версию плагина). .so новой версии загружается только перезапуском steerd (musl не выгружает библиотеки, PLUGINS.md 4.1.6), поэтому плагин с so включается рестартом службы steer.
  10. Проверка здоровья — ниже. Прошла — .prev/<id> удаляется, событие plugin enabled. Не прошла — откат.

Снятие (remove): scripts/prerm "", удаление каталога и ссылок, plugin-reload. Настройки в conf/<id> остаются без --purge. Плагин, вид которого есть в спеке, снимается только с --force: отказ называет выходы («выходы nl, de — вида tunnel:vless»). Системные пакеты не снимаются.

Отключение (disable): файлы на месте, плагин выпадает из реестра. Его выходы уходят в свой on_fail с причиной «плагин vless отключён» (spec-fields.md, unavail).

ABI библиотек

Диапазон 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 или замена отозванной стоящей — сразу, не дожидаясь окна.
  • Что. Плагины с auto_update: true (умолчание у всех), без pinned, обновляются из своего репозитория тем же отбором; не берутся версии из bad_versions. Обновление ядра в фоне не делается — только вручную (upgrade-core).
  • Как. Тот же цикл установки: место, подпись, .stage/.prev, проверка здоровья, откат. Обновления разных плагинов идут по одному, в порядке зависимостей; откат одного не трогает другие.
  • Чего не делает. Не ставит новые плагины, не снимает системных пакетов, не трогает плагины unsigned и плагины в состоянии failed. Индекс скачивается напрямую, не через выходы steer, так что упавший после обновления туннель не мешает откату.
  • Человек видит итог в разделе «Плагины» и событием plugin (updated, rolled-back).

sysupgrade

steer-core пишет /lib/upgrade/keep.d/steer-plugins:

/usr/lib/steer/plugins/
/etc/steer/plugins/

плюс пути keep всех стоящих плагинов (переписывается при каждой установке и снятии). После загрузки с новым образом служба steer-plugins (START раньше steer):

  1. сверяет каждый плагин с MANIFEST (файлы на overlay целы);
  2. ставит заново пропавшие системные пакеты из system_ours — kmod новой прошивки;
  3. если ядро в образе другой версии — подбирает совместимые версии (как при обновлении ядра).

Если steer-core в новом образе нет, сохранённые плагины лежат без дела до установки ядра.

Семя

/usr/share/steer/seed/ в пакете steer-core (решение В4): подписанные .s2p всех протоколов официального репозитория (default: true) под архитектуру пакета, плюс index.json и index.json.sig — снимок индекса на момент выпуска ядра. Менеджер ставит из семени, если сети нет, и при первой связи обновляет плагины из сети обычным отбором. Подробно — migration-2.1.md.