NetBird на власному сервері: mesh-VPN як Tailscale без хмари

Що ми налаштовуємо і навіщо

NetBird — це self-hosted платформа для побудови mesh-VPN. За призначенням вона близька до Tailscale, ZeroTier і Headscale: ви встановлюєте агент на сервери, ноутбуки та інші пристрої, авторизуєте їх в одній мережі й отримуєте захищену зв'язність між учасниками.

В основі передавання даних лежить WireGuard. Це означає, що користувацький трафік за можливості йде безпосередньо між двома вузлами. Центральний сервер NetBird не зобов'язаний проксувати кожен пакет: він зберігає стан мережі, видає конфігурації peer-вузлам, застосовує ACL-політики, допомагає з виявленням учасників і надає адміністративну панель.

Якщо пряме з'єднання неможливе через CGNAT, симетричний NAT або корпоративний firewall, NetBird може передати трафік через TURN-релей. У self-hosted схемі таким релеєм зазвичай виступає coturn, запущений на тому самому VPS. Це не скасовує шифрування WireGuard: TURN бачить транспортний потік, але не розшифровує VPN-трафік.

Що вийде після виконання інструкції

У результаті ви отримаєте домен на кшталт netbird.example.com з HTTPS-панеллю керування. У панелі можна запрошувати користувачів, створювати setup keys для серверів без інтерактивного входу, об'єднувати peers у групи, додавати маршрути до локальних підмереж і обмежувати доступ правилами.

Кожен підключений пристрій отримає адресу з внутрішньої мережі NetBird, наприклад 100.64.0.0/10 або вибраного вами діапазону. Ви зможете підключатися до приватних сервісів через SSH, відкривати внутрішні бази даних, зв'язувати кілька VPS, надавати розробникам доступ лише до staging-інфраструктури або публікувати домашню мережу без пробросу портів на кожному пристрої.

Чому не просто WireGuard

Звичайний WireGuard чудово підходить для схеми «клієнт — сервер», але починає вимагати ручного адміністрування за наявності десятків вузлів. Потрібно створювати ключі, додавати peer-блоки в конфіг усіх машин, узгоджувати AllowedIPs, оновлювати файли під час відкликання пристрою та вирішувати проблеми NAT.

NetBird автоматизує цю роботу. Адміністратор керує логічними об'єктами: користувачами, групами, маршрутами та політиками. Агент сам отримує актуальну конфігурацію. Після видалення ноутбука з мережі його ключ перестає отримувати робочу конфігурацію, а під час додавання нового сервера не потрібно вручну редагувати конфіг на всіх старих вузлах.

Cloud-managed і self-hosted: що вибрати

Self-hosted NetBird має сенс, коли важливі незалежність від зовнішнього облікового запису, контроль над метаданими мережі, власна політика зберігання даних або інтеграція з корпоративним SSO. Для команди з кількох осіб це також хороший спосіб вивчити сучасну mesh-VPN-архітектуру без ручного супроводу десятків WireGuard-конфігів.

NetBird не робить VPS невидимим для інтернету автоматично. Публічні сервіси все одно потрібно захищати firewall, оновленнями, надійними паролями та окремими ACL. Mesh-VPN слід розглядати як рівень захищеної зв'язності, а не як заміну базової безпеки сервера.

Яка VPS-конфігурація потрібна для цього завдання

Навантаження NetBird залежить не стільки від кількості зареєстрованих peers, скільки від кількості активних релейних з'єднань через TURN. Якщо пристрої з'єднуються безпосередньо, VPS переважно обслуговує вебпанель, API, PostgreSQL і сигналізацію. Якщо багато клієнтів постійно працюють за складним NAT, coturn може споживати помітний трафік і CPU.

Для більшості особистих інфраструктур і невеликих команд практичний стартовий варіант — 2 vCPU, 4 ГБ RAM, 50 ГБ NVMe, виділений IPv4 і порт 1 Гбіт/с. Наприклад, можна взяти VPS із зазначеними характеристиками, встановити Ubuntu Server 24.04 LTS і залишити запас пам'яті для PostgreSQL, Docker та майбутнього моніторингу.

