NetBird VPN server zelf hosten op een VPS handleiding

Wat het zelf hosten van de NetBird VPN-server u oplevert

Door de NetBird VPN-server zelf te hosten, plaatst u het control plane op een VPS die uw eigendom is: het onderdeel dat de lijst met peers bijhoudt, bepaalt welke machine welke andere mag bereiken en helpt twee peers elkaar te vinden achter NAT (network address translation). De tunnels zelf blijven WireGuard-tunnels, die direct tussen uw machines worden versleuteld. Het verschil is dat geen enkel extern bedrijf uw apparatenlijst of uw inlogproces beheert.

NetBird bevindt zich tussen twee concepten die u wellicht al kent. Het is een mesh-overlay, wat betekent dat peers onderling verbinding maken in plaats van al het verkeer door één gateway te sturen. Het is ook volledig zelf te hosten, wat het vergelijkbaar maakt met Headscale, de zelf-gehoste Tailscale control server. Als u voorheen alleen een tunnel met één gateway heeft gebruikt, lees dan eerst het verschil tussen standaard WireGuard en een mesh-overlay, omdat dat mentale model essentieel is om de rest van deze pagina nuttig te kunnen gebruiken.

Als u in werkelijkheid slechts één server wilt waar al uw verkeer via naar buiten gaat, dan is een mesh meer complexiteit dan nodig is voor die taak. Een standaard WireGuard VPN op een enkele VPS of een Tailscale exit node bereikt dat met aanzienlijk minder beheer.

Wat de stack daadwerkelijk uitvoert

De lay-out is onlangs gewijzigd en de meeste oudere handleidingen beschrijven de oude situatie. Sinds augustus 2026, bij release v0.76.2, schrijft het quickstart-script standaard een Compose-bestand met drie services.

• netbird-server bevat de management-API, de signal-service, de relay met een ingebouwde STUN-listener en een ingebouwde identity provider. In oudere releases waren dit afzonderlijke containers en was de identity provider een aparte Zitadel-installatie die u eerst moest bouwen.
• dashboard is de admin webconsole.
• traefik handelt TLS (transport layer security) af en vraagt bij de eerste start een certificaat aan bij Let's Encrypt.

Er bestaan nog twee andere services die uitgeschakeld blijven, tenzij u bij een prompt bevestigend antwoordt. De NetBird Proxy-service publiceert interne services op publieke hostnames. CrowdSec filtert schadelijk verkeer. Geen van beide is nodig om een werkend mesh-netwerk op te bouwen, en beide verbruiken geheugen op een kleine server.

Als u overstapt van wg-easy in een enkele Docker-container, is dit een toename in het aantal onderdelen. Wat u hiervoor terugkrijgt, zijn toegangsbeleid, accounts per gebruiker en peers die rechtstreeks met elkaar verbinden in plaats van via één gateway.

Wat u nodig heeft voordat u begint

Een publieke domeinnaam is niet optioneel. Het dashboard, de API en de relay gebruiken HTTPS op poort 443, en Traefik verkrijgt het certificaat van Let's Encrypt via een HTTP-challenge. Hiervoor is een naam vereist die vanaf het publieke internet naar deze VPS verwijst. Een kaal IP-adres werkt niet in dit proces.

Maak één A-record aan, netbird.example.com, dat naar het publieke IPv4-adres van de VPS wijst, en wacht tot dit actief is voordat u iets uitvoert.

dig +short netbird.example.com

Dit moet het adres van uw server tonen. Als u het installatieprogramma uitvoert voordat de DNS-wijzigingen zijn doorgevoerd, mislukt de certificaataanvraag bij de eerste start. Herhaaldelijk mislukte validaties leiden tot rate limits van Let's Encrypt, waardoor u vervolgens een uur moet wachten voordat u het opnieuw kunt proberen.

Drie poorten moeten bereikbaar zijn vanaf het internet: TCP 80 voor de certificaat-challenge en de redirect naar HTTPS, TCP 443 voor het dashboard, de API, signal- en relay-verkeer, en UDP 3478 voor STUN.

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

Open deze poorten ook in de netwerkfirewall van uw provider. Dit is bij de meeste VPS-panelen een aparte instelling en is de reden waarom een server waarvan de eigen ufw status correct lijkt, toch verbindingen weigert.

STUN (session traversal utilities for NAT) zorgt ervoor dat een peer het publieke adres en de poort leert die door de eigen NAT zijn toegewezen, zodat twee peers een directe tunnel kunnen opzetten. Als u UDP 3478 blokkeert, maken peers nog steeds verbinding via de relay op TCP 443, waardoor het lijkt alsof alles werkt. U krijgt echter Connection type: Relayed op elke peer en al het verkeer loopt via uw VPS in plaats van direct tussen peers.

