Netbird (self-hosted) на Ubuntu 24.04: установка

MAATRIX

Netbird — это mesh-VPN поверх WireGuard: устройства соединяются напрямую друг с другом, а не гоняют трафик через центральный хаб, как в классических VPN-схемах. У облачной версии есть бесплатный тариф, но он ограничен по числу пиров и полностью зависит от инфраструктуры разработчиков. Self-hosted вариант снимает эти ограничения и держит все ключи, конфиги и метаданные о ваших устройствах на своём сервере. Ниже — пошаговая установка management-, signal- и relay-серверов Netbird через Docker Compose на Ubuntu 24.04 и подключение первого клиента.

Как устроен self-hosted Netbird

Netbird — это не один сервис, а несколько компонентов, которые вместе образуют control plane для WireGuard-сети:

• Management — сердце системы: хранит список пиров, сети, группы, ACL-правила и раздаёт клиентам конфигурацию через grpc/HTTPS.
• Signal — сервер сигнализации, через который пиры обмениваются публичными ключами и координатами для установки WireGuard-туннеля напрямую друг с другом (NAT traversal, holepunching).
• Relay — резервный канал передачи трафика на случай, если прямое P2P-соединение между пирами не удалось пробить через NAT. Трафик через relay всё равно шифруется WireGuard-ключами пиров, сервер его не видит в открытом виде.
• Coturn — STUN/TURN-сервер, помогает пирам определить свой внешний адрес и договориться о прямом соединении.
• Dashboard — веб-интерфейс администратора: пиры, сети, пользователи, политики доступа.
• Identity Provider — отдельный сервис аутентификации. В официальном self-hosted дистрибутиве по умолчанию это Zitadel (open-source аналог Auth0/Keycloak), можно заменить на Keycloak, Auth0 или Okta, если они уже есть в инфраструктуре.

Важное отличие от WireGuard «в лоб»: сам туннель после установки — обычный WireGuard, тот же протокол, что в сравнении WireGuard и OpenVPN. Netbird добавляет сверху автоматизацию — выдачу ключей, обмен конфигами, ACL между устройствами и NAT traversal, — которую при ручной настройке WireGuard пришлось бы делать вручную для каждого нового пира.

Все эти компоненты запускаются одной командой docker compose up -d из готового шаблона, который генерирует официальный скрипт настройки.

Требования к серверу и подготовка

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

Основной расход памяти даёт не сам Netbird, а Zitadel с собственной базой Postgres внутри — на 2 ГБ RAM всё стартует, но с запасом чувствует себя увереннее на 4 ГБ. Если Zitadel не нужен и identity provider уже есть отдельно, минимальные требования ощутимо ниже.

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

1. Домен, который резолвится на IP сервера (A-запись). Netbird работает по HTTPS с автоматическим TLS через Caddy, без домена управляющий контур не поднять. Если DNS ещё не настроен — см. настройку домена и DNS с нуля.
2. Docker и Docker Compose plugin. Ставим стандартно:

apt update && apt upgrade -y
curl -fsSL https://get.docker.com | sh
systemctl enable --now docker
docker compose version

1. Открытые порты: 80 и 443/tcp для Caddy (HTTP-редирект и HTTPS), 3478/udp для TURN, а также диапазон UDP-портов для relay-медиа, который генерирует скрипт настройки (по умолчанию несколько тысяч портов начиная с 49152 — конкретные значения смотрите в сгенерированном turnserver.conf, они могут отличаться от инсталляции к инсталляции).

Установка через Docker Compose

Официальный способ — клонировать репозиторий и запустить генератор конфигурации, который сам соберёт docker-compose.yml, Caddyfile и конфиги всех сервисов под ваш домен.

git clone https://github.com/netbirdio/netbird.git
cd netbird/infrastructure_files