Чому потрібен публічний IPv4

Публічний IPv4 спрощує роботу TURN і доступ до management-панелі. IPv6 корисний, але не замінює IPv4: частина мобільних і домашніх провайдерів досі працює через IPv4 NAT, а деякі клієнти можуть не мати повноцінної IPv6-зв'язності. В ідеалі сервер повинен мати обидві адреси.

Перевірте, чи дозволяє провайдер вхідний UDP-трафік. Для роботи NetBird зазвичай потрібні UDP-порти WireGuard і TURN. Якщо UDP фільтрується на рівні майданчика, частина клієнтів підключатиметься нестабільно або взагалі не зможе використовувати relay.

Коли потрібен dedicated, а не VPS

Dedicated-сервер виправданий не через сам control plane, а через мережеве навантаження та вимоги до ізоляції. Він корисний, якщо TURN регулярно передає сотні мегабітів за секунду, мережа використовується як шлюз для великої кількості співробітників, потрібна гарантована продуктивність CPU або політика безпеки забороняє shared-virtualization.

Для 5–100 peers dedicated зазвичай не потрібен. Значно ефективніше почати з VPS, увімкнути моніторинг навантаження й окремо винести coturn на другий VPS, якщо relay-трафік став вузьким місцем. Такий поділ легше масштабувати й обслуговувати, ніж передчасну міграцію на великий сервер.

Як вибрати локацію

Локація впливає насамперед на затримку до control plane і TURN-релея. Прямі WireGuard-з'єднання між peers не зобов'язані проходити через VPS, тому два клієнти з одного міста обмінюватимуться даними з низькою затримкою незалежно від країни control plane. Однак у разі relay-з'єднання весь трафік проходитиме через TURN.

Розміщуйте VPS ближче до більшості користувачів або до критичних мереж. Якщо команда розподілена між Європою та Азією, виберіть нейтральну точку для панелі й за потреби додайте другий TURN-релей в іншому регіоні. Для доступу до домашнього сервера вибирайте локацію з хорошим маршрутом до домашнього ISP, а не лише з мінімальною ціною.

Підготовка сервера

Інструкція розрахована на чистий сервер з Ubuntu Server 24.04 LTS x86_64. Ця версія має тривалий термін підтримки, сучасне ядро та стабільні пакети Docker. Перед початком створіть DNS-запис типу A: netbird.example.com має вказувати на публічний IPv4 VPS. Якщо використовується IPv6, також додайте AAAA-запис.

Не встановлюйте NetBird безпосередньо від імені root. Створіть окремого адміністратора, додайте SSH-ключ і лише після перевірки вимикайте вхід за паролем. Залиште поточну root-сесію відкритою до моменту, коли переконаєтеся, що вхід новим користувачем працює.

Оновлення операційної системи

Підключіться до сервера через SSH та встановіть актуальні оновлення. Команда оновлює індекс пакетів, застосовує патчі безпеки й перезавантажує сервер лише за потреби.

sudo apt update && sudo apt full-upgrade -y
sudo reboot

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

cat /etc/os-release
uname -r

Створення користувача та налаштування SSH

Замініть vpnadmin на власне ім'я користувача. На робочому комп'ютері заздалегідь створіть ключ командою ssh-keygen -t ed25519, якщо його ще немає.

sudo adduser vpnadmin
sudo usermod -aG sudo vpnadmin
sudo install -d -m 700 -o vpnadmin -g vpnadmin /home/vpnadmin/.ssh

Скопіюйте публічний ключ у файл authorized_keys. Вставте один рядок, що починається з ssh-ed25519, замість прикладу.

sudo nano /home/vpnadmin/.ssh/authorized_keys
sudo chown vpnadmin:vpnadmin /home/vpnadmin/.ssh/authorized_keys
sudo chmod 600 /home/vpnadmin/.ssh/authorized_keys

Відкрийте друге вікно термінала та перевірте вхід: ssh vpnadmin@SERVER_IP. Лише після успішної перевірки змінюйте налаштування SSH-демона.

sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.bak
sudo nano /etc/ssh/sshd_config