Wat betreft de software heeft u Docker met de Compose v2-plugin nodig, plus jq en curl. Het script controleert op al deze onderdelen en stopt als er een ontbreekt. Als Docker nieuw is op deze server, zorg dan eerst dat Docker Compose werkt op de VPS.

De NetBird-server installeren met het quickstart-script

Het gedocumenteerde one-liner-commando sluist de nieuwste release direct door naar een shell:

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

Pin de versie in plaats daarvan. latest verandert, waardoor hetzelfde commando na twee weken een andere installatie oplevert, terwijl nergens op de schijf wordt vastgelegd welke versie uw configuratie heeft geschreven. Download een getagde release, lees deze door en voer het script daarna uit.

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

Het script vraagt eerst om het domein:

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

Vervolgens vraagt het hoe TLS moet worden afgehandeld:

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):

Kies [0]. Opties 2 tot en met 5 schrijven een configuratiefragment en laten de verdere inrichting aan u over; dit is correct op een server die al een proxy draait, maar onjuist op een verse installatie. Optie 0 vraagt vervolgens om een e-mailadres voor Let’s Encrypt, dat wordt gebruikt voor meldingen over het verlopen van certificaten.

Kies bij een eerste installatie 'nee' voor de NetBird Proxy-service. Deze vereist twee extra DNS-records, proxy.netbird.example.com en het wildcard-record *.proxy.netbird.example.com, en voegt niets toe aan een standaard mesh-netwerk. Kies ook 'nee' voor CrowdSec. Beide kunnen later worden toegevoegd.

Het script schrijft bestanden naar de huidige map: docker-compose.yml, config.yaml met modus 600, dashboard.env, en traefik-dynamic.yaml wanneer u voor de meegeleverde Traefik hebt gekozen. Behandel deze map als essentiële statusinformatie, omdat config.yaml de sleutel bevat die de gegevens in de opslag versleutelt. Verlies hiervan kan niet worden hersteld door een herinstallatie.

docker compose ps
docker compose logs -f netbird-server

Elke service hoort running te lezen en het serverlogboek moet stabiliseren in plaats van in een lus opnieuw op te starten. Monitor het certificaat afzonderlijk:

docker compose logs traefik | grep -i acme

ACME (automatic certificate management environment) is het protocol dat Traefik gebruikt om het certificaat te verkrijgen. Fouten hierbij worden bijna altijd veroorzaakt door DNS-problemen of een gesloten poort 80.

Het eerste beheerdersaccount aanmaken

Open https://netbird.example.com. Bij een nieuwe installatie verschijnt een configuratiepagina in plaats van een inlogformulier. Voer een e-mailadres, een naam en een wachtwoord in en klik op Create Account. Dit account wordt de eerste beheerder en de pagina leidt door naar het inlogformulier.

Dit account bevindt zich in de eigen gebruikersdatabase van NetBird, die wordt aangestuurd door een identiteitsprovider die in de netbird-server-container is ingebed. Er is geen externe partij bij betrokken. Dit is de grootste verandering ten opzichte van de zelfgehoste NetBird van een jaar geleden, toen een werkende installatie betekende dat u eerst Zitadel of Keycloak moest opzetten en vier OIDC (OpenID Connect)-waarden in setup.env moest kopiëren voordat er überhaupt iets werkte.

Als u een certificaatwaarschuwing van de browser krijgt in plaats van de configuratiepagina, dan is het certificaat niet uitgegeven. Los dit op voordat u verdergaat, omdat het dashboard via dezelfde hostnaam met de API communiceert en op verwarrende wijze faalt bij een ongeldig certificaat.

Uw eerste peer toevoegen

Installeer de client op elke Linux-machine, inclusief de VPS zelf als u deze in het mesh-netwerk wilt opnemen:

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

Op Debian en Ubuntu configureert dit script de pakketrepository van NetBird en installeert vervolgens de client via apt, zodat de pakketbeheerder het beheer overneemt. Als u het doorsturen van een script naar een shell onveilig vindt, sla het dan eerst op met curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh en lees het door voordat u sh install.sh uitvoert. Controleer in ieder geval wat er is geïnstalleerd:

apt-cache policy netbird

netbird is de command-line client en de daemon. netbird-ui is de desktop-tray-applicatie; een headless server heeft hier geen nut voor.

Koppel de client nu aan uw server:

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

