Як розгорнути VPN-сервер NetBird на VPS

Що дає самостійне розгортання VPN-сервера NetBird

Самостійне розгортання VPN-сервера NetBird розміщує площину керування на власному VPS. Вона зберігає список вузлів, визначає, яка машина може з’єднуватися з якою, і допомагає двом вузлам знаходити один одного за NAT (перетворенням мережевих адрес). Самі тунелі й надалі працюють через WireGuard і шифруються безпосередньо між вашими машинами. Змінюється лише те, що стороння компанія більше не зберігає дані про ваші пристрої та не керує процесом входу.

NetBird поєднує дві концепції, які можуть бути вам уже знайомі. Це mesh overlay, тому вузли підключаються один до одного, а не передають увесь трафік через один шлюз. Водночас його можна повністю розгорнути у власній інфраструктурі, тому він конкурує з Headscale — self-hosted сервером керування Tailscale. Якщо ви раніше налаштовували лише тунель з одним шлюзом, спочатку прочитайте про різницю між звичайним WireGuard і mesh overlay, оскільки саме ця модель допоможе зрозуміти решту цього матеріалу.

Якщо насправді вам потрібен один сервер, через який виходитиме весь ваш трафік, mesh-схема складніша, ніж потрібно для цього завдання. Звичайний WireGuard VPN на одному VPS або exit node у Tailscale забезпечує це з набагато меншою кількістю компонентів для обслуговування.

Що фактично запускає стек

Структуру нещодавно змінено, і в більшості старих інструкцій описано попередній варіант. Станом на August 2026 року, у release v0.76.2 quickstart script за замовчуванням записує Compose-файл із трьома сервісами.

• netbird-server містить management API, signal service, relay із вбудованим STUN listener і вбудований identity provider. У старіших release це були окремі контейнери, а identity provider був окремою інсталяцією Zitadel, яку потрібно було спочатку зібрати.
• dashboard — це admin web console.
• traefik завершує TLS (transport layer security) і під час першого запуску запитує сертифікат у Let's Encrypt.

Існують ще два сервіси. Вони залишаються вимкненими, якщо під час запиту не вибрати їх запуск. NetBird Proxy публікує внутрішні сервіси на публічних hostname. CrowdSec фільтрує зловмисний трафік. Жоден із них не потрібен для створення працездатної mesh-мережі, а на невеликому сервері обидва споживають додаткову пам’ять.

Якщо ви переходите з wg-easy в одному Docker-контейнері, кількість компонентів зростає. Натомість ви отримуєте access policies і облікові записи окремих користувачів, а peers підключаються безпосередньо один до одного, а не через один gateway.

Що потрібно підготувати перед початком

Публічне доменне ім’я є обов’язковим. Dashboard, API і relay працюють через HTTPS на порту 443, а Traefik отримує сертифікат від Let’s Encrypt за допомогою HTTP challenge. Для цього потрібне ім’я, яке з публічного інтернету розпізнається як адреса цього VPS. У цьому сценарії гола IP-адреса не працює.

Створіть один A-запис, netbird.example.com, що вказує на публічну IPv4-адресу VPS, і дочекайтеся його поширення, перш ніж щось запускати.

dig +short netbird.example.com

Ця команда має вивести адресу вашого сервера. Якщо запустити інсталятор до завершення поширення DNS-запису, запит сертифіката завершиться помилкою під час першого запуску. Повторні невдалі перевірки можуть активувати обмеження швидкості Let’s Encrypt, і тоді доведеться чекати годину перед новою спробою.

З інтернету мають бути доступні три порти: TCP 80 для перевірки сертифіката та перенаправлення на HTTPS, TCP 443 для dashboard, API, signal і relay-трафіку, а також UDP 3478 для STUN.

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp
sudo ufw reload
sudo ufw status

Відкрийте їх також у мережевому firewall вашого провайдера. У більшості панелей керування VPS це окремий елемент керування. Саме тому сервер, на якому власний ufw status налаштований правильно, усе одно може відхиляти підключення.

STUN (session traversal utilities for NAT) дає змогу вузлу дізнатися публічну адресу та порт, призначені його власним NAT, щоб два вузли могли спробувати встановити прямий тунель. Якщо заблокувати UDP 3478, вузли все одно підключатимуться через relay на TCP 443, тому явної помилки не буде. Натомість на кожному вузлі з’явиться Connection type: Relayed, а весь трафік проходитиме через ваш VPS, а не безпосередньо між вузлами.