Додайте або змініть такі параметри. Якщо ви змінюєте порт SSH, не забудьте відкрити його у firewall до перезапуску сервісу.

PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
X11Forwarding no
AllowUsers vpnadmin

sudo sshd -t
sudo systemctl restart ssh

Базові утиліти, firewall і fail2ban

Встановіть інструменти діагностики, firewall і захист від перебору SSH-паролів. Навіть за вимкненої парольної автентифікації fail2ban корисний для зменшення шуму в логах і блокування підозрілих джерел.

sudo apt install -y ca-certificates curl gnupg git jq vim \
  ufw fail2ban unattended-upgrades dnsutils htop

Відкрийте лише необхідні порти. У цьому прикладі SSH працює на стандартному TCP 22, вебпанель використовує 80 і 443, WireGuard NetBird використовує UDP 51820, а coturn — UDP/TCP 3478 і діапазон relay-портів UDP 49152–49200. Вузький діапазон спрощує firewall, але обмежує кількість одночасних relay-сесій; для невеликої команди його достатньо.

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp comment 'SSH'
sudo ufw allow 80/tcp comment 'HTTP ACME'
sudo ufw allow 443/tcp comment 'HTTPS'
sudo ufw allow 51820/udp comment 'NetBird WireGuard'
sudo ufw allow 3478/tcp comment 'TURN TCP'
sudo ufw allow 3478/udp comment 'TURN UDP'
sudo ufw allow 49152:49200/udp comment 'TURN relay range'
sudo ufw enable
sudo ufw status verbose

Створіть мінімальну конфігурацію fail2ban. Значення bantime дорівнює одній годині, а після п'яти невдалих спроб адресу буде тимчасово заблоковано.

sudo tee /etc/fail2ban/jail.d/sshd.local > /dev/null <<'EOF'
[sshd]
enabled = true
maxretry = 5
findtime = 10m
bantime = 1h
EOF

sudo systemctl enable --now fail2ban
sudo fail2ban-client status sshd

Також увімкніть автоматичні security-оновлення Ubuntu. Docker-образи не слід оновлювати автоматично: їх краще оновлювати вручну у заплановане вікно, після резервного копіювання та перевірки release notes.

sudo dpkg-reconfigure --priority=low unattended-upgrades
sudo systemctl status unattended-upgrades --no-pager

Встановлення ПЗ — покроково

У 2026 році найзручніше розгорнути self-hosted NetBird через офіційний Docker Compose-пакет. Він встановлює узгоджений набір контейнерів: management, signal, dashboard, PostgreSQL, coturn та identity provider. Не збирайте образи з випадкових сторонніх репозиторіїв: control plane містить ключі, токени й дані про вашу внутрішню мережу.

Перед запуском перевірте актуальну стабільну версію в офіційному GitHub release NetBird. У командах нижче використовується офіційний інсталяційний скрипт getting-started.sh, який завантажує актуальний релізний стек. Це безпечніше, ніж фіксувати номер версії, який міг застаріти на момент читання статті.

Встановлення Docker Engine

Спочатку видаліть старі конфліктні пакети Docker, якщо вони були встановлені з репозиторію Ubuntu. Команда не видаляє ваші дані Docker у /var/lib/docker, але на новому сервері їх зазвичай немає.

sudo apt remove -y docker.io docker-compose docker-compose-v2 \
  docker-doc podman-docker containerd runc 2>/dev/null || true

Додайте офіційний GPG-ключ і репозиторій Docker для Ubuntu 24.04.

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Встановіть Docker Engine та Compose plugin. На початок 2026 року використовуйте актуальну стабільну гілку Docker Engine з офіційного репозиторію; перевірка нижче покаже фактично встановлену версію.

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
docker version
docker compose version

Дозвольте користувачу vpnadmin запускати Docker без sudo. Після додавання до групи вийдіть із SSH-сеансу та увійдіть знову, інакше група не застосовується.

sudo usermod -aG docker vpnadmin
exit

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

docker run --rm hello-world

Отримання офіційного self-hosted пакета

Створіть каталог для інфраструктурних файлів. Не використовуйте /tmp: він може очищатися системою. Каталог /opt/netbird зручний для сервісів, але власником зробимо адміністратора, щоб не працювати від root.

