Skip to content

Latest commit

 

History

History
703 lines (572 loc) · 67.5 KB

guide.md

File metadata and controls

703 lines (572 loc) · 67.5 KB

steer — ядро маршрутизации по правилам для OpenWrt

steer решает, какой трафик уходит в туннель, а какой идёт напрямую. Правила описываются одним файлом — спекой (YAML или JSON), ядро steer превращает его в правила nftables, таблицы маршрутизации и наборы адресов — одной атомарной транзакцией.

Это ядро и только ядро: списки оно не скачивает, веб-интерфейса у него нет. Если нужен интерфейс с готовым каталогом сервисов и автообновлением списков — смотрите splify2, он управляет этим ядром.

Telegram Поддержать проект

Что он умеет

  • Правила, а не «весь трафик в VPN». Правило описывает, какой трафик и от каких клиентов уходит в какой выход. Правила проверяются сверху вниз, побеждает первое совпавшее.
  • Маршрутизация по доменам, а не только по адресам. Встроенный резолвер подменяет ответ на служебный адрес из диапазона 198.18.0.0/15 (для IPv6 — fdfe:dcba:9876::/96), а ядро Linux возвращает настоящий через DNAT. Это точнее списков адресов: один адрес CDN обслуживает сотни сайтов, и по адресу их не различить. У правила может быть свой сервер DNS — DoT, DoH (в том числе по HTTP/3), DoQ, обычный UDP/TCP, напрямую или через выбранный выход, — группа из нескольких серверов (все сразу или по очереди с переключением), свой сервер для имён вне правил и кэш ответов (dns в docs/spec-v2.md).
  • Экономия памяти. Национальный блок-лист в сотни тысяч префиксов не влезает в роутер как есть. steer fit ужимает его до заданного числа элементов набора, объединяя соседние префиксы по плотности, и честно сообщает, чего это стоило.
  • Отказоустойчивость. Группа выходов выбирает член по порядку, по задержке, вручную или раздаёт соединения по живым; сторож проверяет выходы и переключает трафик на живой. Когда не работает ни один — поведение задаётся вами (on_fail), а по умолчанию трафик останавливается, а не уходит в открытый интернет.
  • Свои клиенты протоколов — плагины из пакета ядра: VLESS/Reality (транспорты tcp, grpc, xhttp, ws, httpupgrade, поток Vision), hysteria2, trojan, shadowsocks, socks, http, vmess, xsteer и Cloudflare WARP. Туннели несут TCP и UDP, IPv4 и IPv6, поэтому через них работают QUIC (HTTP/3), WireGuard и игровой трафик.
  • WireGuard поверх поддельного TCP для сетей, где UDP режут или пропускают по белому списку протоколов. Серверная половина ставится на VPS, см. server/.

Установка

Возьмите пакет своей архитектуры из ветки dist или со страницы релизов. Содержимое одинаковое; ветка на зеркале нужна тем, у кого провайдер закрыл githubusercontent.com — прямая ссылка релиза ведёт именно туда и не откроется. Архитектура в имени файла — та же, что показывает DISTRIB_ARCH в /etc/openwrt_release. Пакеты собираются под 11 архитектур: aarch64_cortex-a53, aarch64_cortex-a72, aarch64_cortex-a73, aarch64_generic, arm_cortex-a7_neon-vfpv4, arm_cortex-a9, arm_cortex-a9_neon, arm_cortex-a9_vfpv3-d16, mipsel_24kc, mips_24kc и x86_64.

Пакет на архитектуру один — steer-core. Протоколы и виды выходов — плагины: vless, hysteria2, proxy, xsteer, obfs, warpbox, awg и общая библиотека net1. Их архивы лежат в самом пакете ядра (семя), поэтому ставятся без сети; подпись архивов ядро проверяет ключами из того же пакета.

# OpenWrt 25.12 и новее (менеджер пакетов apk)
apk add --allow-untrusted ./steer-core-<версия>-1_<арх>.apk

# OpenWrt 24.10, 23.05 и 22.03 (менеджер пакетов opkg)
opkg install ./steer-core-<версия>-1_<арх>.ipk

# что поставлено; недостающий протокол — из семени пакета, без сети
steer plugin list
steer plugin install vless

Установка пакета сама зовёт steer plugin migrate: если спеки ещё нет, из семени ставятся все плагины протоколов, а если спека есть — те, что нужны видам её выходов. Архивы вставших плагинов из семени после этого удаляются: на флеше остаются только распакованные плагины (ядро со всеми протоколами — около 3,8 МБ на mipsel и 3,1 МБ на aarch64). Плагин, снятый потом, без сети из семени уже не поставить — только из сети. Панель splify2 ставит нужные плагины сама — по видам выходов, которые вы заводите.

Что в пакете steer-core:

Что Где
демон и вся логика ядра: компилятор спеки, применение, сторож, резолвер, инструменты, менеджер плагинов /usr/sbin/steerd
клиент управляющего сокета (то, что вы набираете как steer) /usr/sbin/steer
ссылка на steerd, которая отвечает только на инструменты и команды плагинов /usr/sbin/steer-tools
библиотеки ядра и криптографии (модель спеки, TLS, QUIC); wolfSSL и ngtcp2 из них берёт и плагин net1 /usr/lib/libsteer.so.*, /usr/lib/libsteer-wolfssl.so.*, /usr/lib/libsteer-ngtcp2.so.*
служба, реакция на события сети, список настроек для sysupgrade /etc/init.d/steer, /etc/hotplug.d/iface/95-steer, /lib/upgrade/keep.d/steer
семя: подписанные архивы плагинов протоколов и их индекс; архив плагина, который встал, после установки удаляется /usr/share/steer/seed
открытые ключи официальных репозиториев плагинов /usr/share/steer/keys