На рівні програмного забезпечення потрібні Docker із плагіном Compose v2, а також jq і curl. Скрипт перевіряє всі ці компоненти й завершує роботу, якщо хоча б одного з них немає. Якщо Docker ще не налаштований на цьому сервері, спочатку виконайте інструкції Налаштування Docker Compose на VPS.

Встановлення сервера NetBird за допомогою quickstart-скрипту

Задокументована однорядкова команда передає останній випуск безпосередньо в shell:

curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

Зафіксуйте версію. latest змінюється, тому та сама команда, виконана з інтервалом у два тижні, створює дві різні інсталяції, а на диску не залишається інформації про те, яка з них записала конфігурацію. Завантажте конкретний випуск, перегляньте його, а потім запустіть.

mkdir -p ~/netbird
cd ~/netbird
curl -fsSL -o getting-started.sh \
  https://github.com/netbirdio/netbird/releases/download/v0.76.2/getting-started.sh
less getting-started.sh
bash getting-started.sh

Спочатку скрипт запитує домен:

Enter the domain you want to use for NetBird (e.g. netbird.my-domain.com):

Потім він запитує, як оброблятиметься TLS:

Which reverse proxy will you use?
  [0] Traefik (recommended - automatic TLS, included in Docker Compose)
  [1] Existing Traefik (labels for external Traefik instance)
  [2] Nginx (generates config template)
  [3] Nginx Proxy Manager (generates config + instructions)
  [4] External Caddy (generates Caddyfile snippet)
  [5] Other/Manual (displays setup documentation)
Enter choice [0-5] (default: 0):

Виберіть [0]. Варіанти 2–5 записують фрагмент конфігурації та залишають підключення на ваш розсуд. Це правильно для сервера, де вже працює проксі, але неправильно для нового сервера. Після цього варіант 0 запитує адресу електронної пошти для Let's Encrypt. Вона використовується для сповіщень про завершення строку дії сертифіката.

Під час першого встановлення відмовтеся від сервісу NetBird Proxy. Для нього потрібні ще два DNS-записи: proxy.netbird.example.com і wildcard-запис *.proxy.netbird.example.com. Для звичайної mesh-мережі він не потрібен. Також відмовтеся від CrowdSec. Обидва компоненти можна додати пізніше.

Скрипт записує дані в поточний каталог: docker-compose.yml, config.yaml з mode 600, dashboard.env і traefik-dynamic.yaml, якщо ви вибрали вбудований Traefik. Вважайте цей каталог даними стану, які потрібно зберігати, оскільки config.yaml містить ключ шифрування даних у сховищі. Перевстановлення не відновить роботу після його втрати.

docker compose ps
docker compose logs -f netbird-server

Кожен сервіс має читати running, а журнал сервера має стабілізуватися, а не показувати циклічні перезапуски. Окремо перевірте сертифікат:

docker compose logs traefik | grep -i acme

ACME (automatic certificate management environment) — це протокол, який Traefik використовує для отримання сертифіката. Помилки на цьому етапі майже завжди спричинені DNS або закритим портом 80.

Створіть перший обліковий запис адміністратора

Відкрийте https://netbird.example.com. Після нового встановлення відкриється сторінка налаштування, а не форма входу. Укажіть адресу електронної пошти, ім’я та пароль, а потім натисніть Create Account. Цей обліковий запис стане першим адміністратором, після чого сторінка перенаправить вас до форми входу.

Цей обліковий запис зберігається у власному сховищі користувачів NetBird, роботу якого забезпечує постачальник ідентифікаційних даних, вбудований у контейнер netbird-server. Зовнішні компоненти не потрібні. Це головна відмінність від self-hosted NetBird річної давності: тоді для робочого встановлення спочатку потрібно було розгорнути Zitadel або Keycloak і скопіювати чотири значення OIDC (OpenID Connect) у setup.env, і лише після цього система взагалі могла запуститися.

Якщо замість сторінки налаштування браузер показує попередження про сертифікат, сертифікат не було випущено. Виправте це, перш ніж продовжувати, оскільки dashboard звертається до API через те саме ім’я хоста й за некоректного сертифіката працює непередбачувано.

Підключення першого вузла

Встановіть клієнт на будь-якій машині з Linux, зокрема на самому VPS, якщо потрібно додати його до mesh-мережі:

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

У Debian і Ubuntu цей скрипт налаштовує репозиторій пакетів NetBird, а потім встановлює клієнт через apt. У будь-якому разі пакетом керує менеджер пакетів. Якщо ви не хочете передавати скрипт безпосередньо в shell, спочатку збережіть його за допомогою curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh і прочитайте перед виконанням sh install.sh. У будь-якому разі перевірте, що саме було встановлено:

apt-cache policy netbird

netbird — це клієнт командного рядка та демон. netbird-ui — це desktop tray app, яка не потрібна на headless-сервері.

Тепер підключіть клієнт до свого сервера:

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

Якщо не вказати --management-url, клієнт зареєструється в хостинговому сервісі NetBird, оскільки це значення за замовчуванням, вбудоване в програму. Команда все одно виконається успішно, машина отримає адресу, а self-hosted dashboard залишиться порожнім. На цьому етапі помиляються майже всі.

Команда виведе URL, який потрібно відкрити в браузері для завершення входу. Після цього:

netbird status
ip addr show wt0

З netbird status буде виведено чотири рядки: Management: Connected, Signal: Connected, рядок Relays: з інформацією про всі доступні relay-сервери та NetBird IP: у діапазоні overlay-мережі. wt0 — це інтерфейс WireGuard, який створює NetBird. Він має використовувати ту саму адресу.

Підключення другої машини без участі користувача за допомогою setup key

Вхід через браузер не підходить для машини без браузера, перед якою ніхто не працює. setup key — це токен попередньої автентифікації, який реєструє машину без інтерактивного кроку. Створіть його в dashboard у розділі Setup Keys.

Є два типи ключів. Одноразовий ключ автентифікує рівно одну машину, після чого його буде використано. Багаторазовий ключ реєструє кілька машин. Для нього можна додатково встановити максимальну кількість реєстрацій. Обидва типи мають строк дії. Обидва також можуть автоматично додавати новий peer до group, щоб правила доступу цієї group застосовувалися одразу після появи машини.

sudo netbird up --setup-key <SETUP-KEY> \
  --management-url https://netbird.example.com \
  --hostname build-runner-01

--hostname задає ім’я, яке відображається в dashboard. Якщо його не вказати, peer отримає ім’я, під яким машина ідентифікує себе. Список записів, названих ubuntu, не допомагає розрізняти машини.

Для контейнерів і короткоживучих build agent позначте ключ як ephemeral під час його створення. Peer, зареєстровані за допомогою ephemeral key, автоматично видаляються після перебування offline понад 10 хвилин. Це не дає неактивним записам накопичуватися у списку peer.

Перед використанням setup keys врахуйте одне обмеження: завершення строку дії або видалення ключа припиняє нові реєстрації, але не відключає машини, які вже зареєструвалися за його допомогою. Щоб забрати доступ у машини, потрібно видалити відповідний peer.

Вам і далі потрібен окремий identity provider?

Для невеликої інсталяції — ні. Вбудоване сховище користувачів обробляє облікові записи, створені з dashboard, і цього достатньо для кількох користувачів.

Зовнішній identity provider потрібен, якщо він у вас уже є і ви не хочете вести другий список користувачів. NetBird підтримує будь-який provider, що працює за протоколом OIDC. Зареєструйте confidential OIDC client у своєму provider, а потім додайте його в dashboard NetBird, вказавши чотири значення: name, client ID, client secret та issuer. NetBird надасть redirect URL, який потрібно вставити назад у provider. Окремі інтеграції доступні для Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik і Pocket ID. Для всіх інших provider використовуйте generic OIDC. Якщо ви вже використовуєте Authentik як self-hosted single sign-on, цей варіант дає змогу зберегти один список облікових записів замість двох.

Local login залишається доступним після додавання provider, і кожен налаштований provider з’являється на сторінці входу. Збережіть один local admin account із надійним паролем. Якщо конфігурація OIDC буде неправильною, у вас усе одно залишиться спосіб увійти.

NetBird чи Headscale: який control plane розгорнути?

Обидва усувають одну й ту саму залежність — hosted control server, до якого ваші клієнти в іншому випадку зверталися б. Але це різні за структурою проєкти.

Headscale повторно реалізує control server Tailscale, а ви й надалі використовуєте офіційні клієнти Tailscale. Офіційної вебконсолі немає. Користувачами та pre-authentication keys ви керуєте командою headscale на основі config file. Community web interfaces існують, але не входять до складу проєкту. Це підходить тим, хто хоче зберігати свій стан у файлах і відстежувати зміни у version control.

NetBird постачається як повний продукт: із власним клієнтом, власною dashboard, вбудованим identity provider і access policies, які редагуються у браузері. На VPS з’являється більше компонентів, зате передати керування колезі значно простіше, навіть якщо він ніколи не відкриватиме термінал.