Laat --management-url weg en de client registreert zich bij de gehoste dienst van NetBird, omdat dit de standaardinstelling is in de gecompileerde code. Het commando slaagt nog steeds, de machine krijgt een adres, en uw zelfgehoste dashboard blijft leeg. Dit is een veelvoorkomende fout.

Het commando toont een URL die u in een browser moet openen om het inloggen te voltooien. Daarna:

netbird status
ip addr show wt0

Lees vier regels uit netbird status: Management: Connected, Signal: Connected, een Relays:-regel die alle beschikbare relays rapporteert, en een NetBird IP: binnen het overlay-bereik. wt0 is de WireGuard-interface die NetBird aanmaakt, en deze hoort hetzelfde adres te bevatten.

Een tweede machine onbeheerd koppelen met een setup key

Inloggen via een browser werkt niet voor een machine zonder browser en zonder gebruiker. Een setup key is een pre-authenticatietoken waarmee een machine zonder interactieve stap wordt geregistreerd. Maak er een aan in het dashboard onder Setup Keys.

Er zijn twee soorten. Een eenmalige sleutel authenticeert precies één machine en vervalt daarna. Een herbruikbare sleutel registreert er vele, eventueel met een limiet op het aantal. Beide hebben een verloopdatum en beide kunnen de nieuwe peer automatisch toewijzen aan een groep, zodat de toegangsregels voor die groep direct van kracht zijn zodra de machine verschijnt.

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

--hostname stelt de naam in die in het dashboard wordt getoond. Zonder deze vlag neemt de peer de naam over die de machine aan zichzelf geeft, en een lijst vol items die allemaal ubuntu heten, is niet nuttig.

Markeer de sleutel als ephemeral bij het aanmaken voor containers en kortstondige build-agents. Peers die met een ephemeral sleutel zijn geregistreerd, worden automatisch verwijderd zodra ze langer dan 10 minuten offline zijn. Dit houdt de lijst met peers vrij van inactieve items.

Eén beperking om te begrijpen voordat u setup keys inzet: het laten verlopen of verwijderen van een sleutel stopt nieuwe registraties, maar verbreekt niet de verbinding met machines die zich er al mee hebben geregistreerd. Om de toegang van een machine in te trekken, moet u de betreffende peer verwijderen.

Hebt u nog steeds een aparte identiteitsprovider nodig?

Voor een kleine installatie niet. De ingebouwde gebruikersdatabase beheert accounts die via het dashboard zijn aangemaakt, en dat volstaat voor een handvol personen.

U hebt een externe identiteitsprovider nodig wanneer u er al een hebt en niet met een tweede gebruikerslijst wilt werken. NetBird accepteert elke provider die OIDC ondersteunt. Registreer een vertrouwelijke OIDC-client bij uw provider en voeg deze vervolgens toe in het NetBird-dashboard met vier waarden: naam, client ID, client secret en issuer. NetBird verstrekt u een redirect URL die u in de provider moet plakken. Er zijn specifieke integraties beschikbaar voor Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik en Pocket ID; alle overige providers kunnen als generieke OIDC worden toegevoegd. Als u al Authentik als uw zelfgehoste single sign-on gebruikt, is dit de methode om één accountlijst te behouden in plaats van twee.

Lokaal inloggen blijft beschikbaar nadat u een provider hebt toegevoegd en elke geconfigureerde provider verschijnt op de inlogpagina. Houd één lokaal beheerdersaccount aan met een sterk wachtwoord. Bij een defecte OIDC-configuratie hebt u dan nog steeds toegang tot het systeem.

NetBird of Headscale: welke control plane moet u draaien?

Beide verwijderen dezelfde afhankelijkheid: de gehoste control server waar uw clients anders verbinding mee zouden maken. Het zijn projecten met een verschillende opzet.

Headscale implementeert de Tailscale control server opnieuw, waarbij u de officiële Tailscale-clients blijft gebruiken. Er is geen officiële webconsole. U beheert gebruikers en pre-authentication keys met het headscale-commando op basis van een configuratiebestand. Er bestaan webinterfaces van de community, maar deze maken geen deel uit van het project. Dit is geschikt voor gebruikers die hun status in bestanden willen bijhouden en wijzigingen in versiebeheer willen opslaan.

NetBird levert het volledige product: een eigen client, een eigen dashboard, een ingebouwde identity provider en toegangsbeleid dat in een browser wordt beheerd. Dit betekent meer onderdelen op uw VPS, maar het is aanzienlijk minder werk om over te dragen aan een collega die nooit een terminal zal openen.

Draai Headscale als u al gebruikmaakt van Tailscale-clients of als u de kleinst mogelijke control plane wilt. Draai NetBird als meerdere personen peers moeten beheren en u een console en SSO wilt zonder deze zelf te hoeven samenstellen.