Зависимости пакета — nftables, ip-full, conntrack, kmod-nft-queue и kmod-tun (туннелям VLESS, hysteria2, прокси и xsteer нужно устройство TUN). Пакет steer-core заменяет пакеты steer, libsteer и libsteer-wolfssl прежней раскладки: при установке они снимаются.

Плагины

Плагин Что даёт Откуда
vless выход kind: tunnel, protocol: vless — VLESS/Reality по подписке или ссылкам vless:// (docs/vless.md) семя
hysteria2 protocol: hysteria2 — QUIC, Brutal, Salamander, прыжки по портам (docs/hysteria2.md) семя
proxy protocol: trojan, shadowsocks, socks, http, vmess (docs/proxy.md) семя
xsteer выход kind: xsteer — клиент звезды xsteer (docs/xsteer.md) семя
obfs обфускатор для выхода kind: interface с ключом obfs: WireGuard поверх поддельного TCP семя
warpbox выход kind: warp — Cloudflare WARP: регистрация, подбор точек, сторож туннелей (docs/warp.md); ставит и awg семя
awg модуль ядра Linux для выходов kind: awg (AmneziaWG) и членов WARP: ставит системный пакет kmod-amneziawg, а если его нет в фидах — kmod-wireguard. Сам вид awg — в ядре steer и принимается и без плагина семя
net1 общая сетевая библиотека плагинов vless, hysteria2, proxy, xsteer и warpbox; ставится вместе с ними семя
tgws выход kind: tgws — мост Telegram; пул доменов, пути и адреса дата-центров, туннели WARP — настройки плагина репозиторий splify2-extended-plugins

Выход, чей плагин не стоит или выключен, недоступен: apply спеку с ним не принимает с причиной «нужен плагин … — поставить», а status показывает выход unavail с той же причиной. Какие виды выходов и ключи есть на этом роутере сейчас, печатает steer spec-schema.

Команды менеджера плагинов (steer help plugin; у каждой есть --json):

Команда Что делает
steer plugin list стоящие плагины: состояние, причина, доступное обновление
steer plugin search [слово] каталог всех подключённых репозиториев
steer plugin status [id] состояние; с id — ещё сверка файлов плагина с его описью
steer plugin install <id> [версия] поставить самую новую подходящую (или названную) версию; без сети — из семени
steer plugin install --file x.s2p [--unsigned] поставить из файла; без подписи — только с --unsigned, и такой плагин сам не обновляется
steer plugin update [id] обновить один или все
steer plugin remove <id> [--force] [--purge] снять; плагин, нужный выходам спеки или другим плагинам, снимается только с --force; --purge удаляет и его настройки
steer plugin enable <id>, disable <id> включить, выключить, не снимая
steer plugin autoupdate <id> on|off фоновое обновление плагина
steer plugin repo list, repo add <url> <номер ключа>, repo del <имя> репозитории; ключ для repo add — со стандартного ввода или --key-file

Плагины лежат в /usr/lib/steer/plugins/<id>/, их состояние — в /etc/steer/plugins/state.json, настройки — в /etc/steer/plugins/conf/<id>/, репозитории — в /etc/steer/plugins/repos.d/. Оба каталога плагинов переживают обновление прошивки с сохранением настроек (/lib/upgrade/keep.d/steer-plugins).

Подписи. Плагины ставятся только с подписью. Открытые ключи официальных репозиториев приходят в пакете steer-core (/usr/share/steer/keys), чужой репозиторий добавляется со своим ключом: steer plugin repo add <url> <номер ключа> — номер ключа (16 знаков hex) обязан совпасть с самим ключом, а индекс репозитория скачивается и проверяется этим ключом сразу. Пакет steer-core подключает официальный репозиторий splify2; репозиторий splify2-extended-plugins, откуда ставится tgws, подключает панель splify2 (без неё — steer plugin repo add).

Обновление в фоне. Демон раз в сутки проверяет обновления плагинов, у которых оно включено, и ставит их в ночном окне (по умолчанию 03:00–05:00); обновление безопасности ставится сразу. После установки менеджер проверяет здоровье плагина и при неудаче откатывает его на прежнюю версию. Плагины семени — той же версии, что ядро; новое ядро при установке обновляет из своего семени уже стоящие плагины официального репозитория, если в семени версия выше.

Обновление с 2.0.x на 2.1

steer-core 2.1.0 сам снимает пакеты steer-vless, steer-hysteria2, steer-proxy, steer-xsteer, steer-obfs, steer-warpbox, steer-tgws и steer-extended: протоколы теперь плагины, они ставятся из семени в самом пакете ядра, без сети. Какие ставить, steer plugin migrate (его зовёт установка пакета) решает по видам выходов вашей спеки и по прежним пакетам модулей: стоял steer-vless — встанет плагин vless, стоял steer-extended — vless, xsteer и obfs. Мост Telegram — тоже плагин (tgws), но из репозитория splify2-extended-plugins: в семени ядра его нет, ставьте его из вкладки «Плагины» splify2. Пока плагина нет, выход моста недоступен и живёт по своему on_fail, остальные выходы работают: steer status показывает его с причиной «нужен плагин tgws — поставить», steer diag — что сделать, а steer plugin migrate при установке ядра называет плагин, который придётся поставить из сети. Настройки микропакета stgws переносятся в плагин при его установке. Если прежние пакеты ставились файлами и apk отвечает breaks: world[steer-core><Q1…], назовите прежние модули в той же команде (… steer-vless steer-xsteer) или уберите закрепления способом ниже.

