splify2
Ядро steer

Спека v2 — справочник формата#

Спека v2 — формат, который ядро читает наряду с JSON со schema: 1|2 (спека v1, docs/contract-v1.md). Во что спека разбирается — разделы 3 и 4в docs/architecture.md; здесь — все ключи, умолчания и отказы. Разбор — src/model/v2.c, печать (steer spec convert; --json — та же спека JSON-объектом с теми же ключами, --spec - — со стандартного ввода) — src/model/v2print.c, стенд — tests/v2match.sh.

Те же ключи в машиночитаемом виде отдаёт steer spec-schema [--json] (spec-schema.md): типы, значения, умолчания, подсказки, условия и ключи каждого вида выхода, включая виды плагинов.

Формат и файл#

  • YAML (читается libyaml из дерева, src/third_party/libyaml) или JSON: JSON — это тоже YAML, и спеку v2 можно записать JSON-объектом с "version": 2. Алиасы и якоря (*имя, &имя), повтор ключа и несколько документов в одном файле — отказ (src/lib/ynode.h).
  • version: 2 наверху обязателен. Формат узнаётся по содержимому, а не по имени файла:
    • текст начинается с { — это JSON: ключ version наверху — спека v2, иначе — спека v1 с отказами v1 слово в слово; и version, и schema сразу — отказ;
    • всё остальное — YAML, то есть спека v2; YAML без version — отказ «нет version: 2», YAML со schema — отказ «спека v1 пишется JSON-объектом».
  • Файл по умолчанию — {etc}/spec.json (роутер: /etc/steer, телефон: /data/misc/steer) или {etc}/spec.yaml рядом. Лежит одна — читается она; нет ни одной — spec.json (туда пишет управляющий слой). Лежат обе — отказ «две спеки», а не правило старшинства: какая из двух настоящая, знает только тот, кто их положил, и молча читать одну значило бы, что правки во второй не действуют. Путь, названный --spec, читается как есть — кроме самих spec.json и spec.yaml по умолчанию: названный так путь значит «какая из двух лежит» (init-скрипт роутера всегда передаёт --spec /etc/steer/spec.json). Пакет роутера знает оба имени: init-скрипт (reapply), hotplug и список sysupgrade (/lib/upgrade/keep.d/steer).
  • steer apply --spec, клиент steer (тело apply демону) и ctl apply (тело спеки в сокет) — всё идёт через один разбор (load_spec), поэтому тело может быть и v1 JSON, и v2 YAML/JSON. ctl apply кладёт тело в тот файл, который сейчас спека (spec.json или spec.yaml), какого бы формата тело ни было.

Общие правила разбора#

  • Неизвестный ключ — отказ, на любом уровне, с подсказкой, какие ключи там есть. v1 незнакомые ключи пропускал (совместимость вперёд внутри мажора), и опечатка в ключе молча не действовала; у v2 совместимость вперёд держит version.
  • Ключ чужого вида — отказ («ключ strategy есть только у kind: recheck»).
  • Каждый отказ — с местом: файл:строка:столбец: что не так.
  • Перечень — список [a, b] или одно значение: to: youtube и to: [youtube] значат одно.
  • Строка — скаляр в любом стиле записи (wg0, "wg0"). Число и true/false — только без кавычек ("5" — строка, как в JSON), по базовой схеме YAML 1.2: yes/no/on/off — строки, а не логические значения.
  • Имена клиентов, списков, выходов и апстримов — латинские буквы, цифры, _ - ., до 31 байта; имя не начинается с - и не равно . или .. (имя уходит аргументом программам плагинов и в имена файлов состояния). У каждого раздела своё пространство имён. Занятые слова: клиент lan, список all.
  • Ссылки по именам (for, to, out, members, default, over, dns) проверяются: несуществующее имя — отказ; круг в группах и в over — отказ.
  • Ещё не поддерживается. То, что формат уже описывает, а ядро ещё не умеет, разбирается и проверяется как всё остальное (и хранится в модели там, где у модели есть место), но спека отвергается отказом ещё не поддерживается в этой версии ядра steer: … с местом в тексте. Этот отказ звучит ПОСЛЕ всех настоящих проверок: ошибка в спеке называется раньше, чем то, чего ядро ещё не умеет. Молча не игнорируется ничего. Перечень — в конце файла.

Пример#

То, что ядро принимает сегодня (стенд tests/v2match.sh проверяет, что оно разбирается):

version: 2

lan: { devices: [br-lan] }

clients:
  kids: { mac: [aa:bb:cc:dd:ee:01, aa:bb:cc:dd:ee:02] }
  tv:   { addr: [192.168.1.50] }

lists:
  work:  { prefixes_file: lists/work.lst, domains_file: lists/work.dom }
  voice: { prefixes_file: lists/dc.lst, proto: udp, ports: [50000-65535] }

outputs:
  wg0:  { kind: interface, device: wg0 }
  wg1:  { kind: interface, device: wg1 }
  nl:   { kind: tunnel, protocol: vless, subscription: sub/nl, nodes: [3, 5], over: wg0 }
  res:  { kind: group, pick: order, members: [wg0, wg1], on_fail: drop }
  fast: { kind: group, pick: latency, members: [nl, wg1], tolerance: 50 }
  eu:   { kind: group, pick: manual, members: [nl, res], default: nl }
  bal:  { kind: group, pick: balance, members: [nl, wg1], weights: [2, 1] }
  dpi:  { kind: block }

dns:
  mode: fakeip

rules:
  - { name: kids,  for: [kids], to: all, out: res, scope: device }
  - { name: work,  to: [work], out: fast, resolve: realip }
  - { name: voice, for: tv, to: voice, out: res }
  - { name: bulk,  for: tv, to: all, out: bal }

Разделы#

Все разделы необязательны, кроме version. Спека из одного version: 2 законна: ядро настроено и ничего не направляет (так же, как пустая спека v1).

version#

2, числом. Другое число — отказ «version N не поддерживается».

lan — клиенты по умолчанию#

for правила без клиентов значит «клиенты по умолчанию».

Ключ Значение Умолчание
devices перечень устройств, с которых ядро забирает трафик клиентов [br-lan]
addr перечень адресов, подсетей или диапазонов клиентов, IPv4 и IPv6 (в v1 — from_default); из одних IPv4 — IPv6 клиентов берётся по devices —

Отказы: пустой devices; имя устройства негодного состава; устройство дважды; addr рядом с несколькими devices (клиенты описаны дважды — «уберите addr»); выход, ведущий в устройство из devices (петля).

На роутере с Linux 5.10 и новее правила раздачи ставятся на хук ingress устройств из devices (docs/contract-v1.md, §7). Устройство, которого нет при apply, не отказ: его трафик размечается в prerouting, как на старом ядре, а в цепочку ingress оно попадает при следующем apply или reload. Клиент, заданный адресом, чей трафик приходит не с устройства из devices, тоже размечается в prerouting.

clients — именованные группы клиентов#

имя: { ключ: перечень }.

Ключ Значение
addr адреса, подсети или диапазоны IPv4 и IPv6 (смесь законна; клиент из одних IPv4 по IPv6 не узнаётся — нужен адрес IPv6 или mac)
mac MAC-адреса aa:bb:cc:dd:ee:ff
uid только на телефоне: UID приложения 10123 или диапазон 10000-10099
self только на телефоне: true — трафик всех приложений устройства
app только на телефоне: имена пакетов приложений — ещё не поддерживается (пишите uid)

Отказы: пустой клиент; addr и mac в одном клиенте (nft не умеет «или» внутри правила — два клиента); негодный адрес, в том числе с ведущим нулём в октете (010.1.1.1 nft прочёл бы восьмеричным — как 8.1.1.1); телефон (uid, self) вместе с клиентами раздачи; self рядом с uid; uid 0 (root); uid/self/app на роутере.

lists — назначения#

имя: { ключ: значение }.

Ключ Значение
srs перечень наборов sing-box (.srs): имена, подсети и сужение в одном файле
prefixes_file перечень файлов адресов и подсетей (строка списка — как у v1; строки IPv6 идут в парный набор <группа>6). Испорченная адресная строка (300.1.1.1, 10.0.0.0/33, 1.2.3.4/, 1...2, оборванная загрузка, диапазон задом наперёд, октет с ведущим нулём — 010.1.1.1) пропускается с одним предупреждением на список, а не отвергает весь набор правил
domains_file перечень файлов доменов
proto tcp, udp или both (записанное умолчание — сужения нет)
ports перечень портов 443 и диапазонов 50000-65535; диапазонов не больше 16 (каждый размножает адреса списка в составном наборе ядра)
all true — весь трафик (с сужением proto/ports, если оно нужно)
override_port подмена порта назначения, 1..65535: соединение TCP и UDP к поддельному адресу имени из списка уходит на настоящий адрес с этим портом (как override_port у route-options sing-box). Только у списка имён (domains_file без prefixes_file, srs и all) и только в режиме fakeip: подмена идёт по карте fake-IP. У списка с подменой свой набор (<выход>_dom_c<N>_p<M>), соседние имена того же выхода порт не теряют
domains, prefixes встроенные записи — ещё не поддерживается (вместо них — файлы)

Путь файла — до 255 байт; относительный путь — от каталога файла спеки (lists/dc.lst рядом с /etc/steer/spec.yaml — это /etc/steer/lists/dc.lst), спека со стандартного ввода — от рабочего каталога. Так же читаются subscription, conf и strategy у выходов. У v1 путь относительный от рабочего каталога ядра, поэтому steer spec convert печатает пути абсолютными. В пути нельзя «|» и управляющие символы, а относительный путь не начинается с dns: — такой путь отвергается с местом в тексте (переименуйте файл). Отказы: у списка нет источника (порты источником не являются — правило без набора адресов забрало бы весь трафик с этими портами); all рядом с файлами; негодный порт или диапазон (1..65535, начало не больше конца); пересекающиеся диапазоны.

outputs — куда#

имя: { kind: вид, … }. Общие ключи:

Ключ У кого Значение Умолчание
kind у всех вид выхода (ниже) обязателен
on_fail у выхода с устройством или меткой (в том числе tgws), у группы drop, direct, zapret (не на телефоне; уживание с системным zapret) drop
over у выхода со своим соединением с сервером выход-подложка, через который идёт трафик самого туннеля (в v1 — via) напрямую
device interface, tunnel, xsteer, awg устройство у interface обязательно; у остальных выводится из имени
ipv6 routed, nat — interface, awg; off — ещё tunnel и группа IPv6 от хоста на том конце туннеля (ниже, «IPv6 от хоста») ключа нет — выход несёт IPv6, если его несёт вид
prefix выход с ipv6: routed префикс хоста, 2001:db8:1::/56 (длина 1..64, без битов хоста) выводится из адресов LAN

Виды и их ключи (проверяет ключи сам вид — kind_ops.parse у видов ядра, схема ключей вида у видов плагинов; один разбор на оба формата). В самом ядре живут direct, block, interface, awg и группа; виды протоколов — tunnel, xsteer, warp, tgws — приходят только плагинами, и колонка «Плагин» называет, каким. Без своего плагина выход недоступен: apply спеку с ним не принимает с причиной «нужен плагин … — поставить», а при запуске демона и reload спека применяется, выход недоступен и живёт по своему on_fail — status показывает его unavail с той же причиной, diag — что поставить. Какой плагин даёт вид, ядро узнаёт из индекса семени, а виды официальных плагинов вне семени (tgws) — из своей таблицы, порождённой из их манифестов; так tgws без плагина ведёт себя так же, как tunnel без плагина протокола. Плагины протоколов лежат в пакете ядра (семя) и ставятся без сети — steer plugin install <id> (docs/guide.md, «Установка»); мост Telegram tgws — из репозитория splify2-extended-plugins. Какие виды и ключи есть на этом роутере сейчас, печатает steer spec-schema.

kind Ключи Что это Плагин
direct — не маршрутизировать: трафик идёт обычным путём —
block — «Блок»: трафик правила не пропускается. Адреса — по метке соединения в цепочках forward и output: TCP получает сброс (RST), остальное — ICMP «запрещено»; устройства и таблицы у выхода нет. Домены — резолвер отвечает на имена правила сам: A 0.0.0.0, AAAA ::, прочие запросы — пустым ответом; в наборы адресов и fake-IP имена не попадают (настоящий адрес часто общий у CDN, и блок по нему закрыл бы чужие сайты), resolve не значит ничего. Умение — block в features status —
interface device, obfs: { mode, server, listen } устройство системы (wireguard, pppoe…); obfs — WireGuard поверх поддельного TCP: server и listen — адрес:порт литералами, mode — wg-over-tcp (умолчание) — (обфускатор для obfs — плагин obfs)
tunnel protocol: vless, hysteria2, trojan, shadowsocks, socks, http или vmess; subscription, nodes, device, transport, insecure, exclude, exclude_name, only, active, by, interval, silence, pick, tolerance туннель по подписке; subscription — файл подписки (v1: sub_file), nodes — номера пригодных узлов по предпочтению (пусто — первый рабочий); transport — какими транспортами узлов ходить (ниже; только у vless); exclude, exclude_name — какие узлы не брать, only — узлы каких стран брать (ниже; у всех протоколов); active, by, interval, silence, pick, tolerance — сколько узлов работают сразу, как делятся соединения, как выбираются узлы и как клиент следит за ними (ниже, «Пул узлов туннеля») vless; hysteria2; proxy — trojan, shadowsocks, socks, http, vmess
xsteer conf, stream, stream_port, device xsteer; conf — файл в стиле wg (умолчание {etc}/xsteer/<имя>.conf) xsteer
awg conf, device AmneziaWG, устройство заводит ядро; conf — умолчание {etc}/awg/<имя>.conf — (код вида в ядре; плагин awg ставит kmod-amneziawg или kmod-wireguard)
tgws domain мост Telegram; domain обязателен; пул доменов, пути дата-центров и туннели WARP — настройки плагина tgws (репозиторий splify2-extended-plugins)
group members, pick, default, tolerance, interval, url, idle_timeout, weights, by, only, exclude группа выходов (ниже) —
warp count, transport, countries, exclude_countries, pick, tolerance, interval, url, idle_timeout, on_fail, over, ipv6 (nat или off) Cloudflare WARP: группа из count туннелей «<имя>.» (по умолчанию один: самую быструю точку входа плагин держит у того же устройства) — awg или, с transport: masque, MASQUE (устройство TUN плагина); count — 1..255; transport — awg (умолчание) или masque; pick — latency (умолчание) или order; interval по умолчанию 600 с; ipv6 по умолчанию nat; имя выхода не длиннее 27 знаков. Регистрацию и точки ведёт плагин (docs/warp.md) warpbox (тянет awg)

kind: zapret убран в 2.1.0 вместе с обработчиком steer-nfqws: спека с ним отвергается с названием замены — модуль DPI recheck или kind: direct. on_fail: zapret (уживание с системным zapret) остался.

Почему VLESS пишется kind: tunnel, protocol: vless, а не kind: vless: туннель поверх потоков — общий стек, а протокол — его дайлер (docs/architecture.md, «Туннели: стек, дайлер, транспорт»). kind: vless в v2 — отказ с подсказкой. xsteer туннелем в этом смысле не является (везёт пакеты, а не потоки) и остаётся своим видом.

protocol: hysteria2 — клиент hysteria2 (QUIC), только с плагином hysteria2 (без него — «нужен плагин hysteria2 — поставить»). Ключи — subscription, nodes, exclude, exclude_name, only, interval, silence (схема вида плагина): транспорта, insecure (у hysteria2 это параметр ссылки узла) и пула из нескольких узлов у него нет, и такой ключ — ошибка разбора «неизвестный ключ». Узлы подписки — ссылки hysteria2:// / hy2:// либо конфиг Xray-core (docs/hysteria2.md). В спеке v1 hysteria2 не выражается.

kind: warp — выход через Cloudflare WARP одной строкой, только с плагином warpbox. Подготовка спеки (хук expand плагина) разворачивает его в группу с именем выхода и члены <имя>.1 … <имя>.<count>: вида awg с файлами {etc}/warp/<имя>-<n>.conf (файлы пишет плагин, а до первого файла член ждёт и ошибкой apply не считается) или, с transport: masque, вида plugin-device — устройство TUN, которое держит процесс плагина-владельца (руками этот вид в спеке не пишется: его принимает только подготовленная спека и только с owner). Подмену IPv4 на устройствах членов ставит само ядро (postrouting_nat4). Имена членов заняты: выход с таким именем рядом — отказ разбора. steer spec convert печатает выход обратно одной строкой kind: warp. Ключи и поведение — docs/warp.md.

protocol: trojan, shadowsocks, socks, http, vmess — клиенты протоколов прокси (podkop/forkop поверх steer через коннектор sing-box), только с плагином proxy (без него — «нужен плагин proxy — поставить»). Узлы из подписки: стандартные share-ссылки trojan://, ss://, socks*://, http(s)://, vmess:// (docs/proxy.md). Ключа transport нет (транспорт берётся из ссылки узла); insecure есть у trojan, vmess и http (есть TLS), у ss и socks его нет.

transport туннеля — tcp, grpc, xhttp, ws, httpupgrade, одно имя или список (transport: ws, transport: [ws, httpupgrade]); ключа нет — любые. Это фильтр узлов подписки, а не замена их транспорта: транспорт — свойство входа на сервере, и узлы с ним приходят из подписки (type= ссылки, network конфига Xray). Нужен тому, у кого панель отдаёт один сервер в нескольких видах: transport: ws держит туннель на узлах через CDN и после обновления подписки, когда номера уехали. Вместе с nodes — пересечение, номера при этом те же (среди всех пригодных, как печатает steer vless-nodes); не осталось ни одного узла — туннель не поднимается и говорит «среди выбранных узлов нет ни одного с транспортом из transport», а не уходит на узел другого транспорта. steer spec convert печатает список так, как он записан (одно имя — списком из одного). Отказы (по схеме вида): незнакомое имя, имя дважды, пустой список, ключ у другого вида. Параметры самих транспортов (path, host, заголовки) — у узла в подписке (docs/vless.md, «ws и httpupgrade»). Постквантовые поля узла — encryption (шифрование VLESS) и pqv (ключ проверки подписи ML-DSA-65 у Reality) — тоже приходят из подписки (docs/vless.md, «Постквантовая часть»); в спеке для них ключей нет, а помощник перезапускается при их изменении, потому что подпись помощника включает содержимое файла подписки.

insecure туннеля vless — true: не проверять сертификат узлов security=tls этого выхода (цепочку, имя, срок, закрепления; подпись CertificateVerify остаётся). По умолчанию выключен; узлы подписки с allowInsecure без этого ключа пропускаются с причиной. Пока ключ включён, steer diag предупреждает, а steer status печатает "insecure":true. У hysteria2 ключа нет (там insecure — параметр ссылки узла), у других видов — ошибка разбора. Закрепление сертификата (pcs) и имена проверки (vcn) — поля узла в подписке (docs/vless.md, «Проверка сертификата узла»).

exclude, exclude_name и only туннеля — какие узлы подписки брать в кандидаты, у всех протоколов туннеля. exclude — страны: код из двух заглавных латинских букв (ISO 3166-1), одно значение или список (exclude: RU, exclude: [RU, US]). Страна узла — флаг-эмодзи в его имени: первая пара подряд идущих символов regional indicator где угодно в имени («🇳🇱 Амстердам» → NL), так же, как страну по имени понимает интерфейс splify2. Узел без флага страны не имеет, и exclude его не исключает; названия стран словами ядро не читает. exclude_name — куски имени узла без учёта регистра латиницы и кириллицы (exclude_name: [Мобильный, LTE]): узел, в имени которого есть любой из них, не берётся. only — обратное: список стран (тот же вид и те же коды), узлы которых ТОЛЬКО и берутся; узел чужой страны и узел без флага (страны у него нет, угадывать нечем) в кандидаты не идёт. С pick: latency получается «самый быстрый среди узлов этих стран» (only: [NL, DE]), а с exclude и pick: latency — «самый быстрый, кроме страны X» (exclude: RU): замер идёт только по оставшимся, а допуск tolerance не даёт узлу прыгать между близкими по задержке. Страна одна и там и там (only: DE, exclude: DE) — ошибка разбора. Страна — обещание имени узла в подписке: выход её не проверяет. Исключение называет свойство узла, а не номер, поэтому переживает обновление подписки: новые узлы исключённой страны тоже не берутся, в том числе при пустом nodes («первый рабочий»). Это только отбор: номера узлов от него не сдвигаются (они по-прежнему среди всех пригодных, как печатает steer vless-nodes), вместе с nodes и transport — пересечение. Не осталось ни одного кандидата — туннель не поднимается и говорит «все … узлов-кандидатов исключены exclude, exclude_name или only», а не перебирает исключённые. Узел, названный явно (*-probe --node N), проверяется и исключённым. В перечне узлов (*-nodes) у узла — cc (страна по флагу) и, у выхода, "excluded":true у исключённых (contract-v1.md, раздел 6). steer spec convert печатает ключи списками в порядке записи. Отказы: код не из двух заглавных латинских букв («ru», «RUS»), код или кусок дважды, пустая строка, ключ у другого вида. Умение названо в features status: exclude (exclude, exclude_name) и node_only (only).

Страна выхода туннеля: заявленная и фактическая. Файл состояния клиента (у vless, hysteria2 и протоколов прокси) несёт страну первого активного узла двумя полями: node_cc — по флагу в имени узла (обещание продавца подписки; поля нет, если флага нет) и geo_cc — какую видят сайты через выход. Фактическую клиент узнаёт одним запросом GET /cdn-cgi/trace к Cloudflare через устройство туннеля (https://1.1.1.1, запасная цель https://www.cloudflare.com; поле loc=): после подъёма и после каждой смены активного узла, а не опросом; не вышло — одна повторная попытка через 20 с, дальше поле geo_failed: true до следующей смены узла. Расходятся node_cc и geo_cc — geo_mismatch: true и строка в журнале. У пула с несколькими активными узлами (active больше 1) проверки нет: запрос ушёл бы на любой из них. geo_cc важнее node_cc при выборе членов группы. Поля аддитивны: прежний читатель файла их пропускает.

Пул узлов туннеля — active, by, interval, silence, pick, tolerance у kind: tunnel:

outputs:
  nl: { kind: tunnel, protocol: vless, subscription: sub/nl.txt, active: 3, by: site }
  fast: { kind: tunnel, protocol: vless, subscription: sub/all.txt, pick: latency }
Ключ Значение Умолчание
active сколько узлов из кандидатов (nodes, transport — порядок предпочтения) работают сразу, 1..65536; больше, чем узлов в nodes, — отказ; кандидатов в подписке меньше — активны все 1
by как новые соединения делятся между активными узлами: connection — каждое на случайный живой узел (поровну), site — по адресу назначения (сайт на одном узле), site_client — по паре «клиент, адрес»; только при active больше 1 connection
pick какие узлы активны: order — первые живые по порядку предпочтения, latency — самые быстрые по замеру (ниже); у hysteria2 ключа нет (всегда order) order
tolerance pick: latency — на сколько миллисекунд кандидат должен быть быстрее активного узла, чтобы его сменить, 0..60000; 0 — на любой более быстрый 50
interval период проверки каждого активного узла, секунды, 5..86400; при pick: latency — и период замера всех кандидатов 60 (при pick: latency — 180)
silence порог молчания узла на живом соединении, секунды: 0 — порога нет, иначе 5..32767 20 (у hysteria2 — 30)

Клиент держит active живых узлов сразу; соединение получает узел при открытии и остаётся на нём до конца. Имена значений by — те же, что у by группы balance, а адрес назначения — тот, что в пакете (при fake-IP — уже настоящий адрес сайта). Каждый активный узел проверяется раз в interval той же проверкой, по которой выбран при подъёме; две неудачи подряд (после обрыва соединения по silence — одна: узел и так молчал дольше порога) — узел мёртв: соединения через него сбрасываются (RST клиенту — приложение переподключается сразу, на живой узел), а на его место берётся следующий свободный кандидат по порядку предпочтения — в том же процессе, без перезапуска и не трогая соединения живых узлов. Замены нет — круг через 15 с (сперва прежний узел, потом свободные кандидаты), с каждым пустым кругом вдвое дольше, до 30 с. Демону (--supervise) клиент говорит down, только когда живых узлов не осталось, и up, когда живой нашёлся (docs/ctl.md, «Сторож выходов»).

pick: latency — самые быстрые узлы подписки, а устройство и туннель по-прежнему одни: «самый быстрый» не требует держать открытыми соединения ко всем узлам или заводить по устройству на узел. Раз в interval клиент меряет всех кандидатов той же проверкой, что при подъёме, — соединение, рукопожатие, запрос через узел и первый байт ответа, время проверки целиком, — по три раза на узел (см. «Оценка узла»); соединение проверки разовое, в покое к неактивным узлам ничего не открыто. Затем активный узел меняется на свободного кандидата, если его оценка лучше больше чем на tolerance (не ответивший на замер или мёртвый — на самого лучшего). Смена — для новых соединений: открытые доживают на прежнем узле, он ведь жив, и ничего не рвётся. Мёртвый узел заменяется так же, как при order, только кандидаты перебираются по последнему замеру (быстрые первыми, не мерянные — по порядку предпочтения, не ответившие — последними), и сбрасываются соединения только умершего узла. Первый замер — сразу после подъёма устройства (подъём ждёт только первого живого узла по порядку). tolerance без pick: latency — отказ.

Оценка узла (pick: latency у туннеля и у группы kind: group). Один замер не отличает быстрый, но рвущийся узел от ровного, поэтому узел или член группы мерится три раза за круг. Все пробы круга идут разом (у узлов подписки по четыре потока на пробу, у членов группы — три запроса urltest одновременно), поэтому круг занимает столько же, сколько с одной пробой: самая долгая проба, но не три подряд; ни время подъёма туннеля (первый замер идёт после него, в своём потоке), ни проход сторожа замер не задерживает. Из ответивших проб считаются среднее m и джиттер j — среднее отклонение от среднего; оценка узла:

    оценка = m + 2·j + 1000 · (потерянных проб / проб),  мс

Ни одной ответившей пробы — узел не отвечает (-1), как и прежде. Допуск tolerance — в единицах оценки: узел меняется, только если его оценка лучше на допуск. Примеры при трёх пробах: 100, 100, 100 мс — оценка 100; 100, потеря, 130 — 115 + 2·15 + 333 = 478; 70, 130, 100 — 100 + 2·20 = 140. Потеря одной пробы из трёх стоит 333 мс — больше типичной разницы между узлами, но узел при этом не мёртв; два узла «быстрый, но теряет» и «в два раза медленнее, но ровный» выбираются в пользу второго. В status у пула узлов latency — оценки, а lat_stat.nodes.<номер> — из чего оценка сложена: ms (среднее), jitter, loss (проценты); у группы latency — тоже оценки. Для групп с двумя семействами оценка считается по каждому, выбирается худшая (как раньше).

silence — молчание узла под живым соединением: отправленное узлу не подтверждено им дольше порога (узел умер под загрузкой, звонком, ТСПУ режет поток после N КБ) или от узла ничего нет дольше порога и он не отвечает на проверку TCP keepalive (умер под закачкой). Такое соединение ядро обрывает, клиенту уходит RST, а слежке — повод проверить узел сразу, не дожидаясь interval. Долгий опрос и простаивающее соединение не страдают: живой узел подтверждает принятое и отвечает на проверку сам, даже когда приложению отвечать ещё нечего. Плата — одна пустая проверка TCP за порог простоя на соединение. У hysteria2 silence — срок простоя QUIC (PING — втрое чаще срока, но не реже 10 с), а silence: 0 оставляет прежние 30 с: соединению QUIC срок простоя нужен всегда.

Где что есть: у vless и протоколов прокси (trojan, shadowsocks, socks, http, vmess) — все шесть ключей; у hysteria2 — только interval и silence (соединение с узлом у него одно QUIC на все потоки, и ключи active, by, pick, tolerance у него — «неизвестный ключ»). Какие узлы активны сейчас — steer status (объект vless или proxy у выхода: active — номера и имена, при pick: latency ещё latency — последний замер) и helper демона (поле active, docs/ctl.md); steer diag предупреждает, пока активных меньше active. steer spec convert печатает только отличное от умолчания. Отказы: active вне 1..65536 или больше узлов в nodes; by не из трёх имён или при active: 1; pick не order/latency; tolerance вне 0..60000 или без pick: latency; interval вне 5..86400; silence 1..4 («меньше 5 с: столько длится повторная передача на медленной линии, и живые соединения обрывались бы») или больше 32767 (предел ядра для keepalive); ключ у вида не tunnel. Умение названо в features status (active_nodes, pick: latency — pool_latency).

Группа (kind: group) — выход, у которого вместо устройства члены:

Ключ Значение Умолчание
members перечень выходов с устройством (в том числе других групп), по предпочтению обязателен
pick order — первый живой; latency — самый быстрый с допуском (urltest); manual — выбор человека командой select; balance — ядро раскидывает новые соединения по живым членам order
tolerance pick: latency: допуск в мс, 0..60000; 0 — без допуска: выбирается строго самый быстрый, а с текущего уходят на любой выигрыш умолчание сторожа (50)
interval pick: latency: интервал замера в секундах, 5..86400 (у демона — свой таймер группы, и интервал может быть короче периода сторожа) умолчание сторожа (180)
url pick: latency: адрес проверки — http://… или https://… (https — в пакете steer-core; в статической сборке без TLS — отказ разбора) http://cp.cloudflare.com/generate_204
idle_timeout pick: latency: сколько секунд без трафика через группу замер не делается, 0..86400; 0 — мерить всегда телефон — 1800, роутер — 0
only pick: latency и order: брать только члены, у которых страна ЖИВОГО узла из списка (код или список кодов ISO 3166-1, как у exclude туннеля). Страну читает сторож из файла состояния туннеля-члена: фактическую (geo_cc, проверка выхода, ниже), а пока её нет — по флагу в имени узла (node_cc). Член без известной страны (не туннель по подписке, у узла нет флага, процесс не жив) при only не берётся нет
exclude то же, но члены этих стран не берутся; член без известной страны берётся нет
default pick: manual: член до первой команды select первый
weights pick: balance: вес каждого члена по порядку members, 1..100 — доля новых соединений все по 1
by pick: balance: как раздаются новые соединения — connection (каждое само по себе, случайно по весам), site (один сайт — один член), site_client (сайт у одного устройства — на одном члене) connection

Страна члена группы. only и exclude группы отбирают членов так же, как у туннеля — узлов подписки: «самый быстрый, кроме страны X» (pick: latency, exclude: RU) и «самый быстрый из NL и DE» (only: [NL, DE]). Член вне отбора считается не живым для выбора и не мерится; при смене живого узла члена (туннель переехал на узел другой страны) отбор пересчитывается на ближайшем проходе, а несущий член, оказавшийся вне отбора, заменяется как умерший. Не осталось ни одного члена — группа в отказе с её on_fail, как при отказе всех членов. Вложенная группа и члены, у которых нет файла состояния туннеля (interface, awg, xsteer), страны не имеют. only и exclude группы — только при pick: latency и order; manual (человек выбрал сам) и balance — отказ, как и одна страна в обоих ключах, и код не из двух заглавных латинских букв. status у группы с отбором — объект countries (only, exclude, members — страна каждого члена с известной страной, skipped — члены вне отбора).

Как выбирает каждый pick:

  • order — первый живой член; возврат на более предпочтительный — после нескольких проходов подряд, когда он отвечает (гистерезис сторожа).
  • Закрепление соединений (order и latency): новое соединение идёт на выбранный член, а установленное остаётся на том, где началось, пока тот жив, — смена члена по задержке или возврат на предпочтительный соединений не рвут. Умер член — его соединения снимаются, и следующие их пакеты идут на выбранный (у туннеля другой адрес выхода: TCP такого перехода не переживает, приложения переподключаются). У manual закрепления нет — выбор человека переводит всё; у пула v1 (devices) тоже нет: у его членов нет своих меток. Не закрепляются и соединения самого роутера через группу — туннель с over на группу, апстримы DNS: они идут таблицей группы и при любой смене члена переходят на новый (соединение TCP — переподключением).
  • latency — задержка члена меряется как urltest sing-box: запрос GET к url через члена (сокет с меткой члена — его правило и таблица, тот же путь, что у трафика группы, включая туннель VLESS и цепочки over), время до первого байта ответа 204 или 200. Мерятся живые члены раз в interval; выбирается самый быстрый, а из тех, кто хуже него не больше чем на tolerance, — самый предпочтительный по порядку; с живого текущего группа уходит только за выигрыш больше tolerance. Отсюда «первый живой» у группы «самый быстрый»: пока члены различаются меньше tolerance (по умолчанию 50 мс), порядок решает при равенстве, и выбран первый из равных; tolerance: 0 делает выбор строгим. Мёртвый член не выбирается, как бы быстро он ни отвечал в прошлый замер: упал самый быстрый — берётся самый быстрый из оставшихся живых. Замер идёт своим таймером группы раз в interval, а не с проходом сторожа, и сторож переключает группу сразу, как только замер меняет выбор (docs/ctl.md, «Сторож выходов»).

    Замер, не давший ответа ни у одного живого члена (проверочный адрес не отвечает через них: DNS, часы у HTTPS, порт закрыт, сертификат не принят), группу не останавливает: она идёт по порядку, как order, — и ядро говорит об этом строкой в журнале (ни у одного живого члена нет замера задержки) и в status (group.why: no_measure, group.latency_failed). Причину каждой неудачи — «ответ 503 вместо 204/200», «имя не разрешилось», «сертификат не принят: …», «срок вышел» — ядро пишет строкой latency: группа …, член …: замер … не удался — …, раз в 10 минут на члена, пока причина та же. Повтор замера у члена без ответа — раньше срока: через 15 с, дальше вдвое реже, не дольше interval. Пока через группу нет трафика дольше idle_timeout (по счётчикам её правил), проверочных запросов нет вовсе (status: group.why: idle). Имя из url разрешает системный резолвер.

    Выбор члена один на оба семейства: если все живые члены несут IPv6, замер идёт и по IPv4 (запись A), и по IPv6 (AAAA, сокет IPv6 с меткой члена), и у члена берётся худший из двух — член, быстрый по IPv4, но медленный или глухой по IPv6, не выигрывает; если по IPv6 не ответил никто (у адреса нет AAAA, туннели не выпускают IPv6), — по IPv4. У группы, где хоть один член IPv6 не несёт (xsteer, tgws), и у пула devices спеки v1 — только по IPv4. Литерал IPv6 в url не принимается. - manual — член, выбранный командой select <группа> <член> (docs/ctl.md), без apply; выбор переживает перезапуск и перезагрузку (файл select рядом со спекой). Не работает выбранный член — группа применяет свой on_fail, а не переходит на другой: manual — выбор человека. При запуске это действует сразу, до первого прохода сторожа: таблица группы — на выбранном члене или, если его устройства нет, on_fail (docs/ctl.md, «Сторож выходов», «До первого прохода»). - balance — ядро раздаёт НОВЫЕ соединения по живым членам по весам (карта из 120 слотов), член соединения запоминается в метке соединения, и соединение остаётся на своём члене. Упавший член сторож убирает из карты (только карту, без перезагрузки набора правил); живых нет — on_fail группы. IPv6 раздаётся так же, если его несут все члены; если хоть один не несёт (xsteer, tgws), IPv6 правил группы отвергается, как у выхода без IPv6. Для правил на сам телефон (uid, self) — ещё не поддерживается. Слот нового соединения выбирает by (режимы load-balance у Clash): - connection — случайно (numgen random): каждое новое соединение само по себе, и соединения одного сайта расходятся по членам; - site — хеш адреса назначения (jhash ip daddr, у IPv6 — ip6 daddr; consistent-hashing): все соединения к сайту — через один член, у любого клиента. Сайт — адрес назначения до подмены fake-IP: у канала с fake-IP это имя (у каждого имени свой поддельный адрес), без fake-IP — адрес, и имя на нескольких адресах может попасть на разные члены; - site_client — хеш пары «адрес клиента, адрес назначения» (sticky-sessions): сайт у одного устройства — через один член, у другого устройства — возможно, через другой.

    Хеш постоянный: тот же сайт попадает на тот же член и после apply, и после перезагрузки (семя хеша — номер таблицы группы). Упал член — его сайты расходятся по живым по весам, а сайты живых членов остаются на своих местах; член вернулся — его сайты снова на нём (установленные соединения при этом остаются там, где начались).

Вложенность. order, latency и manual разворачивают выбор до листа: трафик группы идёт в устройство, которое сейчас несёт трафик выбранного члена (у вложенной группы — её текущий лист). У balance вложенная группа — один член со своим весом: её собственный выбор (order, manual) сохраняется внутри её доли, а вложенная balance делит свою долю дальше по своим весам и своему by: сайт остаётся на одном выходе до самого листа, только если by: site (или site_client) у всех balance на пути; хеш у каждой группы свой, поэтому вложенная группа делит сайты своей доли по всем своим членам.

Отказы: члена нет; группа в себе самой; член дважды; член без устройства (direct, tgws); круг групп; default не из членов или не у manual; tolerance/interval/url/idle_timeout не у latency; url не http(s)://хост[:порт][/путь], https:// в сборке без TLS; weights не у balance или не по числу членов; by не у balance или не connection/site/site_client; группа balance членом группы order/latency/manual (у такой группы трафик идёт в одно устройство, а у balance устройство на каждое соединение своё); device у группы.

Отказы вида (текст — вида, место — выхода): у interface нет device; у tunnel нет subscription; путь conf/strategy с кавычкой; stream_port без stream; имя устройства awg длиннее 15 символов или выдаёт туннель; у tgws нет domain. Сквозные (как у v1): выход в локальное устройство; устройство дважды в группе; over у вида без своего соединения с сервером, на выход без устройства, на себя, круг (в том числе через устройства членов группы), цепочка длиннее трёх.

IPv6 от хоста (ipv6 у выхода). Хост — сервер на том конце туннеля WireGuard, у которого IPv6 есть; роутер без своего IPv6 у провайдера получает IPv6 через него, внутри самого туннеля. Сторону хоста человек настраивает сам (обычный сервер WireGuard с IPv6), раздачу IPv6 в LAN — тоже сам, в netifd и odhcpd; steer маршрутизирует и в diag говорит, чего не хватает (id ipv6_host).

outputs:
  host:  { kind: interface, device: wg1, ipv6: routed, prefix: "2001:db8:1::/56" }
  other: { kind: interface, device: wg2 }
  • routed — хост маршрутизует на пира префикс (или отвечает за адреса из него NDP proxy), и у клиентов LAN адреса из него. Роутер: option ip6prefix '2001:db8:1::/56' у интерфейса туннеля и option ip6assign '64' у LAN в /etc/config/network — netifd выдаст LAN кусок префикса, odhcpd раздаст его клиентам. IPv6 клиентов с адресом из префикса идёт по правилам: правила в этот выход («донор») ведут IPv6 в него; у правил в любые другие выходы (и в direct) IPv6 отвергается сразу (ICMPv6 «administratively prohibited» — клиент переходит на IPv4), а имена под ними получают пустой AAAA; всё несовпавшее IPv6 из префикса — в донора. Адрес из префикса не уходит ни в другой выход, ни в WAN никогда (другой сервер отбросил бы его по AllowedIPs, провайдер — по BCP38): такой пакет отвергается, в каком бы направлении его ни увёл маршрут. Донор лёг — IPv6 отвергается сразу (запрет prohibit в его таблице), а не уходит напрямую. Донор в спеке один. prefix — необязателен: без него префикс выводится из адресов LAN — нуль-маршрут unreachable P, который netifd ставит на каждый раздаваемый префикс, накрывающий глобальный адрес устройства раздачи; префикс провайдера (с маршрутом default from P через WAN) не берётся; двух кандидатов ядро не угадывает — тогда нужен prefix. Выведенный префикс сторож переписывает сам, когда netifd его выдаёт или меняет. ULA-префикс хоста (хост сам делает NAT66 для ULA) — только prefix явно. Клиенты с ULA рядом с префиксом ходят к поддельным адресам fake-IP (fdfe:…) со своего ULA, и такой IPv6 в донора отвергается (хост его не пропустит) — доменные правила fake-IP в донора для них идут по IPv4; resolve: realip или LAN только с префиксом хоста (ip6class) это снимают.
  • nat — у пира один адрес IPv6, клиенты LAN на ULA: masquerade IPv6 на устройство выхода ставит само ядро steer, в своей таблице (зоны fw4 не трогаются; masq6 зоны для этого не нужен), и IPv6 идёт по правилам, как IPv4. Роутер: у интерфейса туннеля — адрес IPv6, выданный хостом; если у LAN только ULA — option ra_default '1' в секции dhcp LAN, иначе odhcpd не объявит маршрут по умолчанию.
  • off — выход IPv6 не несёт, хотя вид умеет: IPv6 его правил отвергается, AAAA имён под ними пуст.
  • IPv6 через tunnel. Выход kind: tunnel (vless, hysteria2, trojan, shadowsocks, socks, http, vmess) несёт IPv6 клиентов по TCP и по UDP, как IPv4: правила с family: 6 или both ведут IPv6 в такой выход, на AAAA имён под правилом идёт поддельный (fakeip) или настоящий (realip) IPv6. Адрес назначения IPv6 едет в протоколе узла в его форме (VLESS — тип адреса 3, SOCKS5, trojan и shadowsocks — ATYP 4, VMess — тип 3, HTTP CONNECT — [адрес]:порт, hysteria2 — [адрес]:порт); SOCKS4 адресов IPv6 не знает, и такой поток к SOCKS4-узлу не открывается. Ограничения: разбор пакета IPv6 из устройства принимает за фиксированным заголовком только TCP, UDP или заголовок фрагментации (пакет с hop-by-hop, маршрутизацией или параметрами получателя отбрасывается), ICMPv6 через туннель не идёт (как и ICMP). ipv6: off снимает IPv6 у выхода; routed и nat ему не нужны (подмена не требуется, хоста с префиксом на том конце нет). Адрес самого узла по IPv6 доступен по-прежнему (over — только IPv4, см. docs/vless.md).
  • Ключа нет — выход несёт IPv6, если его несёт вид. Рядом с донором выход без ключа IPv6 не несёт (как off); nat рядом с донором несёт IPv6 клиентов с ULA, а адрес из префикса и туда не уходит.
  • Телефон. Раздачей IPv6 там владеет Android (Tethering): routed и nat разбираются, но действуют как отсутствие ключа — apply и diag говорят об этом; off действует.

Отказы: неизвестный режим; routed/nat у группы («задайте у члена») или у вида без туннеля; ipv6 у вида без IPv6 (xsteer, tgws, direct); routed/nat у tunnel (ему доступен только off); prefix без routed; префикс с битами хоста, длиннее /64, служебный (link-local, multicast, пул fake-IP); второй routed в спеке.

dns#

Ключ Значение Умолчание
mode fakeip или realip — режим доменных правил без своего resolve; оба семейства: на AAAA имени под правилом — поддельный IPv6 из пула fdfe:dcba:9876::/96 (fakeip) или настоящий адрес в наборе IPv6 правила (realip), если правило ведёт в выход с IPv6 (interface, awg, direct, группа из таких) и его клиенты узнаются по IPv6 (см. ниже) fakeip
traceroute_hops true — трассировка через fake-IP видит настоящие узлы (в v1 — traceroute_hops верхнего уровня) false
mesh_clients true — запросы DNS клиентов mesh-VPN (устройства tailscale*, zt*) к порту 53, UDP и TCP, заворачиваются на резолвер ядра steer, и доменные правила действуют на этих клиентов. Нужна и настройка самой сети: Tailscale-клиент спрашивает свой MagicDNS, и до роутера запрос доходит, только если сеть Tailscale выдаёт клиентам адрес роутера как сервер имён; для ZeroTier — то же через DNS-сервер сети. Без этого поля чужую сеть не трогаем false
cache записей в кэше ответов на имена под правилами (и на имена вне правил, когда задан other); 0 — кэша нет; от 0 до 100000 0
cache_ttl { min, max, negative } — секунд: ответ живёт не меньше min и не дольше max, отрицательный (NXDOMAIN, пустой) — negative. TTL в ответе клиенту зажат теми же пределами и уменьшается на возраст записи. Пределы: min 0..86400, max 1..604800, negative 0..86400; min больше max — отказ { min: 10, max: 3600, negative: 30 }
upstreams имя: { url, out, ips, bootstrap, fragment } — серверы DNS, или имя: { servers, mode } — группа серверов, см. ниже —
upstream имя из upstreams (сервер или группа) — общий сервер для имён под правилами, у которых своего нет нет: прежний путь наверх
other имя из upstreams (сервер или группа) — сервер для имён, не попавших ни под одно правило, см. ниже нет: прежний путь наверх
bootstrap адреса (IPv4 или IPv6) серверов обычного DNS, которыми разрешается имя сервера DoT/DoH/DoQ/DoH3; число не ограничено —

Апстримы. url выбирает транспорт: https://имя[:порт][/путь] — DoH (RFC 8484, POST application/dns-message, HTTP/1.1 с keep-alive, путь по умолчанию /dns-query); tls://имя[:порт] — DoT (853); quic://имя[:порт] — DoQ (RFC 9250, UDP, порт 853, ALPN doq); h3://имя[:порт][/путь] — DoH по HTTP/3 (RFC 8484 и RFC 9114, UDP, порт 443, ALPN h3, путь по умолчанию /dns-query); udp://адрес[:порт] и tcp://адрес[:порт] — обычный DNS (у udp усечённый ответ повторяется по TCP); адрес IPv6 пишется в скобках. Для udp:// и tcp:// нужен адрес, не имя. Другой записи DoQ (doq://) нет.

DoQ — одно долгоживущее соединение QUIC на апстрим, каждый вопрос идёт своим потоком, поэтому потеря пакета задерживает только тот вопрос, чей ответ в нём. Простаивающее соединение закрывается через 5 минут после последнего вопроса кодом DOQ_NO_ERROR; пока оно держится, резолвер раз в 15 с молчания шлёт PING. Соединение, молчащее 1,5 с после отправленного вопроса, пересоздаётся, а вопрос уходит на новом; если от сервера не было ни пакета больше 17 с ещё до вопроса (PING остался без ответа), срок — 400 мс, а после 20 с такого молчания соединение без вопросов закрывается само. Соединения TCP (tcp://, DoT, DoH) проверяет ядро: отправленное и не подтверждённое сервером 1,5 с или проба простаивающего соединения (через 15 с тишины) без ответа за 5 с — соединение закрывается, а вопрос, ушедший в него, один раз повторяется на новом. Билеты сессии хранятся в памяти процесса резолвера (по одному на сервер — имя и порт, не больше восьми серверов), на диск не пишутся: со второго соединения к тому же серверу рукопожатие идёт по билету, а первый вопрос уходит в 0-RTT (early data, RFC 9250 разрешает — вопрос DNS идемпотентен), не дожидаясь конца рукопожатия. Если сервер 0-RTT не принял, вопросы уходят заново на новом потоке того же соединения. STEER_DOQ_EARLY_DATA=0 в окружении резолвера выключает билеты и 0-RTT.

DoH3 устроен так же, как DoQ (одно соединение QUIC на апстрим, вопрос — свой поток, простой 5 минут, пересоздание молчащего соединения), но по потоку идёт запрос HTTP/3: POST с content-type и accept application/dns-message, тело — вопрос с номером 0, ответ — заголовки с :status и тело. С рукопожатием уходит поток управления с SETTINGS. Сжатие заголовков QPACK — только по статической таблице: резолвер объявляет таблицу нулевой, и сервер не может занять её ссылками (ссылка на динамическую таблицу в ответе — ошибка, соединение закрывается). Ответ с кодом не 200, сброшенный поток и тело короче заголовка DNS отказывают только вопросу, причина — в dns-log. Билеты и 0-RTT у DoH3 не используются. Вторая сторона GOAWAY (сервер просит прекратить новые запросы) не разбирается: соединение, закрытое сервером, пересоздаётся вопросом.

  • out — выход, через который уходит запрос к серверу (выход со своим устройством: interface, awg, tunnel любого протокола, xsteer; группа и tgws не годятся); нет ключа, или выход direct, или слово direct — напрямую. Запрос уходит с меткой выхода, так что может идти по отдельному стабильному выходу, не тому, что у трафика правила. Выход лёг — запрос не уходит мимо него (набор правил не выпускает помеченный пакет в другое устройство), а клиент получает SERVFAIL, не прежний путь наверх.
  • Имя сервера DoT/DoH/DoQ/DoH3 разрешается не системным резолвером: ips (адреса сервера, имя тогда не разрешается вовсе) либо bootstrap апстрима, либо общий dns.bootstrap. Bootstrap — обычный DNS по UDP, с той же меткой пути, что и апстрим; результат живёт срок TTL ответа (60-3600 с), при молчании bootstrap берутся прежние адреса. Ни ips, ни bootstrap — отказ.
  • fragment: true — только у DoT (tls://) и DoH (https://): ClientHello уходит двумя записями TLS, а не одной. Разрез — в случайной точке внутри имени сервера (SNI; у Hello без SNI — на 30-80-м байте сообщения), между двумя отправками пауза около 2 мс (сокет с TCP_NODELAY, так что это два сегмента). Это против DPI, который ищет SNI в одной записи или одном сегменте (с такими провайдерами DoH к cloudflare-dns.com и dns.google с коротким ClientHello не проходит рукопожатие). Делится только первая запись соединения; сервер собирает сообщение из двух записей сам (RFC 8446, 5.1), поэтому рукопожатие, сертификат и всё остальное не меняются. Умолчание — false: лишние две отправки и 2 мс на каждое новое соединение ни к чему, где перехвата SNI нет. Не помогает против DPI, который собирает записи; у udp://, tcp://, quic:// и группы ключ — отказ разбора.
  • Сертификат сервера проверяется до корней (на роутере — /etc/ssl/certs/ca-certificates.crt, на телефоне — системное хранилище), имя — по SNI (у DoQ и DoH3 — имя из url, то же и при адресе, найденном через ips или bootstrap). В статической сборке без TLS DoT и DoH не работают, без обёртки QUIC (статическая сборка без src/proto/quic) не работают DoQ и DoH3; в пакете steer-core есть и то и другое. Там, где их нет, апстрим показывается в dns-log со состоянием no-tls, а вопросы к нему получают SERVFAIL.

Апстрим задаётся у правила (dns: имя или сразу dns: { url: …, out: … } — те же ключи) или общий (dns.upstream). Правила с одним выходом, клиентами и режимом, но разными апстримами остаются отдельными каналами резолвера. Имена вне правил спрашиваются, как раньше (dnsmasq на роутере, исходный сервер запроса на телефоне), если не задан dns.other.

Группа серверов — запись upstreams с ключами servers (имена серверов из upstreams, по порядку; число не ограничено) и mode вместо url. Группа годится везде, где имя апстрима: dns.upstream, dns.other, dns правила (в том числе сразу в правиле: dns: { servers: [a, b], mode: race }). Годный ответ — любой, кроме SERVFAIL и REFUSED (NXDOMAIN и пустой ответ годны: это ответ об имени, а не отказ сервера).

  • mode: race — вопрос уходит всем серверам группы сразу, клиенту — первый годный ответ; отказ (SERVFAIL клиенту), только если годного не дал никто. Сервер, который отказал (SERVFAIL, REFUSED, нет ответа за 4 с, не принял вопрос), уходит на ту же паузу, что и в failover (5 с, 10 с … 300 с), и пока она идёт, ему вопросы не уходят — известно плохого сервера не дёргают каждым вопросом.
  • mode: failover (умолчание) — по очереди: вопрос уходит первому; он ответил SERVFAIL/REFUSED или не принял вопрос (нет соединения, пауза после неудачи соединения) — сразу следующему; не ответил за 1,5 с (за 350 мс, если готового соединения с ним нет и вопрос ждёт рукопожатия) — вопрос уходит и следующему, а годный ответ любого из спрошенных — ответ группы. Сервер, который отказал (SERVFAIL, REFUSED, нет ответа за 4 с, не принял вопрос), уходит на паузу 5 с, 10 с, 20 с … до 300 с: пока она идёт, он спрашивается последним, после всех серверов без паузы. Пауза кончилась — сервер снова первый в своём порядке, и следующий вопрос проверяет его; годный ответ снимает паузу, отказ удлиняет вдвое. Пока вернувшийся сервер не ответил годно, вместе с ним сразу спрашивается следующий, и клиент получает первый годный ответ. Вопросы, бывшие в пути к серверу в момент его отказа, удлиняют паузу один раз, а не каждый. Медленный, но отвечающий сервер паузы не получает.

Память отказов у обоих режимов одна. Годный ответ снимает паузу, но только если вопрос ушёл серверу после его последнего отказа: запоздалый годный ответ на старый вопрос не возвращает сервера, который только что отказал (победа не переживает более позднего отказа). Если на паузе все серверы группы, вопрос уходит ровно один раз — наименее плохому (пауза короче, то есть меньше отказов подряд; при равных — кончается раньше), без обхода остальных и без веера; отказал — его пауза вдвое длиннее, и следующий вопрос уходит уже другому. Отдельной памяти о победах нет: сервер без паузы стоит на своём месте в порядке спеки.

У каждого сервера группы — свой путь (out), свои адреса и соединения. Отказы: url и servers вместе; пустой servers; имя, которого нет в upstreams; имя дважды; группа в группе («перечислите её серверы»); mode не race и не failover.

Сервер для остальных имён (dns.other). Имена, не попавшие ни под одно правило, резолвер спрашивает этим сервером или группой, а не прежним путём. Имена своей сети остаются у DNS роутера: имя без точки (имя устройства из DHCP), домены lan, local, home.arpa, internal, localhost, localdomain, home и обратные зоны in-addr.arpa, ip6.arpa. Сервер не ответил (нет ответа за 4 с, нет соединения) — вопрос уходит прежним путём, клиент получает ответ DNS роутера, а следующие имена вне правил идут прежним путём сразу, пока длится пауза (5 с, 10 с … до 300 с, как у группы); после паузы сервер снова спрашивается первым. Ответ SERVFAIL или REFUSED — этот вопрос тоже уходит прежним путём, но без паузы. Так интернет не пропадает вместе с сервером. Кэш (dns.cache) держит и ответы other. Без other — как раньше. На телефоне прежний путь — сервер, к которому шёл запрос приложения.

dns:
  cache: 2048
  bootstrap: [1.1.1.1, 8.8.8.8]
  upstream: doh3
  other: g
  upstreams:
    g:    { url: https://dns.google/dns-query, out: dnsvpn }
    dot:  { url: tls://one.one.one.one, ips: [1.1.1.1, 1.0.0.1] }
    q9:   { url: https://dns.quad9.net/dns-query, ips: [9.9.9.9] }
    cf:   { url: https://cloudflare-dns.com/dns-query, ips: [1.1.1.1] }
    doh3: { servers: [q9, cf, g], mode: failover }
rules:
  - { name: work, to: [work], out: eu, dns: dot }
  - { name: yt,   to: [youtube], out: dpi }                              # спрашивает doh3
  - { name: ai,   to: [ai], out: eu, dns: { servers: [q9, cf], mode: race } }
# имена вне правил — g; router, nas.lan — DNS роутера

steer explain <имя> называет под ответом строкой DNS:, каким сервером или группой ответил резолвер; dns-log — то же у каждого имени (поле dns), состояние групп и other (docs/ctl.md).

IPv6 доменных правил. Клиенты правила узнаются по IPv6, когда они — lan (клиенты по умолчанию: IPv6 берётся по devices), устройства, MAC, адреса IPv6 или приложения телефона; клиент из одних адресов IPv4 по IPv6 не узнаётся. У правила без IPv6 (выход xsteer, tgws, выход с ipv6: off, группа с таким членом, или клиент из одних IPv4) на AAAA его имён — пустой ответ, и клиент с двумя стеками сразу идёт по IPv4. Имя, совпавшее с несколькими правилами, получает AAAA, только если IPv6 есть у всех них: иначе поддельный или настоящий IPv6 у клиентов правила без IPv6 ушёл бы мимо его выхода. fakeip и realip — оба семейства. На HTTPS и SVCB для имён под правилом ответ пустой. Поддельный IPv6 — пара поддельного IPv4 того же имени (fdfe:dcba:9876::c612:5 — 198.18.0.5); steer explain по такому адресу называет правило и имя.

Пул fake-IP (resolve: fakeip). Поддельные адреса IPv4 берутся из 198.18.0.0/15 — 131070 адресов на всех клиентов. Адрес имени, которое не спрашивали 30 минут и к которому нет соединений, возвращается в пул. Что важно знать:

  • Настоящий адрес под поддельным закреплён. Пока имя спрашивают, под его поддельным адресом остаётся прежний настоящий, даже если в свежем ответе DNS его нет, — сеансы QUIC после паузы не уходят на другой сервер. Адрес заменяется, когда имя спросили после десяти минут простоя или прежнего адреса нет в ответах полчаса.
  • Имя, заблокированное сервером DNS. Ответ 0.0.0.0 (на AAAA — ::) не подменяется поддельным адресом: клиент получает пустой адрес и отказ сразу, как у выхода block, а не ждёт срока соединения.
  • Пул кончился — SERVFAIL. Имя под правилом получает SERVFAIL, а не настоящий адрес мимо выхода.
  • Доля клиента. За одним клиентом — адресом IPv4 или префиксом /64 IPv6 (кроме петли: за ней пересыльщики на самом роутере) — не больше 16384 поддельных адресов, восьмой части пула. У предела сначала возвращаются его же простоявшие имена; вернуть нечего — SERVFAIL получает только он.
  • Ожидания ответа. В таблице вопросов, ждущих сервера, у одного клиента не больше 128 мест из 1024: клиент, засыпающий резолвер вопросами без ответа, не отнимает DNS у остальных — его новый вопрос вытесняет его же самый давний.
  • Имена с чужими байтами. Вопрос, в метке которого байт 0, точка, пробел или управляющий символ, уходит наверх как есть — без правил, кэша и fake-IP.

Таблица выданных адресов переживает перезапуск резолвера (файл состояния в /var/lib/steer пишется в фоне через секунду после изменения).

rules — сверху вниз, выше — сильнее#

Список отображений.

Ключ Значение Умолчание
name подпись: в status и журнале резолвера; по-русски можно, кавычку нельзя; до 31 байта rule-<номер>
for клиенты из clients; lan — клиенты по умолчанию lan
to списки из lists; all — весь трафик обязателен
out выход или группа обязателен
resolve fakeip или realip dns.mode
dns имя апстрима (сервера или группы) из dns.upstreams или отображение { url, out, ips, bootstrap, fragment } либо { servers, mode } dns.upstream
enabled false — правило лежит в спеке, но не действует true
scope device — правило на одно устройство, старше глобальных по построению (в v1 — scope канала); global global
quic block — UDP/443 к назначениям правила отвергается (см. «Выключение QUIC» ниже); allow — не трогать allow
torrent block — торренты клиентов правила не пропускаются, direct — идут напрямую мимо выхода правила (см. «Торренты» ниже); allow — как весь трафик правила allow
family 4, 6 или both — семейство IP правила (см. «Семейство IP правила» ниже) both
on_family_unavailable fallback или block — что делать при family: 6, если выход IPv6 не несёт fallback

to: all — явное «весь трафик»; согласия allow_all, как у v1, не нужно: слово all пишут нарочно, опечаткой оно не получается.

Порядок правил — приоритет. Пакет или имя, попавшие в списки нескольких правил, забирает верхнее из них (правила scope: device — выше всех глобальных); у имени это верно и тогда, когда нижнее правило называет его точнее (youtube.com в нижнем, google.com и youtube.com — в верхнем: решает верхнее). Правила одного выхода с одними клиентами ядро держит одним набором nft, пока между ними нет правила с другим действием (другой выход, quic, torrent, override_port, family, resolve, dns), чьи клиенты могут совпасть с их клиентами. Если такое правило есть, нижнее получает свой набор на своём месте — с хвостом _s<номер> в имени (vpn_dom_s2): в [insta → A, youtube → B, google → A] адрес из списков youtube и google уходит в B.

Весь трафик и инверсный режим «РФ напрямую, остальное в туннель»#

to: all — правило «весь трафик» клиентов правила в выход: не только то, что совпало со списками. Своя сеть (10/8, 172.16/12, 192.168/16, link-local, multicast) в него не входит. Правило читается как последнее слово: выше — исключения, ниже — всё остальное.

Отдельного ключа «инверсия» нет, и отрицания списка тоже: порядок правил выражает то же, что режим «всё в туннель, кроме РФ» (throne, splify2#8), и ничего нового для разбора не требует. Первое совпавшее правило решает, а direct ловит пакет без метки и оставляет ему обычный путь:

lists:
  ru: { srs: lists/geoip-ru.srs, prefixes_file: lists/ru.lst, domains_file: lists/ru.dom }
outputs:
  direct: { kind: direct }
  nl:     { kind: tunnel, protocol: vless, subscription: sub/nl }
rules:
  - { name: ru-direct, to: [ru], out: direct }   # РФ — напрямую
  - { name: rest,      to: all,  out: nl }       # всё остальное — в туннель

Что стоит знать. Домены и адреса списка РФ работают так же, как у любого выхода: имя из доменного списка получает адрес из набора правила (direct_dom), набор стоит выше to: all и освобождает пакет от метки. Список ru обязан быть полным: адрес или имя РФ, которых в нём нет, уйдёт в туннель вместе с остальным. Обратный режим («в туннель только список, остальное напрямую») — обычное правило со списком, без to: all.

Семейство IP правила (family, on_family_unavailable)#

По умолчанию правило ведёт оба семейства, где выход их несёт (ключ ipv6 выхода, раздел outputs). family сужает правило до одного семейства, не трогая трафик и имена другого: человек управляет IPv6 по сервисам, а не глобально. Режим fake-IP правила — не отдельный ключ, это уже resolve: fakeip | realip.

family Резолвер Правила ядра
both (умолчание) A и AAAA — как раньше правило IPv4 и его двойник IPv6, где выход несёт IPv6
4 AAAA имён правила — пустой ответ, клиент идёт по IPv4 только правило IPv4; у to: all — ещё и отказ IPv6 клиентов правила (admin-prohibited, комментарий steer-v6fam:<набор>), чтобы IPv6 не ушёл напрямую мимо выхода
6 A имён правила — пустой ответ (не настоящий адрес мимо правила), AAAA — как у both только двойник IPv6; правила IPv4 нет

on_family_unavailable действует при family: 6, если IPv6 правилу недоступен: выход его не несёт (xsteer, tgws), ipv6: off или routed рядом с донором, либо клиенты заданы только адресами IPv4. fallback — правило работает по IPv4, как при family: 4; block — имена правила получают нулевые адреса на A и AAAA (соединение падает сразу, как у выхода block), а к IPv4 трафик не уходит. Ключ on_family_unavailable: block при другом family — отказ разбора: у 4 семейство есть всегда, а у both без IPv6 правило остаётся по IPv4, как и без ключей.

Правила с разной политикой не сливаются в один набор: к имени набора добавляется буква v (family: 4), w (family: 6, fallback) или k (family: 6, block); у правил без family имена прежние. family: 6 со списком srs пока не поддерживается (отказ «ещё не поддерживается»). Ключи пишет и spec convert; значение both не печатается.

rules:
  - { name: video, to: [video], out: wg0, family: 4 }          # видео — только IPv4
  - { name: v6net, to: [v6net], out: wg0, family: 6 }          # подсети IPv6 — только IPv6
  - { name: bank,  to: [bank],  out: nl,  family: 6, on_family_unavailable: block }

Выключение QUIC (quic: block)#

quic: block у правила отвергает UDP/443 клиентов правила к его назначениям — адресам списка, доменам (по fake-IP или реальному адресу, как у самого правила) или, при to: all, ко всему интернету вне своей сети. Отказ — ICMP «запрещено», как у kind: block: браузер узнаёт о нём сразу и открывает сайт по TCP, а не ждёт срока QUIC. Нужен там, где выход не несёт UDP (туннель по TCP: vless без UDP, socks, http) или несёт его плохо.

rules:
  - { name: video, to: [video], out: nl, quic: block }   # QUIC к video — отказ, TCP — в туннель nl
  - { name: rest,  to: all,     out: nl, quic: block }

Правила: порядок тот же — отказ действует только для пакетов, до которых дошло это правило, и правило выше QUIC своих адресов не теряет. Правило без ключа QUIC не трогает, даже если в тот же выход и для тех же клиентов ведёт соседнее правило с ключом (у них разные группы и наборы). Отказ ставится в prerouting_mark, поэтому при таком правиле разметка на ingress (docs/architecture.md) не включается — пересылка пакета на 2-5 % дешевле с ней. Только для клиентов раздачи: у правила на сам телефон (uid, self) ключ отвергается. Отказы разбора: значение не block/allow; список только proto: tcp или с ports, где нет 443. Со списками srs — ещё не поддерживается. Счётчик отказов — в комментарии правила steer-quic:<набор>.

Торренты (torrent: block | direct)#

Продавцы VPN банят за BitTorrent: их панели (Marzban, Remnawave, 3x-ui, Hiddify) включают на сервере распознавание протокола (sniffing Xray-core или sing-box) и правило protocol: bittorrent. Ключ torrent у правила не пускает торрент-клиентов его клиентов в выход правила: block — отказ (TCP — сброс, остальное — ICMP «запрещено», как у kind: block: клиент сразу идёт к другому пиру), direct — напрямую, обычным путём роутера.

rules:
  - { name: rest, to: all, out: nl, torrent: direct }   # всё в туннель, торренты — напрямую
  - { name: kids, for: kids, to: all, out: nl, torrent: block }

Что распознаётся. Не уже серверных снифферов: всё, что Xray-core (SniffBittorrent, SniffUTP) или sing-box (BitTorrent, UTP, UDPTracker) назовут bittorrent, распознаёт и ядро steer; сверх них — DHT и трекеры по HTTP. Стенд — tests/torrentmatch.sh на образцах из их тестов и граничных случаях их логики.

Признак Xray-core sing-box steer
Рукопожатие TCP \x13BitTorrent protocol да да да, в любом пакете TCP
SYN uTP (0x41, расширения 1 и 2, timestamp_difference 0, точная длина) да да да
Любой пакет uTP версии 1 типа 0..4 первой датаграммой потока нет да (после DNS, QUIC, STUN) да, кроме порта 53 и датаграмм с magic cookie STUN
Connect к UDP-трекеру (protocol_id 0x41727101980) нет да да
DHT (d1:ad2:id20:, d1:rd2:id20:) нет нет да
Трекер по HTTP (GET /announce, GET /scrape) нет нет да
Шифрованный MSE/PE, трекер по HTTPS нет нет только через память (ниже)

Правило sing-box для uTP широкое: первую датаграмму рукопожатия WireGuard (01 00 00 00) оно тоже зовёт bittorrent — значит, и ядро steer под ключом torrent не пускает WireGuard, который клиент правила сам запускает поверх выхода (сервер забанил бы за него так же).

Память. Один признак ловит малую часть потока, поэтому ядро запоминает на 10 минут (каждое совпадение продлевает срок) UDP-сокет клиента, с которого шёл торрент (DHT, uTP и UDP-трекеры у клиента идут с одного порта), и пира — адрес и порт из рукопожатия, uTP и трекера: следующее соединение к нему — торрент, в том числе шифрованное и по TCP после uTP. Пир запоминается только на порту от 1024: адреса пиров приходят от роя, и в нём бывают чужие (CDN на 80 и 443) — память о таком «пире» закрыла бы клиенту обычный HTTPS к нему; торрент-клиенты слушают порты от 1024, а соединение с признаком к порту ниже отвергается и без памяти (у direct поэтому трекер по HTTP на порту 80 сбрасывается при каждом анонсе — клиент берёт другие трекеры и DHT). Наборы памяти — torrent_src[6], torrent_peer[6]; их потолок — 65535 записей у каждого: набор, который пополняют пакеты клиентов, ядро Linux без потолка не заводит (сам ставит 65535), а без предела любое устройство в сети наполняло бы память роутера. Переполнение не отказ: новые записи не запоминаются, распознавание по содержимому идёт дальше. Шифрованный MSE/PE к пиру, которого ядро не видело ни по одному признаку, не распознаётся.

direct и уже открытый поток. Напрямую уходит поток, который ещё не ушёл в выход: первая датаграмма, SYN к запомненному пиру или поток, уже пущенный напрямую. Рукопожатие BitTorrent идёт первым пакетом данных, когда TCP уже открыт через выход, — такое соединение сбрасывается, пир запоминается, и следующее соединение к нему идёт напрямую с первого пакета.

Порядок — как у quic: block: распознавание стоит перед меткой своего правила, и правило выше свои торренты не теряет. Распознавание идёт в prerouting_mark, поэтому при таком правиле разметка на ingress не включается. Только для клиентов раздачи: у правила на сам телефон ключ отвергается. Отказы разбора: значение не block/direct/allow; ключ у правила в kind: block; direct у правила в kind: direct. Со списками srs — ещё не поддерживается. Счётчики и число запомненного — объект torrent в status (contract-v1.md); правила — комментарий steer-torrent:<набор>.

Сменили правилу out (или сняли, выключили правило) — после применения его установленные соединения прежнего выхода снимаются, и приложения соединяются заново уже через новый выход: иначе они жили бы на прежнем до своего конца (у группы balance, где прежний выход — член, — держались бы на нём). Правило узнаётся по name, поэтому переименование вместе со сменой выхода читается как новое правило и снятое прежнее. Подробно — docs/ctl.md, apply, «Смена выхода правила».

Несколько клиентов или списков у правила компилятор пока ведёт одним клиентом и одним списком, поэтому разбор сводит их, когда это не меняет смысла: клиенты одного вида (все адреса, все MAC, все UID) — в одного клиента, списки с одним сужением и без all — в один список, ровно как v1 пишет несколько файлов в одном канале. Не сводится (адреса с MAC, списки с разными proto/ports) — ещё не поддерживается: разнесите по правилам.

Отказы: нет out или to; ссылка на несуществующее имя; имя дважды в for/to; lan или all рядом с другими; у включённого правила на устройство — нет клиентов или у клиента подсеть, диапазон или диапазон UID (приоритет достался бы не одному устройству); правило на сам телефон в выход только для клиентов раздачи (tgws). Выключенное правило по смыслу не проверяется (иначе сломанное правило нельзя выключить, только удалить), но имена в нём обязаны существовать.

steer spec convert#

steer spec convert [--spec ФАЙЛ|-] [--json] читает спеку (v1 или v2) и печатает её спекой v2 в стиле примера раздела 3; --json — та же спека JSON-объектом с теми же ключами, --spec - — со стандартного ввода. Файл спеки не меняется. Напечатанное даёт тот же набор правил, что исходная спека v1, до байта — это проверяет tests/v2match.sh на всех спеках v1 из стендов генератора, — с одним исключением: пул devices спеки v1 печатается группой (kind: group, pick: order) с именованными членами <выход>.<устройство>, и у группы v2 есть закрепление соединений за членом (разделы «Группа» и «Закрепление»): у членов свои метки и таблицы, и набор правил другой.

Ответы резолвера после перевода те же, что у спеки v2: на AAAA имени под доменным правилом — поддельный или настоящий IPv6 там, где это разрешают выход и клиенты правила (см. «IPv6 доменных правил» выше).

Что придумывается при переводе — у v1 этого нет:

  • клиент и список канала получают имя канала, если оно годится в идентификатор (иначе rule<номер>); список «весь трафик» без сужения — to: all, с сужением — список all: true;
  • выход v1 с devices (пул) — группа pick: order (или latency при prefer: latency, с tolerance/interval) из выходов kind: interface с именами <пул>.<устройство>. Они печатаются после всех выходов спеки: реестр раздаёт метки по порядку выходов, и прежние выходы сохраняют прежние метки. В v2 это обычные выходы — со своей меткой и таблицей;
  • via — over; sub_file — subscription; opts_file — strategy; node: N — nodes: [N]; from_default — lan.addr; lan_device(s) — lan.devices; mode: realip — resolve: realip; traceroute_hops — dns.traceroute_hops;
  • умолчания, которые вид выводит из имени выхода (путь conf/strategy, имя устройства tunnel, xsteer и awg), не печатаются.

Ещё не поддерживается#

Спека с этим отвергается ещё не поддерживается в этой версии ядра steer: …:

Что Чем выразить сейчас
pick: balance для правил на сам телефон (uid, self) группой order, latency или manual
встроенные domains/prefixes списка файлами: domains_file, prefixes_file, srs
app клиента uid
клиенты разных видов или списки с разными сужениями в одном правиле разнести по правилам
family: 6 у правила со списком srs списками prefixes_file и domains_file либо to: all
torrent у правила со списком srs to: all или списки prefixes_file и domains_file
quic: block у правила со списком srs отдельный список all: true, proto: udp, ports: [443] с out в выход block выше правила (для всех адресов)