splify2
splify2

Контракт объекта splify2 в rpcd#

splify2 отдаёт веб-интерфейсу (и любому авторизованному вызывающему rpcd) объект ubus/rpcd с именем splify2. Этот документ — контракт того объекта: методы, их вход и выход.

splify2 — тонкая обёртка на shell поверх ядра steer. Методы, спрашивающие состояние или диагностику (status, diag, vless_nodes, explain), зовут соответствующую подкоманду ядра и возвращают её JSON дословно. Это сделано намеренно: разбор вывода ядра здесь означал бы вторую модель данных на shell, которая расходится с ядром при первом же его изменении. Печатает ядро JSON — обёртка пропускает его без правок; не печатает — обёртка отвечает единым объектом ошибки.

Методы каркаса и методы плагинов#

На объекте splify2 методы трёх родов.

  • Методы каркаса объявлены в блоке list) диспетчера /usr/libexec/rpcd/splify2 и в таблице /usr/lib/splify2/methods.tsv (часть splify2-api); все они — в «Перечне методов» в конце документа. Вид метода в таблице: frame — метод каркаса, плагин может обернуть или заменить его (methods.override); fast — live, spec_get, applied_get: на них диспетчер отвечает раньше, чем читает реестр плагинов, поэтому заменить их нельзя; final — plugin_*, plugins_*, repo_*, repos_*, prefs_*: ни заменить, ни обернуть.
  • Вынесенные в плагины (вид moved): объявлены каркасом, а работают в официальном плагине — lists, list_*, lists_update, local_lists, allow_domains, fetch_mode, fetch_mode_set, lists_source, lists_source_set (15 методов, плагин lists-catalog), backup_get, backup_put (backup), sub_auto, sub_quota, sub_rename (subscriptions), outbound_geo (node-check), steer_versions, steer_install, splify2_versions, splify2_install (updater). Имя на объекте splify2 берёт псевдонимом (methods.alias) только этот плагин и только из официального репозитория. Плагина нет, он выключен или снят — ответ {"ok":false,"code":"not_installed","msg":"plugin.needed","error":"The <id> plugin is required. Install it on the Plugins tab.","args":{"plugin":"<id>"}}.
  • Новые имена от плагинов — методы, которых у каркаса нет: autoapply_*, group_*, nodes_*, subs_schedule, update_status, update_check. Они есть на объекте, пока плагин стоит и включён, права на них даёт ACL плагина (/usr/share/rpcd/acl.d/splify2-p-<id>.json). Описаны в разделе «Методы плагинов».

Точки расширения каркаса — splify2-api: хуки pre_spec_set, post_spec_set, pre_apply (в ответ apply при отказе: ok:false, veto:true, error), post_apply, post_apply_fail, heal, backup_sections, support_report, purge, plugin_changed, sub_fields (поля плагинов в строках sub_list и sub_info: auto, auto_at, due дописывает плагин subscriptions). Ответ plugins_list несёт поля splify2_api и ext_errors. Метод spec_set при предупреждении хука кладёт его в warn. Задачи плагинов — блок crontab # splify2-plugins begin … end, запуск /usr/sbin/splify2-task.

Плагины пользуются каркасом только через API: библиотека SPLIFY2_LIB (jshn, s2_fail, s2_setting) и службы хоста /usr/sbin/splify2-host (SPLIFY2_HOST): fetch, fetch-mode, paths, spec get|uses|check, apply, engine, settings get|set, state check|export|import, hook backup_sections, sub list|info|refresh|quota|title, call, probe, release, pkg, engine modules|settle (описание — splify2-api, раздел 8). Настройки плагина лежат в /etc/steer/plugins/conf/<id>/settings.json по схеме плагина (plugin_settings_get, plugin_settings_set), а не в uci каркаса.

Тексты отказов. Ниже у отказа указаны код (code, у плагинной части — msg) и английский текст: каркас и плагины пишут по-английски, а перевод даёт словарь включённого языкового плагина (lang-ru, lang-en). Без языкового плагина метод отвечает английским текстом.

Соглашения#

  • Транспорт. Каждый метод, принимающий вход, читает его как JSON на stdin, а не позиционным аргументом. rpcd пропускает только поля, объявленные в сигнатуре метода (блок list)), и только объявленного типа: булево поле, присланное числом, до метода не доходит.
  • Успех — форма, описанная у каждого метода.
  • Ошибка — единый объект у всех методов:

json { "ok": false, "error": "причина для человека", "code": "req.unknown_method", "args": {} }

`error` — текст на языке каркаса: каркас английский, перевод даёт словарь `i18n/backend/<язык>.json`
включённого плагина (языковые плагины `lang-ru`, `lang-en`; язык вида `pt-br` при отсутствии словаря берёт
`pt`). Язык — `luci.main.lang`; при `auto` или без значения — язык, выбранный в интерфейсе
(`splify2.main.ui_lang`, метод `prefs_set`), а без него английский. `code` — код текста (ключ словаря),
`args` — значения его подстановок `{имя}`; клиент с собственным переводом берёт их, а не `error`.
У отказов плагинной части (`plugin_*`, `plugins_*`, `repo_*`, методы плагинов) `code` — вид отказа
(`bad_request`, `not_installed`, `disabled`, `no_method`, `unavailable`, `timeout`, `failed`, `busy`,
`no_job`, `no_settings`, `core_too_old`), а код текста — в `msg`. Отказ ядра steer, названный ядром кодом
(steer, `docs/errors.md`), приходит с `code: "steer.<код ядра>"` и `args` ядра, текст переводится тем же
словарём; отказ ядра без кода и слова менеджера пакетов идут в `error` дословно и без `code`. Подробно —
plugin-sdk, `docs/splify2-api.md`, «Тексты для человека».

Методы, проксирующие ядро, отвечают этим же объектом, когда ядро не выдало годного JSON —
например, `{"ok":false,"error":"The core did not respond","code":"core.no_answer","args":{}}` (текст — на языке каркаса).

**Ненулевой код возврата ядра сам по себе ошибкой не является:** `diag` и `vless-probe`
завершаются с `1`, когда нашли проблему, но JSON при этом валидный, и он возвращается как успех.
Полная таблица кодов — в контракте steer, §6.
  • Важно для вызывающего: отказ приезжает УСПЕШНЫМ вызовом. Объект ошибки отдаётся с нулевым кодом возврата скрипта, поэтому промис в браузере резолвится, а не отклоняется. Проверять надо поле ok, а не только факт отказа вызова: иначе объект ошибки status выглядит как ответ работающего ядра.
  • Замок. Методы, которые читают, меняют и заменяют общие файлы (спеку, учёт зон фаервола, подписки), идут по одному: spec_set, apply, spec_heal, sub_set, sub_del, sub_refresh, awg_put, awg_del и xsteer_link_put держат один замок state, steer_module_add и steer_module_del — замок install. Второй вызов ждёт до 60 с и затем отказывает с lock.busy («Another change of the settings is still running. Try again in a minute.»). Вложенный вызов (spec_heal применяет через apply, служба хоста apply программ плагинов зовёт тот же метод) замок родителя не ждёт. Без flock на роутере методы идут без замка.
  • Права. Методы разделены на группы read и write в luci/root/usr/share/rpcd/acl.d/splify2.json. Проверка на этапе сборки в build.sh роняет сборку, если объявленный метод отсутствует в ACL. Новый метод обязан появиться и в блоке list) скрипта rpcd, и в файле ACL.
  • Имя метода написано в пяти местах, и каждое ребро между ними сторожится отдельно: блок list) скрипта rpcd, таблица methods.tsv splify2-api (tests/exttest.sh сверяет её с диспетчером), ACL LuCI (барьер в build.sh), таблица ниже (проверка tests/pkgmatch.sh, в обе стороны) и вызовы интерфейса — Andromeda в репозитории andromeda (стенд tests/api-calls.sh сверяет их со списком methods.tsv splify2-api, направление «каждый вызов имеет метод»). Метод, которого интерфейс не зовёт, законен — у объекта есть вызовы со страницы протокола и из ssh; вызов без метода — нет: ubus отвечает «Method not found», а страница показывает «нет данных».
  • Менеджер пакетов. Методы установки работают и с apk (OpenWrt 25.12+), и с opkg (24.10, 23.05, 22.03): менеджер определяется на старте скрипта, и от него зависят расширение файла пакета (apk или ipk) и суффикс для пакета без бинарного кода (noarch или all).
  • Скачивание. Всё, что бэкенд берёт из сети (манифест, списки, пакеты), идёт через одну функцию — download из /usr/lib/splify2/fetch.sh. Путей у неё три, по очереди:

    1. прямой адрес;
    2. тот же файл с других адресов — сначала зеркало на GitLab (gitlab.com/<владелец>/<репозиторий>/-/raw/<ветка>/<путь>: тот же путь, сырой файл со своего домена, без заголовка и без счётчика запросов), затем хосты самого GitHub — поштучно через api.github.com/repos/…/contents/… (заголовок Accept: application/vnd.github.raw), а если API отказал — из архива ветки через codeload.github.com. Для ссылок релиза ветка — dist: релизный workflow выкладывает в неё те же пакеты;
    3. через туннель роутера — но ТОЛЬКО если человек это включил (fetch_mode): на время скачивания добавляется ip rule to <адрес> lookup <таблица выхода> с приоритетом 30000 и снимается сразу после. У туннеля vless, hysteria2 или прокси, TCP которого ядро steer несёт по метке выхода, вместо правила запрос curl получает метку выхода (временная таблица nft splify2_om<N>_<pid> метит его порты источника и не выпускает их мимо туннеля; снимается сразу после) — для этого нужен curl. Включённый туннель идёт ПЕРВЫМ, а не последним.

    Провайдеры закрывают githubusercontent.com целиком (raw., objects. и release-assets. — одни адреса Fastly), и тогда роутер лишался бы и списков, и пакетов, хотя сам GitHub доступен. Третий путь не делается, если адрес издателя совпал с адресом узла подписки (это была бы петля), если имя разрешается в fake-IP 198.18.0.0/15, или если он выключен — uci set splify2.main.fetch_via_tunnel=0.

    Методы, у которых обход сработал, добавляют в ответ поле via — строку на языке каркаса о том, каким путём приехал файл. Прямое скачивание поля не добавляет.

  • Перечень выпусков. Версии ядра и интерфейса и адреса их файлов бэкенд берёт сначала из version.json репозитория splify2/releases — с трёх адресов одного файла по порядку: raw.githubusercontent.com/splify2/releases/main/version.json, cdn.jsdelivr.net/gh/splify2/releases@main/version.json, splify2.github.io/releases/version.json (FETCH_REL_URLS в fetch.sh). Каждый адрес — туннелем, если он включён, затем напрямую; обходов по хостам GitHub у самого перечня нет. Файл принимается, только если schema равно 1. Не ответил ни один адрес, схема другая или нужного продукта в файле нет — запасной путь целиком (api.github.com, затем VERSION ветки dist). Перечень и отказ его адресов помнятся тот же срок, что и список версий (GH_CACHE_TTL_MIN, полчаса).

    Пакет выпуска качает download_rel: адреса файла из version.json по порядку (сначала выпуск в splify2/releases, потом исходный выпуск проекта), у каждого скачанного сверяется sha256 из перечня — если на роутере есть sha256sum; не сошлось — следующий адрес. Потом лестница download по прямой ссылке выпуска проекта (зеркало gitlab.com, contents API, архив через codeload — ветка dist держит только последнюю версию, и её адресов в перечне нет); прямой заход по этой ссылке второй раз не делается, если она уже была среди адресов перечня. Сумма сверяется и у файла, взятого лестницей. Версии или файла в перечне нет — это обычный download.

Ядро, пакеты и версии#

steer_versions (read) — плагин updater#

Версии ядра, доступные к установке: из перечня выпусков splify2/releases (version.json, см. «Перечень выпусков» в соглашениях), а когда он не ответил — у GitHub. Зашитого списка нет.

  • Вход: нет.
  • Выход:

json { "ok": true, "arch": "aarch64_cortex-a53", "versions": ["2.1.0", "2.0.5", "2.0.4"], "names": { "2.1.0": "2.1.0", "2.0.5": "2.0.5", "2.0.4": "2.0.4" }, "prerelease": "2.1.0" }

- `versions` — версии продукта `steer` из перечня выпусков в его порядке (от новой к старой: до десяти стабильных и
    текущая предварительная), на запасном пути — теги последних десяти релизов `splify2/steer` без ведущего `v`. В обоих
    случаях остаются только значения из цифр и точек — ту же форму требует установка, поэтому значений может быть
    меньше десяти. Число составляющих не проверяется: `26.9` — такая же законная версия, как `1.2.0`.
- `names` — название выпуска по версии: поле `name` версии в перечне, на запасном пути — заголовок релиза GitHub.
    Названия нет (поля нет, заголовок `null` или в нём есть `|`) — версия называет себя сама. На установку название
    не влияет: интерфейс показывает название, а отправляет версию.
- `prerelease` — необязательное: версия, которую перечень называет предварительной (поле `prerelease` продукта).
    На запасном пути поля нет.
- `note` — необязательное, только на последнем запасном пути: не ответили ни перечень, ни `api.github.com`, и версия
    взята из файла `VERSION` ветки **`dist`** (скачивается общей `download()` со всей лестницей обходов). Тогда
    `versions` содержит одну версию, а `note` говорит, почему список короткий (`pkg.releases_missing`, «The release
    list was not available: the version is taken from VERSION of branch dist…»).

splify2_versions (read) — плагин updater#

То же для самого splify2.

  • Вход: нет.
  • Выход: { "ok": true, "current": "26.11.0", "versions": ["26.11.0", "26.10.4", "..."], "names": { … } } — установленная версия (пакет splify2, без него — luci-app-splify2), доступные версии (тем же фильтром «цифры и точки») и названия выпусков. Источник и поля prerelease, note — как у steer_versions. Установленной версии в перечне может не быть (сборка новее последнего выпуска) — перечень всё равно отдаётся.

steer_install (write) — плагин updater#

Скачивает и ставит указанную версию ядра — пакет steer-core.

  • Вход: { "version": "2.1.0", "modules": "vless,hysteria2,proxy" }.
    • version — обязательно, только цифры и точки, не младше 2.1.0 (поле min_version метода engine).
    • modules — необязательно: протоколы-плагины ядра, которые довести вместе с ядром, имена через запятую или пробел из vless, hysteria2, proxy, xsteer, obfs, tgws.
  • Порядок. До сети: ядро не занято коннектором (поле busy метода engine), версия годна, менеджер пакетов ответил, архитектура определена, имена modules известны. Потом файл steer-core-<версия>-1_<арх>.<apk|ipk> скачивается по адресам перечня выпусков со сверкой sha256, затем лестницей download по ссылке github.com/splify2/steer/releases/download/v<версия>/<имя> (см. «Перечень выпусков»). Место на флеше проверяется до менеджера пакетов. Ставится apk add --allow-untrusted --force-overwrite или opkg install --force-overwrite; если менеджер не нашёл зависимостей в пустых списках пакетов, списки обновляются (apk update, opkg update) и установка повторяется один раз. Прежних пакетов метод не снимает.
  • После установки менеджер плагинов ядра доводит (steer plugin ensure) протоколы из modules и те, что нужны текущей спеке (выход tunnel с protocol: vless или hysteria2 — свой плагин, протоколы прокси — proxy, xsteer и tgws — свои, interface с obfs — obfs); затем включается автозапуск службы ядра, спека из spec.json переводится ядром в spec.yaml, служба перезапускается, если спека есть.
  • Выход (успех):

json { "ok": true, "installed": "steer-core 2.1.0", "modules": ["vless", "proxy"], "restarted": true }

- `modules` — протоколы, которые доводились; `ensure_error` — слова менеджера плагинов, если довести не удалось
    (установку ядра это не отменяет); поля нет, если всё прошло.
- `restarted` — перезапустилась ли служба ядра. `false` — и неудача, и «перезапускать нечего» (спеки ещё нет).
- `via` — пакет взят не первым адресом: туннелем, обходом после отказа прямой ссылки или со следующего адреса
    перечня, потому что `sha256` первого не сошёлся.
- `output` — слова менеджера пакетов, если он что-то напечатал.
  • Выход (отказ): core.busy («The core is busy: {by}»), release.bad_version («A version may contain only digits and dots»), pkg.manager_silent («The package manager did not answer»), updater.steer_min («The interface works with a core no older than {min}»), updater.no_arch («The architecture was not detected»), module.unknown («Unknown module: {name}»), updater.download («Download failed: {name} (no such version for {arch}?){note}» — в том числе когда sha256 не сошёлся ни на одном адресе, причина — после тире) либо слова менеджера пакетов дословно. Поля removed у этого метода нет.

splify2_install (write) — плагин updater#

Ставит указанную версию splify2: пакет лежит в выпусках проекта, а не в репозитории OpenWrt.

  • Вход: { "version": "26.11.0" } — только цифры и точки.
  • Файл. splify2-<версия>-1_<noarch.apk|all.ipk>; не скачался — то же под именем luci-app-splify2-… (выпуски до переименования пакета). Скачивание — как у steer_install.
  • Установка — тем же путём, что steer_install, плюс замена luci-app-splify2: если менеджер пакетов отказал из-за конфликта и в строках о конфликте назван luci-app-splify2, этот пакет снимается и установка повторяется. После ответа, через две секунды, перезапускается rpcd.
  • Выход (успех): { "ok": true, "installed": "<имя файла>", "output": "<слова менеджера пакетов>", "reload_needed": true }, при обходе — ещё via. reload_needed — страницу надо перезагрузить.
  • Выход (отказ): release.bad_version, pkg.manager_silent, updater.download_noarch («Download failed: splify2-{ver}-1_{arch} (no such version?){note}») или { "ok": false, "error": "<слова менеджера пакетов>", "removed": <bool> } — removed: true, если по дороге снимался luci-app-splify2.

steer_modules (read)#

Протоколы ядра и их состояние у менеджера плагинов ядра — для карточки протоколов; полный перечень плагинов — plugins_list.

  • Вход: нет.
  • Выход:

