Jak zainstalować NetBird VPN na własnym serwerze VPS
Instrukcja samodzielnej konfiguracji serwera NetBird na VPS. Omówienie DNS, certyfikatów TLS, skryptu instalacyjnego oraz zarządzania kluczami dla węzłów w trybie unattended.
Co daje samodzielne hostowanie serwera NetBird VPN
Samodzielne hostowanie serwera NetBird VPN przenosi płaszczyznę sterowania (control plane) na własny VPS. Jest to komponent przechowujący listę węzłów, decydujący o uprawnieniach do połączeń oraz ułatwiający wzajemne odnajdywanie się węzłów za NAT (network address translation). Same tunele nadal wykorzystują protokół WireGuard i są szyfrowane bezpośrednio między maszynami. Zmiana polega na tym, że żadna zewnętrzna firma nie posiada spisu urządzeń ani nie obsługuje procesu logowania. Należy mieć świadomość korzyści, ponieważ hostowana płaszczyzna sterowania również nie posiada kluczy szyfrujących ruch, a co faktycznie może zrobić serwer koordynujący w przypadku przejęcia jest zakresem węższym, niż większość osób zakłada przed lekturą dokumentacji.
NetBird pozycjonuje się pomiędzy rozwiązaniami, które mogą być już znane. Jest to nakładka typu mesh, w której węzły łączą się bezpośrednio ze sobą, zamiast przesyłać cały ruch przez jedną bramę. Jest to również rozwiązanie w pełni hostowalne samodzielnie, co stawia je w jednym rzędzie z Headscale, samodzielnie hostowanym serwerem sterującym Tailscale. Jeśli dotychczas używano wyłącznie tuneli z pojedynczą bramą, należy najpierw przeczytać różnice między zwykłym WireGuard a nakładką mesh, ponieważ ten model pojęciowy jest niezbędny do zrozumienia dalszej części strony.
Jeśli celem jest posiadanie jednego serwera, przez który wychodzi cały ruch, architektura mesh jest rozwiązaniem zbyt złożonym. Zwykły VPN WireGuard na pojedynczym VPS lub węzeł wyjściowy Tailscale realizują to zadanie przy znacznie mniejszym nakładzie pracy. Jeśli natomiast celem jest uzyskanie dostępu do jednej sieci prywatnej, a nie łączenie maszyn ze sobą, router podsieci Tailscale na VPS rozgłasza ten zakres do istniejącej sieci typu tailnet bez konieczności wdrażania całego poniższego stosu.
Co faktycznie uruchamia stos
Układ uległ niedawno zmianie, a większość starszych opracowań opisuje poprzednią wersję. Sprawdzono w październiku 2026 r. w odniesieniu do v0.80.0 oraz v0.76.2, czyli wydania, na którym bazuje ten przewodnik; skrypt quickstart domyślnie tworzy plik Compose z trzema usługami.
netbird-serverobsługuje API zarządzania, usługę sygnałową, przekaźnik z wbudowanym słuchaczem STUN oraz wbudowanego dostawcę tożsamości. W starszych wydaniach były to oddzielne kontenery, a dostawca tożsamości był osobną instalacją Zitadel, którą należało najpierw zbudować.dashboardto konsola administracyjna WWW.traefikdokonuje terminacji TLS (transport layer security) i przy pierwszym uruchomieniu żąda certyfikatu od Let's Encrypt.
Istnieją dwie dodatkowe usługi, które pozostają wyłączone, chyba że użytkownik wyrazi zgodę w odpowiedzi na monit. Usługa NetBird Proxy publikuje usługi wewnętrzne pod publicznymi nazwami hostów. CrowdSec filtruje szkodliwy ruch. Żadna z nich nie jest wymagana do zbudowania działającej sieci mesh, a obie zużywają pamięć na małym serwerze.
Jeśli użytkownik przechodzi z wg-easy w pojedynczym kontenerze Docker, oznacza to wzrost liczby komponentów. W zamian uzyskuje się polityki dostępu, konta dla poszczególnych użytkowników oraz węzły, które łączą się bezpośrednio ze sobą, zamiast przez jedną bramę.
Co jest potrzebne przed rozpoczęciem
Publiczna nazwa domenowa jest wymagana. Panel, API i relay działają przez HTTPS na porcie 443, a Traefik pobiera certyfikat z Let's Encrypt, korzystając z wyzwania TLS-ALPN-01 obsługiwanego na porcie 443. Wymaga ono nazwy, która z publicznego Internetu rozwiązuje się na adres tego VPS. W tym scenariuszu sam adres IP nie zadziała.
Utwórz jeden rekord A, netbird.example.com wskazujący na publiczny adres IPv4 VPS, i przed wykonaniem kolejnych czynności zaczekaj na propagację DNS.
dig +short netbird.example.comPolecenie musi wyświetlić adres serwera. Uruchomienie instalatora przed propagacją DNS powoduje niepowodzenie żądania certyfikatu przy pierwszym uruchomieniu. Wielokrotne nieudane walidacje mogą również doprowadzić do osiągnięcia limitów Let's Encrypt. W takim przypadku przed ponowną próbą trzeba zaczekać na odnowienie limitu.
Z Internetu muszą być dostępne trzy porty: TCP 80 do przekierowania na HTTPS, TCP 443 dla panelu, API, ruchu signal i relay oraz wyzwania certyfikatu, a także UDP 3478 dla STUN.
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp
sudo ufw reload
sudo ufw statusOtwórz je również w sieciowej zaporze dostawcy. W większości paneli VPS jest to osobne ustawienie. Dlatego serwer może nadal odrzucać połączenia, mimo że jego własny ufw status jest skonfigurowany prawidłowo.
STUN (session traversal utilities for NAT) umożliwia peeringowi ustalenie publicznego adresu i portu przypisanych przez jego własny NAT, aby dwa peery mogły spróbować utworzyć bezpośredni tunel. Po zablokowaniu UDP 3478 peery nadal się łączą przez relay na TCP 443, więc problem może nie być widoczny. Peery, które nie mogą znaleźć bezpośredniej ścieżki, wyświetlają Connection type: Relayed, a ich ruch przechodzi przez VPS zamiast bezpośrednio między peerami. Peery w tej samej sieci LAN nadal mogą łączyć się bezpośrednio, korzystając z lokalnych adresów.
Po stronie oprogramowania potrzebne są Docker z wtyczką Compose v2, a także jq i curl. Skrypt sprawdza obecność Docker, Compose i jq oraz kończy działanie, jeśli któregoś z nich brakuje. Używa curl bez sprawdzania jego obecności, dlatego należy zainstalować je wcześniej. Jeśli Docker został niedawno zainstalowany na tym serwerze, najpierw skonfiguruj działający Docker Compose na VPS.
Porty przy pominięciu dołączonego reverse proxy
Bez Traefik połączony serwer nadal obsługuje zarządzanie, signal i relay przez jeden backend HTTP, dlatego lista portów zwiększa się tylko nieznacznie. Wygenerowany plik Compose publikuje:
- TCP 8080, panel, domyślnie powiązany z 127.0.0.1
- TCP 8081,
netbird-server, domyślnie powiązany z 127.0.0.1 - UDP 3478, STUN, publikowany bezpośrednio
Własny proxy kończy TLS na TCP 443 i przekazuje ruch do tych dwóch portów lokalnych. STUN nigdy nie przechodzi przez proxy, dlatego UDP 3478 musi pozostać otwarty w zaporze niezależnie od konfiguracji. Instrukcje wymieniające osobne porty dla management gRPC, signal gRPC i relay opisują starszy układ z wieloma kontenerami.
Wybierz to rozwiązanie tylko wtedy, gdy serwer już kończy TLS dla innej usługi. W przeciwnym razie dołączony Traefik oznacza mniej reguł i mniej błędów.
Instalacja serwera NetBird za pomocą skryptu quickstart
Udokumentowana jednolinijkowa komenda przekazuje najnowsze wydanie bezpośrednio do powłoki:
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bashNależy przypiąć konkretną wersję. latest ulega zmianie, dlatego ta sama komenda uruchomiona w odstępie dwóch tygodni zainstaluje dwa różne wydania, a na dysku nie zostanie informacja, które z nich zapisało konfigurację. Należy pobrać oznaczone wydanie, przeczytać skrypt, a następnie go uruchomić.
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.shNajpierw skrypt pyta o domenę:
Enter the domain you want to use for NetBird (e.g. netbird.my-domain.com):Następnie pyta, jak będzie obsługiwany 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):Należy wybrać [0]. Opcje od 2 do 4 zapisują fragment konfiguracji i pozostawiają podłączenie po stronie administratora, natomiast opcja 5 zapisuje plik Compose, dashboard.env i config.yaml oraz wyświetla dokumentację konfiguracji w terminalu. Jest to prawidłowe na serwerze, na którym proxy już działa, ale nie na świeżym systemie. Opcja 0 pyta następnie o adres e-mail, który Traefik rejestruje na koncie Let's Encrypt. Komunikat nadal opisuje go jako adres do powiadomień o certyfikacie, ale Let's Encrypt zaprzestał wysyłania wiadomości o wygaśnięciu certyfikatów 4 czerwca 2025 roku. Problemy z odnawianiem są więc widoczne w logu Traefik, a nie w skrzynce odbiorczej.
Przy pierwszej instalacji należy odmówić włączenia usługi NetBird Proxy. Wymaga ona dodatkowego rekordu DNS: wieloznacznego rekordu *.netbird.example.com CNAME wskazującego na netbird.example.com, a przy zwykłej sieci mesh nie zapewnia żadnych dodatkowych funkcji. Monit dotyczący CrowdSec pojawia się tylko po włączeniu proxy, dlatego odmowa włączenia proxy pomija również ten etap. Oba komponenty można dodać później.
Skrypt zapisuje pliki w bieżącym katalogu: docker-compose.yml, config.yaml z uprawnieniami 600 oraz dashboard.env. W przypadku dołączonego Traefik dodaje także traefik-dynamic.yaml i proxy.env, ale tylko po włączeniu NetBird Proxy. Ten katalog należy traktować jako zachowywany stan, ponieważ config.yaml zawiera klucz szyfrujący dane w magazynie. Utraty tego pliku nie naprawi ponowna instalacja.
docker compose ps
docker compose logs -f netbird-serverKażda usługa powinna odczytywać running, a log serwera powinien się ustabilizować, zamiast wskazywać na ciągłe restarty. Certyfikat należy monitorować osobno:
docker compose logs traefik | grep -i acmeACME (automatic certificate management environment) to protokół używany przez Traefik do uzyskiwania certyfikatu. Błędy w tym miejscu niemal zawsze wynikają z problemu z DNS albo z zamkniętego portu 443.
Tworzenie pierwszego konta administratora
Otwórz https://netbird.example.com. W przypadku świeżej instalacji zamiast formularza logowania wyświetlona zostanie strona konfiguracji. Wprowadź adres e-mail, nazwę użytkownika oraz hasło, a następnie kliknij Create Account. Konto to stanie się pierwszym kontem administratora, a strona przekieruje użytkownika do formularza logowania.
Konto to jest przechowywane w wewnętrznej bazie użytkowników NetBird, obsługiwanej przez dostawcę tożsamości wbudowanego w kontener netbird-server. Nie wymaga to żadnych zewnętrznych zależności. Jest to największa zmiana w stosunku do samodzielnie hostowanej wersji NetBird sprzed roku, kiedy to poprawne wdrożenie wymagało najpierw uruchomienia Zitadel lub Keycloak, a następnie skopiowania czterech wartości OIDC (OpenID Connect) do setup.env przed rozpoczęciem jakichkolwiek działań.
Jeśli zamiast strony konfiguracji pojawi się ostrzeżenie przeglądarki dotyczące certyfikatu, oznacza to, że certyfikat nie został wystawiony. Należy rozwiązać ten problem przed przejściem dalej, ponieważ panel sterowania komunikuje się z API za pośrednictwem tej samej nazwy hosta i w przypadku nieprawidłowego certyfikatu wystąpią trudne do zdiagnozowania błędy.
Dołączanie pierwszego węzła
Zainstaluj klienta na dowolnej maszynie z systemem Linux, w tym na samym VPS, jeśli ma on należeć do sieci mesh:
curl -fsSL https://pkgs.netbird.io/install.sh | shW systemach Debian i Ubuntu skrypt konfiguruje repozytorium pakietów NetBird, a następnie instaluje klienta za pomocą apt, dzięki czemu menedżer pakietów przejmuje zarządzanie oprogramowaniem. Jeśli przesyłanie skryptu bezpośrednio do powłoki budzi zastrzeżenia, zapisz go najpierw za pomocą curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh i przejrzyj przed uruchomieniem sh install.sh. Niezależnie od metody, sprawdź poprawność instalacji:
apt-cache policy netbirdnetbird to klient wiersza poleceń oraz demon. netbird-ui to aplikacja z ikoną w zasobniku systemowym, która jest zbędna na serwerze typu headless.
Teraz wskaż klientowi swój serwer:
sudo netbird up --management-url https://netbird.example.comPominięcie --management-url spowoduje zarejestrowanie klienta w hostowanej usłudze NetBird, ponieważ jest to domyślne ustawienie wkompilowane w oprogramowanie. Polecenie zostanie wykonane poprawnie, maszyna otrzyma adres, ale Twój własny panel sterowania pozostanie pusty. Jest to częsty błąd.
Polecenie wyświetli adres URL, który należy otworzyć w przeglądarce, aby dokończyć logowanie. Następnie:
netbird status
ip addr show wt0Odczytaj cztery linie z netbird status: Management: Connected, Signal: Connected, linię Relays: raportującą wszystkie dostępne przekaźniki oraz NetBird IP: w zakresie sieci nakładkowej. wt0 to interfejs WireGuard utworzony przez NetBird, który powinien posiadać ten sam adres.
Dołączanie drugiej maszyny w trybie bezobsługowym za pomocą klucza instalacyjnego
Logowanie przez przeglądarkę nie działa na maszynie pozbawionej interfejsu graficznego, do której nikt nie ma bezpośredniego dostępu. Klucz instalacyjny (setup key) to token preautoryzacji, który rejestruje maszynę bez udziału użytkownika. Klucz można wygenerować w panelu sterowania w sekcji Setup Keys.
Dostępne są dwa rodzaje kluczy. Klucz jednorazowy uwierzytelnia dokładnie jedną maszynę, po czym traci ważność. Klucz wielorazowy pozwala zarejestrować wiele maszyn, opcjonalnie z limitem ich liczby. Oba typy wymagają określenia czasu wygaśnięcia i oba pozwalają na automatyczne przypisanie nowego węzła do grupy, dzięki czemu reguły dostępu dla tej grupy są stosowane w momencie pojawienia się maszyny w sieci.
sudo netbird up --setup-key <SETUP-KEY> \
--management-url https://netbird.example.com \
--hostname build-runner-01Flaga --hostname ustala nazwę widoczną w panelu sterowania. Bez niej węzeł przyjmuje nazwę własną systemu, a lista zawierająca wiele wpisów o nazwie ubuntu nie ułatwia zarządzania.
W przypadku kontenerów oraz krótkotrwałych agentów budujących, podczas tworzenia klucza należy oznaczyć go jako efemeryczny (ephemeral). Węzły zarejestrowane za pomocą takiego klucza są automatycznie usuwane, gdy pozostają w trybie offline przez ponad 10 minut, co zapobiega gromadzeniu się nieaktywnych wpisów na liście węzłów.
Przed zaplanowaniem wdrożenia z użyciem kluczy instalacyjnych należy pamiętać o jednym ograniczeniu: wygaśnięcie lub unieważnienie klucza blokuje jedynie nowe rejestracje, ale nie rozłącza maszyn, które zostały już za jego pomocą zarejestrowane. Aby odebrać maszynie dostęp, należy usunąć dany węzeł.
Czy nadal potrzebny jest oddzielny dostawca tożsamości?
W przypadku małej instalacji nie. Wbudowany magazyn użytkowników obsługuje konta tworzone z poziomu panelu sterowania, co jest wystarczające dla kilku osób.
Zewnętrzny dostawca tożsamości jest potrzebny, gdy już posiadasz takie rozwiązanie i nie chcesz utrzymywać drugiej listy użytkowników. NetBird akceptuje każdego dostawcę obsługującego protokół OIDC. Zarejestruj poufnego klienta OIDC u swojego dostawcy, a następnie dodaj go w panelu NetBird, podając cztery wartości: nazwę, client ID, client secret oraz issuer. NetBird wygeneruje adres URL przekierowania, który należy wkleić w konfiguracji dostawcy. Dostępne są gotowe integracje dla Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik oraz Pocket ID, a każde inne rozwiązanie można dodać jako generyczny OIDC. Jeśli już korzystasz z Authentik jako własnego rozwiązania single sign-on, jest to droga pozwalająca na utrzymanie jednej listy kont zamiast dwóch.
Logowanie lokalne pozostaje dostępne po dodaniu dostawcy, a każdy skonfigurowany dostawca pojawia się na stronie logowania. Zachowaj jedno lokalne konto administratora z silnym hasłem. Dzięki temu w przypadku błędnej konfiguracji OIDC nadal będziesz mieć możliwość uzyskania dostępu.
NetBird czy Headscale: który płaszczyznę sterowania wybrać?
Oba rozwiązania eliminują tę samą zależność, czyli zewnętrzny serwer sterujący, z którym łączyłyby się klienty. Projekty te różnią się jednak charakterystyką.
Headscale stanowi reimplementację serwera sterującego Tailscale, co pozwala na korzystanie z oficjalnych klientów Tailscale. Projekt nie posiada oficjalnej konsoli webowej. Zarządzanie użytkownikami oraz kluczami pre-autoryzacji odbywa się za pomocą polecenia headscale w odniesieniu do pliku konfiguracyjnego. Istnieją społecznościowe interfejsy webowe, jednak nie stanowią one części projektu. Rozwiązanie to jest odpowiednie dla użytkowników preferujących przechowywanie stanu w plikach oraz zarządzanie zmianami poprzez system kontroli wersji.
NetBird dostarcza cały produkt: własnego klienta, własny panel, wbudowanego dostawcę tożsamości oraz zasady dostępu edytowane w przeglądarce. Oznacza to więcej komponentów na VPS oraz znacznie mniej pracy przy przekazaniu obsługi współpracownikowi, który nie będzie korzystać z terminala. Jeśli porównanie dotyczy rzeczywiście NetBird i hostowanej usługi Tailscale, a nie Headscale, należy pamiętać, że oba rozwiązania wykorzystują pod spodem WireGuard. Porównanie NetBird i Tailscale opisuje rzeczywiste różnice: kto zarządza płaszczyzną sterowania, jak definiuje się reguły dostępu oraz jak przekaźniki obsługują ruch.
Wybierz Headscale, jeśli korzystasz już z klientów Tailscale lub wymagasz minimalnej płaszczyzny sterowania. Wybierz NetBird, jeśli zarządzanie węzłami wymaga udziału kilku osób i oczekujesz konsoli oraz SSO bez konieczności samodzielnej konfiguracji tych elementów. Przed podjęciem decyzji sprawdź co faktycznie obejmuje darmowy plan Tailscale, ponieważ grupy niekomercyjne liczące do sześciu użytkowników nie ponoszą kosztów za hostowaną płaszczyznę sterowania, otrzymując w zamian nielimitowaną liczbę urządzeń użytkownika oraz 50 zasobów z tagami na start, co może czynić własną instalację zbędną. Po przekroczeniu tego limitu opłaty rosną wraz z liczbą osób, a nie liczbą maszyn, dlatego obliczenie kosztów Tailscale dla danej grupy pozwala uzyskać kwotę, którą można zestawić z kosztami VPS oraz czasem poświęconym na utrzymanie własnego stosu technologicznego.
Jak mały VPS wystarczy do uruchomienia tej usługi?
Udokumentowane minimum to 1 CPU i 2 GB pamięci. Należy wybrać 2 GB.
Na małym serwerze można bezpiecznie pominąć trzy elementy. Należy odrzucić usługę NetBird Proxy, która służy do publikowania usług wewnętrznych pod publicznymi nazwami hostów i nie ma związku z nawiązywaniem połączeń między peerami. Należy pominąć CrowdSec, który skrypt oferuje wyłącznie razem z proxy. Warto dodać go później na serwerze wystawionym do Internetu, a nie podczas pierwszej instalacji. Należy pozostawić domyślny magazyn SQLite w wolumenie netbird_data. Do PostgreSQL należy przejść dopiero po rozdzieleniu wdrożenia między kilka maszyn albo po wystąpieniu rzeczywistej współbieżności. Migrację można wykonać później zgodnie z dokumentacją.
Z przekaźnika nie można zrezygnować. Dwaj peerzy, którym NAT przypisuje inny port dla każdego miejsca docelowego, nigdy nie ustanowią bezpośredniego tunelu. Przekaźnik jest więc jedyną ścieżką, która w ogóle umożliwia ich działanie. Jego wyłączenie oszczędza bardzo mało pamięci, a powoduje problemy z połączeniami, które trudno zdiagnozować.
Gdy jedna maszyna przestaje wystarczać, w pierwszej kolejności należy przenieść z niej przekaźniki. Samodzielny przekaźnik działa z użyciem NB_LISTEN_ADDRESS, NB_EXPOSED_ADDRESS, NB_AUTH_SECRET i NB_ENABLE_STUN. Współdzielony sekret musi być identyczny na przekaźniku i serwerze głównym. W przeciwnym razie uwierzytelnianie klientów na przekaźniku kończy się niepowodzeniem.
Tryby awarii i obserwowane objawy
Panel pokazuje ostrzeżenie dotyczące certyfikatu. Traefik nie uzyskał certyfikatu. Uruchom docker compose logs traefik | grep -i acme. Możliwe są dwie przyczyny. Albo dig +short netbird.example.com nie wskazuje jeszcze na ten VPS, albo port TCP 443 jest zamknięty gdzieś między Let's Encrypt a kontenerem, zwykle w zaporze sieciowej dostawcy, a nie na ufw. Weryfikacja odbywa się na porcie 443, dlatego otwarty port 80 nie rozwiązuje problemu. Przed ponowną próbą usuń przyczynę problemu. Let's Encrypt zezwala na maksymalnie pięć nieudanych autoryzacji dla nazwy hosta i konta w ciągu godziny. Pętla może zablokować kolejne próby do czasu odnowienia tego limitu.
Klient informuje o nawiązaniu połączenia, ale panel jest pusty. Klient zarejestrował się w hostowanej usłudze NetBird, ponieważ brakowało --management-url. Uruchom netbird status --detail i odczytaj wiersz Management:, w którym podano serwer, z którym klient faktycznie się komunikuje. Wartość Management: Connected to https://api.netbird.io:443 oznacza połączenie z chmurą. Uruchom sudo netbird down, a następnie ponownie sudo netbird up --management-url https://netbird.example.com.
Każdy peer ma status Connection type: Relayed. Nie są tworzone tunele bezpośrednie. Cały ruch przechodzi więc przez VPS, co dodaje opóźnienie wynikające z dodatkowego przeskoku. Sprawdź port UDP 3478 w zaporze VPS oraz w zaporze dostawcy. STUN umożliwia peerowi ustalenie własnego publicznego adresu i portu. netbird status --detail wyświetla również Direct: false oraz typy kandydatów ICE (interactive connectivity establishment) dla każdego peera. Pokazuje to, na jakim etapie zakończyła się próba. W niektórych sieciach jedynym dostępnym wynikiem jest połączenie przez przekaźnik i nie oznacza to problemu.
Peer dołącza do sieci, ale nie może dotrzeć do żadnego zasobu. Obecność w mesh nie oznacza, że dwa peery mogą się ze sobą komunikować. Decydują o tym zasady dostępu. Grupa bez przypisanej polityki nie uzyskuje dostępu do żadnych zasobów. Przed rozpoczęciem analizy tras i zapór sprawdź politykę w panelu.
netbird status zgłasza problem z daemonem. Usługa nie działa. Użyj sudo netbird service status i sudo netbird service start. Dzienniki klienta znajdują się w /var/log/netbird/client.log. Jeśli nie można ustalić przyczyny, netbird debug bundle --anonymize --system-info zbiera dzienniki, stan systemu, trasy, ustawienia DNS i stan zapory do jednego archiwum.
Kopie zapasowe i aktualizacje
Cała instalacja opiera się na dwóch elementach: katalogu zawierającym docker-compose.yml oraz config.yaml, a także wolumenie Docker przechowującym bazę danych i klucze szyfrujące. Należy tworzyć ich kopie zapasowe łącznie. Plik config.yaml zawiera klucz szyfrujący dane w magazynie, więc kopia bazy danych bez niego uniemożliwia odczytanie jakichkolwiek informacji po przywróceniu.
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 -dCompose dodaje prefiks katalogu projektu do nazw wolumenów, dlatego wolumen opisany jako netbird_data zazwyczaj występuje pod nazwą netbird_netbird_data. Najpierw należy uruchomić docker volume ls i użyć wyświetlonej nazwy, w przeciwnym razie polecenie docker run zakończy się niepowodzeniem, tworząc pusty wolumen i nie archiwizując żadnych danych. Archiwa należy przechowywać poza serwerem VPS. Jeśli używane jest już narzędzie do kopii zapasowych, restic lub BorgBackup obsłuży proces przesyłania danych do zewnętrznej lokalizacji.
Aktualizacja serwera polega na pobraniu nowej wersji obrazów i ponownym utworzeniu kontenerów:
docker compose pull
docker compose up -d
docker compose psZanim proces ten zostanie wdrożony, należy uruchomić docker compose config | grep image:. Każdy tag oznaczony jako latest powinien być przypięty do konkretnej wersji z tego samego powodu, dla którego przypięto skrypt instalacyjny: administrator musi wiedzieć, co jest uruchomione, oraz posiadać wersję, do której można wrócić w przypadku problemów po aktualizacji. Klienci aktualizują się za pomocą menedżera pakietów, który został użyty do ich instalacji.
FAQ
Czy do samodzielnego hostowania NetBird potrzebny jest własny dostawca tożsamości?
Nie. Bieżące wydania zawierają wbudowany magazyn użytkowników. Pierwsze konto administratora tworzy się w przeglądarce pod adresem https://netbird.example.com, a następnie dodaje użytkowników z poziomu dashboardu. Zewnętrzny dostawca OIDC jest opcjonalny. Można go dodać później, podając 4 wartości: nazwę, client ID, client secret i issuer. Instrukcje wymagające wdrożenia Zitadel lub Keycloak przed NetBird opisują konfigurację, która nie jest już wymagana. Ich zastosowanie oznacza konieczność utrzymywania dodatkowej usługi.
Dlaczego wszyscy moi peeringi mają status Connection type: Relayed?
Nie są nawiązywane połączenia bezpośrednie. Ruch przechodzi więc przez relay na serwerze VPS. Typową przyczyną jest blokowanie UDP 3478. Jest to port STUN używany przez peeringi do ustalenia własnego publicznego adresu i portu. Należy otworzyć go w firewallu VPS oraz w oddzielnym firewallu sieciowym dostawcy. Następnie należy ponownie uruchomić netbird status --detail i odczytać wiersz Direct:. Jeżeli oba peeringi znajdują się za NAT przypisującym inny port dla każdego miejsca docelowego, status relayed jest oczekiwanym wynikiem i nie oznacza błędnej konfiguracji.
Klient połączył się, ale dashboard nie pokazuje peeringów. Co się stało?
Klient zarejestrował się w usłudze hostowanej przez NetBird, a nie na własnym serwerze. Dzieje się tak, gdy pominięto --management-url. Polecenie netbird status --detail wyświetla serwer, z którym klient się komunikuje, w wierszu Management:. Wartość taka jak https://api.netbird.io:443 potwierdza ten problem. Należy uruchomić sudo netbird down, a następnie sudo netbird up --management-url https://netbird.example.com. Peering pojawi się wtedy na dashboardzie.
Czym różni się samodzielnie hostowany NetBird od Headscale?
Oba rozwiązania zastępują hostowany serwer sterujący serwerem utrzymywanym samodzielnie. Headscale jest wyłącznie płaszczyzną sterowania. Zarządza się nim za pomocą polecenia headscale i pliku konfiguracyjnego. Nie ma oficjalnej konsoli webowej i steruje oficjalnymi klientami Tailscale. NetBird dostarcza własnego klienta, dashboard administratora oraz integrację z dostawcą tożsamości w ramach tego samego stosu. Headscale jest prostszy w utrzymaniu i przechowuje stan w plikach. NetBird łatwiej przekazać użytkownikom, którzy nie będą korzystać z terminala.
Jakiego rozmiaru VPS wymaga samodzielnie hostowany serwer NetBird?
Udokumentowane minimum to 1 CPU i 2 GB pamięci. 2 GB to zalecana wartość przy wyborze planu. Podczas instalacji należy odrzucić opcjonalną usługę proxy, co powoduje również pominięcie pytania dotyczącego CrowdSec. Do czasu rzeczywistej potrzeby użycia PostgreSQL należy pozostać przy domyślnym magazynie SQLite.