С коннектором (steer-box-connector, sing-box для podkop и forkop) ядро ставится вместе с пакетом steer-box-connector 2.1 одной командой (apk upgrade или оба файла в одном apk add): с 2.1 коннектор — плагин ядра box-connector, а пакет без файлов держит имя sing-box, которое требуют podkop и forkop, и ставит плагин. Одно ядро apk не поставит — пакет 2.0.x требует ядро своей версии. Подробно — в документации коннектора.

Пути, которые чужая программа ищет по известному адресу (у box-connector — /usr/bin/sing-box, /etc/init.d/sing-box), плагин объявляет в манифесте (steer.links, steer-api 1.3), а ставит их менеджер плагинов: ссылки в каталог плагина, настройки — копией. Путь, который занят файлом пакета, менеджер не перезаписывает — отказ называет пакет.

Своего экземпляра ядра у коннектора нет: sing-box run отдаёт переведённую спеку службе steer через её сокет. Чтобы правила steer не пересекались с метками podkop и forkop, плагин просит у ядра другое поле метки (0x000000ff), приоритет правил выходов, возврат решения после чужой перезаписи метки и каналы на сам роутер (steer.platform, steer-api 1.4). Менеджер плагинов пишет их в /etc/steer/plugins/platform.env и поднимает службу ядра заново; снят или выключен плагин — ядро возвращается к своему полю.

Что ещё изменилось в 2.1 и может встретиться после обновления:

  • Выход kind: zapret удалён: спека с ним отвергается с названием замены — модуль DPI recheck или kind: direct. on_fail: zapret (уживание с системным zapret) остался.
  • Нужен Linux 5.2 и новее (nat в таблице inet): раскладка набора правил для Linux 4.9 удалена.
  • /etc/init.d/steer restart (его же зовёт обновление пакета) больше не снимает правила — подробно в разделе «Команды».
  • Проверка спеки строже — см. «Имена и пути» ниже.

Если после неудачной установки apk отказывает во всём

apk add локального файла записывает в /etc/apk/world не просто имя пакета, а имя с контрольной суммой файла — steer-core><Q1…. Если установка оборвалась на середине (чаще всего на роутере с малым флешем: «No space left on device» при распаковке пакета), в этом файле остаются суммы новых файлов, а в базе — прежние пакеты. С тех пор любая команда apk, в том числе установка чужого пакета, отвечает:

ERROR: unable to select packages:
  steer-core-2.0.3-r1:
    breaks: world[steer-core><Q1…]

Поломка воспроизведена на apk 3.0.5 (его ставит OpenWrt 25.12.5). Чинится правкой самого файла (apk add имя в таком состоянии тоже отказывает): записи о пакетах, которых нет в базе, убираются, остальные теряют привязку к файлу и остаются просто именами.

awk 'FILENAME==ARGV[1]{if($0~/^C:/){c=substr($0,3);if(p!="")i[p]=c}else if($0~/^P:/){p=substr($0,3);if(c!="")i[p]=c}if($0==""){c="";p=""}next}{k=index($0,"><");if(!k){print;next}n=substr($0,1,k-1);if(n in i)print n}' /lib/apk/db/installed /etc/apk/world > /tmp/world.fix && cat /tmp/world.fix > /etc/apk/world && apk fix

После неё поставьте пакет заново (при нехватке места — сначала освободите флеш: df -h /overlay). Установщики splify2 и коннектора делают то же сами — до установки и после неё.

Быстрый старт

Спека лежит в /etc/steer/spec.yaml или /etc/steer/spec.json — одна из двух: лежат обе — отказ «две спеки». Формат — спека v2 (docs/spec-v2.md); прежний формат, спеку v1 (JSON со schema, docs/contract-v1.md), ядро тоже читает и переводит в v2 при загрузке, а steer spec convert печатает её спекой v2. Минимальная конфигурация — «домены и адреса из списков через WireGuard, всё остальное напрямую»:

version: 2
lan: { devices: [br-lan] }
lists:
  blocked: { domains_file: lists/blocked.dom, prefixes_file: lists/blocked.lst }
outputs:
  vpn: { kind: interface, device: wg0, on_fail: drop }
rules:
  - { name: блоклист, to: [blocked], out: vpn }
steer apply --dry-run          # посмотреть, что получится, ничего не применяя
steer apply                    # применить
steer status                   # что стоит сейчас
steer diag                     # проверки состояния: что сломано и почему
steer explain example.org      # какое правило и какой выход достанутся этому имени

Списки — обычные текстовые файлы, по записи на строку; относительный путь считается от каталога спеки (lists/blocked.dom — это /etc/steer/lists/blocked.dom). Адресные: 10.0.0.0/8, 1.2.3.4 (это то же, что /32), диапазон 10.0.0.1-10.0.0.9, IPv6. Доменные: example.org (имя и его поддомены), *.example.org, =exact.example.org (только это имя), re: с регулярным выражением. Пустые строки и строки, начинающиеся с # или ;, пропускаются. Испорченная адресная строка (300.1.1.1, 10.0.0.0/33, 1.2.3.4/, оборванная загрузка, октет с ведущим нулём 010.1.1.1) пропускается с одним предупреждением на список, а не отвергает весь набор правил.

Ядро списки не скачивает: оно читает то, что ему положили. Это сознательное разделение — скачивание, расписания и выбор источника принадлежат управляющему слою.

Настройка: спека