sudo install -d -m 750 -o vpnadmin -g vpnadmin /opt/netbird
cd /opt/netbird

Задайте повне доменне ім'я. Воно має вже резолвитися в IP-адресу VPS, інакше автоматичне отримання TLS-сертифіката через Let's Encrypt не спрацює.

export NETBIRD_DOMAIN="netbird.example.com"
getent ahostsv4 "$NETBIRD_DOMAIN"

Завантажте офіційний installer із latest release і спочатку перегляньте перші рядки скрипту. Перевірка перед запуском особливо важлива для скриптів, що отримують права на запуск Docker-контейнерів.

curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh \
  -o getting-started.sh
less getting-started.sh
chmod 700 getting-started.sh

Запустіть скрипт зі змінною домену. Офіційний bootstrap створює Compose-конфігурацію, файл оточення та початкові налаштування self-hosted NetBird. Якщо upstream installer запитає параметри identity provider або email для ACME, вкажіть робочу адресу та збережіть усі видані секрети в захищеному password manager.

NETBIRD_DOMAIN="$NETBIRD_DOMAIN" ./getting-started.sh

Після завершення встановлення перевірте, які файли було створено. Назви можуть дещо відрізнятися між версіями NetBird, тому орієнтуйтеся на фактичний вивід скрипту, а не створюйте другий Compose-стек вручну.

cd /opt/netbird
find . -maxdepth 2 -type f | sort
docker compose ps

Перевірка контейнерів і журналів

Усі критичні контейнери мають перебувати у стані running або healthy. Перше отримання TLS-сертифіката може зайняти одну-дві хвилини. Якщо контейнери перезапускаються, одразу переглядайте логи, а не намагайтеся багаторазово виконувати встановлення поверх наявної конфігурації.

docker compose ps
docker compose logs --tail=100
docker compose logs --tail=100 management
docker compose logs --tail=100 coturn

Перевірте доступність HTTPS. Прапорець -I запитує лише HTTP-заголовки. Відповідь 200, 302 або 307 зазвичай означає, що reverse proxy та dashboard доступні.

curl -I https://netbird.example.com
curl -fsS https://netbird.example.com/ > /dev/null && echo "HTTPS OK"

Конфігурація

Після bootstrap не поспішайте підключати всі сервери. Спочатку зафіксуйте конфігурацію, переконайтеся в наявності TLS і створіть окремий адміністративний обліковий запис. Залежно від версії self-hosted пакета NetBird екран входу може використовувати вбудований Zitadel або зовнішній OpenID Connect provider. Логіка однакова: identity provider відповідає за автентифікацію, а NetBird management — за peers і політики мережі.

Робота з файлом середовища

Офіційний installer зазвичай створює файл на кшталт setup.env, .env або аналогічний. У ньому містяться домен, URL сервісів, паролі PostgreSQL, секрети OIDC і TURN credentials. Обмежте доступ до цього файлу: права 600 обов’язкові, оскільки витік змінних дає змогу захопити control plane.

cd /opt/netbird
ls -la
find . -maxdepth 2 -type f \( -name ".env" -o -name "setup.env" \) -print
chmod 600 .env 2>/dev/null || true
chmod 600 setup.env 2>/dev/null || true

Нижче наведено типовий фрагмент, а не файл для сліпої заміни. Назви змінних можуть відрізнятися в конкретному релізі. Не публікуйте реальні значення, не зберігайте їх у Git і не надсилайте в чат-боти або тікети.

NETBIRD_DOMAIN=netbird.example.com
NETBIRD_MGMT_API_ENDPOINT=https://netbird.example.com:443
NETBIRD_MGMT_GRPC_API_ENDPOINT=https://netbird.example.com:443
NETBIRD_AUTH_AUDIENCE=netbird
POSTGRES_DB=netbird
POSTGRES_USER=netbird
POSTGRES_PASSWORD=CHANGE_TO_A_LONG_RANDOM_SECRET
TURN_MIN_PORT=49152
TURN_MAX_PORT=49200

