NetBird: модуль скрипта (автоматизация)

NetBird это mesh-сеть на базе WireGuard: серверы соединяются напрямую, а адреса и ключи выдаёт управляющий сервер. После подключения панель обращается к нодам по адресам в сети вместо публичных: управление нодами перестаёт зависеть от публичных портов и IP, а публичный путь 2222 остаётся открытым как запасной. Если облако NetBird недоступно, панель всё равно дотянется до нод.

Всё описанное ниже делает модуль скрипта, пункт NetBird: сеть для нод и панели в главном меню. Ручной вариант без скрипта описан в отдельной статье, он подходит всем.

Что понадобится

Панель и аккаунт NetBird

Установленная панель Remnawave на этом сервере и аккаунт в NetBird: облачный на app.netbird.io или свой сервер управления.

Setup-key

Из аккаунта NetBird для первого подключения.

SSH-доступ до серверов

Для перевода нод и работы со страницей подписки: SSH-доступ с панели до этих серверов, настраивается расширением SSH-доступ.

Токен для режима API

Для режима API (рекомендуется): токен доступа сервисного пользователя NetBird.

Как это устроено

Модуль уводит служебный трафик в частную сеть, но ничего не ломает на публичном пути. Каждому соединению соответствует свой маршрут:

Соединение	Обычный путь	Через NetBird
Панель → ноды (управление)	публичный адрес, порт `2222`	адрес ноды в сети, тот же порт
Страница подписки → панель	публичный адрес панели	отдельный порт панели из диапазона 3100+, закрыт из интернета
Чекер → панель (подписка)	публичная подписка	тот же порт, только `/api/sub/`
Панель → метрики чекера	публичный порт `2112`	адрес чекера в сети, под паролем

Гарантии, которые модуль держит на каждом шаге:

Публичный путь запасной

Публичный путь каждой ноды остаётся запасным и не закрывается переводом.

Без привязки к адресу сети

Ничто не привязывается к адресу в сети и порты Docker не публикуются на нём: сервис, привязанный к такому адресу, не пережил бы перезагрузку сервера.

Проверка перед переводом

Перевод ноды меняет адрес в панели только после живой проверки пути из контейнера панели.

Каждый шаг обратим

Аварийный возврат нод одной командой, возврат подписки и чекера своим пунктом меню.

Подготовка в аккаунте NetBird

Зарегистрируйтесь на app.netbird.io.
В разделе Settings → Setup Keys создайте ключ:
- тип Reusable, срок годности любой: ключ нужен только в момент подключения, потом модулю он не требуется, делать его бессрочным не обязательно.
- ключ показывается один раз, скопируйте его.
Если планируете режим API (рекомендуется): в разделе Team → Service Users нажмите Create Service User, задайте имя и роль Admin. Затем откройте созданного пользователя и нажмите Create Access Token. Токен показывается один раз, скопируйте его. Срок действия токена (Expires in) выбирайте самый большой из доступных: токен сохраняется на сервере панели и используется модулем постоянно, а после истечения срока режим API перестанет работать, пока вы не введёте новый токен в настройках модуля.

Подключение панели

Выполните на сервере панели:

remnawave_reverse

Выберите пункт NetBird: сеть для нод и панели.
Выберите Подключить этот сервер к NetBird.

Вставьте setup-key (ввод скрыт) и подтвердите имя сервера:

root@server: ~

Setup-key (ввод скрыт):
 Ключ создаётся в панели NetBird: Settings → Setup Keys → Create Setup Key.
 Подойдёт тип Reusable, стандартного срока годности достаточно
Имя сервера в NetBird [panel]: panel
Адрес своего сервера NetBird (Enter = облако NetBird): 
 Вопрос только для self-hosted управления. Облако — просто Enter

Модуль установит клиент NetBird, зафиксирует версию пакета, отключит подключения по требованию (lazy) и зарегистрирует сервер в сети:

root@server: ~

