Skip to content

Latest commit

 

History

History
86 lines (66 loc) · 6.78 KB

splify2-api-1.3.md

File metadata and controls

86 lines (66 loc) · 6.78 KB

splify2-api 1.3 — что добавлено к 1.2

splify2 26.11 говорит splify2-api 1.3. Прибавка к splify2-api.md, splify2-api-1.1.md и splify2-api-1.2.md: плагин, написанный по 1.0–1.2, работает без изменений. Плагину, которому нужно новое, пишут compat.splify2-api: "^1.3".

Нужда: выход kind: awg — туннель WireGuard или AmneziaWG, который ядро steer создаёт само по файлу /etc/steer/awg/<имя>.conf (плагин ядра awg). Файл попадает на роутер через панель, и ей нужны методы, которые его проверят, положат и уберут.

Методы awg_list, awg_put, awg_del

Три строки methods.tsv, все вида frame: плагин вправе звать их, обернуть или заменить (methods.override), имя занять нельзя.

Метод Доступ Параметры Что делает
awg_list чтение — перечисляет файлы туннелей в /etc/steer/awg/
awg_put запись name, text, replace проверяет конфигурацию и кладёт файл /etc/steer/awg/<name>.conf с правами 0600
awg_del запись name убирает файл туннеля

awg_list

{ "ok": true, "plugin_ready": true, "dir": "/etc/steer/awg",
  "tunnels": [
    { "name": "home", "conf": "/etc/steer/awg/home.conf", "endpoint": "198.51.100.7:51820",
      "addresses": ["10.8.0.2/32"], "amnezia": false, "ipv6": "off", "outputs": ["home"] }
  ] }
  • plugin_ready — плагин ядра awg включён: без него выход kind: awg не применится.
  • amnezia — в файле есть параметры AmneziaWG; ipv6 — "nat" или "off".
  • outputs — имена выходов спеки, которые используют файл.

awg_put

Параметры: name — имя будущего выхода (буквы, цифры, _, -, ., до 31 байта, не с точки); text — конфигурация в формате wg-quick или awg-quick; replace (необязательный, true) — заменить файл, который уже есть под этим именем.

{ "ok": true, "name": "home", "conf": "/etc/steer/awg/home.conf", "endpoint": "198.51.100.7:51820",
  "addresses": ["10.8.0.2/32"], "amnezia": false, "ipv6": "off",
  "checked": true, "plugin": "awg", "plugin_ready": true,
  "output": { "kind": "awg", "on_fail": "drop", "ipv6": "off" } }
  • Метод проверяет форму конфигурации и просит ядро проверить файл (steer apply --dry-run над спекой с одним выходом). checked — проверка ядром была. Ядро без плагина awg вида не знает и файл не проверяет: он кладётся по проверке формы, checked: false, plugin_ready: false; то же, когда ядро не ответило вовсе.
  • Файл с тем же именем замещается только с replace: true — так меняют конфигурацию туннеля, который уже в работе. Без него отказ awg.exists: второй туннель под тем же именем не заменяет молча ключи первого. Имя выхода другого вида или выхода awg со своим ключом conf (он читает другой файл) — отказ awg.name_taken.
  • Закрытый ключ не возвращается и не пишется в журнал.
  • Спеку метод не пишет. Выход добавляет тот, кто звал: объект output ответа кладётся в спеку под именем name через spec_set. У спеки есть ревизия и черновик панели — метод, который пишет спеку мимо черновика, разошёлся бы с ним.

awg_del

Параметр name. Убирает файл. Пока файл использует выход сохранённой спеки, метод отказывает с кодом awg.in_use и называет эти выходы; выход убран, но правка не применена (файл читает применённая спека) — отказ awg.in_use_applied. Порядок: выход убирают из спеки (spec_set), применяют её, затем удаляют файл.

xsteer_link_put создаёт интерфейс сам

Строка methods.tsv не менялась, изменилось поведение. Если интерфейса <iface> нет, метод сам создаёт раздел network.<iface> с proto=xsteer и добавляет в ответ created: true — раньше он отказывал с кодом xs.not_xsteer_create. В ответе теперь всегда есть device — имя устройства интерфейса (xs-<iface> или заданное device_name). Имя нового интерфейса — буквы, цифры и _, до 12 знаков (отказ xs.bad_new_iface): устройство обязано влезть в 15 знаков ядра Linux. Интерфейс, который есть и у которого другой proto, и имя, занятое другой секцией сети, метод по-прежнему не трогает: отказ xs.not_xsteer. Заведённый интерфейс записан в расписке /etc/splify2/net-owned, и полное удаление убирает его по ней.

Архив настроек: формат 5

Плагин backup везёт файлы туннелей разделами [awg <имя>]; архив с ними — формата 5 (без них версия прежняя: 3, с разделами плагинов — 4). Служба хоста splify2-host state export|check|import выгружает, проверяет и кладёт их файлами awg.<имя>; ответ import несёт число awg.

Версии

  • PLUGIN_SPLIFY2_API хоста — 1.3.0.
  • Строка tests/compat/matrix.json: SDK 1.6.0 — splify2 26.11.0 — splify2-api 1.3.0, host-api 1.0.0, steer-api 1.5.0 (заглушка splify2-1.3).
  • s2p lint сверяет compat.splify2-api с 1.3.0.