Згенерувати безпечний секрет можна локально на сервері. Не використовуйте короткі паролі або повторювані значення для PostgreSQL, Zitadel і TURN.

openssl rand -base64 48

TLS/HTTPS і Caddy

Офіційний quickstart NetBird зазвичай містить reverse proxy та автоматичний TLS. У багатьох релізах для цього застосовується Caddy, який прослуховує порти 80 і 443 та отримує сертифікат Let's Encrypt. Якщо installer уже запустив Caddy, не встановлюйте другий Caddy або Nginx на хост: два процеси не зможуть одночасно зайняти TCP-порти 80 і 443.

Перевірте, який контейнер публікує веб-порти. У виводі має бути сервіс із прив’язкою 0.0.0.0:80->80 і 0.0.0.0:443->443.

docker compose ps
sudo ss -lntup | grep -E ':(80|443|3478|51820)\b'

Якщо ви свідомо керуєте reverse proxy самостійно, приклад мінімального Caddyfile для dashboard і management API має такий вигляд. Реальні внутрішні імена контейнерів і порти візьміть із постачаного NetBird Compose-файлу. Не копіюйте приклад, доки не звірите їх через docker compose config.

netbird.example.com {
    encode zstd gzip

    handle /api/ {
        reverse_proxy management:33073
    }

    handle /ws-proxy/ {
        reverse_proxy signal:10000
    }

    handle {
        reverse_proxy dashboard:80
    }
}

Перевірте дату сертифіката та ім’я в Subject Alternative Name. Помилка сертифіката майже завжди означає неправильний DNS-запис, закритий TCP 80/443, наявність іншого proxy або спробу запросити сертифікат для домену, який іще не поширився в DNS.

echo | openssl s_client -connect netbird.example.com:443 \
  -servername netbird.example.com 2>/dev/null | \
  openssl x509 -noout -subject -issuer -dates

Створення першого адміністратора

Відкрийте в браузері https://netbird.example.com. Створіть першого користувача через вбудований identity provider або через налаштований OIDC. Після входу перевірте, що ваш користувач має роль адміністратора в NetBird dashboard. Відразу увімкніть MFA в identity provider, особливо якщо панель доступна з публічного інтернету.

Для серверів зручніше не використовувати особистий інтерактивний вхід. У панелі NetBird створіть Setup Key, обмежте його кількістю використань і строком дії. Наприклад, для одного production-сервера створіть ключ на одне використання та видаліть його після реєстрації вузла.

Підключення Linux-peer

На сервері, який ви хочете включити до mesh-VPN, встановіть офіційний NetBird client. Перед запуском звіряйте пакетний репозиторій і команду з документацією вашого релізу. Для Ubuntu/Debian типовий варіант використовує install-скрипт NetBird, який додає офіційний репозиторій.

curl -fsSL https://pkgs.netbird.io/install.sh | sudo bash
sudo apt update
sudo apt install -y netbird
netbird version

Замініть SETUP_KEY на одноразовий або обмежений setup key із панелі. Параметр --management-url вказує вашому агенту використовувати власний control plane, а не хмарний endpoint.

sudo netbird up \
  --management-url https://netbird.example.com \
  --setup-key SETUP_KEY

Перевірте стан агента. У справній конфігурації команда показує статус Connected, призначений NetBird IP і кількість peers. У деяких версіях команда може виводити додаткову інформацію про signal server і relay.

sudo netbird status
ip addr show wt0 2>/dev/null || ip addr | grep -A2 -B2 netbird

Групи, політики та мінімальний ACL

Не залишайте мережу в режимі «усі бачать усіх», якщо в ній є production-сервери. Створіть групи admins, developers, prod-servers і staging. Додавайте peers до груп за призначенням, а не за ім’ям співробітника: так простіше підтримувати правила під час зміни пристроїв і ролей.

Мінімальна політика може дозволяти адміністраторам доступ до всіх серверів через SSH, розробникам — лише до staging, а production-серверам — вихідні з’єднання один з одним лише на потрібні порти. Політики створюються в Dashboard у розділі Access Control. Для початку використовуйте правило рівня мережі, потім поступово звужуйте його до груп і портів.