[ * ] Устанавливаю клиент NetBird
Клиент NetBird установлен
[ * ] Выключаю подключения по требованию (NB_LAZY_CONN=off)
Подключения по требованию выключены
[ * ] Регистрирую сервер в сети
Жду подключения к серверу управления и адреса в сети (до 60 с)
Подключено, адрес в сети 100.88.10.7/16
Сервер подключён к NetBird

Модуль предложит сразу включить режим API: сам создаст группы и однонаправленные политики, а затем спросит, выключить ли политику Default (предварительно проверив, что пути до нод живы). Отказаться можно: модуль покажет краткую инструкцию по ручной настройке политик, а API включается позже через Настройки.
root@server: ~
```
Настроить управление по API сейчас? (y/n): y
```

Клиент подключается с обязательными настройками: DNS NetBird отключён (хостовой /etc/resolv.conf не трогается), маршруты и файрвол клиента не вмешиваются в работу сервера, связь держится постоянно. Если сервер был подключён вручную до модуля, пункт Восстановить правильные настройки клиента переприменит их.

Режим API: группы, ключи, политика Default

В меню Настройки модуля (токен доступа, режим API) введите токен доступа сервисного пользователя. Модуль:

создаст группы rrp-…-panel, rrp-…-nodes и однонаправленную политику панель → ноды tcp/2222.
будет выпускать одноразовые ключи для каждого сервера и отзывать их сразу после использования, вставлять ключи больше не нужно.
в пункте Политики и Default покажет состояние доступа и по подтверждению выключит Default (с автоматическим возвратом, если пути не выдержат).

Без режима API модуль работает, но ключи для новых серверов придётся создавать и вставлять вручную, а политики настраивать самому.

Перевод нод в сеть NetBird

Для каждой ноды нужен SSH-доступ с панели (расширение «SSH-доступ»). Модуль подключает серверы только по публичному адресу: адрес в сети после перевода становится основным путём панели к ноде.

В меню NetBird выберите Ноды: перевод в сеть NetBird…, затем Перевод ноды в сеть NetBird и укажите ноду.

Подтвердите план. Модуль подключит сервер к NetBird, проверит путь до 2222 прямо из контейнера панели и только потом сменит адрес ноды в панели на адрес в сети:

root@server: ~

Перевод ноды в сеть NetBird
Выберите ноду (0-4): 1
План: NetBird на de-fra-01 → проверка пути → смена адреса в панели → ожидание подтверждённого переподключения до 120 с
Продолжить? (y/n): y
[ * ] SSH до 203.0.113.20
DNS-предохранитель: DNS-серверы remnanode
remnanode использует DNS хоста
[ * ] Клиент NetBird на de-fra-01
de-fra-01 подключена, адрес в сети 100.88.4.12
Страховочное правило интерфейса сети на ноде
Страховочное правило добавлено
[ * ] Проверка пути из контейнера панели до 100.88.4.12:2222
Путь подтверждён (TCP + TLS, PMTU в порядке)
Привязка адреса в сети к SSH-подключению
Привязка записана, сервер сверен по идентификатору
Меняю адрес ноды на 100.88.4.12
Адрес обновлён
Ожидание подтверждённого переподключения (до 120 с + 45 с стабильности)
Нода переподключилась по адресу в сети

Дождитесь подтверждённого переподключения. Публичное правило 2222 при этом остаётся как запасной путь.

Если путь не прошёл проверку, адрес ноды не меняется, а модуль подсказывает вероятные причины (политики, подключения по требованию, плагины нод). Любой незавершённый перевод можно продолжить или вернуть обратно из того же пункта меню.

Ноды, уже подключённые к NetBird вручную, модуль возьмёт под управление через Импорт нод… в том же подменю.

Страница подписки

Пункт Страница подписки на отдельном сервере рассчитан на страницу подписки, которая уже работает на отдельном сервере. Модуль:

открывает на панели отдельный порт из диапазона 3100+, закрытый из интернета, и разрешает на нём только адрес сервера подписки в сети.
подключает сервер подписки к NetBird, если клиента там ещё нет.
переписывает её compose на адрес панели в сети: EGAMES_COOKIE и auth-гейты из compose уходят, конфигурация панели больше не проходит через публичный интернет.
перед изменением сохраняет снимок публичной конфигурации и проверяет результат живьём: контейнер держится, панель отвечает.

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

Xray Checker

Пункт Xray Checker через сеть NetBird переносит чекер на работу внутри сети:

чекер берёт подписку у панели только через /api/sub/, публичная подписка ему не нужна.
метрики и страница мониторинга отвечают под паролем и только серверам сети, из интернета их не видно.
перед переносом модуль сохраняет снимок публичной конфигурации чекера, если она была.

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

Аварийный возврат и диагностика

Пункт Аварийный возврат нод на публичные адреса одной командой возвращает все ноды на публичные адреса, NetBird при этом не отключается.
Диагностика и сверка адресов сверяет записанные в модуле адреса с фактическими (адрес мог измениться после переподключения), показывает состояние клиента и путей.

Отключение

Отключить NetBird (с полным возвратом) останавливает клиент на этом сервере, установка и состояние модуля сохраняются. Порядок при сворачивании схемы: сначала верните ноды на публичные адреса (аварийным возвратом или по одной), затем перенесите обратно подписку и чекер, панель отключается последней. Пока в панели есть ноды с адресами сети, а подписка или чекер работают через неё, модуль не даст панели отключиться.

Полное удаление

Пункт Удалить NetBird полностью сносит всю схему целиком, а не один сервер панели. Пока что-то ещё работает через сеть (ноды в панели, сервер подписки, чекер), модуль откажется и подскажет, что сначала вернуть на публичный путь. Дальше по желанию клиент удаляется и с нод, куда его ставил модуль: по SSH выполняется отключение, выход из сети и удаление пакета, а старые записи этих серверов вычищаются из аккаунта. Затем то же самое на самой панели: клиент, регистрация и состояние модуля (режим, токен доступа, записи нод). Группы и политики в аккаунте остаются. Единственный ручной хвост: клиент на сервере подписки или чекера, если они работали через сеть и уже возвращены на публичный путь (модуль их адресов после возврата не помнит), там выполните apt purge netbird. Это способ начать установку с нуля: после удаления пункт Подключить этот сервер к NetBird снова предлагает подключение, как в первый раз.

Меню модуля: что делает каждый пункт

Состав меню зависит от состояния сервера: до установки клиента виден только пункт подключения, часть пунктов появляется только на панели или в режиме API. Шапка меню показывает клиента (версию и закрепление), адрес в сети, связь с сетью и режим работы. На подключённой панели с режимом API меню выглядит так:

root@server: ~

NetBird
 Подробности в wiki: https://wiki.egam.es/ru/configuration/netbird-module/

 Клиент NetBird: 0.59.0 · адрес в сети: 100.88.10.7/16 · связь с сетью: есть
 Режим работы: API

1.Ноды: перевод в сеть NetBird, импорт ручной схемы, статус
2.Аварийный возврат нод на публичные адреса
3.Страница подписки на отдельном сервере
4.Xray Checker через сеть NetBird
5.Диагностика и сверка адресов
6.Политики и Default (режим API)
7.Настройки модуля (токен доступа, режим API)
8.Восстановить правильные настройки клиента
9.Обновить клиент NetBird (по одному серверу)
10.Отключить NetBird (с полным возвратом)
11.Удалить NetBird полностью (клиент и состояние модуля)

0.Выход

Выберите действие (0-11):

Подключение

Подключить этот сервер к NetBird: первое подключение сервера: установка клиента, регистрация по ключу, проверка, что NetBird не тронул DNS и маршруты сервера. После подключения модуль предлагает включить режим API.
Настройки модуля (токен доступа, режим API): ввод и хранение токена доступа, включение и выключение режима API, ротация токена сервера подписки.
Политики и Default (режим API): только в режиме API: модуль создаёт группы и политику «панель → ноды», показывает чужие пиры и предлагает выключить политику Default (предварительно проверив, что пути до нод выживут, а при неудаче возвращает её обратно).