Hoe klein mag een VPS zijn om dit te draaien?

Het gedocumenteerde minimum is 1 CPU en 2 GB geheugen. Volgens de eigen aantekeningen van NetBird ligt de ondergrens momenteel rond de 1 GB RAM nu het gebruikersbeheer lokaal is, in tegenstelling tot de 2 GB tot 4 GB die de oudere opzet vereiste toen een volledige Zitadel-implementatie deel uitmaakte van de stack. Schaf 2 GB aan. De extra ruimte zorgt ervoor dat een upgrade nieuwe images kan ophalen terwijl de oude nog op de schijf staan.

Drie zaken kunt u veilig weglaten op een kleine server. Zie af van de NetBird Proxy-service; deze is bedoeld om interne services op publieke hostnames te publiceren en heeft niets te maken met het verbinden van peers. Zie af van CrowdSec; dit is de moeite waard om later aan een blootgestelde server toe te voegen in plaats van op de eerste dag. Behoud de standaard SQLite-opslag in het netbird_data-volume en stap pas over op PostgreSQL wanneer u de implementatie over meerdere machines verdeelt of tegen echte gelijktijdigheid aanloopt; dit is gedocumenteerd als een migratie die u later kunt uitvoeren.

De relay is het enige onderdeel dat u niet kunt weglaten. Twee peers waarvan de NAT voor elke bestemming een andere poort toewijst, zullen nooit een directe tunnel opzetten, dus de relay is het enige pad waardoor ze überhaupt werken. Het uitschakelen ervan bespaart nauwelijks geheugen en verbreekt verbindingen op een manier die lastig te achterhalen is.

Wanneer één server niet langer volstaat, zijn relays het eerste dat u moet verplaatsen. Een zelfstandige relay draait met NB_LISTEN_ADDRESS, NB_EXPOSED_ADDRESS, NB_AUTH_SECRET en NB_ENABLE_STUN. Het gedeelde geheim (shared secret) moet identiek zijn op de relay en op de hoofdserver, anders slagen clients er niet in om zich erbij te authenticeren.

Foutmodi en wat u zult zien

Het dashboard toont een certificaatwaarschuwing. Traefik heeft geen certificaat verkregen. Voer docker compose logs traefik | grep -i acme uit. Er zijn twee oorzaken. Ofwel verwijst dig +short netbird.example.com nog niet naar deze VPS, of TCP 80 is ergens tussen Let's Encrypt en de container geblokkeerd, meestal door de netwerkfirewall van de provider in plaats van op ufw. Los de oorzaak op voordat u het opnieuw probeert; mislukte validaties zijn onderworpen aan rate limiting, waardoor u uzelf een uur lang kunt uitsluiten van nieuwe pogingen.

De client meldt dat deze verbonden is, maar het dashboard is leeg. De client heeft zich geregistreerd bij de gehoste dienst van NetBird omdat --management-url ontbrak. Voer netbird status --detail uit en lees de regel Management:, die de server noemt waarmee daadwerkelijk wordt gecommuniceerd. Als u Management: Connected to https://api.netbird.io:443 ziet, betekent dit dat de verbinding naar de cloud gaat. Voer sudo netbird down uit en daarna opnieuw sudo netbird up --management-url https://netbird.example.com.

Elke peer toont Connection type: Relayed. Er worden geen directe tunnels gevormd, waardoor al het verkeer via uw VPS verloopt en er een extra hop aan latentie wordt toegevoegd. Controleer UDP 3478 op de VPS-firewall en de firewall van de provider, aangezien STUN ervoor zorgt dat een peer zijn eigen publieke adres en poort leert kennen. netbird status --detail toont ook Direct: false en de ICE-candidatentypen (interactive connectivity establishment) voor elke peer, wat aangeeft hoe ver de poging is gekomen. Op sommige netwerken is relayed de enige beschikbare uitkomst en is er niets mis.

Een peer sluit zich aan maar kan niets bereiken. Deel uitmaken van het mesh-netwerk betekent niet dat twee peers met elkaar kunnen praten. Toegangsbeleid bepaalt dit; een groep waaraan geen beleid is gekoppeld, bereikt niets. Controleer het beleid in het dashboard voordat u begint met het debuggen van routes en firewalls.

netbird status rapporteert een probleem met de daemon. De service draait niet. Gebruik sudo netbird service status en sudo netbird service start. Client-logs bevinden zich op /var/log/netbird/client.log. Voor zaken die u niet kunt plaatsen, verzamelt netbird debug bundle --anonymize --system-info logs, status, routes, DNS-instellingen en de firewall-status in één archief.