Перевірка mesh-з’єднання

Підключіть щонайменше два peer-пристрої. У dashboard знайдіть NetBird IP другого пристрою, потім виконайте ping і SSH через тунель. Якщо ping заборонений політикою, перевіряйте потрібний прикладний порт за допомогою nc або curl.

ping -c 4 100.64.0.10
nc -vz 100.64.0.10 22
ssh [email protected]

Щоб перевірити, що доступ здійснюється саме через VPN, підключіться до сервісу, який firewall дозволяє лише через інтерфейс NetBird. На цільовій машині можна переглянути вхідні з’єднання та інтерфейс маршруту.

ip route get 100.64.0.10
sudo ss -tnp | grep ':22'

Маршрут до локальної підмережі та exit node

NetBird уміє публікувати маршрути до мереж за одним peer. Наприклад, сервер в офісі з доступом до 192.168.50.0/24 може стати routing peer. Для цього на ньому вмикають IP forwarding, а маршрут додають у Dashboard і призначають групі-одержувачу.

sudo tee /etc/sysctl.d/99-netbird-forwarding.conf > /dev/null <<'EOF'
net.ipv4.ip_forward=1
net.ipv6.conf.all.forwarding=1
EOF

sudo sysctl --system

Після увімкнення forwarding налаштуйте firewall/NAT відповідно до вашої схеми. Не публікуйте домашню підмережу повністю без ACL: спочатку дозвольте доступ лише групі адміністраторів. Exit node, через який клієнт надсилає весь інтернет-трафік, потребує особливо ретельного налаштування NAT, моніторингу трафіку та розуміння юридичних наслідків використання публічного IP.

Бекапи та обслуговування

Контейнери NetBird можна пересоздати, але дані control plane без резервної копії складно відновити. Головний актив — PostgreSQL: у ній містяться користувачі, peers, політики, маршрути, налаштування та пов’язані дані identity provider. Окремо зберігайте Compose-файли, файли середовища, Caddy-дані та всі ключі OIDC/TURN.

Що потрібно бекапити

• Дамп PostgreSQL у логічному форматі pg_dump.
• Каталог /opt/netbird без тимчасових файлів і без Docker image layers.
• Docker volumes, якщо в них зберігаються дані PostgreSQL, Zitadel і Caddy.
• Файли .env, setup.env, Compose YAML і Caddyfile.
• Секрети identity provider, recovery codes MFA та документацію щодо DNS-записів.
• Список setup keys і адміністративних користувачів, але не активні ключі у відкритому вигляді.

Перед налаштуванням автоматизації з’ясуйте імена контейнера PostgreSQL і volume. Це важливо: ім’я може бути не просто postgres. Команда нижче покаже сервіси та підключені volumes.

cd /opt/netbird
docker compose ps
docker compose config --services
docker volume ls

Встановлення restic і підготовка сховища

Зберігати єдину копію на тому самому VPS безглуздо: у разі видалення сервера, збою диска або компрометації root-доступу її можна втратити разом із даними. Використовуйте S3-сумісне об’єктне сховище, окремий backup-VPS через SFTP або інший незалежний сервер.

Нижче використовується restic із S3. Замініть значення на реквізити свого сховища. Пароль репозиторію restic повинен зберігатися поза самим VPS, наприклад у password manager. Після ініціалізації видаліть експортовані змінні з інтерактивної shell history або використовуйте захищений root-only файл.

sudo apt install -y restic
sudo install -d -m 700 /root/.config/restic
sudo nano /root/.config/restic/netbird.env
sudo chmod 600 /root/.config/restic/netbird.env

export RESTIC_REPOSITORY="s3:https://s3.example.com/netbird-backups"
export RESTIC_PASSWORD="REPLACE_WITH_LONG_UNIQUE_RESTIC_PASSWORD"
export AWS_ACCESS_KEY_ID="REPLACE_WITH_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="REPLACE_WITH_SECRET_KEY"

Ініціалізуйте репозиторій один раз. Команда створить зашифровану структуру backup-репозиторію.

sudo bash -c 'source /root/.config/restic/netbird.env && restic init'

Скрипт автоматичного бекапу