Все ключи, умолчания и отказы — docs/spec-v2.md; машиночитаемая схема — steer spec-schema [--json] (docs/spec-schema.md). Здесь — то, что нужно в первую очередь.

Разделы

Раздел Что в нём
version 2, обязательно.
lan Клиенты по умолчанию: devices — устройства, с которых берётся трафик клиентов (по умолчанию [br-lan]), или addr — их адреса.
clients Именованные группы клиентов: по адресам (addr) или MAC (mac).
lists Назначения: файлы адресов (prefixes_file), доменов (domains_file), наборы sing-box (srs), сужение по протоколу и портам (proto, ports), «весь трафик» (all).
outputs Выходы: куда можно направить трафик — устройство, туннель, группа, блок.
dns Резолвер: режим fakeip или realip, кэш, серверы DNS и их группы.
rules Правила сверху вниз: каких клиентов (for), что (to), куда (out). Порядок значим.

Не только устройства из LAN

Роутер часто служит выходной точкой не одному мосту: к домашним устройствам добавляются хосты из Tailscale или ZeroTier, для которых он шлюз. Перечислите их интерфейсы, и те же правила начнут работать и для них:

lan: { devices: [br-lan, tailscale0, ztrq4abcde] }

Выбор идёт по устройству, а не по подсети, и это важно: у tailscale0 адрес на роутере обычно /32, то есть подсеть пиров из него не вывести вовсе. Устройство, которого нет при apply, — не отказ: правило для него начнёт действовать, когда интерфейс поднимется. Чтобы доменные правила действовали и на клиентов mesh-сети, их запросы DNS заворачивает на резолвер ключ dns.mesh_clients: true (по умолчанию выключено).

Имена и пути

Имена клиентов, списков, выходов и серверов DNS — латиница, цифры, _, - и точка, до 31 байта; имя не начинается с - и не равно . или ..: имена подставляются в командные строки, в имена наборов nftables и файлов состояния, и разбор отвергает всё остальное. Имена правил — подписи для человека, в них можно писать по-русски; нельзя только кавычку. В пути файла нельзя «|» и управляющие символы, а относительный путь не начинается с dns:. Адрес с ведущим нулём в октете (010.1.1.1) в спеке — отказ: nft прочёл бы его восьмеричным, как 8.1.1.1. Каждый отказ называет место в тексте спеки: файл:строка:столбец.

Выходы

outputs:
  wg:   { kind: interface, device: wg0, on_fail: drop }
  awg:  { kind: awg }                                   # AmneziaWG, настройка — /etc/steer/awg/awg.conf
  nl:   { kind: tunnel, protocol: vless, subscription: sub/nl.txt, on_fail: zapret }
  res:  { kind: group, pick: order, members: [wg, nl] }
  deny: { kind: block }
  • kind — direct (не маршрутизировать), interface (уже существующее устройство), awg (AmneziaWG, устройство заводит ядро), block (трафик правила не пропускается), group (группа выходов) и виды плагинов: tunnel (VLESS, hysteria2, trojan, shadowsocks, socks, http, vmess), xsteer, warp, tgws.

  • group — members по предпочтению и способ выбора pick: order — первый живой, latency — самый быстрый с допуском, manual — выбор человека (steer select <группа> <член>), balance — новые соединения раздаются по живым членам. У order и latency установленное соединение доживает на прежнем члене, пока тот жив, а новые идут на выбранный.

  • on_fail — что делать, когда выход не работает:

    Значение Поведение
    drop (по умолчанию) Трафик останавливается. Правило заводят именно для того, чтобы трафик НЕ шёл напрямую; молча вернуть его на открытый путь в момент поломки — значит нарушить единственное обещание выхода ровно тогда, когда это опаснее всего.
    direct Трафик идёт напрямую, как обычный трафик роутера: общий обход DPI (zapret), если он запущен, его разбирает.
    zapret Напрямую, но ядро проверяет, что обход DPI действительно запущен.
  • obfs — WireGuard поверх поддельного TCP, только для kind: interface (нужен плагин obfs). Поля: server и listen — адрес:порт литералами ("203.0.113.10:4567", "127.0.0.1:51820"; listen должен совпадать с Endpoint пира WireGuard), mode — wg-over-tcp (умолчание).

Подмену адреса IPv4 (masquerade) для выходов interface, awg и членов WARP ставит само ядро steer в своей таблице — в зоне fw4 она не нужна.

Правила

clients:
  tv: { addr: [192.168.1.50] }
rules:
  - { name: телевизор, for: [tv], to: [video], out: res }
  - { name: телефон, for: [phone], to: all, out: nl, scope: device }
  • name — подпись. Она же уходит в status, чтобы у счётчика было имя.
  • for — клиенты из clients; без ключа — клиенты по умолчанию (lan). У одного клиента — либо адреса, либо MAC, смешивать нельзя (nft не умеет «или» внутри правила): заведите два клиента.
  • to — списки из lists; all — весь трафик клиентов правила, кроме своей сети.
  • out — выход или группа.
  • enabled: false выключает правило целиком: ни набора, ни правила в цепочке. Удобно, чтобы отключить правило на вечер, не удаляя его вместе с выбранными списками.
  • resolve — режим резолвера для доменов правила, fakeip или realip (по умолчанию — dns.mode).
  • quic: block отвергает UDP/443 к назначениям правила, и браузер переходит на TCP; torrent: block | direct не пускает BitTorrent клиентов правила в его выход — отказ или напрямую.
  • family: 4 | 6 | both и on_family_unavailable — семейство IP правила (ниже, «IPv6»).

Правило на устройство

scope: device у правила, чей клиент — одно устройство, делает правило старше любого глобального — и старше по построению, а не по месту в списке.