Ноды

Ноды: перевод в сеть NetBird, импорт ручной схемы, статус: подменю работы с нодами:
- Перевод ноды в сеть NetBird: перенос одной ноды: клиент устанавливается на неё по SSH, путь проверяется прямо из контейнера панели, адрес в панели меняется на адрес в сети, перезапуск подтверждается. Публичный путь 2222 остаётся запасным, незаконченный перевод можно продолжить или вернуть.
- Импорт нод, уже подключённых к NetBird вручную: для нод, подключённых до модуля своими силами: модуль находит в панели ноды с адресами из вашей сети NetBird и вносит их в своё состояние.
Аварийный возврат нод на публичные адреса: одной командой возвращает все ноды на публичные адреса, NetBird при этом не отключается.
Страница подписки на отдельном сервере: открывает на панели отдельный порт (закрытый из интернета) и переводит сервер подписки на панель через сеть NetBird. Когда страница уже в сети, пункт сначала предлагает вернуть её на публичный путь (восстановление из снимка с проверкой публичного пути) или перевести заново после ручных правок.
Xray Checker через сеть NetBird: чекер берёт подписку у панели только через сеть, метрики и страница мониторинга отвечают только серверам внутри сети. Возврат на публичный путь идёт тем же пунктом: снимок публичного чекера восстанавливается, без снимка контейнер модуля останавливается и удаляется.

Служебные пункты

Диагностика и сверка адресов: состояние клиента и обязательных настроек, сверка записанных адресов с фактическими, предупреждения о чужих настройках и незакреплённом пакете.
Восстановить правильные настройки клиента: перезапуск клиента с обязательными настройками: нужен, если сервер был подключён вручную до модуля или диагностика показала расхождение.
Обновить клиент NetBird (по одному серверу): узнаёт последнюю версию из репозитория, Enter ставит её. Если установлена последняя, модуль так и скажет. Версия закреплена, чтобы фоновые обновления не перезапускали клиент сами.
Отключить NetBird (с полным возвратом): обратимое отключение: останавливает клиент, установка и состояние модуля сохраняются.
Удалить NetBird полностью (клиент и состояние модуля): полный снос для установки с нуля (см. выше).

Ручная установка (без модуля)

Если модуль недоступен, минимальный набор шагов такой (со всеми оговорками, которые модуль закрывает автоматически):

# на панели и на ноде
curl -fsSL https://pkgs.netbird.io/install.sh | sh
apt-mark hold netbird

# ключ передавайте только через файл, не в командной строке (ключ в argv виден в ps и истории)
install -m600 /dev/null /run/nbkey
printf '%s' 'ВАШ-SETUP-KEY' > /run/nbkey
netbird up --setup-key-file /run/nbkey --disable-dns=true --disable-client-routes=true \
    --disable-server-routes=true --block-inbound=false --disable-firewall=false
rm -f /run/nbkey
netbird service reconfigure --service-env NB_LAZY_CONN=off

Затем в панели укажите адрес ноды в сети в поле «Адрес» её карточки. Помните: без однонаправленных политик трафик между пирами ничем не ограничен (Default = все ко всем), а UFW-правила на интерфейс wt0 не действуют: доступ фильтруется только политиками NetBird.

Итог

Панель и ноды связаны защищённым туннелем, публичный 2222 остаётся запасным путём.
Подписка и мониторинг ходят через сеть NetBird, их порты закрыты из интернета.
В любой момент всё возвращается на публичные адреса: ноды одной командой, подписка и чекер своими пунктами меню.

NetBird вручнуюТот же результат без скрипта: установка клиента, ключи и политики своими руками, для любого сервера.

SSH-доступ к серверамКлючи и цели для второго сервера: нужны модулю NetBird для перевода нод и страницы подписки.