Створіть скрипт. Він робить дамп PostgreSQL у тимчасовий каталог, зберігає конфігурацію, надсилає дані в restic і очищає локальні дампи, старші за сім днів. Замініть postgres і netbird на реальні ім’я сервісу та ім’я бази з вашого Compose-файлу.

sudo tee /usr/local/sbin/backup-netbird.sh > /dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

source /root/.config/restic/netbird.env

STACK_DIR="/opt/netbird"
BACKUP_DIR="/var/backups/netbird"
DATE="$(date +%F_%H-%M-%S)"
PG_SERVICE="postgres"
PG_DATABASE="netbird"
PG_USER="netbird"

mkdir -p "$BACKUP_DIR"
chmod 700 "$BACKUP_DIR"

cd "$STACK_DIR"

docker compose exec -T "$PG_SERVICE" \
  pg_dump -U "$PG_USER" -Fc "$PG_DATABASE" \
  > "$BACKUP_DIR/postgres_${DATE}.dump"

restic backup \
  "$BACKUP_DIR" \
  "$STACK_DIR/.env" \
  "$STACK_DIR/setup.env" \
  "$STACK_DIR/docker-compose.yml" \
  --tag netbird --tag postgres

restic forget --tag netbird \
  --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

find "$BACKUP_DIR" -type f -name '.dump' -mtime +7 -delete
EOF

sudo chmod 700 /usr/local/sbin/backup-netbird.sh

sudo /usr/local/sbin/backup-netbird.sh
sudo bash -c 'source /root/.config/restic/netbird.env && restic snapshots'

sudo tee /etc/cron.d/netbird-backup > /dev/null <<'EOF'
25 3    root /usr/local/sbin/backup-netbird.sh >> /var/log/netbird-backup.log 2>&1
EOF

Перевірка відновлення

Бекап, який не перевіряли відновленням, не можна вважати робочим. Раз на квартал запускайте тимчасову VM, завантажуйте snapshot, відновлюйте конфіги та намагайтеся імпортувати PostgreSQL у тестовий контейнер. Не тестуйте відновлення на production-базі.

sudo bash -c 'source /root/.config/restic/netbird.env && restic check'
sudo bash -c 'source /root/.config/restic/netbird.env && restic restore latest --target /tmp/netbird-restore'

Оновлення NetBird

Для невеликої мережі використовуйте maintenance window: попередьте користувачів, зробіть бекап, прочитайте release notes, оновіть контейнери та перевірте підключення двох peers. Rolling update має сенс лише за кількох екземплярів control plane та запланованої зовнішньої бази даних; на одному VPS коротка перерва зазвичай безпечніша й простіша.

cd /opt/netbird
sudo /usr/local/sbin/backup-netbird.sh
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100

Не запускайте необдумано docker system prune -a на production-сервері: команда може видалити образи, потрібні для швидкого rollback. Зберігайте попередні версії образів до завершення перевірки. Після оновлення перевірте login у dashboard, реєстрацію тестового peer, status наявного клієнта та TURN-зв’язність із мережі з NAT.

Troubleshooting + FAQ

Чому браузер показує помилку TLS-сертифіката або сайт не відкривається?

Спочатку перевірте DNS: команда dig +short netbird.example.com A повинна повернути IP вашого VPS. Потім переконайтеся, що TCP 80 і 443 відкриті та не зайняті іншим Nginx, Apache або Caddy: sudo ss -lntp. Перегляньте логи reverse proxy через docker compose logs. Для Let's Encrypt домен повинен бути публічно доступним під час HTTP-01 challenge. Якщо використовується проксування DNS/CDN, тимчасово вимкніть його або налаштуйте DNS challenge.

Peer зареєстрований, але статус залишається Disconnected. Що перевірити?

На клієнті виконайте sudo netbird status і переконайтеся, що management URL вказує на ваш домен. Перевірте роздільну здатність DNS і доступність HTTPS: curl -I https://netbird.example.com. На сервері відкрийте логи management і signal-контейнерів. Поширена причина — неправильний зовнішній URL у файлі середовища, прострочений setup key або policy/firewall, що блокує вихідний HTTPS у клієнта. Після виправлення виконайте sudo netbird down і знову sudo netbird up.