json { "core": "2.1.0", "modules": [ { "name": "vless", "installed": true, "version": "2.1.0", "state": "enabled", "needed": true, "outputs": "nl" }, { "name": "hysteria2", "installed": false, "needed": false } ] }

- `core` — версия пакета `steer-core`; пусто — ядра нет.
- `modules` — шесть протоколов по порядку: `vless`, `hysteria2`, `proxy`, `xsteer`, `obfs`, `tgws`. `installed` —
    стоит ли плагин; `version` — его версия; `state` и `why` — состояние у менеджера (`enabled`, `disabled`,
    `failed`, `pending`, `installed`) и причина; `needed` — нужен ли текущей спеке, `outputs` — каким выходам.
- `busy` — как у `engine`: ядро ведёт коннектор.

steer_module_add (write) и steer_module_del (write)#

Поставить или снять один протокол-плагин менеджером ядра, синхронно (задание с ходом — plugin_install). Оба держат замок install.

  • Вход: { "module": "hysteria2" } — имя из перечня выше; иное — module.unknown («Unknown module: {name}»).
  • Поставить: steer plugin install <id>. Выход: { "ok": true, "installed": "hysteria2 2.1.0" }. Отказы: core.not_installed («The steer core is not installed») и слова менеджера плагинов (место, совместимость, подпись).
  • Снять. Протокол, нужный спеке, не снимается: module.in_use («The module is used by outputs: {outputs}»). Иначе steer plugin remove <id>. Выход: { "ok": true }.
  • После обоих ссылки и ACL объектов плагинов приводятся в согласие (как у plugin_install).
  • При коннекторе оба отвечают core.busy.

purge (write)#

«Удалить splify2» одной кнопкой: следы на роутере (команда splify2-purge: служба ядра, зоны и правила фаервола, таблицы nftables, расписание, каталоги состояния и — если не просили оставить — /etc/steer с /etc/config/splify2), затем пакеты проекта: steer, steer-*, libsteer*, splify2*, luci-app-splify2, luci-i18n-splify2-*, steer-box-connector, luci-app-steer-box-connector — те, что стоят; splify2, luci-app-splify2 и steer — последними.

Если ядро ведёт steer-box-connector (engine.busy), ядро и коннектор — не наши: служба steer, таблица nftables inet steer и пакеты ядра остаются (команда говорит об этом строкой в notes), снимаются только пакеты самого splify2.

  • Вход: { "plan": <bool>, "keep_config": <bool> }, оба необязательны. keep_config — оставить настройки (--keep-config).
  • plan: true — только план, ничего не меняется. Выход: { "ok": true, "plan": true, "keep_config": <bool>, "items": ["<что будет удалено>", ...], "notes": ["<что останется и почему>", ...], "packages": ["<пакет>", ...] }. Команда зовётся без --yes: items — её строки плана, notes — остальные её сообщения (чужое, что остаётся), packages — пакеты, которые будут сняты.
  • Без plan — выполнение, отсоединённое. Снимается пакет, в котором живёт сам обработчик, и снятие дольше срока вызова. Поэтому задание пишется в /tmp, запускается в своём сеансе (setsid) с закрытыми дескрипторами, ждёт две секунды (ответ успевает дойти), делает splify2-purge --yes, снимает пакеты и перезапускает rpcd. Ответ сразу: { "ok": true, "started": true, "keep_config": <bool>, "log": "/tmp/splify2-purge.log" }. После этого страница перестаёт отвечать — это ожидаемо.
  • Выход (отказ): purge.no_command («The removal command is missing: {path}»).

Состояние и здоровье ядра#

live (read)#

Весь круг опроса одним вызовом: применённое состояние, счётчики устройств, сведения о сети и — по просьбе — диагностика. Это тот метод, который интерфейс зовёт раз в пять секунд, пока открыта страница; остальные в этом разделе остаются законными и отвечают тем же, но по одному.

  • Вход: { "diag": <bool>, "fast": <bool> }, необязательно.
  • Выход:

json { "status": { "...": "вывод steer status дословно" }, "devices": { "awg0": { "rx": "...", "tx": "...", "rx_packets": "...", "tx_packets": "..." } }, "net": { "uptime": 1200, "active_clients": 3 }, "diag": { "...": "вывод steer diag дословно, только если просили" } }

- `status`, `devices`, `net`, `diag` — ровно то же, что отдают `status`, `dev_stats`, `net_info` и
    `diag` по отдельности: считает их один и тот же код (`/usr/lib/splify2/fast.sh`), второй
    реализации нет.
- `diag` приходит **только когда его просили**: проверки ядра заметно дороже состояния, а меняются
    реже — решает вызывающий. Проверки считаются по применённой спеке (`/etc/steer/spec.applied.json`; нет
    снимка — по сохранённой): иначе неприменённые правки выглядели бы поломками. Ядро не выдало JSON
    проверок (не умеет `diag`) — вместо поля `diag` приходит `"diag_old": true`.
- `fast` просит ядро отдать **запомненное**: `steer status --fast` печатает свой последний
    полный ответ немедленно, не разбирая спеку и не спрашивая ни `/sys`, ни `nft`. Тогда в
    `status` приходят `"cached": true` и `"at"` — время сборки ответа; по ним видно, что это
    память, и какой она давности. Ключ уходит **только ядру**: счётчики устройств и число
    клиентов считаются как обычно (они стоят единицы миллисекунд), иначе один ответ смешивал
    бы память с измерением и описывал бы мгновение, которого не было.
    Ядро, которое ключа не знает и не печатает JSON, даёт отказ `core.no_answer`.
- Ядро не ответило — отказ `core.no_answer` («The core did not respond»), как у `status`.
- **Журнала ядра здесь нет намеренно:** его читает один экран, а `logread` на каждом круге стоил бы
    всем. За ним ходят в `engine_state`, и только пока этот экран открыт.

Зачем один метод: каждый вызов ubus запускает скрипт объекта заново, и разбор скрипта busybox ash стоит дороже самого ответа; LuCI к тому же выполняет вызовы одного такта подряд.

live, spec_get и applied_get обслуживаются до разбора остального скрипта (первые строки files/usr/libexec/rpcd/splify2 уводят их в /usr/lib/splify2/fast.sh). На поведение это не влияет никак — только на цену. Поэтому эти три метода плагин не может ни заменить, ни обернуть (вид fast в methods.tsv).

status (read)#