Задаём переменные окружения для домена и почты (нужна для выпуска Let's Encrypt сертификата):

export NETBIRD_DOMAIN=vpn.example.com
export NETBIRD_LETSENCRYPT_EMAIL=admin@example.com

Запускаем интерактивный конфигуратор:

./configure.sh

Скрипт спросит, какой identity provider использовать (по умолчанию — встроенный Zitadel), сгенерирует случайные пароли и ключи, разложит итоговые файлы в artifacts/ и подготовит docker-compose.yml. Проверьте, что домен из переменной NETBIRD_DOMAIN совпадает с реальной A-записью — иначе Caddy не сможет выпустить сертификат и контейнер уйдёт в цикл перезапуска.

Поднимаем стек:

cd artifacts
docker compose pull
docker compose up -d

Первый запуск занимает пару минут: скачиваются образы, Zitadel инициализирует свою базу, Caddy запрашивает сертификат у Let's Encrypt. Смотрим статус и логи:

docker compose ps
docker compose logs -f caddy management

Если все контейнеры в состоянии Up и в логах Caddy видно успешный ACME challenge — можно идти в браузер.

Первый вход и настройка Zitadel

Открываем https://vpn.example.com — попадём на страницу первичной настройки Zitadel. Она попросит создать организацию и root-пользователя: логин, email, пароль. Это отдельная сущность от самого Netbird — Zitadel здесь работает как самостоятельный сервис аутентификации, через который потом будут логиниться и администраторы, и обычные пользователи, добавляющие свои устройства.

После создания root-пользователя Zitadel выдаст ссылку на активацию через email или сразу форму логина, в зависимости от того, настроен ли у вас SMTP в конфиге. Если почтового сервера нет — активацию можно провести напрямую в консоли Zitadel по адресу https://vpn.example.com/zitadel.

После входа в Zitadel вас перенаправит на сам дашборд Netbird (https://vpn.example.com). На первом входе он попросит подтвердить те же учётные данные через OAuth-флоу — это нормально, так работает связка Netbird + внешний IdP. В итоге вы окажетесь в привычном интерфейсе: слева — «Peers», «Networks», «Access Control», «Users», «Setup Keys».

Если планируете подключать сотрудников, а не только личные устройства, на этом шаге стоит сразу создать в Zitadel дополнительных пользователей или настроить вход через существующий SSO (Google Workspace, Microsoft Entra) — self-hosted Zitadel умеет работать как посредник (federation) для внешних провайдеров.

Подключение первого peer

Клиент Netbird ставится на Linux, macOS, Windows, iOS, Android. На Linux-машине, которую хотим подключить к сети, ставим клиент официальным скриптом:

curl -fsSL https://pkgs.netbird.io/install.sh | sh

Скрипт сам определит дистрибутив и подключит нужный репозиторий (apt для Debian/Ubuntu, yum/dnf для RHEL-семейства). Дальше поднимаем соединение, указав адрес своего management-сервера:

netbird up --management-url https://vpn.example.com

Клиент выведет ссылку для авторизации через браузер — переходите по ней, логинитесь через Zitadel тем же пользователем, что и в дашборде. После подтверждения устройство появится в разделе «Peers» дашборда со своим WireGuard-ключом, внутренним IP из подсети Netbird (по умолчанию 100.64.0.0/10 — тот же диапазон Carrier-Grade NAT, что используют и Tailscale, и облачный Netbird) и статусом подключения.

Для серверов и headless-окружений, где нет браузера, есть setup keys — одноразовые или многоразовые токены, которые генерируются в дашборде («Setup Keys» → «Create Setup Key») и подставляются вместо интерактивного логина:

netbird up --management-url https://vpn.example.com --setup-key <ваш-ключ>

Это удобно для автоматизации через Ansible или cloud-init: сервер поднимается и сразу сам регистрируется в сети без ручного шага.

Сети, группы и правила доступа

Сразу после установки все пиры по умолчанию попадают в группу All с открытым доступом друг к другу — это удобно для теста, но не годится для продакшена. Первое, что стоит сделать после подключения пары устройств:

1. Разбить пиры по группам — например, servers, laptops, admins. Группа назначается при регистрации пира или редактируется потом в дашборде.
2. Настроить Access Control — правила вида «группа A может достучаться до группы B по таким-то портам». По умолчанию Netbird идёт с политикой «разрешить всё внутри All», её стоит заменить явными правилами под свою топологию.
3. Добавить сетевые маршруты (Network Routes), если нужно пустить через один узел трафик до целой подсети — например, дать удалённым сотрудникам доступ к локальной сети офиса через шлюз-пир с включённым IP forwarding.
4. Включить DNS-management, если хотите резолвить внутренние имена пиров (peer-name.netbird.cloud или свой домен) вместо IP-адресов.

Для машин, которые слушают входящие подключения через relay или туннель (например, свежеразвёрнутый сервер приложений), стоит отдельно проверить, что штатный ufw не блокирует WireGuard-интерфейс wt0, который создаёт клиент Netbird. Базовые принципы настройки firewall для таких случаев разобраны в статье про ufw на Ubuntu 24.04.

Частые вопросы