Контракт объекта 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.tsvsplify2-api (tests/exttest.shсверяет её с диспетчером), ACL LuCI (барьер вbuild.sh), таблица ниже (проверкаtests/pkgmatch.sh, в обе стороны) и вызовы интерфейса — Andromeda в репозиторииandromeda(стендtests/api-calls.shсверяет их со спискомmethods.tsvsplify2-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. Путей у неё три, по очереди:- прямой адрес;
- тот же файл с других адресов — сначала зеркало на GitLab
(
gitlab.com/<владелец>/<репозиторий>/-/raw/<ветка>/<путь>: тот же путь, сырой файл со своего домена, без заголовка и без счётчика запросов), затем хосты самого GitHub — поштучно черезapi.github.com/repos/…/contents/…(заголовокAccept: application/vnd.github.raw), а если API отказал — из архива ветки черезcodeload.github.com. Для ссылок релиза ветка —dist: релизный workflow выкладывает в неё те же пакеты; - через туннель роутера — но ТОЛЬКО если человек это включил (
fetch_mode): на время скачивания добавляетсяip rule to <адрес> lookup <таблица выхода>с приоритетом 30000 и снимается сразу после. У туннеля vless, hysteria2 или прокси, TCP которого ядро steer несёт по метке выхода, вместо правила запрос curl получает метку выхода (временная таблица nftsplify2_om<N>_<pid>метит его порты источника и не выпускает их мимо туннеля; снимается сразу после) — для этого нужен curl. Включённый туннель идёт ПЕРВЫМ, а не последним.
Провайдеры закрывают
githubusercontent.comцеликом (raw.,objects.иrelease-assets.— одни адреса Fastly), и тогда роутер лишался бы и списков, и пакетов, хотя сам GitHub доступен. Третий путь не делается, если адрес издателя совпал с адресом узла подписки (это была бы петля), если имя разрешается в fake-IP198.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), без него — открытая
страница или кнопка «Применить» базового вида.
Присланный файл — недоверенный ввод. Проверяется, по порядку:
- Размер — накопленный архив не больше настройки плагина
max_archive_kb(2048 КБ по умолчанию); считается по сумме кусков, а не по куску. Тем же пределом ограничена выгрузка:backup_getне отдаёт архив, которыйbackup_putне примет. - Двоичные данные — весь файл, кроме перевода строки и табуляции, обязан быть печатным.
- Разделы — строгий разборщик: непонятный заголовок, повторный раздел, строка вне раздела, строка раздела плагина без отступа и чужая первая строка отвергают файл целиком. Имена файлов в песочнице собираются из проверенных регулярным выражением частей; из присланного файла ни один путь не берётся.
- Проверка всего, ничего не записывая. Настройки каркаса — служба хоста
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 МБ, что и при загрузке списка. Отказ любой проверки отменяет восстановление целиком. - Запись. Сначала разделы плагинов (свои списки — спека из архива ссылается на них), затем настройки каркаса:
подписки, ключи и файлы туннелей, поля 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 } } }
xsteer_link (write)#
Ссылка 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_link_put (write)#
Принять ссылку: записать её в настройку интерфейса 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/). Если документ и код расходятся — прав код.