Так записываются две вещи, которые иначе не выразить надёжно: «весь трафик этого телефона в туннель» (to: all и туннельный выход) и «этот ноутбук не маршрутизируем вовсе» (to: all и выход direct). Пока порядок читался только со спеки, исключение для телефона работало ровно до тех пор, пока человек держал его выше глобальных: добавил новое глобальное правило первым — и исключение перестало действовать, молча. С scope: device компилятор кладёт правила устройств первыми; внутри каждой из двух половин порядок спеки сохраняется.

Клиент такого правила — одиночные хозяева: адрес, адрес с /32 или MAC. Подсеть отвергается: приоритет достался бы не одному устройству, а всем в ней, и достался бы тихо. MAC надёжнее адреса: адрес по DHCP сменится, MAC — нет.

Протокол и порты

Ради одного случая, которого иначе не выразить: discord у itdoginfo/allow-domains — это не домены, а 104.16.0.0/12 плюс udp 50000-65535, 19000-20000. Подсеть эта — Cloudflare, и взять её без портов значит увести в туннель весь TCP к Cloudflare молча.

lists:
  discord: { prefixes_file: lists/discord.lst, proto: udp, ports: [50000-65535, 19000-20000] }

Порты не источник совпадения: список из одних портов, без адресов или all, отвергается — правило без адресов накрыло бы этими портами весь интернет. Диапазонов портов на список — не больше 16, пересечения отвергаются.

Наборы sing-box (.srs)

Списки itdoginfo/allow-domains и геоданные sing-box публикуются двоичными .srs. Список читает их сам — раскладывать в текстовые файлы не нужно:

lists:
  discord: { srs: lists/discord.srs }

Сужение у правил набора своё (у discord.srs имена без сужения, подсети — только udp и порты голоса), и ядро применяет его само. Логические правила, исключения, source_ip_cidr тоже выражаются; то, что к платформе неприменимо (процессы, Wi-Fi), снимается с предупреждением. Набор, дерево правила которого больше 131072 узлов, отвергается с этим числом. steer srs-read печатает набор синтаксисом списка — посмотреть, что в нём.

fakeip или realip

fakeip (по умолчанию) realip
Как работает Резолвер выдаёт клиенту служебный адрес из 198.18.0.0/15, ядро Linux подменяет его на настоящий через DNAT Резолвер отдаёт настоящий ответ сервера DNS и кладёт этот адрес в набор правила
Точность По имени, максимальная Теряется там, где два домена живут на одном адресе
traceroute Все узлы показывают поддельный адрес: ядро переписывает ICMP-ошибки так, будто они пришли с того адреса, к которому обращался клиент Узлы читаются нормально

Берите fakeip, пока не понадобится читаемый traceroute (или ключ dns.traceroute_hops).

Как ведёт себя fake-IP:

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

Команды

В пакете ядра три имени. steerd — демон, компилятор, применение, резолвер, менеджер плагинов и инструменты. Протоколы приходят плагинами (/usr/lib/steer/plugins/<id>/, ставит steer plugin): помощников их выходов демон поднимает программой плагина, а команды протоколов (vless-nodes, sub-fetch, xsteer-key, obfs-server и другие) объявляет манифест плагина — steerd запускает его программу с теми же словами, выводом и кодом возврата; нет плагина — нет и команды. steer — маленький клиент: команды, на которые отвечает демон (status, diag, explain, conns, dns-log, select, apply, reload, subscribe), он посылает в сокет демона и печатает ответ с тем же выводом и кодом возврата, что у одноимённой подкоманды ядра; всё остальное — и любую команду, когда демон не запущен, — исполняет steerd. steer-tools — ссылка на steerd, которая отвечает только на инструменты (fit, srs-read, sub-hwid, dev-id, dnsd-table) и на команды плагинов.

Службу держит /etc/init.d/steer: procd запускает один процесс steerd daemon --watch --supervise --apply. Он применяет спеку при старте, сторожит выходы, держит помощников выходов и резолвер. Если применение при старте не прошло (fw4 ещё не поднялся, список докачивается), демон повторяет его сам — через 5 с, с удвоением паузы до 5 минут. /etc/init.d/steer reload (и reload_dnsd, reload_zapret, reapply) просит демон перечитать спеку, и он трогает только изменившееся.

restart (его же зовёт обновление пакета) правила не снимает: сменяется только демон, набор правил, правила маршрутизации и таблицы выходов остаются в ядре Linux, резолвер достаётся новому демону — DNS клиентов не пропадает, а трафик выходов с on_fail: drop не уходит мимо туннеля. На время смены туннели лежат, и их трафик ведёт себя как при отказе выхода. stop гасит демон и снимает правила: кто остановил службу, хочет её выключить.

Ядро само себя документирует:

steer help                 # список команд по разделам
steer help apply           # что делает команда и какие у неё флаги
steer apply --help         # то же самое
steer --version            # версия, вариант сборки и ревизия
steer version --json       # версии ядра, steer-api и steer-abi
Команда Что делает
apply [--dry-run] Скомпилировать спеку в правила. --dry-run печатает готовый набор правил и ничего не применяет.
status [--fast] Применённое состояние: выходы, выбранные устройства, правила, счётчики. JSON.
diag Проверки состояния: таблица, наборы, устройства, резолвер, подмена адреса, обфускация. JSON; код 1 — что-то сломано.
explain <адрес|имя> Какое правило поймает адрес и в какой выход он уйдёт. Отвечает на вопрос «почему этот сайт идёт не туда».
select <группа> <член> Выбрать член группы pick: manual; выбор переживает перезапуск.
reload Попросить демон перечитать спеку и применить только изменившееся. Без демона — отказ с кодом 3.
subscribe Печатать события демона по мере прихода: спека применена, выход переключён, помощник поднялся или упал.
daemon [--watch] [--supervise] [--apply] Сам демон: сокет управления, сторож выходов, помощники и резолвер детьми, применение при старте. Протокол — docs/ctl.md.
down Снять правила и маршруты ядра steer.
plugin … Менеджер плагинов (выше, «Плагины»).
spec convert [--json] Напечатать спеку спекой v2 (YAML или JSON), не меняя файл.
spec-schema [--json] Схема спеки v2: ключи, типы, умолчания, подсказки, виды установленных плагинов.
outputs [--kind ВИД] [--obfs] Перечислить выходы.
failover Один проход сторожа: выбрать живое устройство для каждого выхода. В службе сторожит демон.
fit [файл] Подогнать список префиксов под память.
srs-read <файл.srs> Напечатать набор sing-box синтаксисом списка.
conns Соединения, которые ведёт ядро: какой выход держит каждое (по метке conntrack). JSON.
dns-log Журнал имён: какие имена недавно спрашивали, в какое правило они попали и сколько раз. JSON.
dns-probe URL… Проверить серверы DNS тем же кодом, что у резолвера. JSON.
sub-hwid Идентификатор этого роутера для панели подписки. JSON.

Команды плагинов: vless-nodes, vless-probe, sub-fetch, sub-quota, sub-check, tls-probe (плагин vless, docs/vless.md); hysteria2-nodes, hysteria2-probe (плагин hysteria2); proxy-nodes, proxy-probe (плагин proxy); xsteer-key, xsteer-link, xsteer-peers, xsteer-check (плагин xsteer); warp-scan, warp-reg (плагин warpbox); obfs-server (плагин obfs). Справка — steer help <команда>, когда плагин стоит.

sub-fetch скачивает подписку с потолком 64 МиБ на скачанное и на распакованное тело. Ответ панели без единого пригодного узла не заменяет рабочую подписку: отказ «прежняя подписка оставлена». Идентификатор и модель устройства уходят только панели, а не хосту, на который она переадресует.

Общие флаги: --spec ФАЙЛ (по умолчанию /etc/steer/spec.json или /etc/steer/spec.yaml) и --state-dir КАТАЛОГ (по умолчанию /var/lib/steer) принимает каждая команда, читающая спеку.

status запоминает свой ответ в состоянии, а status --fast отдаёт запомненное немедленно, не разбирая спеку и не спрашивая ни /sys, ни nft: он нужен первым при открытии окна управления. Запомненный ответ несёт "cached": true, а время сборки стоит в at у любого ответа — память нельзя рисовать живой. Снимок раз в пять минут освежает и демон.

Разбор аргументов строгий: неизвестный флаг, флаг, которого команда не понимает, потерянное значение и не-число там, где ждали число, — это отказ с кодом 2, а не молчание. Опечатка в --dry-run не применит правила по-настоящему.

Коды возврата и разделение потоков описаны в docs/contract-v1.md, раздел 6. Коротко: 0 — сделано, 2 — ядро отказалось, а 1 зависит от команды и означает «отрицательный ответ» у diag и fit, но настоящий провал у apply. Отказы спеки, менеджера плагинов и управляющего сокета несут код и подстановки — список в docs/errors.md.

Подгонка списков под память

steer fit --budget 20000 --report /tmp/fit.json < ru.lst > ru-fitted.lst

Фиттер объединяет соседние префиксы по плотности: если внутри /24 лежат хотя бы два адреса из списка, вся сеть заменяется одним элементом. Отчёт говорит, сколько адресов при этом добавилось лишних (waste_addresses) и влезло ли вообще (fits).

Если не влезает — по умолчанию список выходит целиком с пометкой fits:false и кодом 1, а не обрезается: тихая дыра над одним адресом хуже честного отказа. Обрезать хвост разрешает --truncate.

--exclude принимает список адресов, которые не должны попасть в результат. --punch-out вместо отказа от объединения выписывает пересечения в отдельный файл — их держат отдельным правилом выше.

Диагностика

steer diag отвечает JSON со списком проверок и вердиктами ok, note, warn, fail. Код возврата 1 означает, что хотя бы одна проверка — fail; JSON при этом полный и валидный.

steer explain <адрес|имя> называет правило и выход. Это первое, что стоит спросить, когда сайт идёт не туда.

Ядро steer пишет в журнал с префиксом уровня — steer[warn] или steer[info], — и классифицировать строки следует по префиксу, а не по тексту: формулировки меняются между версиями. За префиксом идёт метка подсистемы, например apply, ctl, dnsd. Отказы тому, кто позвал ядро (негодная спека, плохой аргумент), уровня не несут: это ответ вызывающему, а не запись в журнал. Отвергнутый набор правил остаётся для разбора одним файлом steer-ruleset.rejected.

Что случается чаще всего

Домены не маршрутизируются, а адресные списки работают. Резолвер не запущен или не перечитал спеку. steer diag назовёт это.

Публичный резолвер внутри списка. Списки по номеру автономной системы забирают всё, что живёт в той же AS, поэтому 8.8.8.0/24 приезжает в категорию «Google», а 1.1.1.0/24 — в Cloudflare. Такой адрес уводит в туннель DNS клиентов, которые ходят напрямую к публичному резолверу. diag находит это и называет и резолвер, и файл.