Розгортайте Headscale, якщо вже використовуєте клієнти Tailscale або хочете мінімально можливий control plane. Розгортайте NetBird, якщо кільком людям потрібно керувати peers і ви хочете отримати console та SSO без самостійного складання такої системи.

Який мінімальний VPS потрібен для цього?

Задокументований мінімум — 1 CPU і 2 GB пам’яті. У власних примітках NetBird зазначає, що тепер мінімальний обсяг становить приблизно 1 GB RAM, оскільки керування користувачами виконується локально. Раніше для компонування з повним розгортанням Zitadel потрібно було 2 GB–4 GB. Оберіть VPS із 2 GB. Додатковий запас пам’яті дає змогу під час оновлення завантажувати нові images, поки старі ще зберігаються на диску.

На невеликому сервері безпечно не встановлювати три компоненти. Відмовтеся від сервісу NetBird Proxy. Він потрібен для публікації внутрішніх сервісів за публічними іменами хостів і не пов’язаний із підключенням peer-вузлів. Відмовтеся від CrowdSec. Його варто додати пізніше на сервер, доступний з Інтернету, а не під час початкового встановлення. Залиште стандартне сховище SQLite у томі netbird_data. Переходьте на PostgreSQL лише після розподілення розгортання між кількома машинами або за появи реальної конкуренції за доступ до даних. У документації зазначено, що таку міграцію можна виконати пізніше.

Relay — єдиний компонент, від якого не можна відмовитися. Якщо NAT двох peer-вузлів призначає інший порт для кожного призначення, вони ніколи не встановлять прямий тунель. Тому relay — єдиний шлях, який узагалі дає змогу їм працювати. Його вимкнення майже не зменшує споживання пам’яті та порушує з’єднання так, що причину складно визначити.

Коли одного сервера вже недостатньо, найперше слід винести з нього relay. Окремий relay запускається з параметрами NB_LISTEN_ADDRESS, NB_EXPOSED_ADDRESS, NB_AUTH_SECRET і NB_ENABLE_STUN. Спільний секрет на relay і головному сервері має бути однаковим. Інакше клієнти не зможуть пройти автентифікацію на relay.

Типові проблеми та їхні ознаки

На панелі відображається попередження про сертифікат. Traefik не отримав сертифікат. Виконайте docker compose logs traefik | grep -i acme. Можливі дві причини. Або dig +short netbird.example.com ще не повертає адресу цього VPS, або TCP 80 десь між Let's Encrypt і контейнером закритий. Зазвичай це трапляється на мережевому firewall провайдера, а не на ufw. Усуньте причину, перш ніж повторювати спробу в циклі, оскільки невдалі перевірки обмежуються за частотою, і ви втратите можливість повторних спроб на годину.

Клієнт повідомляє про успішне підключення, але панель порожня. Клієнт зареєструвався в hosted service NetBird, оскільки --management-url був відсутній. Виконайте netbird status --detail і прочитайте рядок Management:. У ньому вказано сервер, з яким клієнт фактично взаємодіє. Якщо ви бачите Management: Connected to https://api.netbird.io:443, клієнт підключився до cloud. Виконайте sudo netbird down, а потім знову sudo netbird up --management-url https://netbird.example.com.

Для кожного peer відображається Connection type: Relayed. Прямі тунелі не встановлюються, тому весь трафік проходить через ваш VPS і додає затримку через додатковий мережевий вузол. Перевірте UDP 3478 у firewall VPS і firewall провайдера, оскільки STUN дає peer змогу визначити власні публічні адресу та порт. netbird status --detail також виводить Direct: false і типи кандидатів ICE (interactive connectivity establishment) для кожного peer. Це показує, наскільки далеко просунулася спроба підключення. У деяких мережах relayed є єдиним доступним результатом, і це нормально.

Peer підключається, але не може отримати доступу до жодного ресурсу. Наявність peer у mesh не означає, що два peer можуть обмінюватися трафіком. Це визначають політики доступу. Група без призначеної політики не має доступу до жодного ресурсу. Перевірте політику на панелі, перш ніж починати налагодження маршрутів і firewall.

netbird status повідомляє про проблему з daemon. Сервіс не запущений. Використайте sudo netbird service status і sudo netbird service start. Журнали клієнта зберігаються в /var/log/netbird/client.log. Якщо ви не можете визначити причину, netbird debug bundle --anonymize --system-info збирає журнали, стан системи, маршрути, налаштування DNS і стан firewall в один архів.