Back-ups en upgrades

Twee onderdelen vormen de basis van de gehele installatie: de map met docker-compose.yml en config.yaml, en het Docker-volume dat de database en de encryptiesleutels bevat. Maak van beide tegelijk een back-up. config.yaml bevat de sleutel die de gegevens in de opslag versleutelt; een databasekopie zonder dit bestand is onleesbaar en kan niet worden hersteld.

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 voegt de projectmap toe als voorvoegsel aan volumenamen, waardoor het volume dat gedocumenteerd staat als netbird_data meestal verschijnt als netbird_netbird_data. Voer eerst docker volume ls uit en gebruik de naam die wordt weergegeven, anders mislukt docker run doordat er stilletjes een leeg volume wordt aangemaakt en er niets wordt gearchiveerd. Sla de archieven op buiten de VPS. Als u al over een back-uptool beschikt, dan is restic of BorgBackup geschikt voor het offsite-gedeelte.

Het upgraden van de server bestaat uit een pull en een recreate:

docker compose pull
docker compose up -d
docker compose ps

Voordat u hierop vertrouwt, voert u docker compose config | grep image: uit. Elke tag met de tekst latest moet worden vastgezet op een specifieke versie, om dezelfde reden dat u het installatiescript heeft vastgezet: u wilt weten wat er draait en u wilt een versie hebben om naar terug te keren wanneer een upgrade problemen veroorzaakt. Clients worden geüpgraded via de pakketbeheerder waarmee ze zijn geïnstalleerd.

FAQ

Heb ik een eigen identity provider nodig om NetBird zelf te hosten?

Nee. Huidige releases bevatten een ingebouwde gebruikersopslag. U maakt het eerste beheerdersaccount aan in de browser op https://netbird.example.com en voegt daarna gebruikers toe via het dashboard. Een externe OIDC-provider is optioneel en kan later worden toegevoegd met vier waarden: naam, client ID, client secret en issuer. Handleidingen die adviseren om Zitadel of Keycloak te implementeren vóór NetBird, beschrijven een configuratie die niet langer vereist is. Het volgen daarvan leidt tot het onnodig draaien van een extra service.

Waarom tonen al mijn peers Connection type: Relayed?

Er worden geen directe verbindingen tot stand gebracht, waardoor het verkeer via de relay op uw VPS verloopt. De gebruikelijke oorzaak is dat UDP 3478 is geblokkeerd; dit is de STUN-poort die peers gebruiken om hun eigen publieke adres en poort te achterhalen. Open deze poort in de firewall van de VPS en in de externe netwerkfirewall van uw provider. Voer daarna netbird status --detail opnieuw uit en lees de regel Direct:. Op een netwerk waar de NAT per bestemming een andere poort toewijst, is een relay de enige mogelijke uitkomst en is er geen sprake van een foutieve configuratie.

Mijn client is verbonden, maar het dashboard toont geen peers. Wat is er aan de hand?

De client is geregistreerd bij de gehoste service van NetBird in plaats van bij uw eigen server. Dit gebeurt wanneer --management-url wordt weggelaten. netbird status --detail toont de server waarmee verbinding wordt gemaakt op de regel Management:; een waarde zoals https://api.netbird.io:443 bevestigt dit. Voer sudo netbird down uit, gevolgd door sudo netbird up --management-url https://netbird.example.com, waarna de peer in uw dashboard verschijnt.

Wat is het verschil tussen zelfgehoste NetBird en Headscale?

Beide vervangen een gehoste control server door een server die u zelf beheert. Headscale is uitsluitend een control plane: u beheert dit met het commando headscale en een configuratiebestand. Er is geen officiële webconsole en het systeem stuurt de officiële Tailscale-clients aan. NetBird levert een eigen client, een beheerdersdashboard en integratie met identity providers in dezelfde stack. Headscale is lichter in gebruik en slaat de status op in bestanden. NetBird is eenvoudiger in gebruik voor personen die geen terminal gebruiken.

Welke grootte VPS heeft een zelfgehoste NetBird-server nodig?

Het gedocumenteerde minimum is 1 CPU en 2 GB geheugen; 2 GB is de aanbevolen hoeveelheid. De praktische ondergrens is in recente releases gedaald naar ongeveer 1 GB, omdat de identity provider nu is ingebed in plaats van een afzonderlijke implementatie. Schakel de optionele proxy- en CrowdSec-services uit tijdens de installatie en blijf bij de standaard SQLite-opslag totdat u daadwerkelijk PostgreSQL nodig heeft.