DNS-сервер внутри LAN перестал получать запросы. Загружен br_netfilter и включён net.bridge.bridge-nf-call-iptables — тогда кадры, ходящие внутри моста, проходят через ip-хуки netfilter, и перенаправление порта 53 забирает даже запросы клиента к Pi-hole на той же сети: правило смотрит на клиента, а не на получателя. diag называет это (bridge_nf). Само ядро steer настройку не трогает — она общесистемная, её ставят docker и libvirt.

Трафик уходит в туннель и не возвращается. У устройства выхода нет подмены адреса (NAT). Для выходов interface, awg и членов kind: warp masquerade IPv4 ставит само ядро steer, в своей таблице (цепочка postrouting_nat4); выходам, которые сами завершают соединения (VLESS, hysteria2, прокси), и xsteer она не нужна. diag проверяет подмену для устройства и говорит об этом отдельной строкой.

Через туннель работает всё, кроме больших пакетов. MTU. Особенно при обфускации, см. server/README.md.

Правило заведено, а трафик им не идёт. Проверьте порядок: побеждает первое совпавшее правило. И посмотрите for — если клиента там нет, правило его не касается.

В журнале «не отвечает (1 из 3 подряд) — трафик пока не трогаю». Устройство выхода не ответило на проверку, но сторож не перезапускает туннель и не останавливает трафик по одному проходу: потерянные пакеты проверки и короткий провал у провайдера не должны рвать соединения, которые через туннель идут. Проверка повторяется через 15 секунд; три прохода без ответа подряд — туннель перезапускается, а если не ожил — действует on_fail выхода. Туннель, который в это время принимает трафик, не перезапускается вовсе (строка «принимает трафик — туннель не трогаю»), как и любой туннель, пока у самого роутера нет пути наружу («молчит провайдер»). Подробно — docs/ctl.md, «Сторож выходов».

Пинг через интерфейс идёт, а правила через него молчат. Разъехалась политическая маршрутизация выхода, а не туннель: у выхода своя таблица и своя метка, и пинг с роутера в эту таблицу не заглядывает вовсе. Смотреть надо ip rule show | grep fwmark и ip route show table N (номер таблицы — в /var/lib/steer/registry): в таблице должен лежать default dev <выход>, а не blackhole default и не пусто. Сторож сверяет это каждый проход и возвращает сам, сообщая в журнал строкой «маршрутизация разъехалась»; перезапускать ядро для этого не нужно.

Новые соединения через туннель получают отказ при большой нагрузке. У туннелей есть бюджет памяти — половина доступной системе памяти при запуске (не меньше 16 МиБ), а у одного клиента — половина бюджета и не больше четверти ожидающих рукопожатия. На пределе новые соединения получают отказ (TCP — RST, UDP — ICMP «порт недоступен»), а медленные читатели ждут; журнал называет занятое и бюджет. Бюджет в мегабайтах задаёт переменная окружения STEER_TUN_MEM_MB. Рукопожатие с узлом целиком укладывается в 16 с.

Обфускация: WireGuard поверх TCP

Для сетей, где UDP режут. Клиентская половина — плагин obfs на роутере, серверная ставится на VPS из архива steer-obfs-<версия>-<арх>.tar.gz (x86_64 и aarch64) со страницы релизов или из ветки dist-vps — она нужна там, где закрыт githubusercontent.com, ровно как ветка dist для пакетов роутера:

tar xzf steer-obfs-<версия>-x86_64.tar.gz
cd obfs-x86_64 && sudo sh install.sh --port 4567 --forward 127.0.0.1:51820

Бинарник в архиве статический — компилятор на сервере не нужен. Подробности, требования к firewall и расчёт MTU — server/README.md.

Формат на проводе совместим с phantun: с той стороны может стоять phantun_server.

Этот слой не шифрует (это делает WireGuard) и не защищает от целенаправленного зондирования: поток без ретрансмиссий отличим от настоящего TCP при анализе. Задача — пройти там, где UDP режут, а не спрятаться от исследователя.

Сборка из исходников

make                      # нативная сборка для разработки
make test                 # весь набор стендов, офлайн: без роутера, без сети, без nft
make ext-test             # стенды расширенной части на настоящем wolfSSL (скачивается со сверкой суммы)
make libs-test            # разделяемая раскладка (библиотеки и плагины) на хосте, на настоящем wolfSSL
./build.sh                # пакеты всех архитектур (нужен Docker); STEER_ARCH=<арх> — одной

Роутерные сборки — musl через кросс-тулчейн zig. Ядро и программы плагинов — динамические бинарники: загрузчик musl (/lib/ld-musl-<арх>.so.1) берётся из самой прошивки, а libsteer.so и libsteer-wolfssl.so лежат в пакете steer-core. Версию libc под релиз OpenWrt подбирать не нужно, но нужен musl 1.2 и новее (OpenWrt 22.03 и новее): на 32-битных архитектурах бинарники берут из libc символы времени 64 бит (__clock_gettime64 и соседи), которых в musl 1.1 нет.

./build.sh кладёт в out/: .apk и .ipk пакета steer-core для каждой архитектуры, подписанные архивы плагинов .s2p (их же — в семя пакета) и архивы для VPS steer-obfs-<версия>-<арх>.tar.gz и steer-hub-<арх>.tar.gz для x86_64 и aarch64 — статические. Архивы плагинов подписываются ключом из S2P_KEY; без него — тестовым ключом build/s2p-testkey/test.sec, и такие архивы примет только ядро, которому этот ключ положили руками.

make test обязателен перед правкой: почти каждый стенд там стоит на конкретной поломке, которая однажды случилась, и в его комментарии написано, на какой именно.