Применённое состояние ядра. Пропускает вывод steer status дословно. Если ядро не выдало объекта, начинающегося с {, отвечает отказом core.no_answer («The core did not respond»). Состав полей — контракт steer §2, включая down_packets/down_bytes, at и — у запомненного ответа — cached. Память здесь не спрашивается никогда: за ней ходят через live с fast: true.

Обратите внимание: channels в этом выводе — объединённые группы, а не исходные правила один к одному, и name там — служебное имя набора nft. Читаемые имена исходных правил приходят в поле channels каждой группы; именно их и стоит показывать человеку.

У выхода kind: vless без устройства бывает поле probe (контракт steer §2): ядро перебирает узлы подписки, и up: false в это время не означает отказа. Интерфейс показывает «проверяю узлы: 3 из 26» вместо «нет устройства» и не спрашивает у такого выхода отклик — устройства ещё нет, мерить нечего. Поля нет — «не знаем».

diag (read)#

Диагностика ядра, вывод steer diag дословно. Ядро завершается с 1, когда нашло вердикт fail, но JSON печатает валидный — он возвращается как обычный ответ, ненулевой код не считается ошибкой. Набор вердиктов (ok/note/warn/fail, note исключён из счётчиков) — контракт steer §4. Проверки считаются по применённой спеке, как у live. Если JSON не получен вовсе — отказ core.no_diag («The core does not support diagnostics. Update steer.»).

engine (read)#

Наличие и версия ядра.

  • Вход: нет.
  • Выход: { "present": true, "vless": <bool>, "modules": ["vless", "proxy"], "arch": "...", "version": "...", "min_version": "2.1.0", "enabled": <bool>, "running": <bool>, "ui_version": "26.11.0", "update": { "url": "…", "command": "…" } }. Без ядра (/usr/sbin/steer нет) — { "present": false, "vless": false, "enabled", "running", "ui_version", "update" } (и busy, если есть).
    • version — версия пакета steer-core; min_version — не старше какой версии ядра нужен интерфейсу.
    • update — страница выпусков splify2 (url) и команда установщика (command): по ним обновляются без плагина updater.
    • ui_version — установленная версия пакета splify2 (пусто, если пакет поставлен мимо менеджера пакетов). Есть и без ядра (present: false). В отличие от splify2_versions, в сеть за ней метод не ходит.
    • modules — протоколы ядра, доступные сейчас: включённые плагины среди vless, hysteria2, proxy, xsteer, obfs, tgws (по state.json менеджера плагинов — так видит их и само ядро).
    • vless — умеет ли ядро VLESS: включён плагин vless.
    • busy — есть только тогда, когда ядро ведёт steer-box-connector (sing-box для podkop и forkop на ядре steer): кем занято ядро — podkop, forkop, podkop, forkop либо steer-box-connector, если ни одной из двух служб нет. Признак — служба /etc/init.d/sing-box с именем коннектора внутри (то же ищут скрипты пакетов ядра). Пока поле есть, engine_start, apply, spec_heal, steer_install, steer_module_add и steer_module_del отвечают отказом core.busy («The core is busy: {by}») и ничего не делают, а spec_get не заводит спеку; коннектором splify2 не управляет.
    • enabled — стоит ли служба в автозапуске; running — работает ли хотя бы один экземпляр. Спрашивается у procd, а не по наличию процесса: у ядра их несколько (сам steer, резолвер, клиенты vless), и «жив ли процесс с таким именем» на это не отвечает. Эти два поля — источник состояния для переключателя «Остановить всё».

engine_state (read)#

Состояние экземпляров ядра и последние строки их журнала: «выход настроен» и «туннель несёт трафик» — разные вещи, и причину упавшего туннеля видно в журнале.

  • Вход: нет.
  • Выход: { "instances": { "<экземпляр procd>": { "running": <bool>, "pid": <n> } }, "log": ["…"] } — экземпляры службы steer по ответу procd и последние двенадцать строк системного журнала со словом steer, дословно (общим списком, а не по экземплярам). Обёртка намеренно не разбирает текст сообщений ядра: формулировки меняются вместе с ядром, и разбор здесь ломал бы отображение при каждой правке сообщения. Классифицировать строки следует по префиксу steer[warn]/steer[info] — см. контракт steer §5.

engine_stop (write) и engine_start (write)#

Останавливают и запускают службу ядра целиком, вместе со снятием и постановкой автозапуска. Правила из ядра Linux сносит сама остановка ядра steer.

  • Вход: нет.
  • Выход: { "ok": true, "enabled": <bool>, "running": <bool> } — состояние после операции, теми же полями, что у engine.
  • engine_start при коннекторе (поле busy у engine) службу steer не включает и не запускает: { "ok": false, "error": "…", "code": "core.busy", "args": { "by": "<кем>" }, "busy": "<кем>", "enabled": …, "running": … }.

Остановленное ядро ночное обновление списков не поднимает: когда служба не работает и снята с автозапуска, оно только обновляет файлы списков и пишет в журнал «ядро выключено — списки обновлены, правила не применяю». Включает ядро снова engine_start.

dev_stats (read)#

Счётчики байтов и пакетов по сетевым устройствам из /sys/class/net/*/statistics (кроме lo). Нужны потому, что счётчик канала nft стоит на правиле метки в направлении LAN→WAN, и обратный поток с устройства туннеля в него не попадает. У устройств туннеля rx — то, что ядро отдало клиентам (скачано), tx — то, что взяло у них.

  • Вход: нет.
  • Выход:

json { "devices": { "awg0": { "rx": "...", "tx": "...", "rx_packets": "...", "tx_packets": "..." } } }

support_report (read)#

Один готовый к копированию текст для чата поддержки. Собирает в него то, о чём помогающий спрашивает первым делом: время сборки, модель роутера и версию OpenWrt, архитектуру пакетов и менеджер пакетов, версии интерфейса и ядра, состояние службы ядра, приговоры steer diag (по применённой спеке) читаемым видом, выходы с их состоянием и число наборов правил в ядре Linux, правила из спеки (имя, выход, вид списков), строку о резолвере доменов ядра, по строке на подписку — есть ли файл и сколько в ней пригодных, пропущенных и чужих узлов, — разделы плагинов (хук support_report, ответ плагина {ok, section: {title, text}}; из текста убираются управляющие знаки, за отсутствие секретов в своём разделе отвечает плагин) и строку о том, что в отчёт не вошло.

  • Вход: нет. Состав отчёта решает бэкенд: набор полей и есть договорённость с помогающим, а право выбрать половину означало бы отчёты, по которым нельзя задать один и тот же вопрос.
  • Выход: { "ok": true, "text": "<весь отчёт одной строкой с переводами строк>" }. Именно текст, а не объект полей: читатель здесь не интерфейс, а человек, который жмёт «скопировать», и формулировки — половина смысла отчёта. Отчёт пишется по-английски и не переводится (core service: running, autostart off): его читает помогающий, а не владелец роутера.

В отчёте нет и не должно быть секретов, и это его главное требование, а не оговорка: текст уезжает в публичный чат. Не попадают ссылка подписки (в ней ключ доступа к панели), ссылки узлов, приватные ключи туннелей, UUID и адреса узлов, имена узлов подписки (их пишет панель, и там встречаются и рекламные сообщения, и логин владельца) и внешний адрес роутера. Способ, которым это обеспечено, — отчёт читает только НАЗВАННЫЕ поля чужих ответов и никогда не пересказывает документ целиком: состояние выхода несёт поля спеки (контракт steer §2), а ответ vless-nodes — весь список узлов, поэтому дословный пересказ любого из двух был бы готовой утечкой. Проверки на каждую из этих подстрок стоят в tests/rpcdmatch.sh.

Ничего своего метод не считает: версии, вариант сборки и состояние службы приходят от своего же метода engine (он зовётся подпроцессом — его помощники живут в группе ядра, а копия здесь была бы вторым местом, где решается «какая версия стоит»), приговоры и выходы — от ядра, подписки — из common.sh и ядра. Интерфейс называется плагином и версией из менеджера плагинов (splify2 interface plugins: andromeda 26.11.0; без плагина интерфейса — none (the page opens the frame view)): в сеть отчёт не ходит, его собирают как раз тогда, когда с сетью беда.

Цена вызова — дороже обычного метода: подпроцесс метода engine, steer diag, steer status и по steer vless-nodes на каждую скачанную подписку. Платится она раз на нажатие кнопки, а не на круге опроса.

Спека#

spec_get (read)#

Текущая спека в JSON. Файл ядра — /etc/steer/spec.yaml (так её пишет spec_set) или прежний /etc/steer/spec.json; при spec.yaml JSON-вид печатает ядро (steer spec convert --json), и он пересчитывается, когда меняется файл. Если spec.yaml лежит, а ядро её JSON-ом не напечатало, метод отказывает без JSON-ответа (ненулевой код скрипта): пустая заготовка вместо настоящей спеки показала бы роутер без выходов и правил. Ни одного файла нет или он пуст — метод заводит пустую спеку v2 {"version":2,"outputs":{"direct":{"kind":"direct"}}} в spec.json, ту же, что кладёт установка пакета, и отдаёт её. Службе ядра при этом велено подхватить спеку: не работает — запускается; работает (ядро поставили раньше интерфейса, и его демон поднялся без спеки) — перечитывает её (reload), ничего не перезапуская. Когда ядро ведёт steer-box-connector (поле busy у engine), спека не заводится и служба не поднимается — отдаётся та же пустая спека, файла нет. Так же спеку заводят applied_get и live — с той же оговоркой.

Ревизия rev. К спеке в ответе добавлено поле верхнего уровня rev — md5 её JSON-вида (при spec.yaml — вида, который печатает ядро). Это не поле спеки: разбирая ответ, клиент снимает его и запоминает отдельно. Файл, переписанный кем угодно (вторая вкладка, ssh, самолечение apply, плагин), меняет ревизию. JSON-вид, который не начинается с {, или пустой объект {} отдаётся как есть, без rev.

applied_get (read)#

Снимок спеки в момент последнего успешного apply — из /etc/steer/spec.applied.json (JSON). По нему интерфейс считает, сколько правил и выходов отличается от применённого.

Снимка нет (свежая установка, спеку ещё ни разу не записывали) — отдаётся текущая спека: чего не применяли — то и применено, иначе свежепоставленный пакет показывал бы неприменённые изменения, которых человек не делал. Первая запись spec_set при отсутствии снимка снимает его с той спеки, которую заменяет (её и исполняет ядро), поэтому записанная, но не применённая правка видна как неприменённая и до первого apply.

Почему помнит бэкенд, а не браузер: перезагрузка страницы не должна обнулять счётчик.

spec_set (write)#

Проверяет и сохраняет новую спеку.

  • Вход: { "spec": "<вся спека текстом: YAML или JSON>", "rev"?: "<ревизия из spec_get или spec_yaml>" }. Текст, начинающийся с {, идёт как JSON; иначе его переводит ядро (steer spec convert --json --spec -).
  • Выход: { "ok": true, "rev": "<новая ревизия>", "warn"?: "<предупреждения хуков плагинов>" } или отказ.
  • Отказы: req.unparsable (вход не JSON), spec.empty; конфликт ревизий (ниже); ошибка разбора текста — { "ok": false, "error", "line"?, "col"? } (как у spec_check); отказ хука pre_spec_set — { "ok": false, "error": "<причина плагина>" }; отказ ядра — его слова (с кодом ядра — code: "steer.<код>"), перед ними через «; » — предупреждение хуков, если оно было (например, о нескачанном списке: оно и есть причина); spec.not_replaced — файл не встал на место.

rev — ревизия, от которой сделана правка. Если спеку на роутере с тех пор переписали, метод ничего не пишет и отвечает { "ok": false, "conflict": true, "rev": "<текущая>", "error", "code": "spec.changed", "args" }: клиент читает spec_get, сливает свою правку с лежащим и пишет от свежей ревизии. Без rev (ssh) запись идёт без сверки. Сверка и запись идут под замком state (см. «Замок» в соглашениях), поэтому между ними файл не меняется. Новую ревизию клиент берёт из ответа и не перечитывает спеку.

Порядок: перевод текста в JSON; хуки pre_spec_set плагинов (могут переписать спеку, отказать или предупредить; плагин lists-catalog довозит списки, на которые ссылается присланная спека); проверка ядром до записи — через управляющий сокет демона (steer ctl check), а без него steer apply --dry-run: ядро — единственный судья, оно же будет её применять, и на диске не должно оказаться спеки, которую оно отвергнет при следующей загрузке; запись; хуки post_spec_set (так плагин autoapply ставит отложенное применение, см. apply). Предупреждение хука сохранение не отменяет — оно приезжает полем warn.

Запись атомарна: временные файлы создаются рядом с целевым, а не в /tmp (mv между tmpfs и overlay в busybox — копирование, а не rename()).

Формат: записывается spec.yaml — печать ядра (steer spec convert) присланной спеки, а не присланный текст, поэтому комментарии YAML не сохраняются. Лежавший spec.json убирается, а его копия остаётся как spec.json.bak (одна, старейшая). Помощников выходов метод не трогает: ими управляет демон ядра, а apply перечитывает спеку целиком.

apply (write)#

Применяет текущую спеку через steer apply.

  • Вход: нет.
  • Выход: { "ok": <bool>, "output": "<вывод целиком>" }. Обратите внимание: здесь нет поля error — причина лежит в output, потому что ядро объясняет её лучше, чем обёртка могла бы пересказать. В output по порядку: предупреждения хука pre_apply, строки зон фаервола и самолечения (каждая начинается с splify2:), вывод ядра (например, что у туннеля нет NAT) и предупреждения хуков post_apply/post_apply_fail. Помощников выходов метод не перезапускает: их держит демон ядра.
  • Ядро занято коннектором. Если на роутере стоит steer-box-connector (служба /etc/init.d/sing-box — его), ответ — отказ core.busy, и steer apply не вызывается: без службы steer его исполнило бы само ядро и поставило бы свою таблицу inet steer поверх таблицы коннектора (см. engine, поле busy).
  • Отказ плагина. Хук pre_apply может остановить применение: { "ok": false, "veto": true, "error": "<причина плагина>", "output": "splify2: apply stopped by a plugin: <причина>" } (текст — на языке каркаса).

Порядок шагов: самолечение zapret (см. spec_heal), зоны фаервола, лечение хуком heal плагинов, самолечение ключа ipv6, хук pre_apply, steer apply, на успехе — снимок применённого, затем хуки post_apply (успех) или post_apply_fail. Исход хуки не меняют.

Перед применением создаются зоны firewall: для устройств всех выходов (vless, hysteria2, прокси trojan, shadowsocks, socks, http, vmess, xsteer, члены WARP warp-masque, а также interface и awg) — одна зона steer_zone без masq: IPv4-подмену адреса делает само ядро steer в своей таблице, а зона нужна только для пропуска транзита; для устройств клиентов из спеки, у которых зоны нет (tailscale0, сервер WireGuard), — steer_clients. Зоны steer_vless и steer_iface, если их завёл splify2 (по расписке), убираются вместе с пробросами, а их устройства переходят в steer_zone; одноимённые зоны человека не трогаются. fw4 отвергает форвардинг на устройство, не входящее ни в одну зону, и клиент получил бы «Operation not permitted» ещё до туннеля. Зона создаётся здесь, а не в ядре, потому что это управляющее решение и делается через uci. Устройство, которое человек уже положил в свою зону, остаётся в ней — и когда зона называет его списком device, и когда она называет логический интерфейс списком network (так пишет зоны LuCI): в нашу зону оно не добавляется (в двух зонах fw4 устройство не прощает), а в output сказано, какие устройства оставлены. Проброс в такую зону заводится: для каждой зоны устройств клиентов — своя секция forwarding «зона клиентов → зона человека», если её ещё нет. Без неё пакет помечен, маршрут ведёт в туннель, а fw4 отбрасывает его на паре зон, которую никто не разрешил. Сама зона человека не меняется; проброс записан в расписке (xfwd <зона выхода> <зона клиентов>) и убирается по ней, когда устройство ушло из выходов или из зоны либо клиентов в зоне-источнике не осталось, — и при полном удалении. Проброс, который человек завёл сам, не дублируется и за нами не числится.

Зоны клиентов и внешней сети — настоящие, а не слова lan и wan. В steer_zone пробрасывается из зон, в которых лежат устройства клиентов спеки (без перечня — br-lan): зона ищется по списку device и по списку network, и называться может как угодно; ни одна не узналась, а зона lan есть — из lan. Такие пробросы записаны в расписке (fwd <зона> <зона клиентов>) и убираются, когда устройств клиентов в зоне-источнике больше нет. Зона внешней сети для проброса из steer_clients — та, в чей список network входит интерфейс wan; нет такой — зона устройства, через которое идёт маршрут по умолчанию; нет и её — зона с именем wan. Не нашлась вовсе — проброса нет, и output говорит об этом. Правила fw4 перезагружаются один раз на все зоны и только если что-то изменилось.

Прежнее применённое — рядом. Перед тем как снимок spec.applied.json сдвигается на новую спеку, его копия остаётся как spec.prev.json (только когда применённое изменилось: повторный apply без правок откат не затирает). Откатить применение руками — положить spec.prev.json на место спеки и применить. Andromeda откатывает правку сама, из памяти страницы («Применено: N изменений» → «Отменить»).

apply может переписать спеку. Самолечение вписывает ipv6 выходам без ключа (и убирает выходы zapret), и снимок для applied_get снимается уже с исправленного файла, после steer apply. Ответ спеку не несёт: тот, кто держит её в памяти, после ответа читает spec_get и applied_get заново и берёт то, что лежит на роутере. spec_set, присланный во время apply, ждёт замка state и пишет после него. Строки самолечения ipv6 в output начинаются словами splify2: outputs without an ipv6 key got ipv6: nat и splify2: outputs without an ipv6 key got ipv6: off (не переводятся); это начало — часть контракта.

apply применяет файл, а не то, что на экране. Вызывающий, который держит правки в памяти, перед вызовом записывает их spec_set, и если тот отказал, apply не зовёт: применилась бы прежняя спека с диска, а ответ ok выдавался бы за применение той, что на экране.

Применение на роутере — плагин autoapply (включён по умолчанию с версии 1.1, настройка enabled). Его хук post_spec_set после каждой записи ставит отложенное применение: через паузу pause_s (по умолчанию 1 с) после последней записи применяется последняя спека — тем же методом apply через службу хоста, под тем же замком; правки, идущие подряд, склеиваются в одно применение. Применять нечего (спека равна снимку применённого) — роутер не трогается. Задача sweep раз в 5 минут применяет записанное и не применённое (настройка sweep); спеку, которую ядро отвергло, плагин не повторяет, пока она не изменится. Ход виден методом autoapply_status (поле state: applying — роутер применяет, pending — ждёт паузу, rejected — ядро отвергло эту спеку, unapplied — записано и не применено, idle — всё применено), см. «Методы плагинов». Ручной apply при этом остаётся законным: применение идемпотентно.

explain (read)#

  • Вход: { "address": "1.2.3.4 | example.com" }.
  • Выход: { "text": "<вывод steer explain>" } — текст ядра дословно.

Аргумент уходит ядру позиционным, поэтому значение, начинающееся с дефиса, отвергается здесь же (req.bad_address, «This is neither an address nor a name»): ядро разобрало бы его как флаг. Пустое значение — req.no_address. Ни адрес, ни имя с дефиса не начинаются.

Списки и подписка#

Методы списков — плагина lists-catalog (кроме подписок, у которых свои пометки). Кэш каталога, отметки версий второго издателя и настройки лежат в /etc/steer/plugins/conf/lists-catalog/, временные файлы — в рабочем каталоге плагина в памяти; сами списки — в /etc/steer/lists.

lists (read) — плагин lists-catalog#

Манифест каталога списков, дословно. Кэша (manifest.json) ещё нет — метод скачивает каталог по адресу из настройки плагина manifest_url; не скачался — lists.manifest_failed («The manifest was not downloaded{why}»).

local_lists (read) — плагин lists-catalog#

Файлы списков, лежащие на роутере: { "files": { "<путь от /etc/steer/lists>": { "count": <строк>, "mtime": <unix-время> } } }. Наборы .srs, которые правила берут файлом (см. list_fetch), тоже здесь — с count 0: строк у двоичного файла нет.

list_fetch (write) — плагин lists-catalog#

Скачать один список из манифеста.

  • Вход: { "id": "<id списка>", "kind": "prefixes|domains" }.
  • Выход: { "ok": true, "count": <строк>, "path": "<путь>", "tag": "<версия>" } или объект ошибки. tag — версия записи каталога (у второго издателя — тег его выпуска, у набора srs — тоже). У обычного списка первого издателя поля tag нет: ответ — ok, count, path и, при обходе, via. При обходе закрытого издателя добавляется via (см. «Скачивание» в соглашениях).

Набор каталога, который списком не выразим. Запись каталога с format: "srs" разбирается steer srs-read на две половины. Набор с исключениями (@@ фильтра AdGuard) или с логикой «и/не» ядро понимает, но списком не выражает (код 2). Тогда на роутер ложится сам набор: путь записи без .lst (jinndi/domains/adguard.srs.lst → jinndi/domains/adguard.srs, от адресной записи, если у набора их две). Ответ: { "ok": true, "srs": "<путь набора>", "path": "<он же>", "tag": … }, без count. Интерфейс ставит такой файл в правило ключом srs списка спеки v2. Сохранение спеки, применение и ночное обновление доскачивают и обновляют его по той же записи каталога, list_remove убирает вместе с записью.

kind обязателен и объявлен в сигнатуре метода: categories и domain_lists — разные пространства имён, и один id законно есть в обоих (у издателя так с news и hodca). Без вида запрос уходит в ветку «искать где найдётся», где адресные категории проверяются первыми, и доменный запрос скачал бы адресный файл под именем доменного.

Путь из манифеста проверяется: он обязан состоять из безопасных символов и не может выходить за каталог списков. Поле file приходит из интернета, и без проверки значение вида ../../../etc/crontabs/root давало бы запись файла от root куда угодно.

Сужение подсетей (narrow). У второго издателя набор бывает ограничен протоколом и портами (discord: подсети Cloudflare только для udp 50000-65535 и 19000-20000). steer srs-read отдаёт это третьим потоком (--meta-out), бэкенд кладёт его рядом со списком подсетей файлом <список без .lst>.meta и возвращает в ответе list_fetch для вида prefixes: "narrow": { "proto": "udp", "ports": ["50000-65535", "19000-20000"] }. То же поле у сервиса в allow_domains, когда список уже лежит. Сужение — свойство канала, а не списка (steer, srs.c), поэтому в спеку его переносит интерфейс: правило человека остаётся одним, а в файл пишутся два канала — правило с доменами и канал-спутник с подсетями, proto/ports и полем "part_of": "<имя правила>" (ядро незнакомые поля терпит). При чтении спутники складываются обратно в правило (Andromeda, ui/src/lib/model.ts: normalizeSpec/expandNarrow). Спека с сужением пишется схемой 2.

allow_domains (read) — плагин lists-catalog#

Каталог ВТОРОГО издателя списков — itdoginfo/allow-domains — и то, что из него уже лежит на роутере.

  • Вход: нет.
  • Выход:
{
  "ok": true,
  "id": "itdog",
  "repo": "itdoginfo/allow-domains",
  "tag": "2026-09-14_15-11",
  "tag_default": "2026-09-14_15-11",
  "tag_warn": "",
  "base_url": "https://github.com/itdoginfo/allow-domains/releases/download",
  "services": [
    { "id": "telegram", "name": "Telegram", "kinds": ["domains", "prefixes"],
      "have": { "domains":  { "tag": "2026-09-14_15-11", "lines": 1234 },
                "prefixes": { "tag": "2026-09-14_15-11", "lines": 567 } } },
    { "id": "anime", "name": "Аниме", "kinds": ["domains"] }
  ]
}

Типы: ok булев; id, repo, tag, tag_default, tag_warn, base_url — строки; services — массив объектов { id: строка, name: строка, kinds: массив строк ("domains" и/или "prefixes"), have?: объект }; ключ have — объект, ключами которого могут быть только domains и prefixes, а значением — { tag: строка, lines: целое }.

Метод НИЧЕГО НЕ КАЧАЕТ. Он читает таблицу сервисов из описания источника плагина (lib/allow-domains.sh), тег из настроек плагина (allow_domains_tag) и сами файлы на диске — и всё. В сеть он не ходит НИКОГДА, файлов не создаёт и отметок не пишет. Причина простая: его зовёт открытие вкладки, а поход в сеть на опросе — это полминуты ожидания у того, у кого GitHub закрыт, то есть ровно у той аудитории, которой этот издатель и нужен. Скачивание — отдельное действие по нажатию, и делает его list_fetch.

Почему id уезжает с приставкой. Скачивают список этого издателя через тот же list_fetch, но с id вида itdog:telegram — имя источника (id в ответе) плюс двоеточие плюс services[].id. Приставкой, а не вторым методом: метод — это запись в сигнатуре объекта и в ACL, и второй метод «то же, но у другого издателя» означал бы, что каждое место, которое умеет качать список, надо учить дважды. Пространство id при этом разделено честно — у нашего манифеста id это слово из категорий, двоеточия в нём нет и быть не может. Собирать itdog: в интерфейсе руками не надо гадать: имя источника отдаётся полем id этого же ответа.

have — это «что скачано и какой версии», и только про то, что ЛЕЖИТ. Вида нет на диске — ключа нет вовсе; нет ни одного вида — нет и самого have. Ноль строк не заменяет отсутствие файла: пустой скачанный список — законное состояние, и подмена сделала бы кнопку «Загрузить» висящей над уже загруженным. tag внутри have берётся из отметки версий (/etc/steer/plugins/conf/lists-catalog/allow-domains.tag), а не из нынешней настройки: файл мог приехать при другом теге, и ответ на вопрос «какая у меня версия» обязан говорить про файл, а не про настройку. Пустой tag при существующем файле законен — так выглядит список, положенный руками или вернувшийся из архива настроек.

tag против tag_default против tag_warn. Версия списков зафиксирована ТЕГОМ релиза, а не latest: при плавающей ссылке состав списков меняется сам собой, ночью, и объяснить «вчера пускало, сегодня нет» нечем. tag_default — зашитый в плагин, tag — тот, по которому реально качаем. Поднять версию можно настройкой плагина allow_domains_tag; негодное значение (latest или знаки кроме латиницы, цифр, _, . и - — оно уезжает в URL) отбивается, tag остаётся зашитым, а tag_warn объясняет, что именно отбито (строка журнала плагина, по-русски, без кода). Непустой tag_warn обязан доехать до человека: настройка, отбитая молча, — ровно та беда, ради которой предупреждение и заведено.

lists_update (write) — плагин lists-catalog#

Обновить разом все списки, на которые ссылаются правила.

  • Вход: нет.
  • Выход: { "ok": true, "updated": <сменившихся файлов>, "failed": <оставшихся прежними>, "fitted": <подогнанных под память>, "lines": ["<строки прогона>"] }. lines — строки журнала прогона (метка lists-catalog), они не переводятся.

Метод не делает работу сам, а запускает bin/update-lists плагина — тот же прогон, что ходит по расписанию: скачивание, подгонка адресных списков под память (steer fit), проверка скачанного до подмены, откат на прежние копии при отказе ядра и apply в конце. Вторая реализация этого в rpcd разошлась бы с первой на первом же изменении.

ok: false означает, что хотя бы один список обновить не удалось. Прогон, в котором ничего не изменилось, — это успех с updated: 0: списки уже свежие.

Строки прогона скрипт дублирует в файл (REPORT), потому что его log() печатает в stdout только под терминалом. Нет программы прогона — lists.no_updater («The list updater was not found»).

list_put (write) — плагин lists-catalog#

Свой список — текстом, по ссылке или порциями из файла.

  • Вход: { "name": "<имя>", "kind": "prefixes|domains", "text": "...", "url": "...", "append": <bool>, "source": "text|file|url", "filename": "..." }.
    • name — только латиница, цифры, дефис и подчёркивание: имя становится частью пути на диске.
    • Одно из text или url; если пришли оба, берётся url, а text игнорируется. Ссылка обязана начинаться с http:// или https://.
    • append — булево, не число. Метод объявлен в сигнатуре как boolean, и число приезжает другим типом blobmsg: rpcd молча отбросит несовпавший атрибут, и каждая порция файла заместит предыдущую вместо дописывания.
    • source — откуда список, и спрашивается явно, а не выводится из присланного: файл едет тем же полем text, порциями, и отличить его от набранного руками здесь нечем. Различать надо: правку предлагают по тому же разделению, каким список завели (см. list_custom). Поля нет — считается по присланному: ссылка значит url, текст значит text.
    • filename — как файл назывался у человека, только для показа («выбран blocked.txt»). Запоминается вместе с source на первой порции: порции — это один и тот же файл.
  • Выход: { "ok": true, "path": "...", "count": <строк итого>, "dropped": <отброшено строк> }.

Содержимое проверяется и приводится к годному виду: одиночный адрес дополняется до /32, домены приводятся к нижнему регистру и лишаются ведущего *., у адресов проверяются диапазоны октетов и длина префикса. Отброшенные строки считаются и называются числом — молчаливая потеря строк была бы худшим из возможных поведений. Проверка стоит здесь, а не в интерфейсе: интерфейс можно обойти, а последствие непроверенного списка молчаливое — nft отвергнет весь набор правил целиком.

Предел размера — 1 МБ, и считается он по итоговому файлу, а не по одной порции: overlay на роутере мал, и список, который туда не влезет, положит не только себя.

list_custom (read) — плагин lists-catalog#

Свои списки с происхождением: чем каждый завели и, значит, чем его править.

  • Вход: нет.
  • Выход: { "lists": [ { "name", "kind", "path", "count", "bytes", "source", "url", "filename", "at" } ] }.
    • source — text (набран руками), file (выбран файлом), url (дан ссылкой) либо пустая строка: происхождение неизвестно. Так выглядят списки без записи о происхождении, положенные в каталог руками и вернувшиеся из архива настроек (архив происхождения не носит). Интерфейс тогда предлагает все три способа правки — признать незнание честнее, чем угадать неверно.
    • at — когда происхождение записано, unix-время; 0 значит «не записано».

Отдельным методом, а не полем local_lists, и это разделение по цене: тот считается одним awk по всему каталогу и зовётся на каждое открытие настроек, а происхождение бывает только у своих списков — их единицы. Само происхождение лежит рядом со списком, файлом <список>.lst.src в формате «ключ=значение»: список — это файл на диске, и его происхождение обязано теряться вместе с ним, а не отдельно. Расширение не .lst нарочно — иначе local_lists и сборка архива увидели бы его как ещё один список.

list_get (read) — плагин lists-catalog#

Записи своего списка обратно, порциями по байтам. Нужно редактору набранного руками: запись списка ЗАМЕЩАЕТ его целиком, поэтому пустое поле вместо записей — это не «начни заново», а предложение молча потерять набранное.

  • Вход: { "name": "<имя>", "kind": "prefixes|domains", "offset": <байт> }.
  • Выход: { "ok": true, "name", "kind", "total": <байт всего>, "offset", "next": <байт>, "eof": <bool>, "text": "..." }.

Читаются только свои списки: список издателя приезжает по расписанию, и всякая правка была бы стёрта следующим обновлением молча. Нарезка по байтам, а не по строкам, и кусок приезжает байт в байт (та же заплатка printf X, что в backup_get): потерянный на границе перевод строки склеил бы две записи в одну, а склеенная не отбрасывается санитайзером — она молча уносит обе.

list_remove (write) — плагин lists-catalog#

Удалить один список.

  • Вход: { "id": "<id из манифеста>", "kind": "prefixes|domains" } — для списка издателя, { "id": "itdog:<сервис>", "kind": "..." } — для списка второго издателя, либо { "name": "<имя>", "kind": "..." } — для своего. Ветка name — единственный способ удалить свой список.
  • Выход: стандартный объект успеха или ошибки. Список, задействованный правилом, не удаляется, и метод говорит об этом причиной.

Вместе со своим списком снимается и запись о его происхождении (<список>.lst.src): оставленная, она переехала бы на следующий список того же имени и рассказала бы про него чужую правду.

Id с приставкой itdog: метод понимает так же, как list_fetch, и путь строит ТОЙ ЖЕ функцией раскладки: своя укладка здесь означала бы, что удаление стирает не тот файл, который создало скачивание.

Для второго издателя kind обязателен, когда на диске лежат оба вида: один набор .srs даёт два наших списка, и list_fetch кладёт оба сразу — то есть «оба на диске» здесь обычное состояние, а угадывание удалило бы не то и промолчало об этом. Лежит ровно один вид — он и удаляется.

Вместе с файлом снимается и отметка версии (ad_stamp_del). Отметка утверждает «лежащий файл набит этим тегом»; пережившая свой файл, она заявляет о том, чего на роутере нет, — и первый же читатель версий (allow_domains) показал бы её как версию удалённого списка. Отметка ведётся по виду, поэтому и снимается по виду: второй вид того же набора остаётся на диске вместе со своей.

sub_info (read)#

Сведения о подписке: источник, вид, размер, идентификатор устройства.

  • Вход: { "name": "<имя подписки>" }. Поля нет — первая подписка (main), та, что лежит в /etc/steer/sub.txt. Так отвечают и интерфейсы, которые про несколько подписок не знают.

  • Выход: { "url", "name", "kind", "path", "hwid", "present", "bytes"?, "mtime"?, "quota"? } и поля расписания auto, auto_at?, due от плагина subscriptions — как у sub_list; bytes и mtime есть, когда файл скачан.

  • kind — url или links. Поле значимо: для вставленных руками ссылок узлов обновление подписки не значит ничего, и предлагать «Обновить» там не нужно — адреса, откуда обновляться, не существует.
  • Поле hwid — идентификатор ЭТОГО роутера для панели подписки (см. ниже). Отдаётся всегда, а не только после скачивания: устройство в панели заводят заранее. Пустая строка значит «считать не из чего» — ни одного физического порта с постоянным MAC.
  • Поле quota — остаток трафика, как его назвала панель. Приходит БЕЗ обращения наружу: отдаётся запомненное с последнего запроса. Обновляет его отдельный метод sub_quota.

json "quota": { "up": "1288490188", "down": "139458183168", "total": "214748364800", "expire": 1789200000, "at": 1787428800, "since": 1786132800, "since_used": "2147483648" }

- `up` / `down` / `total` — байты, **строками**. 200 ГБ — это 2·10¹¹, а `json_add_int` у jshn
    32-битный: числом такая подписка приехала бы обрезанной, и остаток выглядел бы законным. Тот же
    довод, по которому строками отдаются счётчики `dev_stats`.
- `total` пустой ИЛИ РАВНЫЙ `"0"` — подписка без ограничения по объёму: нулём безлимит
    обозначают сами панели, и клиенты читают его так же. Бэкенд отдаёт слово панели как есть,
    а интерфейс в обоих случаях рисует знак бесконечности; прочитанный буквально, такой ноль
    давал «0 Б из 0 Б осталось» на безлимитном тарифе.
- `expire` — unix-время конца периода, `0` — панель срока не назвала.
- `at` — когда спрашивали. Нужно, чтобы интерфейс мог сказать «обновлено 12 минут назад» и решить,
    не пора ли спросить заново. `mtime` файла для этого не годится: файл переписывается и когда
    числа не изменились.
- `since` / `since_used` — ПЕРВОЕ наблюдение этого периода: время и расход на тот момент.
    Панель начала периода не сообщает, только конец, а без начала средний расход в сутки не
    посчитать. Угадывать длину периода нельзя: на подписке на девяносто дней догадка
    «тридцать дней» завысила бы темп втрое и обещала бы, что трафик кончится, когда он не
    кончится. Поэтому бэкенд запоминает первое наблюдение и переносит его из опроса в опрос;
    период считается новым при смене срока или объёма и при уменьшении расхода (панель
    обнулила счётчик). Делит и предсказывает интерфейс — второе место, где то же число
    считалось бы иначе, разошлось бы с первым.
- **Поля `quota` нет вовсе** — значит панель остатка не сообщала: либо ни разу, либо в последний
    раз промолчала. Интерфейс говорит об этом прямо («Панель не сообщает остаток»), а прежние числа
    при молчании СНИМАЮТСЯ: «осталось 68 ГБ» от предыдущей подписки выглядит свежим и ничем не
    отличимо от правды.

sub_quota (write) — плагин subscriptions#

Спросить у панели остаток трафика (плагин зовёт службу хоста sub quota).

  • Вход: { "name": "<подписка>" }. Поля нет — первая подписка (main). Ссылку каркас берёт из uci (splify2.main.sub_url у первой, splify2.sub_<имя>.url у остальных): остаток спрашивается у той панели, которой роутер пользуется.
  • Выход: { "ok": true, "kind": "url|links|none", "name", "asked": <bool> } плюс quota (см. sub_info), если её удалось узнать или она была запомнена раньше, и why, если спросить не удалось.
  • asked: false — спрашивать некого: узлы заданы ссылками или не заданы вовсе. Это не отказ: человек ничего не сделал не так, и ok остаётся true.

Почему отдельный метод, а не поле sub_info. sub_info спрашивают в общем опросе страницы, а здесь уходит запрос в интернет. Ходить с роутера к панели на каждом опросе нельзя — ни по цене, ни по тому, как на это посмотрит панель. По расписанию остаток спрашивают задача плагина subscriptions (настройка quota_interval) и суточное обновление списков плагина lists-catalog.

Почему в группе write. Метод ходит наружу и переписывает файл на роутере. Подписку он при этом не подменяет: ни файл узлов, ни выбранный узел, ни признак «перечитать клиента». Поэтому его безопасно звать при открытии обзора — единственное следствие вызова — свежие числа.

Где есть curl, уходит запрос одних заголовков (HEAD): тело подписки для двух чисел качать незачем, а на мобильном канале это десятки килобайт на каждое открытие обзора. Часть панелей на HEAD отвечает отказом — тогда обычная загрузка, но в выбросной файл.

Где эти числа берутся. Панель называет их заголовком ответа subscription-userinfo: upload=…; download=…; total=…; expire=… — соглашение панелей (Marzban, 3x-ui, Remnawave и родня), то же, что читают мобильные клиенты. В теле подписки их нет вовсе, поэтому узнать остаток можно только в момент запроса; запомненное лежит в <файл подписки без .txt>.userinfo и объявлено в keep.d ядра, то есть переживает обновление прошивки «с сохранением настроек».

Средний расход в сутки отдельным полем не отдаётся: интерфейс считает его сам из total − (up + down) и даты сброса. Второе место, где то же число считалось бы иначе, — это второе место, которое разойдётся с первым.

sub_list (read)#

Все подписки роутера одним ответом: имя, название, источник, вид, путь, размер, время скачивания, число выходов на неё и запомненный остаток.

  • Выход: { "subs": [ { "name", "title", "link"?, "url", "kind", "path", "present", "bytes", "mtime", "used", "used_nodes", "auto", "auto_at"?, "due", "quota"? } ], "hwid": "<идентификатор роутера>" }.
  • auto — через сколько минут роутер обновляет подписку сам (0 — не обновляет), auto_at — когда пытался в последний раз, due — пора ли обновлять сейчас. Эти три поля дописывает плагин subscriptions (хук sub_fields); без плагина их нет. Считает их плагин, а не тот, кто спросил: интервал, отметка и часы живут в одном месте.
  • name — имя файла узлов. title — название подписки: то, что вписал человек (см. sub_rename); если его нет — название опознанного по ссылке продавца (sub_brand), иначе то, что назвала сама панель (заголовок profile-title, обычно base64; запасной путь — content-disposition). link — ссылка на продавца, есть только у опознанного продавца; у прочих поля link нет. used — сколько выходов ссылается на файл этой подписки, used_nodes — сколько узлов выбрано у этих выходов (nodes) в сумме.
  • Списком, а не по одной: экран показывает подписки вместе, и десять вызовов ради десяти строк — это десять запусков shell.

sub_rename (write) — плагин subscriptions#

Назвать подписку по-своему (плагин зовёт службу хоста sub title).

  • Вход: { "name": "<подписка>", "title": "<название>" }. Пустое title снимает своё название.
  • Выход: { "ok": true, "name", "title" } — title в том виде, в каком его теперь отдаёт sub_list.
  • Имя, вписанное человеком, сильнее и названия панели, и названия опознанного продавца (sub_brand): продавец подставляется только вместо ПУСТОГО названия. Не длиннее 200 байт, без управляющих знаков; подписки с таким именем нет — отказ.
  • Трогает одно поле: файл узлов, ссылка и выходы остаются как были.

sub_auto (write) — плагин subscriptions#

Как часто роутер обновляет подписку САМ: минуты, 0 — не обновляет. Расписание — данные плагина (/etc/steer/plugins/conf/subscriptions/schedule, строки «имя минуты», и отметки попыток stamps/<имя>), а не uci каркаса; поля auto, auto_at, due в ответах sub_list и sub_info дописывает плагин.

  • Вход: { "name": "<подписка>", "minutes": <число> }. Поля name нет — первая подписка (main).
  • Выход: { "ok": true, "name", "auto": <минуты> }.
  • Пределы по умолчанию: 30 минут … 4320 минут (трое суток), оба — настройки плагина (min_interval, max_interval). Проверяются здесь, а не только в интерфейсе: метод зовут и мимо страницы. Интервал, оказавшийся вне пределов после их смены, не действует (auto — 0), пока не задан новый.
  • Ненулевой интервал ставит отметку последней попытки на момент вызова: первое обновление наступит через заданный интервал, а не на ближайшем тике расписания. 0 снимает интервал и отметку.
  • Вставленным руками ссылкам узлов ненулевой интервал не назначается: обновлять их нечем.
  • Отказы: sub.bad_name («A subscription name may contain Latin letters, digits and underscores»), subs.interval_number («The interval is given as a number of minutes»), subs.interval_min («Less often than once in {min} min is not possible: it is the smallest interval»), subs.interval_max («An interval is never longer than {max} min»), sub.not_exists («There is no subscription "{name}"»), sub.links_only («The nodes are given as links: there is nothing to update»), subs.interval_not_saved («Cannot save the interval»).

У каждой подписки свой интервал: у одной панели узлы меняются раз в сутки, у другой — при каждой смене сервера. Общая настройка означала бы либо лишние хождения к первой, либо устаревшие узлы у второй.

sub_refresh (write)#

Обновить подписку по СОХРАНЁННОЙ ссылке. Этим путём ходит расписание — задача update-subs плагина subscriptions раз в десять минут, через службу хоста sub refresh; человек нажимает «Обновить», и тогда работает sub_set — у него на входе ссылка.

  • Вход: { "name": "<подписка>" }.
  • Выход: { "ok": true, "name", "changed": <bool>, "bytes", "usable" } плюс quota и — только при changed: true — restarted: сколько выходов этой подписки попрошено перечитать узлы (0, если перечитывание отложено неприменёнными правками).
  • changed: false — узлы те же самые. Туннель тогда не трогается вовсе: подписку опрашивают по часам, а узлы у панели меняются редко, и перезапуск на каждом опросе означал бы обрыв связи по расписанию.
  • changed: true — живым туннелям этой подписки уходит сигнал перечитать узлы, тем же способом, каким это делает применение спеки. Ждать, пока человек нажмёт «Применить», здесь нельзя: обновление затем и по часам, чтобы он в него не вмешивался.
  • Ссылками заданная подписка — отказ sub.links_only; не скачалась — sub.download_failed («The subscription was not downloaded{why}»).
  • Плагин subscriptions ставит отметку попытки до похода наружу: иначе мёртвая панель опрашивалась бы на каждом тике расписания.

sub_del (write)#

Удалить подписку целиком: файл узлов, запомненный остаток и ключи uci.

  • Вход: { "name": "<имя подписки>" }.
  • Выход: { "ok": true, "name" } или объект ошибки. Занятую выходом подписку метод не удаляет и говорит, сколькими выходами она занята (sub.in_use, «The subscription is used by outputs: {outputs}», где outputs — число): ядро читает файл узлов при подъёме, и снос под живым выходом оставил бы правило вести в туннель без единого узла. Без имени — sub.no_name. Расписание удалённой подписки плагин subscriptions убирает на следующем тике.

sub_set (write)#

  • Вход: { "url": "<адрес подписки | одна или несколько ссылок узлов>", "name": "<имя>", "title": "<название>", "links": "<ссылки прокси http(s)://>" }. Имени нет — первая подписка (main). Названия нет — берётся то, что назвала панель заголовком profile-title.
  • Выход: { "ok": true, "kind": "url|links", "name": "<имя>", "title": "<название>", "path": "<файл подписки>", "bytes": <n>, "usable": <пригодных узлов> } плюс warn и hwid, либо объект ошибки. Если панель назвала остаток трафика, он приезжает тем же ответом полем quota (см. sub_info): человек нажал «Обновить» именно затем, чтобы увидеть свежие числа, и ждать следующего опроса ему незачем. usable считает ядро тем же кодом, которым читает подписку при подъёме туннеля, — то есть это то самое число, по которому туннель и поднимется.

Если подписка стала ссылками (kind: links), запомненный остаток трафика прежней панели (<подписка>.userinfo) снимается, а интервал автообновления плагина к ней не применяется (auto: 0): ссылки — не панель, и обновлять их нечем.

Принимает обе формы: адрес подписки http(s):// и одну или несколько ссылок узлов через пробел или перевод строки — vless://, hysteria2:// (и hy2://), прокси пакета steer-proxy trojan://, ss://, socks:// (socks4://, socks4a://, socks5://), vmess:// — например, один сервер от знакомого без панели. Ссылки ложатся в файл подписки строками как есть (kind: links); какому протоколу принадлежит узел, различает ядро.

Прокси http:// и https:// приходят полем links, а не url: по виду https://адрес:порт их не отличить от адреса подписки, и в url такая ссылка скачивалась бы как подписка. В links принимаются прокси http(s)://[имя:пароль@]адрес:порт[?sni=…][#имя] — без пути (адрес панели с путём здесь отвергается) — и любые ссылки узлов выше; ссылки узлов из url, если они есть, ложатся туда же. Адрес подписки в url вместе с links — отказ sub.url_and_links («A subscription address and node links belong to different subscriptions»): одно из двух потерялось бы молча. Другие отказы: sub.no_link, sub.need_link, sub.no_links, sub.no_links_proxy (в тексте нет ссылок узлов), sub.download_failed.

Подписку скачивает и разбирает ЯДРО STEER#

Скачивание, заголовки запроса, разбор ответных заголовков, base64 названия, арифметика остатка трафика и повтор за другим форматом живут в steer sub-fetch / steer sub-quota / steer sub-hwid — см. контракт steer и steer/src/proto/vless/subfetch.c. Объект rpcd ведёт УЧЁТ: какая подписка выбрана, где лежат её файлы, что записано в uci, сколько выходов на неё ссылается.

Каждый из этих шагов упирается в то, чего у оболочки нет (на роутере нет ни base64, ни openssl), а у ядра он готов, проверяем стендом и живёт в одном месте.

Практические следствия для вызывающего:

  • sub_set отдаёт usable — сколько узлов ядро сочло ПРИГОДНЫМИ, тем же кодом, которым читает подписку при подъёме туннеля.
  • Сохранённая ссылка может отличаться от присланной: ядро могло перезапросить подписку с суффиксом /json, и обновлять в следующий раз надо по ТОЙ ссылке (панели с привязкой к устройствам выбирают формат ответа по клиенту, и списка ссылок vless:// среди вариантов может не быть).
  • warn — то, что ядро вычитало из ответа панели про устройство: x-hwid-not-supported, x-hwid-limit, либо «идентификатор не ушёл, послать заголовок нечем».
  • hwid во всех ответах — от steer sub-hwid; пустая строка значит «не из чего считать». Значение кэшируется на время работы метода: sub_list спрашивает его один раз на весь ответ.
  • Остаток трафика остаётся в файле <подписка>.userinfo — он и есть контракт между ядром и объектом. Пишет его ядро, а sub_info и sub_list только читают, никуда не ходя. Формат и смысл at0/used0 описаны в контракте steer.

Несколько подписок#

Подписок на роутере бывает несколько: у человека две панели, и локации из обеих он складывает в один пул. Первая живёт в /etc/steer/sub.txt — на этот путь ссылаются выходы в спеках, — остальные в /etc/steer/subs/<имя>.txt; ключи uci у первой — в splify2.main (sub_url, sub_kind, sub_title), у остальных — в секции splify2.sub_<имя> (url, kind, title). Интервалы автообновления — данные плагина subscriptions.

Ядро про этот учёт не знает ничего: ему называют --out и --info явно, и это не мелочь. Ошибка здесь молчаливая в худшем виде — остаток второй панели, записанный поверх остатка первой, выглядит как правда, а узлы, скачанные в чужой файл, уводят трафик к другому поставщику. Имя подписки поэтому чистится до латиницы, цифр и подчёркивания (sub_slug): оно становится и именем файла, и именем секции uci.

За списками категорий идентификатор не уходит: download() его не шлёт — издателю списков незачем знать, какой у человека роутер.

vless_nodes (read)#

Узлы подписки глазами ядра — дословный ответ steer vless-nodes. Спросить можно двумя способами, и указывается ровно один:

  • {output} — по имени выхода kind: vless: узлы его подписки, в chosen — выбранные им номера;
  • {sub} — по пути к файлу подписки (тот, что печатает sub_list полем path): узлы подписки, на которую ещё не заведён ни один выход, chosen пуст.

Вторая форма нужна редактору выхода: локации подписки показываются до того, как из неё что-то взято, — иначе выход собирался бы вслепую. Путь принимается только из перечня подписок роутера (sub_names), чужой — отказ sub.not_found («No such subscription: {name}»): метод читает файл с диска, и произвольный путь означал бы чтение произвольного файла. Нескачанная подписка — sub.not_downloaded («The subscription has not been downloaded yet»). Имя выхода с недопустимыми знаками — req.bad_output. Ядро не выдало JSON — стандартный объект ошибки со словами ядра, и вызывающий обязан его проверить: иначе отказ выглядит как пустой список узлов.

insecure: true вместе с sub — перечень так, как подписку разберёт выход с «не проверять сертификат узла» (ключ insecure выхода): ядру уходит --insecure, узлы TLS с allowInsecure входят в перечень, и номер узла совпадает с номером у такого выхода. Без ключа такие узлы непригодны и в перечень не входят — как у выхода без insecure. С output ключ не действует: у выхода пригодность решает его собственный insecure. То же у vless_probe, proxy_nodes и proxy_probe; у hysteria2_* ключа нет (insecure=1 там — параметр ссылки узла, такие узлы пригодны всегда).

Архив настроек — плагин backup#

Выгрузка и восстановление настроек одним файлом. Файл собирается и разбирается в браузере: сюда он приезжает и отсюда уезжает строкой, кусками по 16 КБ. Второго пути наружу (cgi-io, отдельный обработчик uhttpd) нет — он означал бы вторые права и вторую проверку формата.

Формат архива знает плагин backup; что входит в настройки каркаса и как проверять присланное, знает каркас (служба хоста state export|check|import), а данные других плагинов отдают и принимают сами плагины (хук backup_sections). Подробно — plugins/backup/README.md.

Что в архиве. От каркаса: спека (JSON-вид), первая подписка (/etc/steer/sub.txt) и именованные (/etc/steer/subs/<имя>.txt), ключи туннелей xsteer (/etc/steer/xsteer/*.conf), файлы своих туннелей WireGuard и AmneziaWG — выходов kind: awg (/etc/steer/awg/*.conf), выбор у групп pick: manual (/etc/steer/select, строки «группа член») и поля uci splify2.main (sub_url, sub_kind, sub_title, wizard, fetch_via_tunnel, geo_url), у именованных подписок — url, kind, title. От плагинов — их разделы: у lists-catalog — свои списки (list_domains_<имя>, list_prefixes_<имя>) и настройки, у subscriptions — расписание и настройки, у остальных официальных — настройки.

Чего в архиве нет. Списков каталога в /etc/steer/lists: они не настройка, а копия публикуемого издателем, одинаковы у всех, обновляются суточной задачей плагина и доскачиваются сами перед каждой проверкой спеки (хук pre_spec_set плагина lists-catalog). Остатка трафика подписок тоже нет — это не настройка.

Формат — строчный, с разделами в квадратных скобках; содержимое разделов дословное.

splify2-backup 5
# комментарий
[spec]
{"version":2,...}
[sub]
vless://...
[select]
eu wg1
[sub work]
vless://...
[xsteer home]
[Interface]
PrivateKey = ...
[awg nl]
[Interface]
PrivateKey = ...
[plugin lists-catalog list_domains_mine]
 example.org
[plugin subscriptions schedule]
 work 60
[options]
sub_url=https://example.org/sub
sub_kind=url
wizard=<непрозрачная строка мастера>
sub_work.url=https://example.org/sub2

Версия формата — по набору разделов: 3 — разделы каркаса, 4 — плюс разделы плагинов [plugin <id> <имя>] (их строки едут с отступом в один пробел), 5 — плюс файлы своих туннелей [awg <имя>]. Разбор принимает версии с 1 по 5; более новую, неизвестный или повторённый раздел отвергает целиком. Архив версии 3 и старше со своими списками разделами [list domains|prefixes <имя>] и полями manifest_url, list_shrink_factor, sub_auto, sub_<имя>.auto в [options] восстанавливается: списки и поля каталога переезжают в разделы плагина lists-catalog, интервалы — в раздел schedule плагина subscriptions.

backup_get (write) — плагин backup#

Группа write, хотя метод только читает: архив несёт приватные ключи туннелей и ссылки подписок, и учётной записи «только чтение» их отдавать нельзя. По той же причине xsteer_link — в write.

  • Вход: { "offset": <байт, 0 — собрать заново> }.
  • Выход: { "ok": true, "format": <3|4|5>, "total": <байт>, "offset": <байт>, "next": <байт>, "eof": <bool>, "text": "<кусок архива>" }. offset/next/total — байты, которые считает роутер: следующий кусок запрашивают ровно тем next, который приехал (в UTF-8 символ длиннее байта).
  • Отказы: backup.export_failed («Cannot export the settings»), backup.build_failed («Cannot build the archive»), backup.not_built («The archive is not built: request it from the start» — кусок с ненулевым offset без собранного архива), backup.too_big_out («The settings with their own lists do not fit into the archive: {size} KB with a limit of {max} KB»).

Архив собирается в рабочем каталоге плагина на offset: 0 и дальше отдаётся из него: пересборка на каждом куске означала бы, что куски приезжают из разных мгновений.

backup_put (write) — плагин backup#

  • Вход: { "text": "<кусок>", "append": <bool>, "final": <bool> }. append — дописать к уже принятому, final — это последний кусок, начинай разбор. Оба поля булевы: число приезжает как INT32, и blobmsg_parse молча отбросит его.
  • Выход на промежуточном куске: { "ok": true, "bytes": <накоплено> }.
  • Выход на последнем: { "ok": true, "spec": <bool>, "sub": <bool>, "subs": N, "xsteer": N, "awg": N, "select": <bool>, "plugins": N, "lists": [ { "name": "...", "kind": "domains|prefixes", "count": N, "dropped": N } ], "warn": "<если что-то требует внимания>" }. subs, xsteer и awg — сколько именованных подписок, ключей туннелей xsteer и файлов своих туннелей легло на место, select — лёг ли выбор у групп, plugins — сколько плагинов приняли свои разделы (поля нет, если ни одного), lists — свои списки, которые восстановил lists-catalog. Раздел плагина, которого на роутере нет, не восстанавливается — об этом warn.
  • Отказы с кодом: backup.too_big_in («The archive is larger than {max} KB: settings are never that large»), backup.empty («The archive is empty»), backup.binary («The archive holds binary data: this is not a settings file»). Отказы разбора и проверки приходят текстом без code: «This is not a splify2 settings file», «The file is version {file}, this plugin understands up to {max}», «Unknown section: {text}», причина проверки каркаса, «Plugin {id}: {why}» от проверки плагина, «The archive has neither settings nor lists».

Восстановление не применяет. Спека кладётся на место, но apply не зовётся, а снимок применённого (spec.applied.json) остаётся прежним — восстановленное выглядит как неприменённое. Применяет его плагин autoapply (Andromeda после восстановления просит autoapply_kick; без открытой страницы — задача sweep), без него — открытая страница или кнопка «Применить» базового вида.

Присланный файл — недоверенный ввод. Проверяется, по порядку:

  1. Размер — накопленный архив не больше настройки плагина max_archive_kb (2048 КБ по умолчанию); считается по сумме кусков, а не по куску. Тем же пределом ограничена выгрузка: backup_get не отдаёт архив, который backup_put не примет.
  2. Двоичные данные — весь файл, кроме перевода строки и табуляции, обязан быть печатным.
  3. Разделы — строгий разборщик: непонятный заголовок, повторный раздел, строка вне раздела, строка раздела плагина без отступа и чужая первая строка отвергают файл целиком. Имена файлов в песочнице собираются из проверенных регулярным выражением частей; из присланного файла ни один путь не берётся.
  4. Проверка всего, ничего не записывая. Настройки каркаса — служба хоста state check: спека не больше 64 КБ, без экранированных управляющих символов, имена выходов, устройств и членов групп — только [A-Za-z0-9_.:@-], пути списков — под /etc/steer/lists, файлы подписок — /etc/steer/sub.txt или под /etc/steer/subs, conf выхода — под /etc/steer, без ..; подписка не больше 128 КБ — ссылки узлов, блок base64 или JSON; раздел [options] не больше 8 КБ и только ключи из списка выше (ссылки — http(s):// без пробелов, кавычек, $, |, <, >); файлы своих туннелей — той же проверкой формы, что у awg_put. Разделы плагинов проверяет каждый плагин сам (операция check хука backup_sections); свои списки lists-catalog проверяет тем же разбором и пределом 1 МБ, что и при загрузке списка. Отказ любой проверки отменяет восстановление целиком.
  5. Запись. Сначала разделы плагинов (свои списки — спека из архива ссылается на них), затем настройки каркаса: подписки, ключи и файлы туннелей, поля uci, потом спека — её проверяют хук pre_spec_set и ядро. Если спеку отверг ядро, ответ говорит и это: подписки и ключи из архива уже на диске.

Состояние интерфейса#

ui_get (read) и ui_set (write)#

Состояние мастера настройки, которое создал человек. Хранится непрозрачной строкой в uci (splify2.main.wizard), отдельно от спеки: формат принадлежит интерфейсу и меняется вместе с ним, обёртка его не разбирает.

  • ui_get — вход: нет; выход: { "state": "<строка, возможно пустая>" }.
  • ui_set — вход: { "state": "<строка>" }; выход: { "ok": true }. Строка не длиннее 64 КБ: больше — отказ, называющий предел и присланный размер.

lists_source (read) · lists_source_set (write) — плагин lists-catalog#

Откуда роутер берёт каталог списков — перечень «какие списки бывают, как они называются и где лежит каждый». Адрес — настройка плагина manifest_url; без неё — каталог по умолчанию из схемы настроек плагина (релиз splify2-lists). Эта пара методов — тот же выбор, но одной ссылкой из панели списков.

  • lists_source — { "ok": true, "url": "<действующая>", "default_url": "<по умолчанию>", "default": <bool> }. Признак «каталог по умолчанию» считает плагин.
  • lists_source_set {url} — записать. Пустая строка возвращает каталог по умолчанию. Ссылка обязана начинаться с https:// или http:// (lists.catalog_url, «The catalog link starts with https:// (or http://)»); пробелы, кавычки, $ и переводы строк отвергаются (lists.url_chars, «The link has invalid characters») — значение уезжает в аргумент скачивания. Выход — как у lists_source.

Кэш каталога (/etc/steer/plugins/conf/lists-catalog/manifest.json) при записи удаляется: он от прежнего каталога, и метод lists скачает новый. Уже скачанные списки не трогаются: они лежат в /etc/steer/lists, на них ссылаются правила.

Каталог может называть НАБОРЫ, а не только файлы. У записи бывают format: "srs" и своя url: тогда скачивается набор sing-box по этой ссылке, ядро раскладывает его на домены и подсети (steer srs-read), а на диск ложатся обе половины по путям из file — обычно <источник>/<имя>.srs.lst и <источник>/domains/<имя>.srs.lst. Так каталог описывает чужие релизы, не перекладывая их к себе, — и добавить сервис становится правкой каталога, а не новой сборкой splify2.

fetch_mode (read) и fetch_mode_set (write) — плагин lists-catalog#

Качать ли списки, пакеты и подписки через туннель. Режим общий для всего, что скачивает каркас, поэтому хранит его хост (splify2.main.fetch_via_tunnel, служба fetch-mode), а методы — окно к нему в плагине lists-catalog. Значения два:

  • off (по умолчанию) — туннель не трогать. Остаются прямой адрес и обходные адреса самого GitHub (см. «Скачивание» в соглашениях).
  • always — качать через туннель: файл едет по своему прямому адресу одним запросом, без обходных. Если поднятого выхода нет, порядок обычный — режим не превращается в отказ.

Значения 1, on, yes, true в uci понимаются как always, всё остальное — как off.

  • fetch_mode — вход: нет; выход: { "mode": "always|off", "out": "<имя выхода или пусто>" }. out — выход, через который пойдёт скачивание; пусто — поднятого выхода со своей таблицей нет и включать нечего.
  • fetch_mode_set — вход: { "mode": "always|off" }; выход: { "ok": true, "mode": "..." }. Иное значение — fetch.bad_mode («The mode is always or off»).

DNS#

Шифрованный DNS (DoH, DoT, DoQ) и обычный DNS с выбором выхода — встроенный резолвер ядра, он настраивается в спеке (раздел dns, методы spec_get / spec_set). Методов для https-dns-proxy нет: настройка этого пакета — дело человека, и splify2 её не создаёт, не читает и не правит.

Проверки и устройства#

outbound_probe (read)#

  • Вход: { "output": "<имя выхода>" }.
  • Выход: { "output": "...", "code": "ok|no_answer|no_device", "state": "<слова>", "ms": <мс или -1>, "how": "..." }. Ветвиться — по code; state и how — слова для человека на языке каркаса.

Для туннелей, которые поднимает само ядро, спрашивает ядро, потому что ICMP через их TUN не идёт: vless — steer vless-probe (ms — ответ через туннель, ttfb_ms), hysteria2 — steer hysteria2-probe, прокси steer-proxy (trojan, shadowsocks, socks, http, vmess) — steer proxy-probe (у обоих ms — рукопожатие с запросом, handshake_ms). Задержка берётся только у ответившего узла. Для выхода-интерфейса пингует через устройство.

outbound_geo (read) — плагин node-check#

Где выходит трафик выхода: страна и адрес, как их видит внешняя сторона.

  • Вход: { "output": "<имя выхода>", "fresh": <bool> }. fresh заставляет сходить в сеть, даже если запомненное ещё свежее.
  • Выход: { "output": "...", "ip": "1.2.3.4", "cc": "DE", "ms": <время ответа через выход>, "at": <когда измерено>, "cached": <bool> }; ip, cc, ms, at — когда они известны. В системе нет curl — вдобавок "curl": false.
  • Без fresh метод в сеть не ходит: отвечает запомненным (cached: true), а если измерения нет или оно старше настройки плагина geo_ttl_s (900 с по умолчанию) — запускает новое в фоне; следующий вызов получит свежее. Фоновый замер выхода — не чаще настройки geo_retry_s (60 с): у узла, который не отвечает, замер не удаётся, и без паузы каждый опрос страницы стучался бы к нему заново.
  • С fresh меряет сейчас (cached: false); не вышло — прежнее измерение и why (nodes.no_answer, «No answer through the output: it is not up, curl is missing or the check address is silent»). Недопустимое имя выхода — req.bad_output.

Меряется, а не читается из подписки: имя узла («🇩🇪 Германия №2») пишет продавец, у выходов поверх WireGuard и xsteer имени нет вовсе, а узел мог переехать. Запрос уходит через сам выход (служба хоста probe geo): у туннеля vless, hysteria2 или прокси, TCP которого ядро steer несёт по метке выхода, — с меткой выхода (временная таблица nft метит порты источника curl и не выпускает их мимо туннеля), у остальных выходов — привязкой к их устройству (curl --interface).

Отвечает https://1.1.1.1/cdn-cgi/trace (переопределяется через uci set splify2.main.geo_url=...): ближайший узел Cloudflare, без ключа, две строки простого текста. Адресом, а не именем: по имени сервер туннеля может сам выбрать IPv6 сайта, и тогда виден IPv6 сервера, а не IPv4, которым выход ходит наружу. Запрос идёт по IPv4 (curl -4); ms — полное время запроса (соединение, TLS, ответ). Измерение запоминается в рабочем каталоге плагина в памяти вместе с номером устройства выхода: пересоздано устройство (сменился узел) — запомненное не отдаётся.

vless_probe (read)#

  • Вход: { "output": "<имя выхода>", "node": <номер, -1 — первый рабочий> } или { "sub": "<путь к файлу подписки>", "node": <номер, -1 — все по порядку подписки> }; с sub — необязательный insecure (как у vless_nodes: номера как у выхода с insecure). Путь принимается только из перечня подписок роутера — тот же рубеж, что у vless_nodes: метод читает файл с диска, и произвольный путь означал бы чтение произвольного файла.
  • Выход: JSON steer vless-probe дословно.

Вариант с подпиской нужен редактору выхода: узел выбирают там, где выход собирают, а «какой из них живой» надо знать до того, как на подписку заведён хоть один выход. Перебор всех узлов подписки на роутере, с ходом и лучшим узлом, — методы nodes_* плагина node-check (раздел «Методы плагинов»).

Интерфейс проверяет один узел на вызов: проверка ограничена таймаутом, и «все узлы» вышли бы за время жизни вызова rpcd. Ядро при node: -1 с sub проверяет узлы подряд по порядку подписки, так что такой вызов длинный.

hysteria2_nodes (read) и hysteria2_probe (read)#

То же, что vless_nodes и vless_probe, для выхода protocol: hysteria2: те же входы (output либо sub; для проверки ещё node), те же рубежи на имя и путь, ответ — JSON steer hysteria2-nodes / steer hysteria2-probe дословно (формат узла общий). Нужен плагин ядра hysteria2: без него отказ ядра доезжает до экрана как есть.

proxy_nodes (read) и proxy_probe (read)#

То же для выходов прокси (плагин ядра proxy) — protocol: trojan, shadowsocks, socks, http, vmess: те же входы (output либо sub; для проверки ещё node) и те же рубежи, ответ — JSON steer proxy-nodes / steer proxy-probe дословно; поле type узла называет протокол. Номера узлов у двух входов разные, так их считает ядро: у файла подписки (sub) — сквозные по всем пяти протоколам, у выхода (output) — среди узлов его протокола, и именно их ждёт nodes выхода. proxy_probe с sub принимает сквозной номер. С sub — необязательный insecure, как у vless_nodes (узлы trojan и https с allowInsecure). Задержка у прокси — handshake_ms (рукопожатие и запрос через узел), ttfb_ms ядро печатает -1. Без плагина proxy отказ ядра доезжает как есть.

dns_log (read) и conns (read)#

Ответ steer dns-log и steer conns дословно. dns_log: последние имена, которые спрашивали у резолвера (правило, выход, число, возраст), upstreams[] — серверы DNS (name, url, proto: udp/tcp/dot/doh/doq, via — выход или null, state: ready/idle/connecting/down/ unmarked/no-tls, счётчики, last_ok_ago, последняя ошибка словами) и cache (entries, max, hits, misses) либо null, когда кэша нет. conns: соединения, которые ядро повело в свои выходы (не больше 2000 записей, поле truncated); ядро не отдало ответ (conntrack недоступен) — {ok: false, error} словами ядра. Раздел «Запросы» Andromeda просит conns и dns_log в общем круге опроса панели (тот же такт, что и состояние), пока экран открыт и нет паузы: кто (имя из аренд DHCP или адрес), куда, выход, узел и правило — точно, когда в выход ведёт одно правило (метка соединения — метка выхода, а не правила), иначе перечнем правил этого выхода. Имена из dns_log — имя, правило, выход и узел, «мимо правил», сколько раз и когда спрашивали, «Почему сюда» — вызов explain; серверы и кэш из того же ответа — в разделе «DNS». Журнал ядра (engine_state) «Диагностика» просит тем же способом.

list_peek (read) — плагин lists-catalog#

Что лежит в списке — для показа («глазик» у пилюли списка в правиле приложения для ПК). Только чтение и только в каталоге списков (/etc/steer/lists): путь вне его — отказ. Набор sing-box (.srs) раскладывает ядро (steer srs-read). Ответ: total — записей всего, found — совпавших с q (поиск без учёта регистра), text — до 300 записей строками.

list_srs_put (write) — плагин lists-catalog#

Свой список из набора sing-box (.srs): по ссылке (url) или файлом — base64 порциями (data, append у второй и дальше, final у последней), как list_put, без второго транспорта. Ядро раскладывает набор на домены и подсети, каждая непустая половина ложится своим списком с этим именем (как у list_put), половина, которой в наборе больше нет, у списка убирается. Ответ — domains и prefixes: сколько записей легло. Предел — как у своего списка.

recheck_info (read) · recheck_set (write)#

ReCheck — обход DPI на трафике, который уходит из сети напрямую в WAN, самостоятельная часть splify2: служба /etc/init.d/splify2-recheck ставит таблицу inet splify2_recheck (первые пакеты соединений — в очередь 4340, наблюдение — в 4341; пакеты с битом 0x40000000 — трафик ядра и уведённый в выходы — не трогает; таблица ловит и IPv4, и IPv6, частные адреса и link-local мимо) и запускает программу /usr/sbin/steer-dpi-live из отдельного пакета recheck. Настройки — /etc/splify2/recheck.conf, строка на ключ.

recheck_info → installed (пакет recheck стоит), version, running, enabled, interface (заданный WAN, пусто — по маршруту по умолчанию), wan (действующий), epoch, persist (память в /etc/splify2/recheck.cache, иначе в /tmp), watch_active, resources[] (адреса проверки, до 4), queued/watched (пакетов отдано recheck), state — файл памяти recheck как есть (DPI7, до 64 адресов и 8 семейств; recheck пишет его раз в 5 минут и при остановке), events — последние события recheck из журнала (event=… host=… ip=… port=…).

recheck_set — любые из полей: enabled, interface, persist (память переносится), watch_active (без адреса проверки recheck его не принимает — служба не передаёт), resources (только https://, до 4 — столько принимает recheck), epoch_bump (провайдер сменился: записи прежней эпохи recheck при загрузке отбрасывает), forget (стереть изученное). Служба перезапускается; enabled=0 — останавливается и снимает таблицу.

dns_probe (read)#

Проверка серверов DNS с роутера тем же кодом, которым ходит резолвер ядра: steer dns-probe --timeout 3000 URL[=IP,IP] …, все серверы разом, общий срок 3 с. Вход — urls: адрес сервера, как в dns.upstreams.*.url, по желанию с «=адрес,адрес» (минуя bootstrap). Ответ ядра дословно: results[] — url (без «=адресов»), proto, ok (годный ответ), ms (вопрос по поднятому соединению), first_ms (с подъёмом соединения), error. Ядро без этой команды — {unsupported: true, error}: сервер не проверен, это не то же, что «не отвечает».

helper (read)#

Вход: { "output": "<имя выхода>" }. Живое состояние помощников выхода из памяти демона (steer ctl helper): ответ управляющего сокета как есть — {code, stdout, stderr}, где stdout — строка JSON на помощника (running, up, since, restarts, last_down, у VLESS node и total, у модуля module, module_ver и rejected: true, если демон отверг модуль чужой версии, у моста tgws paths_down). Протокола нет — last_down словами ядра называет нужный плагин. Помощника у выхода нет или демон не запущен — code 1.

Andromeda спрашивает его у выходов с помощником (VLESS, hysteria2, прокси, xsteer, tgws, интерфейс с обфускацией) при открытии «Выходов» и заново при смене состояния выходов и показывает в строке выхода состояние и число перезапусков.

spec_heal (write)#

Вход пустой. Первым делом спека приводится к виду, который принимает ядро: выходы kind: zapret убираются (обход DPI не поддерживается), правила и апстримы DNS, ссылавшиеся на них (out), идут в direct (если выхода direct в спеке не было, он заводится на месте первого убранного), on_fail: zapret у остальных выходов становится direct. Правка — вставка текста, замена атомарна, до неё спеку принимает ядро; прежняя спека остаётся копией spec.json.zapret.bak (одна, старейшая), в журнал пишется строка splify2: …. Пакет zapret и его настройка не затрагиваются. Повторный вызов ничего не меняет. То же делает каждый apply — в его output первой строкой идёт splify2: DPI bypass (zapret) is no longer supported: outputs removed …, rules moved to direct: N (код текста heal.zapret, на языке каркаса); в ответе spec_heal — поле zapret с этой строкой. Затем выходам kind: interface и awg без ключа ipv6, чьё устройство лежит в зоне фаервола steer_zone без masq6, записывается ipv6: nat либо ipv6: off — смотря по адресу IPv6 у самого устройства: без ключа ядро в диагностике просит включить masq6 у зоны, которую завели мы.

  • nat (подмену IPv6 на устройство ставит ядро) — у устройства есть адрес IPv6 области global (ULA тоже: так считает ядро), живой (ip -6) либо записанный в настройке сети его интерфейса (addresses, ip6addr; у интерфейса WireGuard без опции device устройство называется как интерфейс). У выхода awg устройство заводит ядро при apply, а лечение идёт до него, — адрес ищется в строках Address файла настройки (conf, а без него /etc/steer/awg/<имя>.conf).
  • off — адреса IPv6 у устройства нет: выход IPv6 не несёт, клиенты идут по IPv4. Подмену адреса клиентов у туннеля, которому подменять нечем, ядро встретило бы отказом диагностики («у X нет адреса IPv6»).
  • Ничего не пишется, когда решать не нам: у интерфейса задан ip6prefix (раздача префикса туннеля — дело человека, ipv6: routed он пишет сам) или устройства нет и о нём ничего не известно.

Явные routed, off, nat, выходы с устройством в чужой зоне и спека v1 не трогаются. Зона устройства — своя либо чужая — узнаётся и по списку device, и через логический интерфейс (список network: так пишет зоны LuCI); имя устройства, которого в настройке сети нет (pptp-vpn), спрашивается у netifd (ubus call network.interface dump). Правка — вставка текста без перезаписи файла, замена атомарна, до неё спеку принимает компилятор. Если спека изменилась и уже применялась (есть снимок), метод применяет её как apply. Тот же шаг делает каждый apply: в его output — строка про nat и строка про off с именами выходов (каждая — если такие выходы были). Вызывается из /etc/uci-defaults/99-splify2 при установке и обновлении пакета. Выход: { "ok": true, "healed": <bool>, "outputs": "<имена вылеченных выходов через пробел>", "nat": "<имена выходов, которым записан nat>", "off": "<имена выходов, которым записан off>" }.

devices (read)#

Кандидаты в выход kind=interface и в члены группы: { "devices": [ { "name", "up": <bool>, "kind": "<DEVTYPE>", "ipv6": "nat" | "off", "owner": "steer" } ] }. Только туннельные устройства (ARPHRD_NONE и ARPHRD_TUNNEL, без ссылки device). Отбор по типу, а не по имени: на современном OpenWrt порты SoC называются lan2, wan, и выход в физический порт молча ничего не маршрутизирует. Устройства выходов, которые поднимает само ядро (vless, hysteria2, прокси, xsteer), есть в перечне и когда они не подняты — с up: false и пустым kind: имена спрашиваются у ядра (--devices).

ipv6 — что панель пишет в ключ ipv6 НОВОМУ выходу на этом устройстве: nat — у устройства есть адрес IPv6, off — нет. Правило то же, что у spec_heal (там оно описано): живой адрес области global либо адрес в настройке сети его интерфейса. Поля нет, когда решать не бэкенду (у интерфейса задан ip6prefix) и у устройств, которые поднимает ядро: ключ тогда не пишется, и по устройству решит самолечение при apply.

owner — чьё это устройство. "steer" — устройство выхода, которое заводит и держит само ядро (kind vless, hysteria2, прокси — trojan, shadowsocks, socks, http, vmess, — xsteer под демоном и awg): это не свой туннель человека, а внутренность выхода. Метка стоит и у поднятых устройств, и у выключенных, перечисленных выше. Поля нет у остальных — WireGuard, AmneziaWG, OpenVPN, xsteer через netifd (по умолчанию xs-…): их настраивает человек в сети роутера. В /sys те и другие неотличимы (оба ARPHRD_NONE), различает спека: имена устройств выходов ядра спрашиваются у самого ядра (outputs --kind <вид> --devices, вызов на вид), а не выводятся из имён выходов. Хозяин — выход, который устройство завёл: пул kind=interface, назвавший устройство ядра (смешанный пул), метку не снимает.

Метка ничего не убирает из перечня и порядок не меняет. Панель по ней не показывает такие устройства в «Своих туннелях» и не называет их в подписи этого входа: переключатель завёл бы второй выход kind=interface поверх туннеля ядра, а выключатель вынимал бы устройство из выходов, которые его называют, — вплоть до удаления самого выхода. Редактор выхода по-прежнему предлагает их локациями пула. Устройство awg помечается, когда оно есть в системе, а выключенным в перечень не добавляется. Ядро имён не назвало (спека пуста или не разбирается) — меток нет, а перечень остаётся устройствами из /sys.

xsteer_state (read)#

Живое состояние туннелей xsteer: то, чего в настройке нет.

Зачем отдельным методом, а не полем live. Туннель xsteer, поднятый через netifd, ядру не принадлежит: в спеке он — обычный kind: interface, и status знает про него ровно то, что знает про любое устройство. Какой хаб отвечает, сколько секунд назад было рукопожатие, встала ли разгрузка сегментации, сколько раз соединение переподнималось и почему — знает только процесс пира, и он пишет это в свой файл состояния (/var/lib/steer/xsteer-<устройство>.json, схема описана в steer/docs/xsteer.md). Читать эти файлы на каждом круге опроса всем, у кого xsteer нет вовсе, незачем.

  • Вход: нет.
  • Выход:
{ "ok": true, "tunnels": {
    "home": { "device": "xs-home", "age": 2, "state": { "up": true, "hub": "203.0.113.7:443",
              "offload": {"gso": true, "gro": true, "rx": true}, "resets": 3, "…": "…" } },
    "work": { "device": "xs-work", "state": null } } }

Перечень туннелей берётся из настройки сети (секции proto xsteer), а не из списка устройств: иначе выключенный интерфейс исчезал бы с экрана вместо того, чтобы показать, что он выключен.

state — содержимое файла ядра как есть, без пересборки схемы: разбирать чужой JSON, чтобы тут же собрать заново, значило бы переписывать чужую схему у себя (так же поступает status). state: null означает «туннель не поднимался в эту загрузку» — это НЕ то же, что «поднят и молчит», и различать их человек сюда и приходит.

age — возраст файла в секундах. Порог «устарело» решает интерфейс, потому что он знает, как часто спрашивает: процесс, которого убили, оставляет файл лежать навсегда, и без возраста его последнее up: true выглядело бы живым.

Выходы спеки kind: xsteer — отдельной картой outputs (ключ — имя выхода, перечень — steer outputs --kind xsteer). Их клиента держит демон ядра steer, и файла состояния такой клиент не пишет: helper — строка помощника из ответа steer ctl helper <выход> (running, up, since, restarts, last_down, module, module_ver, rejected; см. метод helper), null — демон о нём не знает (не запущен, без --supervise). Хаба, рукопожатия и счётчиков у демона нет. Клиент, запущенный без демона, пишет файл xsteer-<выход>.json — он отдаётся в state с age, как у туннеля netifd; нет файла — state: null.

{ "ok": true, "tunnels": {},
  "outputs": { "xa": { "helper": { "helper": "xsteer", "running": true, "up": true,
                                   "since": 1790000000, "restarts": 0, "…": "…" },
                       "state": null } } }

Ссылка xs:// в обе стороны, и направление выбирает вход:

  • {"iface":"home"} → {ok, link} — ссылка на этот туннель (перенести тот же доступ на телефон);
  • {"link":"xs://…"} → {ok, conf} — текст конфигурации из ссылки (им заполняет поля страница сети).

Так же устроена подкоманда ядра steer xsteer-link, и по той же причине: человек здесь всегда хочет «дай мне другой вид того же самого».

Печатает и разбирает ядро. Формат ссылки описан один раз (steer, src/proto/xsteer/xslink.c) и сверяется побайтово с половиной на Go; сборка или разбор строки здесь были бы третьей реализацией одного формата — и первой, у которой нет стенда. Ссылка уходит ядру стандартным вводом, а не аргументом: аргументы видны в списке процессов всякому, кто есть на роутере, а в ссылке лежит приватный ключ.

Источник для печати — готовый файл /var/run/xsteer/<интерфейс>.conf, собранный обработчиком протокола из uci. Собирать конфигурацию здесь во второй раз нельзя: два места, превращающие uci в настройку, однажды разойдутся, и разойдутся молча. Отсюда следствие, названное человеку прямо: у выключенного интерфейса файла нет, и ссылку отдать неоткуда.

Принять ссылку: записать её в настройку интерфейса xsteer и поднять его (ifup). Интерфейса с таким именем нет — метод заводит его сам (секция network.<имя> с proto=xsteer).

  • Вход: {iface, link}.
  • Выход: {ok, iface, hub, device} и created: true, когда интерфейс заведён этим вызовом, или {ok:false, error, code}.

Интерфейс создаётся здесь, а не в настройках сети. Всё, что ему нужно, лежит в ссылке: ключ, адрес, хаб, MTU — задавать руками нечего. Зону фаервола ставит apply устройству каждого выхода спеки, так что интерфейс, взятый в выход, зону получает. Протокол наш — обработчик netifd ставит пакет splify2, — поэтому это не чужая настройка. Имя нового интерфейса — буквы, цифры и _, до 12 знаков (xs.bad_new_iface): устройство называется xs-<имя>, а ядро Linux принимает 15. Имя, занятое интерфейсом другого протокола или другой секцией сети, — отказ xs.not_xsteer: чужое не переписывается. Негодная ссылка секции не оставляет: интерфейс заводится после разбора.

Заведённый интерфейс записан в расписке /etc/splify2/net-owned (xsteer <имя>), и полное удаление убирает его по ней; интерфейс xsteer, созданный человеком в настройках сети, остаётся его.

Ссылку разбирает ядро, оно же её и проверяет: она приходит от человека, то есть это недоверенный ввод, и разбирать её здесь значило бы держать третью реализацию формата и надеяться, что она отвергает то же самое. Значения берутся из текста конфигурации, которое вернуло ядро, — по строкам, а не по позициям.

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

Единственный метод в этом контракте, который пишет /etc/config/network. Интерфейс поднимается (ifup) сразу после записи: человек вставил ссылку, чтобы туннель заработал, а не чтобы получить запись в файле.

awg_list (read), awg_put, awg_del (write)#

Свой туннель WireGuard или AmneziaWG файлом или текстом, без настроек сети роутера. Выход kind: awg заводит устройство сам — из файла формата wg-quick/awg-quick, который человеку выдал сервер; эти методы принимают такой файл, перечисляют принятые и удаляют ненужные. Файл лежит там, где ядро ищет его по имени выхода: /etc/steer/awg/<имя>.conf (каталог 0700, файл 0600), поэтому ключ conf в спеку не пишется. Зону фаервола устройству ставит apply, ключ ipv6 — самолечение спеки.

awg_put

  • Вход: {name, text, replace?}. name — будущее имя выхода: буквы, цифры, _ - ., до 31 знака, не с точки. text — текст файла целиком (до 256 КБ — предел ядра). replace: true — заменить файл туннеля, который уже есть под этим именем.
  • Выход:

json { "ok": true, "name": "nl", "conf": "/etc/steer/awg/nl.conf", "endpoint": "203.0.113.7:51820", "addresses": ["10.8.0.2/32"], "amnezia": true, "ipv6": "off", "checked": true, "plugin": "awg", "plugin_ready": true, "output": { "kind": "awg", "on_fail": "drop", "ipv6": "off" } }

или `{ok:false, error, code}`: `awg.bad_name`, `awg.need_text`, `awg.name_taken` (имя занято
выходом другого вида либо выходом `awg` со своим `conf` — он читает другой файл), `awg.exists`
(файл с этим именем уже есть, а `replace` не задан), `awg.big`, `awg.binary`, `awg.format`, `awg.no_interface`, `awg.no_key`,
`awg.no_peer`, `awg.rejected` (слова ядра), `awg.not_saved`.

Проверок две. Форма — здесь: один раздел [Interface] с PrivateKey, хотя бы один [Peer] с PublicKey, строки только вида «Ключ = значение». Значения — у ядра: steer apply --dry-run над спекой из одного этого выхода читает файл и называет негодную строку (checked: true). Ядро без плагина awg вида не знает и проверить не может: файл принимается по форме (checked: false, plugin_ready: false), а ядро проверит его при применении.

Выход в спеку метод не добавляет — это делает вызывающий, положив output под именем name в outputs и записав спеку через spec_set. У спеки есть ревизия и черновик панели, и запись за спиной черновика кончилась бы отказом spec.changed либо потерей правок. Плагин awg (plugin_ready: false) вызывающий ставит заданием plugin_install до записи спеки: без него ядро отвергнет выход.

Файл с тем же именем замещается только с replace: true — так меняют настройку туннеля, который уже в работе: ядро кладёт новую поверх живого устройства при следующем применении. Без replace — отказ awg.exists: второй туннель под тем же именем (файлы у серверов часто зовутся одинаково) иначе молча заменил бы ключи первого.

Приватный ключ не возвращается никогда: ни awg_put, ни awg_list содержимого файла не отдают, отказ называет номер строки и имя параметра, но не значение. amnezia — нужен ли файлу модуль AmneziaWG (правило то же, что у ядра); ipv6 — что писать ключу ipv6 выхода: nat, если в Address есть адрес IPv6, иначе off.

awg_list

  • Вход: нет.
  • Выход: {ok, plugin_ready, dir, tunnels: [{name, conf, endpoint, addresses, amnezia, ipv6, outputs}]}; outputs — выходы сохранённой спеки, читающие файл (пусто — файл без выхода).

awg_del

  • Вход: {name}.
  • Выход: {ok, name} или отказ: awg.no_such, awg.in_use (называет выходы сохранённой спеки), awg.in_use_applied (выход убран, но правка ещё не применена — туннель работает).

Файлы туннелей едут в архиве настроек (разделы [awg <имя>]) и уходят при полном удалении вместе с каталогом /etc/steer.

client_nets (read)#

Обратный вопрос к devices: не куда выпустить трафик, а откуда приходят клиенты. Устройства роутера, которые могут быть сетью клиентов, и подсети, выведенные из их адресов.

  • Вход: нет.
  • Выход:

json { "nets": [ { "name": "br-lan", "up": true, "wan": false, "usable": true, "why": "", "subnets": ["192.168.1.0/24"] }, { "name": "tailscale0", "up": true, "wan": false, "usable": true, "why": "", "subnets": ["100.64.1.5/32"] }, { "name": "tun-vless", "up": true, "wan": false, "usable": false, "why": "This is the device of your output: traffic leaves through it rather than coming from clients", "subnets": [] }, { "name": "wan", "up": true, "wan": true, "usable": false, "why": "The interface leads outward: it brings the whole world beyond the router, not your network", "subnets": ["46.42.16.0/22"] } ] }

Отсеивается ровно два случая, и оба не по имени: lo (петля клиентом не бывает) и порт внутри моста (есть ссылка master — клиенты приходят через мост, правило по порту не увидело бы ни одного пакета). Внешний интерфейс помечается, а не прячется: какое устройство наружу, знает uci (network.wan.device), а выкинутое из списка устройство человек ищет глазами и решает, что перечень сломан — помеченное он просто не выберет.

usable и why отвечают на вопрос годится ли устройство в источники (why — слова на языке каркаса, коды clientnet.*). Различаются два вида туннелей, и различие содержательное. Туннель, через который уходим НАРУЖУ мы сами (клиент wireguard до провайдера, tun-vless, устройство любого нашего выхода), источником быть не может: отметив его, человек ждёт «маршрутизировать тех, кто ко мне подключается», а получает попытку забирать трафик из туннеля, через который сам и уходит. А туннель, через который к нам ПРИХОДЯТ другие устройства (сервер wireguard, Tailscale, ZeroTier), — законный источник, ради него перечень lan_devices и заведён.

Признаки, по которым это решается: устройство названо в спеке устройством нашего выхода (точный, спрашивается у ядра); через него идёт маршрут по умолчанию; proto=xsteer в конфигурации сети; у интерфейса wireguard есть пир с allowed-ips 0.0.0.0/0 (клиент до провайдера) против узких allowed-ips (сервер для своих); и отдельным поводом — wan. По ИМЕНИ не отсеивается ничто: tailscale0 ни одним признаком не задет, а если человек сам сделал его устройством выхода, его поймает первый признак.

Негодные не удаляются из ответа, как и wan: выкинутое устройство человек ищет глазами и решает, что перечень сломан. Уже отмеченный в спеке интерфейс, ставший негодным, вкладка обязана показать и назвать — это его настройка, и молча выбросить её нельзя. Поля usable и why печатаются всегда.

subnets — подсказка, по которой человек узнаёт устройство, и ничего больше: ядро отвечает на «кто» правилом iifname по именам из lan_devices, а не по адресам. Считается она тем же правилом, каким адрес обнуляется по маске префикса, — чтобы показанное совпадало с тем, что видно в ip addr. У Tailscale адрес обычно /32, то есть подсеть пиров из него не выводится вовсе; именно поэтому клиентов и описывают именем устройства. Устройство без адреса отдаётся с пустым subnets, а не пропускается: выбрать его законно, адрес появится при поднятии.

leases (read)#

Аренды DHCP — имена устройств по MAC: { "leases": [ { "mac", "ip", "name" } ] } из /tmp/dhcp.leases (* вместо имени — пустая строка). Нужны, чтобы в правиле можно было выбрать устройство по имени, а в спеку положить MAC: адрес меняется, MAC живёт.

net_info (read)#

Сводка сведений о туннеле одним вызовом (вместо трёх отдельных вызовов ubus на каждый опрос: каждый вызов стоит запуска shell).

Поля: uptime — секунды работы демона ядра (steerd daemon; 0 — не запущен), active_clients — число разных частных адресов (10/8, 172.16/12, 192.168/16, 100.64/10), с которых сейчас открыты соединения (по conntrack, без адресов самого роутера и без подсети внешнего интерфейса).

Внешний адрес здесь намеренно отсутствует: чтобы его узнать, запрос должен уйти через туннель, а steer маршрутизирует по метке пакета, а не по адресу источника — привязка к адресу устройства туннеля всё равно отправит запрос по маршруту по умолчанию и вернёт адрес провайдера. Уверенный неверный ответ хуже отсутствующего.

Плагины#

Вкладка «Плагины» и методы самих плагинов. Хозяин плагинов — ядро steer: менеджер steer plugin … --json (команды сокета plugin-*, steer-api, 4.2) ставит, снимает, включает и обновляет. Бэкенд — тонкая обёртка: одно действие менеджера на метод, ответ менеджера не пересказывается (массивы плагинов, каталога и репозиториев приходят из ядра как есть), отказ несёт слова менеджера — место, совместимость, выходы, которым плагин нужен — без правок.

Что бэкенд ждёт от менеджера (форма вывода --json, на которую опираются методы ниже):

Команда Вывод
steer plugin list --json объект с массивом plugins (или сам массив): запись как в state.json — id, version, repo, state, why, auto_update, pinned, плюс доступное обновление
steer plugin search [слово] --json объект с массивом plugins (или сам массив): каталог всех репозиториев
steer plugin repo list --json объект с массивом repos (или сам массив)
steer plugin status [id] --json объект состояния
install <id> [версия], update [id], remove <id> [--force] [--purge], enable <id>, disable <id>, autoupdate <id> on\|off, repo add <url> <номер ключа> (ключ — телом, stdin), repo del <имя>, ensure <id>… при успехе код 0 и (необязательно) объект результата; при отказе код не 0 и слова причины в поле error JSON-ответа либо в stderr

Отказ плагинной части — единый объект с машинным словом: { "ok": false, "error": "<текст на языке каркаса>", "code": "<слово>", "msg": "<код текста>", "args": { … } }. code: bad_request (вход), not_installed, disabled, no_method, unavailable (у плагина нет программы), timeout, failed, busy (менеджер занят другим запросом), no_job. Ещё одно слово — core_too_old: менеджер отказал, а ядро старше 2.1 (менеджер плагинов — с 2.1); в ответе поля installed (версия ядра) и need (2.1). Версию называет ядро (steer version --json, у ядер без --json — первая строка steer X.Y.Z …), текст отказа не разбирается; ядро 2.1 и новее или неизвестная версия дают failed. Текст отказа — plugin.core_too_old («The core {installed} does not support plugins: {need} or newer is required»); базовый вид на core_too_old пишет «Plugins need steer 2.1 or newer. Installed: …».

Задания. Установка и обновление идут минуты (менеджер ждёт сеть и проверяет здоровье до 600 с), а rpcd ждёт обработчик 120 с. Эти методы отвечают сразу — { "ok": true, "job": "<номер>" } — и работают в отдельном процессе, итог читает plugin_job. Задание живёт час после последнего изменения.

Права. Группы ACL — в таблице методов; методы самих плагинов — ACL splify2-p-<id> из манифеста.

plugins_list (read)#

Открытие вкладки и загрузка интерфейсов плагинов: установленные плагины, подключённые репозитории, версия host API панели.

  • Вход: { "lang"?: "ru" } — язык человека; без него названия идут на en.
  • Выход:

json { "ok": true, "host_api": "1.0.0", "names": { "vless": { "name": "VLESS", "description": "…" } }, "plugins": [ { "id": "vless", "version": "2.1.1", "repo": "splify2", "state": "enabled", "why": null, "auto_update": true, "pinned": null } ], "repos": [ { "name": "splify2", "url": "https://…", "official": true } ] }

- `plugins`, `repos` — массивы менеджера как есть; пустой список — `[]`, не отказ.
- `names` — название и описание стоящих плагинов на языке `lang` (ключи `plugin.name` и `plugin.description`
    словаря `i18n/<язык>.json` плагина; порядок: язык, язык без региона, `en`). Плагина, у которого словаря нет,
    в объекте нет — интерфейс берёт `name` и `description` из `plugins` (слова манифеста).
- `repos_error` — есть только если `steer plugin repo list` не ответил: плагины при этом показываются.
- Побочное действие: ссылки и ACL объектов плагинов приводятся в согласие с тем, что стоит и включено
    (после обновления прошивки плагины на месте, а ссылки rpcd — нет); если что-то изменилось, rpcd
    перечитывается через две секунды.
  • Отказ: слова менеджера; ядро без менеджера — plugin.core_cannot («The core does not support plugins. Update steer.»).

plugins_search (read)#

Каталог всех подключённых репозиториев.

  • Вход: { "query"?: "слово" }; слово не начинается с дефиса.
  • Выход: { "ok": true, "plugins": [ … ] } — массив менеджера как есть.

repos_list (read)#

  • Вход: нет. Выход: { "ok": true, "repos": [ … ] } — массив менеджера как есть.

plugin_status (read)#

  • Вход: { "id"?: "vless" } — без id состояние всех.
  • Выход: { "ok": true, "status": { … } } — ответ менеджера целиком под ключом status.

plugin_job (read)#

Ход и итог задания.

  • Вход: { "id": "<номер задания>" }.
  • Выход:
    • идёт — { "ok": true, "id", "state": "running", "progress"?: "последняя строка менеджера" };
    • готово — { "ok": true, "id", "state": "done", "result"?: { … } }, result — ответ менеджера, если он объект JSON;
    • не удалось — { "ok": false, "id", "state": "failed", "error": "…", "code": "failed" } (слова менеджера как есть; процесс пропал — job.aborted, «The job was interrupted»);
    • нет такого задания — { "ok": false, "code": "no_job", "msg": "plugin.no_job", "error": "No such job" }.

plugin_install (write) и plugin_update (write)#

  • Вход: plugin_install — { "id": "vless", "version"?: "2.1.1" }; plugin_update — { "id"?: "vless" }, без id обновляются все.
  • Выход: { "ok": true, "job": "<номер>", "id"?: "vless" }. Итог — plugin_job. По завершении (в процессе задания, до отметки «готово») ссылки и ACL объектов плагинов приведены в согласие и rpcd перечитан.
  • Отказ сразу: bad_request — недопустимое имя плагина (plugin.bad_name) или версия (plugin.bad_version).

plugin_remove (write), plugin_enable (write), plugin_disable (write)#

  • Вход: { "id": "vless" }; у plugin_remove ещё force и purge (булевы): force снимает плагин, чей вид есть в спеке; purge убирает и настройки плагина. Системные пакеты менеджер не снимает.
  • Выход: { "ok": true, "id": "vless", "result"?: { … } } (result — ответ менеджера, если он объект). Ссылки и ACL объектов плагинов приведены в согласие. Перечитать список — дело интерфейса.
  • Отказ: слова менеджера; снятие плагина, нужного выходам, называет их (код ядра steer.plugin.needed_by_outputs, «The plugin {id} is needed by the outputs: {outputs}; to remove it anyway, use --force»).

plugin_autoupdate (write)#

  • Вход: { "id": "vless", "enabled": true } — обе поля обязательны. Выход: { "ok": true, "id", "enabled" }.

repo_key (read)#

Номер ключа репозитория — человек видит его до того, как принять ключ.

  • Вход: { "key": "<открытый ключ: файл .pub целиком или строка base64>" }.
  • Выход: { "ok": true, "key_id": "<16 знаков hex>" }; не ключ — bad_request, repo.key_unknown («The key is not recognized»).

repo_add (write)#

  • Вход: { "url": "https://…", "key": "<файл .pub>", "key_id"?: "<номер>" }. Номер ключа считается здесь; присланный key_id (тот, что человек видел и принял) обязан совпасть.
  • Выход: { "ok": true, "key_id": "…" }. Ключ уходит менеджеру телом, номер — словом.
  • Отказ: bad_request — repo.need_https, repo.bad_url, repo.key_unknown, repo.key_mismatch («The key number {want} does not match the key ({id})») — и слова менеджера.

repo_del (write)#

  • Вход: { "name": "<имя репозитория>" }. Выход: { "ok": true, "name" }.

plugin_call (write)#

Метод самого плагина через объект splify2 — для шлюза приложения вне LuCI (/v1/plugin/<id>/<метод>), у которого нет сессии ubus. В LuCI тот же вызов идёт объектом splify2.p.<id> с ACL из манифеста; диспетчер один.

  • Вход: { "id": "recheck", "method": "status", "params": { … } }; params — объект, программа плагина получает его JSON-ом на stdin (нет — {}).
  • Выход: ответ программы плагина как есть (объект JSON). Код программы не 0 — { "ok": false, "error": "<stderr>", "code": "failed" } (stderr пуст — plugin.exit_code); ответ не объект JSON — failed, plugin.bad_reply («Plugin {id} gave an unexpected reply»); срок (timeout_s метода, по умолчанию 30 с) — timeout, plugin.timeout.
  • Метод с job: true отвечает { "ok": true, "job": "<номер>" }; итог — plugin_job, result — ответ программы.
  • Отказы до вызова: not_installed — plugin.not_installed («Plugin {id} is not installed»); disabled — plugin.disabled («Plugin {id} is off. Turn it on in the Plugins tab.»); no_method — метода нет в rpc.methods манифеста (plugin.no_method); unavailable — у плагина нет программы (plugin.no_program) или методов (plugin.no_methods).

Объекты ubus плагинов splify2.p.<id>#

На каждый включённый плагин с rpc в манифесте бэкенд держит:

  • ссылку /usr/libexec/rpcd/splify2.p.<id> → общий обработчик /usr/lib/splify2/plugin-rpcd (имя объекта rpcd берёт из имени файла);
  • ACL /usr/share/rpcd/acl.d/splify2-p-<id>.json — группа splify2-p-<id>, read и write из access методов манифеста.

Интерфейс плагина (манифест объявляет ui): ссылка /www/luci-static/resources/splify2/plugins/<id> → <каталог плагина>/ui (раздаётся только ui/); создаёт и убирает тот же plugin_sync.

Главный экран плагина (манифест объявляет splify2.luci.interface, splify2-api 1.1): ссылка /www/luci-static/resources/view/splify2/p-<id> → <каталог плагина>/luci (раздаётся только luci/); тот же plugin_sync.

Обработчик: list отдаёт методы манифеста, call <метод> запускает <каталог плагина>/<rpc.prog> <метод> (рабочий каталог — каталог плагина, переменные STEER_PLUGIN_ID, STEER_PLUGIN_DIR, STEER_PLUGIN_CONF), параметры — JSON на stdin, ответ — JSON на stdout; форма ответов и отказов — как у plugin_call. Ссылки и ACL создаёт и убирает plugin_sync (после plugin_install/update/remove/enable/disable, при plugins_list и командой splify2-plugin-sync из postinst пакета); отключённый плагин получает отказ disabled, снятый — not_installed.

Шлюз приложения (плагин desktop-api, в семя не входит): GET|POST /v1/plugin/<id>/<метод> (тело POST — параметры). Отказ плагинной части приходит статусом HTTP: bad_request — 400, not_installed и no_method — 404, disabled, unavailable и busy — 409, timeout — 504, failed — 500; тело — { "error": "<code>", "message": "<текст>" }. Ответ самого плагина с ok: false без code идёт со статусом 200 как есть. Долгий метод — с ?async=1, как любой вызов шлюза.

Каркас на LuCI JS#

Методы, которые зовёт каркас view/splify2/core — базовый вид на LuCI JS (открывается главной страницей, когда настройка interface велит, и всегда по ?basic=1). Каркас написан по-английски, перевод даёт языковой плагин (i18n_get).

spec_schema (read)#

Схема всех ключей спеки: steer spec-schema --json, то есть тот же источник, что у разбора ядра, плюс виды плагинов. Формат — подмножество JSON Schema с расширениями ядра x-…: x-variants и x-discriminator (выход и сервер DNS по видам), x-when, x-when-set, x-needs (условия), x-ref, x-one-or-list, x-name, x-example, x-absent, x-plugin, x-plugins, x-unsupported, x-platform, x-path, x-secret. Полное описание — steer/docs/spec-schema.md.

  • Вход: нет.
  • Выход: { "ok": true, "source": "core"|"bundled", "schema": { … } }. Ядро не ответило схемой — схема из пакета (/usr/share/splify2/spec-schema.json) и source: "bundled": формы тогда следуют пакету, а не ядру, и каркас пишет об этом на экране «Overview».

spec_check (read)#

Проверка спеки ядром (steer check) без записи. Временный файл лежит рядом со спекой: относительные пути в ней считаются от каталога файла спеки.

  • Вход: { "spec": "<спека текстом>" } — YAML (его показывает каркас) или JSON (текст, начинающийся с {, идёт как JSON). YAML переводит ядро: steer spec convert --json --spec -.
  • Выход: { "ok": true[, "warn": "…"] } или { "ok": false, "error": "слова ядра"[, "line": 5, "col": 3] }. line и col — адрес ошибки разбора в присланном тексте, когда ядро его назвало; слова error — без адреса. Отказ самой проверки (steer apply --dry-run) идёт без line и col: она читает перевод, а не текст человека.

spec_set принимает тот же вход (YAML или JSON) и отвечает отказом разбора так же: {ok:false, error, line?, col?}. Комментарии YAML не сохраняются: на диск ложится печать ядра (spec_put), а не присланный текст.

spec_yaml (read)#

Спека так, как её печатает ядро в YAML (steer spec convert без --json): то, что показывает сырой редактор каркаса. Комментарии рукописного spec.yaml в печать не попадают.

  • Вход: нет.
  • Выход: { "ok": true, "yaml": "<текст>", "rev": "<ревизия, как у spec_get>" }; спеки нет — version: 2. rev каркас отдаёт обратно в spec_set, чтобы запись поверх чужой правки отказала (conflict).

prefs_get (read) и prefs_set (write)#

Настройки каркаса. interface — что открывается главной страницей: basic или id плагина-интерфейса — плагина с splify2.luci.interface в манифесте (splify2-api 1.1; так встаёт Andromeda). Выбор хранится в uci splify2.main.interface. Пока человек не выбирал, это andromeda, если плагин Andromeda стоит и включён, иначе basic. Выбор, названный плагином, которого нет или который отключён, страница не исполняет: открывается basic с сообщением.

  • prefs_get — вход: нет; выход: { "ok": true, "interface": "andromeda", "interface_set": false, "andromeda": true, "interfaces": [{ "id": "andromeda", "view": "view.splify2.p-andromeda.home" }], "lang": "auto" } (interfaces — установленные и включённые плагины-интерфейсы, view — модуль LuCI для L.require; andromeda — true, когда в interfaces есть Andromeda; lang — язык LuCI, auto — язык браузера; ui_lang — язык, выбранный в интерфейсе, auto — не выбран).
  • prefs_set — вход: { "interface": "basic", "ui_lang": "ru" }, оба поля необязательны, но хотя бы одно нужно (иначе prefs.nothing). interface — строчные буквы, цифры, дефис; ui_lang — код вида en или pt-br, auto снимает выбор (иначе prefs.bad_lang). Выход: { "ok": true } с переданными полями. Тексты отказов бэкенда идут на ui_lang, когда язык LuCI — auto или не задан.

paths (read)#

Где хост держит то, что интерфейс иначе зашивал бы в код (splify2-api 1.1): тот же ответ, что у службы хоста paths для программ плагинов. Вход: нет; выход: { "ok": true, "lists": "/etc/steer/lists", "spec_dir": "/etc/steer", "subs_dir": "/etc/steer/subs", "steer": "/usr/sbin/steer" } — каталог списков, каталог спеки (относительные пути в спеке отсчитываются от него), каталог подписок, программа ядра. Значения следуют швам хоста (LISTS, SPEC, SUBS_DIR, STEER).

i18n_get (read)#

Словари каркаса для языка: каждый включённый плагин может нести i18n/core/<язык>.json (плоский «английский текст → перевод», подстановки {имя}, множественное число объектом форм one/few/many/other под ключом формы other).

  • Вход: { "lang": "ru" } или pt-BR. Выход: { "ok": true, "lang": "ru", "dicts": [ { "plugin": "lang-ru", "dict": { … } } ] }; пустой массив — словарей нет, каркас остаётся английским. Каркас пробует pt-BR, затем pt.

plugin_settings_get (read) и plugin_settings_set (write)#

Настройки плагина по его обязательной схеме. Манифест: "splify2": { "settings": { "schema": "<файл в каталоге плагина>" } } (подмножество JSON Schema, как у ключей вида); значения лежат в conf/<id>/settings.json — файле, который читает сам плагин.

  • plugin_settings_get — вход: { "id": "vless" }; выход: { "ok": true, "id", "schema": { … }, "values": { … } }; без схемы — { "ok": false, "code": "no_settings" }; плагина нет — not_installed.
  • plugin_settings_set — вход: { "id", "values": { … } } (объект до 256 КБ; в сигнатуре rpcd его нет, как у params в plugin_call); выход: { "ok": true, "id" }. Файл заменяется атомарно; проверка значений — дело формы и плагина.

Методы плагинов#

Новые имена на объекте splify2, которые дают официальные плагины. Их нет в блоке list) диспетчера: rpcd узнаёт их из реестра плагинов при перечитке, пока плагин стоит и включён; права — в ACL плагина splify2-p-<id>. Плагина нет или он выключен — метода на объекте нет: ubus отвечает «Method not found» (или, пока rpcd не перечитал объект, каркас — req.unknown_method). Отказы плагинной части (срок, ответ не по форме) — как у plugin_call.

Метод плагина Плагин Права Вход на stdin
autoapply_status autoapply read —
autoapply_now autoapply write —
autoapply_kick autoapply write —
autoapply_cancel autoapply write —
group_status group-check read {group?}
group_history group-check read {group, limit?}
group_check group-check write {group?}
nodes_check node-check write {sub, insecure?}
nodes_result node-check read {sub}
nodes_best node-check read {sub}
nodes_cancel node-check write {sub}
subs_schedule subscriptions read —
update_status updater read —
update_check updater write —

autoapply_status (read) — плагин autoapply#

Применяет ли роутер сохранённое сам и в каком он состоянии.

{ "ok": true, "enabled": true, "pause_s": 1, "since": 1790000000, "pending": true, "applying": false,
  "unapplied": true, "rejected": false, "state": "pending",
  "last": { "ok": true, "at": 1789999000, "source": "pause", "message": "" } }
  • enabled, pause_s — настройки плагина; since — когда поставлено ожидание (есть только при pending: true).
  • state — одно слово для интерфейса: applying — роутер применяет; pending — ждёт паузу после правки; rejected — ядро отвергло именно эту спеку, повтора не будет, пока она не изменится; unapplied — сохранено и не применено (применит задача sweep или autoapply_kick); idle — всё применено. Порядок проверки — как в перечислении: применение идёт — applying, даже если ждёт и следующее.
  • last — исход последнего применения плагином: source — pause (после правки), sweep (задача), manual (autoapply_now); message — первая строка ошибки или вывода. Поля нет, пока плагин ничего не применял.

autoapply_now (write) — плагин autoapply#

Применить сохранённое сейчас и дождаться исхода — и при выключенной настройке enabled. Ожидание снимается.

  • Выход: применять нечего — { "ok": true, "applied": false }; иначе { "ok": <bool>, "applied": <bool>, "rc": <0|1|3>, "message": "…" }: 0 — применено, 1 — ядро отвергло, 3 — применение не состоялось (ядро занято коннектором, применение остановил хук плагина).

autoapply_kick (write) — плагин autoapply#

Применить сохранённое сейчас, не дожидаясь исхода: ответ сразу, исход — в autoapply_status. Andromeda зовёт его, когда открыта с неприменённым и в конце пачки правок.

  • Выход: { "ok": true, "scheduled": true, "enabled": true }; при выключенной настройке enabled ничего не делает — { "ok": true, "scheduled": false, "enabled": false }.

autoapply_cancel (write) — плагин autoapply#

Отменить ожидающее применение. Выход: { "ok": true, "cancelled": <bool> } — было ли что отменять.

group_status (read) — плагин group-check#

Приговор по каждому члену групп выходов спеки (или одной группы group).

{ "ok": true, "groups": [ { "name": "eu", "checked": 1790000000, "alive": 1, "total": 2, "members": [
    { "name": "nl", "verdict": "alive", "ms": 42, "failures": 0, "since": 1789990000 },
    { "name": "de", "verdict": "dead", "failures": 3, "since": 1789999000 } ] } ],
  "hints": [ { "code": "member_dead", "group": "eu", "member": "de" } ] }

verdict — alive, unstable (отказал меньше dead_after раз подряд), dead, unknown (проверять нечем: вложенная группа, выход без устройства); ms — только у живого; checked — когда группу пробовали (0 — ещё не пробовали); hints — по записи на мёртвого члена. Отказы: spec.none («There is no spec»), group.bad_name («Invalid group name»).

group_history (read) — плагин group-check#

  • Вход: { "group": "eu", "limit": 50 } — limit необязательный, по умолчанию 50.
  • Выход: { "ok": true, "entries": [ { "at": <unix>, "kind": "verdict|switched|failed", "text": "…" } ] } — последние перемены приговоров и события ядра по группе. Без группы — group.none_given («No group given»).

group_check (write) — плагин group-check#

Проверить сейчас, не дожидаясь расписания: проба каждого члена (метод каркаса outbound_probe). Выход: { "ok": true, "checked": <проверено групп> }; нет такой группы — group.none («There is no group "{name}"»).

nodes_check (write) — плагин node-check#

Запустить перебор узлов подписки на роутере, в фоне: не больше parallel (настройка плагина) проверок сразу, каждый узел — методом своего протокола (vless_probe, hysteria2_probe, proxy_probe).

  • Вход: { "sub": "<имя подписки или путь к её файлу узлов>", "insecure": <bool> }.
  • Выход: { "ok": true, "started": true, "running": true }; перебор этой подписки уже идёт — { "ok": true, "started": false, "running": true }.
  • Отказы: sub.none_given («No subscription given»), sub.not_exists, sub.not_downloaded.

nodes_result (read) — плагин node-check#

Ход и итог перебора.

{ "ok": true, "state": "running", "started": 1790000000, "total": 26, "done": 10, "ok_count": 7,
  "best": { "name": "🇳🇱 NL-1", "proto": "vless", "index": 3, "ms": 120 }, "why": "<первая причина отказа>",
  "nodes": [ { "proto": "vless", "index": 3, "name": "🇳🇱 NL-1", "checked": true, "ok": true, "ms": 120 } ] }

state — running, done (тогда ещё finished), stopped (процесс пропал или перебор остановлен) или none (перебора не было: ответ { "ok": true, "state": "none" }). index — номер узла в его протоколе, как у nodes выхода; у непроверенного узла checked: false.

nodes_best (read) — плагин node-check#

Самый быстрый из ответивших: { "ok": true, "found": true, "name", "proto", "index", "ms", "complete": <bool> }; complete — перебор закончен. Ответивших нет — { "ok": true, "found": false }; перебора не было — nodes.not_started («The node search has not been started»).

nodes_cancel (write) — плагин node-check#

Остановить перебор подписки. Выход: { "ok": true, "cancelled": <bool> }.

subs_schedule (read) — плагин subscriptions#

Расписание всех подписок одним ответом: { "ok": true, "subs": [ { "name", "auto": <минуты>, "auto_at": <unix> } ] }. В ответе — подписки, у которых задан интервал; auto — 0, если интервал вне нынешних пределов настроек; auto_at — время последней попытки, 0 — попыток не было.

update_status (read) — плагин updater#

Итог последней проверки выпусков, пересчитанный по тому, что стоит сейчас (после установки отметка «есть новее» гаснет сама). В сеть не ходит.

{ "ok": true, "checked_at": 1790000000, "channel": "stable",
  "steer":   { "current": "2.1.0", "latest": "2.1.1", "available": true },
  "splify2": { "current": "26.11.0", "latest": "26.11.0", "available": false } }

Проверки ещё не было — { "ok": true, "checked_at": 0 }. Менеджер пакетов не ответил — pkg.manager_silent.

update_check (write) — плагин updater#

Проверить сейчас: спросить перечень выпусков (см. «Перечень выпусков») и запомнить итог. Выход: { "ok": true, "checked_at", "channel", "steer": { "current", "latest", "prerelease"? }, "splify2": { … } }; у продукта, перечень которого не получен, вместо latest — why (updater.no_list, «The release list was not received»). При канале prerelease новее считается и текущая предварительная, если она новее стабильной. Поля available здесь нет — его считает update_status.

Перечень методов#

Все 98 объявленных методов каркаса (из блока list) скрипта rpcd) и их группа ACL. Методы вида moved (см. начало документа) работают, только пока стоит их плагин; новые имена от плагинов — в разделе «Методы плагинов».

Метод ACL Вход на stdin
status read —
spec_get read —
applied_get read —
spec_set write {spec}
apply write —
explain read {address}
lists read —
list_fetch write {id, kind}
lists_update write —
devices read —
client_nets read —
local_lists read —
allow_domains read —
list_custom read —
list_get read {name, kind, offset}
list_peek read {path, q?}
list_srs_put write {name, url} или {name, data, append?, final?, filename?}
list_remove write {id, kind} (id может быть itdog:<сервис>) или {name, kind}
list_put write {name, kind, text, url, append, source, filename}
engine read —
sub_set write {url, name, title, links}
sub_info read {name}
sub_list read —
sub_del write {name}
sub_rename write {name, title}
sub_auto write {name, minutes}
sub_refresh write {name}
sub_quota write {name}
backup_get write {offset}
backup_put write {text, append, final}
live read {diag, fast}
dev_stats read —
diag read —
net_info read —
outbound_probe read {output}
outbound_geo read {output, fresh}
leases read —
engine_state read —
support_report read —
ui_get read —
ui_set write {state}
xsteer_state read —
xsteer_link write {iface} или {link}
xsteer_link_put write {iface, link}
awg_list read —
awg_put write {name, text, replace?}
awg_del write {name}
lists_source read —
lists_source_set write {url}
fetch_mode read —
fetch_mode_set write {mode}
vless_nodes read {output} или {sub, insecure?}
vless_probe read {output, node} или {sub, node, insecure?}
hysteria2_nodes read {output} или {sub}
hysteria2_probe read {output, node} или {sub, node}
proxy_nodes read {output} или {sub, insecure?}
proxy_probe read {output, node} или {sub, node, insecure?}
dns_log read —
dns_probe read {urls}
conns read —
helper read {output}
spec_heal write —
engine_stop write —
engine_start write —
purge write {plan?, keep_config?}
splify2_versions read —
splify2_install write {version}
steer_versions read —
steer_install write {version, modules?}
steer_modules read —
steer_module_add write {module}
steer_module_del write {module}
plugins_list read {lang?}
plugins_search read {query?}
repos_list read —
plugin_status read {id?}
plugin_job read {id}
plugin_install write {id, version?}
plugin_update write {id?}
plugin_remove write {id, force?, purge?}
plugin_enable write {id}
plugin_disable write {id}
plugin_autoupdate write {id, enabled}
repo_key read {key}
repo_add write {url, key, key_id?}
repo_del write {name}
plugin_call write {id, method, params?}
spec_schema read —
spec_check read {spec}
spec_yaml read —
prefs_get read —
prefs_set write {interface?, ui_lang?}
paths read —
i18n_get read {lang}
plugin_settings_get read {id}
plugin_settings_set write {id, values}
recheck_info read —
recheck_set write {enabled, interface, persist, watch_active, resources, epoch_bump, forget} — любые из полей

Источник истины#

Документ выведен из кода: диспетчер files/usr/libexec/rpcd/splify2 (быстрый путь круга опроса, блок list, таблица «метод → группа»), файлы групп files/usr/lib/splify2/rpcd/ (common.sh — общие помощники, m-<группа>.sh — ветки методов группы; разнесено, чтобы на каждый вызов разбирался только нужный файл), таблица methods.tsv, службы хоста files/usr/sbin/splify2-host и плагины plugins/<id>/ (манифест, bin/). Если документ и код расходятся — прав код.