Пристрої бачать один одного в панелі, але ping і SSH не працюють. Чому?

Перевірте ACL-політику в Dashboard: наявність peer у мережі не означає автоматичного дозволу будь-якого трафіку. Потім перевірте локальний firewall цільового сервера: UFW може дозволяти SSH лише з публічного інтерфейсу або лише з конкретної підмережі. Перегляньте NetBird IP обох peers і маршрут командою ip route get PEER_IP. Для діагностики тимчасово створіть вузьке правило, яке дозволяє TCP 22 між двома тестовими групами, а не глобальне правило all-to-all.

Чому з’єднання працює повільно або йде через relay?

Зазвичай це означає, що peers не змогли встановити прямий UDP-шлях і використовують TURN. Перевірте доступність UDP 3478, UDP 51820 і relay-діапазону UDP 49152–49200 на VPS, включно із зовнішнім firewall провайдера. У домашніх і корпоративних мережах причиною може бути симетричний NAT або заборона UDP. Перегляньте статус клієнта та логи coturn. Relay — нормальний fallback, але його швидкість залежить від каналу VPS і відстані до користувачів.

Яка VPS-конфігурація мінімально підійде?

Для особистої мережі з 3–10 пристроїв підійдуть 1 vCPU, 2 ГБ RAM, 25 ГБ SSD і публічний IPv4. Для стабільної експлуатації з PostgreSQL, dashboard, coturn і запасом на оновлення краще вибирати 2 vCPU, 4 ГБ RAM і 40–50 ГБ NVMe. Якщо очікується багато клієнтів за NAT, важливіший не розмір диска, а пропускна здатність і ввімкнений UDP-трафік. Стежте за RAM, CPU та вихідним трафіком після запуску.

Що вибрати — VPS чи dedicated для цього завдання?

Для більшості self-hosted NetBird-мереж достатньо VPS. Control plane споживає мало ресурсів, а десятки peers рідко потребують виділеного заліза. Dedicated потрібен за високого постійного TURN-трафіку, вимог до апаратної ізоляції, кількох сотень активних користувачів або необхідності гарантованої смуги. Практичний шлях — почати з VPS на 2–4 vCPU і винести TURN на окрему машину, якщо метрики покажуть, що relay став обмеженням.

Як додати маршрут до домашньої або офісної підмережі?

Виберіть peer, який одночасно підключений до NetBird і до локальної мережі, наприклад 192.168.50.0/24. На ньому увімкніть net.ipv4.ip_forward=1, потім додайте маршрут у Dashboard і призначте групи, яким він доступний. Переконайтеся, що зворотний маршрут існує: або локальний роутер знає шлях до NetBird-підмережі, або routing peer виконує NAT. Починайте з одного хоста або невеликої підмережі та перевіряйте доступ ACL-правилами.

Чи можна видалити peer, якщо ноутбук втрачено?

Так. Відкрийте Dashboard, знайдіть пристрій у списку Peers і видаліть або disable його. Management server перестане видавати йому актуальну конфігурацію, а доступ до мережевих ресурсів буде відкликано відповідно до політики. Додатково вимкніть сесії користувача в identity provider, змініть setup keys, якщо вони могли бути збережені на пристрої, і перевірте audit events. Не використовуйте безстрокові setup keys з необмеженою кількістю реєстрацій.

Висновки та наступні кроки

Тепер у вас є self-hosted NetBird control plane з HTTPS, WireGuard mesh-VPN, TURN fallback, базовим firewall і резервним копіюванням PostgreSQL. Така схема дає змогу об’єднати VPS, домашні сервери та пристрої команди в одну приватну мережу без постійної залежності від зовнішнього хмарного control plane.

1. Створіть групи за ролями та замініть широкі правила доступу на мінімально необхідні ACL.
2. Підключіть моніторинг Docker, диска, TLS-сертифікатів і обсягу TURN-трафіку.
3. У разі зростання навантаження винесіть coturn на окремий сервер, додайте другий relay-регіон і регулярно тестуйте відновлення з бекапу.