Криптография — wolfSSL, собранная из исходников выпуска со своими опциями: версия и контрольная сумма архива — в build/wolfssl/fetch.sh, опции — в build/wolfssl/user_settings.h. В пакете роутера это libsteer-wolfssl.so внутри steer-core (steerd ходит по HTTPS сам).

Лицензия

steer распространяется под GNU GPL v3. Сторонний код: libyaml (src/third_party/libyaml, лицензия MIT), wolfSSL (GPLv3) и ngtcp2 (лицензия MIT, с нашим патчем Brutal), которые в дереве не лежат, а скачиваются и собираются из исходников (версии и суммы — build/wolfssl/fetch.sh, build/ngtcp2/fetch.sh).

Документация

  • docs/spec-v2.md — спека v2: все ключи, умолчания и отказы.
  • docs/spec-schema.md — машиночитаемая схема спеки (steer spec-schema --json).
  • docs/contract-v1.md — прежний формат спеки (v1), формат состояния, ограничения ввода, контракт командной строки и журнала, инварианты. Это то, на что опирается управляющий слой.
  • docs/ctl.md — управляющий сокет демона: команды, события, сторож, помощники.
  • docs/errors.md — коды отказов спеки, менеджера плагинов и управляющего сокета.
  • docs/architecture.md — устройство ядра для тех, кто его правит.
  • docs/vless.md — клиент VLESS/Reality: транспорты, Reality, Vision, UDP и QUIC, задержка установления соединения, коды возврата.
  • docs/hysteria2.md — клиент hysteria2: формат узла, Brutal, Salamander и Gecko, прыжки по портам, слежка за узлом.
  • docs/proxy.md — клиенты trojan, shadowsocks, socks, http и vmess: форматы ссылок, что поддерживается и что нет.
  • docs/xsteer.md — свой протокол с обликом TLS: формат на проводе, рукопожатие Noise IK внутри ClientHello, пачки кадров, согласование MTU, конфигурация в стиле wg и список того, чего протокол не делает.
  • docs/warp.md — Cloudflare WARP выходом kind: warp.
  • server/README.md — серверная половина обфускации.

Известные ограничения

  • Числа в спеке. Выходов, правил, клиентов, списков, членов группы, узлов подписки и серверов DNS — сколько поместится в память: заранее заложенных «не больше N» у них нет. Пределы с настоящей причиной остались, и отказ называет число: выходов с меткой 211 на роутере (43 на телефоне) — размер поля метки; членов группы pick: balance 120 — места в карте ядра; диапазонов портов на список 16; спека — 16 МиБ, тело apply по сокету — 1 МиБ, каталог списков — 4096 файлов и 128 МиБ; подписка — 64 МиБ.

  • Настройки переживают обновление прошивки, сам пакет — нет. Пакет объявляет свои настройки системе файлами /lib/upgrade/keep.d/steer и /lib/upgrade/keep.d/steer-plugins, поэтому sysupgrade и «Создать архив» в LuCI их берут. В первом девять путей: спека (spec.json и spec.yaml), выбор групп select, sub.txt, sub.userinfo, каталог подписок subs/, свои списки lists/custom/, файлы выходов AmneziaWG awg/ и ключи xsteer/; во втором — каталоги плагинов /usr/lib/steer/plugins/ и /etc/steer/plugins/. Каталог в keep.d берётся рекурсивно — sysupgrade кормит эти пути в find, — поэтому подкаталог объявляется одной строкой.

    Чего в списке нет намеренно: сам каталог /etc/steer/lists (десятки файлов, сотни килобайт) — отсутствующий список не мешает применению, и управляющий слой скачает его по расписанию. Исключение внутри него — lists/custom/: свой список набивает человек, и перекачать его неоткуда.

    Самого пакета в архиве нет и быть не может: пакетов проекта нет в feeds OpenWrt, а sysupgrade сохраняет файлы, не пакеты. После обновления прошивки ядро steer надо поставить заново — в splify2 это одна кнопка, — и оно найдёт свои настройки и плагины на месте.

  • ICMP через туннели VLESS, hysteria2 и прокси не идёт. Успешный ping через прокси не означал бы работающий путь, поэтому всё, что не TCP и не UDP, получает ICMP «порт недостижим».

  • IPv6 — не у всех выходов. Выходы interface, awg и WARP несут IPv6 своей таблицей IPv6: у interface и awg с ipv6: nat подмену IPv6 ставит само ядро steer, с ipv6: routed хост маршрутизует префикс, а без ключа для WireGuard в зоне fw4 нужен masq6. Туннели (VLESS, hysteria2, прокси) несут IPv6 по TCP и UDP (ключ ipv6: off у выхода это отключает). На AAAA для имени под правилом резолвер отвечает поддельным IPv6 (режим fake-IP) или настоящим адресом (real-ip) — и у спеки v2, и у спеки v1. У xsteer и моста Telegram IPv6 нет: IPv6 их правил отбрасывается, на AAAA их имён ответ пустой, и клиент переходит на IPv4.

  • IPv6 по правилам. Ключ правила family: 4 | 6 | both сужает правило до одного семейства: при 4 имена правила получают пустой AAAA, а IPv6 клиентов правила «весь трафик» отвергается, а не уходит напрямую; при 6 пустым отвечается A. Если IPv6 нужен, а выход его не несёт, on_family_unavailable: fallback оставляет правило по IPv4, block — закрывает имена правила совсем. Подробности и примеры — docs/spec-v2.md, раздел «Семейство IP правила».


Нужен готовый интерфейс с каталогом сервисов и автообновлением списков — splify2.