Резервне копіювання та оновлення

Усю інсталяцію визначають два компоненти: каталог із docker-compose.yml і config.yaml та Docker volume з базою даних і ключами шифрування. Резервуйте їх разом. config.yaml містить ключ, яким шифруються дані у сховищі, тому копія бази даних без цього ключа не дає змоги відновити дані в читабельному вигляді.

docker volume ls
docker compose down
sudo tar czf netbird-config.tgz -C ~ netbird
docker run --rm -v netbird_netbird_data:/data -v "$PWD":/backup \
  alpine tar czf /backup/netbird-data.tgz -C /data .
docker compose up -d

Compose додає до назв volume префікс із назви каталогу проєкту, тому volume, задокументований як netbird_data, зазвичай має назву netbird_netbird_data. Спочатку виконайте docker volume ls і використайте назву, яку він виведе. Інакше команда docker run мовчки створить порожній volume і не заархівує жодних даних. Зберігайте архіви не на VPS. Якщо у вас уже є інструмент резервного копіювання, restic або BorgBackup подбає про віддалене зберігання.

Оновлення сервера складається з отримання нового образу та повторного створення контейнера:

docker compose pull
docker compose up -d
docker compose ps

Перед тим як покладатися на цей процес, виконайте docker compose config | grep image:. Будь-який тег зі значенням latest потрібно зафіксувати на певній версії з тієї самої причини, з якої ви зафіксували версію скрипту інсталяції: потрібно знати, що саме запущено, і мати версію, до якої можна повернутися, якщо після оновлення виникнуть проблеми. Клієнти оновлюються через відповідний пакетний менеджер, яким їх було встановлено.

FAQ

Чи потрібен власний identity provider для self-hosted NetBird?

Ні. Поточні релізи містять вбудоване сховище користувачів, тому перший обліковий запис адміністратора можна створити у браузері за адресою https://netbird.example.com, а потім додати користувачів через dashboard. Зовнішній OIDC provider необов’язковий. Його можна додати пізніше, вказавши чотири значення: name, client ID, client secret та issuer. Інструкції, у яких перед NetBird пропонують розгорнути Zitadel або Keycloak, описують конфігурацію, яка більше не потрібна. Їх виконання додає ще один сервіс, який доведеться обслуговувати.

Чому всі мої peers мають статус Connection type: Relayed?

Прямі з’єднання не встановлюються, тому traffic проходить через relay на вашому VPS. Зазвичай причина полягає в тому, що UDP 3478 заблокований. Це STUN-порт, який peers використовують для визначення власної публічної адреси та порту. Відкрийте його у firewall VPS і в окремому network firewall вашого provider, потім знову виконайте netbird status --detail і прочитайте рядок Direct:. У мережі, де NAT призначає окремий порт для кожного призначення, статус relayed є єдиним можливим результатом. Це не означає, що конфігурацію налаштовано неправильно.

Клієнт підключився, але dashboard не показує peers. Що сталося?

Клієнт зареєструвався в hosted service NetBird, а не на вашому сервері. Так відбувається, коли не вказано --management-url. Команда netbird status --detail виводить сервер, з яким працює клієнт, у рядку Management:. Значення на кшталт https://api.netbird.io:443 підтверджує це. Виконайте sudo netbird down, потім sudo netbird up --management-url https://netbird.example.com, і peer з’явиться у вашому dashboard.

Чим self-hosted NetBird відрізняється від Headscale?

Обидва рішення замінюють hosted control server на сервер, яким ви керуєте самостійно. Headscale — це лише control plane. Ним керують за допомогою команди headscale і конфігураційного файлу. Офіційної web console немає, а система працює з офіційними клієнтами Tailscale. NetBird постачається з власним клієнтом, admin dashboard та інтеграцією з identity provider в одному стеку. Headscale простіше запускати, і він зберігає стан у файлах. NetBird зручніше передавати користувачам, які не працюватимуть у терміналі.

Який VPS потрібен для self-hosted сервера NetBird?

Задокументований мінімум — 1 CPU і 2 GB пам’яті. Саме конфігурацію з 2 GB варто замовляти. Практичний мінімум у нових релізах знизився приблизно до 1 GB, оскільки identity provider тепер вбудований, а не розгортається як окремий сервіс. Під час інсталяції відмовтеся від необов’язкових сервісів proxy і CrowdSec. Залишайтеся на стандартному сховищі SQLite, доки справді не знадобиться PostgreSQL.