Come installare NetBird self-hosted su un VPS

Cosa offre il self-hosting del server VPN NetBird

Il self-hosting del server VPN NetBird colloca il control plane su un VPS di tua proprietà: è il componente che conserva l’elenco dei peer, stabilisce quale macchina può raggiungere le altre e aiuta due peer a trovarsi dietro NAT (network address translation). I tunnel usano comunque WireGuard e sono cifrati direttamente tra le tue macchine. La differenza è che nessuna azienda esterna conserva l’inventario dei tuoi dispositivi o gestisce il tuo flusso di accesso.

NetBird combina due caratteristiche che potresti già conoscere. È una rete overlay mesh, quindi i peer si connettono tra loro invece di inviare tutto attraverso un unico gateway. È anche completamente self-hostable, e per questo si confronta con Headscale, il control server self-hosted di Tailscale. Se hai utilizzato soltanto un tunnel con gateway singolo, leggi prima la differenza tra WireGuard semplice e una rete overlay mesh, perché questo modello concettuale rende utile il resto della pagina.

Se ciò che ti serve è un unico server attraverso cui esce tutto il traffico, una mesh offre più funzionalità di quelle necessarie. Una VPN WireGuard semplice su un singolo VPS o un exit node Tailscale svolge questo compito con una gestione molto più semplice.

Cosa esegue realmente lo stack

La struttura è cambiata di recente e la maggior parte delle guide più datate descrive quella precedente. Ad agosto 2026, nella release v0.76.2, lo script quickstart scrive per impostazione predefinita un file Compose con tre servizi.

• netbird-server fornisce l'API di gestione, il servizio di segnalazione, il relay con un listener STUN integrato e un identity provider integrato. Nelle release precedenti questi componenti erano container separati e l'identity provider era un'installazione separata di Zitadel, che dovevi preparare prima.
• dashboard è la console web di amministrazione.
• traefik termina TLS (Transport Layer Security) e richiede un certificato a Let's Encrypt al primo avvio.

Esistono altri due servizi, disattivati finché non rispondi affermativamente a una richiesta. Il servizio NetBird Proxy pubblica i servizi interni su hostname pubblici. CrowdSec filtra il traffico abusivo. Nessuno dei due è necessario per creare una mesh funzionante e, su un server con poca memoria, entrambi consumano risorse.

Se provieni da wg-easy in un singolo container Docker, questo comporta un aumento del numero di componenti. In cambio ottieni policy di accesso e account per singolo utente, oltre a peer che si connettono direttamente tra loro invece di passare da un unico gateway.

Cosa serve prima di iniziare

Un nome di dominio pubblico è obbligatorio. Il dashboard, l'API e il relay usano tutti HTTPS sulla porta 443. Traefik ottiene il certificato da Let's Encrypt tramite una challenge HTTP. Per questo serve un nome che dal pubblico Internet risolva verso questo VPS. In questo flusso un semplice indirizzo IP non funziona.

Create un record A, netbird.example.com, che punti all'indirizzo IPv4 pubblico del VPS. Attendete la propagazione prima di eseguire qualsiasi comando.

dig +short netbird.example.com

Il comando deve restituire l'indirizzo del server. Se eseguite l'installer prima della propagazione DNS, la richiesta del certificato fallisce al primo avvio. I tentativi di validazione falliti ripetuti possono inoltre raggiungere i limiti di frequenza di Let's Encrypt. In tal caso dovrete attendere un'ora prima di riprovare.

Tre porte devono essere raggiungibili da Internet: TCP 80 per la challenge del certificato e il redirect verso HTTPS, TCP 443 per il dashboard, l'API, il traffico signal e relay, e UDP 3478 per STUN.

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

Apritele anche nel firewall di rete del provider. Nella maggior parte dei pannelli VPS si tratta di un controllo separato. È per questo che un server il cui ufw status locale sembra corretto può continuare a rifiutare le connessioni.

STUN (session traversal utilities for NAT) consente a un peer di conoscere l'indirizzo pubblico e la porta assegnati dal proprio NAT. In questo modo due peer possono tentare di creare un tunnel diretto. Se bloccate UDP 3478, i peer continuano a connettersi tramite il relay su TCP 443, quindi nulla sembra non funzionare. Su ogni peer viene invece mostrato Connection type: Relayed e tutto il traffico attraversa il VPS anziché passare direttamente da un peer all'altro.

Per quanto riguarda il software, servono Docker con il plugin Compose v2, oltre a jq e curl. Lo script verifica la presenza di tutti questi componenti e si interrompe se ne manca uno. Se Docker è appena stato installato su questo server, configurate prima Docker Compose funzionante sul VPS.

Installare il server NetBird con lo script di avvio rapido

Il comando documentato in una sola riga inoltra la release più recente direttamente a una shell:

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

Blocca invece una versione specifica. latest cambia, quindi lo stesso comando eseguito a distanza di due settimane produce due installazioni diverse e sul disco non rimane alcuna informazione su quale versione abbia scritto la configurazione. Scarica una release contrassegnata da un tag, leggila, quindi eseguila.

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

Lo script chiede prima il dominio:

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

Poi chiede come gestire 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):

Scegli [0]. Le opzioni da 2 a 5 scrivono un frammento di configurazione e lasciano a te il collegamento dei componenti. Questa scelta è corretta su un server che esegue già un proxy, ma non su un server appena installato. L'opzione 0 chiede quindi un indirizzo email Let's Encrypt, usato per le notifiche di scadenza.

Durante la prima installazione, rispondi no al servizio NetBird Proxy. Richiede altri due record DNS, proxy.netbird.example.com e il wildcard *.proxy.netbird.example.com, ma non offre alcun vantaggio per una semplice mesh. Rispondi no anche a CrowdSec. Entrambi possono essere aggiunti in seguito.

Lo script scrive nella directory corrente: docker-compose.yml, config.yaml con modalità 600, dashboard.env e traefik-dynamic.yaml quando hai scelto Traefik incluso. Tratta questa directory come stato persistente da conservare, perché config.yaml contiene la chiave che cifra i dati nell'archivio. Perdere questa chiave non è un problema che una reinstallazione possa risolvere.

docker compose ps
docker compose logs -f netbird-server

Ogni servizio dovrebbe leggere running e il log del server dovrebbe stabilizzarsi, senza riavvii continui. Monitora il certificato separatamente:

docker compose logs traefik | grep -i acme

ACME (automatic certificate management environment) è il protocollo che Traefik usa per ottenere il certificato. Gli errori in questa fase sono quasi sempre dovuti al DNS o alla porta 80 chiusa.

Crea il primo account amministratore

Apri https://netbird.example.com. In una nuova installazione viene visualizzata una pagina di configurazione invece del modulo di accesso. Inserisci un indirizzo email, un nome e una password, quindi fai clic su Create Account. Questo diventa il primo account amministratore e la pagina reindirizza al modulo di accesso.

L'account viene memorizzato nell'archivio utenti interno di NetBird, gestito da un identity provider integrato nel container netbird-server. Non è necessario alcun componente esterno. Questa è la differenza principale rispetto a NetBird self-hosted di un anno fa: per ottenere un'installazione funzionante era prima necessario configurare Zitadel o Keycloak e copiare quattro valori OIDC (OpenID Connect) in setup.env. In caso contrario, nulla si avviava.

Se il browser mostra un avviso relativo al certificato invece della pagina di configurazione, il certificato non è stato emesso. Risolvi il problema prima di continuare, perché la dashboard comunica con l'API usando lo stesso hostname e, con un certificato non valido, può generare errori poco chiari.

Unisciti al primo peer

Installa il client su una macchina Linux qualsiasi, incluso lo stesso VPS se vuoi inserirlo nella mesh:

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

Su Debian e Ubuntu, questo script configura il repository dei pacchetti di NetBird e installa quindi il client tramite apt. In questo modo, in ogni caso, il pacchetto viene gestito dal package manager. Se non vuoi eseguire uno script tramite una pipe verso una shell, salvalo prima con curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh e leggilo prima di eseguire sh install.sh. In entrambi i casi, verifica che cosa è stato installato:

apt-cache policy netbird

netbird è il client a riga di comando e il daemon. netbird-ui è l'applicazione residente nell'area di notifica del desktop e non serve su un server headless.

Ora configura il client affinché utilizzi il tuo server:

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

Se ometti --management-url, il client si registra presso il servizio gestito di NetBird, perché questa è l'impostazione predefinita compilata nel client. Il comando viene comunque eseguito correttamente, la macchina riceve comunque un indirizzo e la dashboard self-hosted resta vuota. È un errore in cui incorrono quasi tutti almeno una volta.

Il comando stampa un URL da aprire nel browser per completare l'accesso. Dopo:

netbird status
ip addr show wt0

Leggi quattro righe da netbird status: Management: Connected, Signal: Connected, una riga Relays: che elenca ogni relay disponibile e una riga NetBird IP: con un indirizzo nell'intervallo overlay. wt0 è l'interfaccia WireGuard creata da NetBird e dovrebbe avere lo stesso indirizzo.

Registrare una seconda macchina senza intervento con una chiave di configurazione

Il login tramite browser non funziona su una macchina senza browser e senza nessuno che possa usarla direttamente. Una chiave di configurazione è un token di preautenticazione che registra una macchina senza il passaggio interattivo. Creane una nella dashboard, alla voce Setup Keys.

Esistono due tipi di chiave. Una chiave monouso autentica esattamente una macchina e poi viene utilizzata. Una chiave riutilizzabile registra più macchine, con un limite opzionale sul numero di registrazioni. Entrambe hanno una scadenza e possono assegnare automaticamente il nuovo peer a un gruppo, applicando immediatamente le regole di accesso del gruppo quando la macchina viene visualizzata.

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

--hostname imposta il nome visualizzato nella dashboard. In sua assenza, il peer utilizza il nome con cui la macchina si identifica. Una flotta di voci denominate tutte ubuntu non è utile a nessuno.

Per i container e gli agenti di build temporanei, imposta la chiave come ephemeral durante la creazione. I peer registrati con una chiave ephemeral vengono rimossi automaticamente dopo più di 10 minuti offline. In questo modo le voci non più attive non rimangono nell'elenco dei peer.

Prima di pianificare l'uso delle chiavi di configurazione, considera un limite importante: la scadenza o l'eliminazione di una chiave impedisce le nuove registrazioni, ma non disconnette le macchine che l'hanno già utilizzata per registrarsi. Per rimuovere l'accesso di una macchina, devi rimuovere il relativo peer.

Ti serve ancora un identity provider separato?

Per una piccola installazione, no. L’archivio utenti integrato gestisce gli account creati dalla dashboard ed è sufficiente per poche persone.

Un identity provider esterno è utile se ne utilizzi già uno e non vuoi gestire un secondo elenco di utenti. NetBird accetta qualsiasi provider che supporti OIDC. Registra un client OIDC confidential nel tuo provider, quindi aggiungilo nella dashboard di NetBird specificando quattro valori: nome, client ID, client secret e issuer. NetBird fornisce un redirect URL da incollare nuovamente nel provider. Sono disponibili integrazioni dedicate per Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik e Pocket ID; per gli altri provider puoi usare la configurazione OIDC generica. Se utilizzi già Authentik come single sign-on self-hosted, questa soluzione mantiene un unico elenco di account invece di due.

L’accesso locale resta disponibile dopo l’aggiunta di un provider e ogni provider configurato compare nella pagina di accesso. Mantieni un account admin locale con una password complessa. In questo modo, una configurazione OIDC non funzionante non ti impedisce di accedere.

NetBird o Headscale: quale control plane conviene eseguire?

Entrambi eliminano la stessa dipendenza: il server di controllo ospitato a cui i client si collegherebbero altrimenti. Tuttavia, i due progetti hanno caratteristiche diverse.

Headscale reimplementa il server di controllo di Tailscale e consente di continuare a usare i client ufficiali di Tailscale. Non dispone di una console web ufficiale. Gli utenti e le chiavi di preautenticazione si gestiscono con il comando headscale e un file di configurazione. Esistono interfacce web sviluppate dalla community, ma non fanno parte del progetto. Questa soluzione è adatta a chi vuole mantenere lo stato nei file e gestire le modifiche tramite controllo versione.

NetBird include l'intero prodotto: un client dedicato, una dashboard dedicata, un identity provider integrato e policy di accesso modificabili dal browser. Sul VPS comporta un numero maggiore di componenti, ma richiede molto meno lavoro quando la gestione viene affidata a un collega che non utilizzerà mai un terminale.

Esegui Headscale se utilizzi già i client Tailscale o vuoi un control plane il più possibile minimale. Esegui NetBird se più persone devono gestire i peer e vuoi una console e SSO senza doverle assemblare.

Quanto può essere piccolo un VPS per eseguire questo stack?

Il minimo documentato è 1 CPU e 2 GB di memoria. Le indicazioni attuali di NetBird considerano sufficiente circa 1 GB di RAM, ora che la gestione degli utenti è locale. Il vecchio layout richiedeva invece da 2 GB a 4 GB quando nello stack era incluso un deployment completo di Zitadel. Scegli 2 GB. Questo margine aggiuntivo consente a un aggiornamento di scaricare nuove immagini mentre quelle precedenti sono ancora presenti sul disco.

Su una macchina con risorse limitate puoi omettere tre componenti. Non installare il servizio NetBird Proxy, che serve a pubblicare servizi interni su hostname pubblici e non ha alcuna relazione con la connessione tra peer. Non installare CrowdSec: è utile aggiungerlo in seguito su una macchina esposta, non necessariamente dal primo giorno. Mantieni lo store SQLite predefinito nel volume netbird_data e passa a PostgreSQL solo quando distribuisci i componenti su più macchine o incontri problemi reali di concorrenza. La documentazione indica questa migrazione come un'operazione eseguibile in seguito.

Il relay è l'unico componente che non puoi omettere. Se il NAT assegna una porta diversa per ogni destinazione, due peer non riusciranno mai a stabilire un tunnel diretto. In questo caso il relay è l'unico percorso che consente loro di comunicare. Disabilitarlo fa risparmiare pochissima memoria e interrompe le connessioni in modo difficile da diagnosticare.

Quando una sola macchina non è più sufficiente, i relay sono i primi componenti da spostare. Un relay autonomo viene eseguito con NB_LISTEN_ADDRESS, NB_EXPOSED_ADDRESS, NB_AUTH_SECRET e NB_ENABLE_STUN. Il secret condiviso deve essere identico sul relay e sul server principale. In caso contrario, i client non riescono ad autenticarsi al relay.

Modalità di errore e cosa verrà visualizzato

Il dashboard mostra un avviso relativo al certificato. Traefik non ha ottenuto un certificato. Esegui docker compose logs traefik | grep -i acme. Le cause possibili sono due. dig +short netbird.example.com non restituisce ancora questo VPS oppure la porta TCP 80 è chiusa in un punto del percorso tra Let's Encrypt e il container, in genere nel firewall di rete del provider e non su ufw. Risolvi la causa prima di riprovare in un ciclo, perché le convalide non riuscite sono soggette a limiti di frequenza e per un'ora non potrai più effettuare tentativi.

Il client indica di essersi connesso, ma il dashboard è vuoto. Il client si è registrato al servizio ospitato da NetBird perché mancava --management-url. Esegui netbird status --detail e leggi la riga Management:, che indica il server con cui sta comunicando effettivamente. Se vedi Management: Connected to https://api.netbird.io:443, il client si è connesso al cloud. Esegui sudo netbird down, quindi nuovamente sudo netbird up --management-url https://netbird.example.com.

Ogni peer mostra Connection type: Relayed. Non si stanno creando tunnel diretti, quindi tutto il traffico attraversa il VPS e aggiunge un passaggio con relativa latenza. Controlla la porta UDP 3478 nel firewall del VPS e nel firewall del provider, perché STUN consente a un peer di rilevare il proprio indirizzo e la propria porta pubblici. netbird status --detail stampa anche Direct: false e i tipi di candidati ICE (interactive connectivity establishment) per ogni peer, mostrando fino a quale punto è arrivato il tentativo. Su alcune reti il relay è l'unico risultato disponibile e non indica necessariamente un problema.

Un peer entra nella rete mesh, ma non riesce a raggiungere nulla. Far parte della rete mesh non significa che due peer possano comunicare. Questo dipende dalle policy di accesso e un gruppo a cui non è associata alcuna policy non può raggiungere nulla. Controlla la policy nel dashboard prima di eseguire il troubleshooting di route e firewall.

netbird status segnala un problema del daemon. Il servizio non è in esecuzione. Usa sudo netbird service status e sudo netbird service start. I log del client si trovano in /var/log/netbird/client.log. Per i problemi che non riesci a classificare, netbird debug bundle --anonymize --system-info raccoglie in un unico archivio i log, lo stato del sistema, le route, le impostazioni DNS e lo stato del firewall.

Backup e aggiornamenti

L'intera installazione dipende da due elementi: la directory che contiene docker-compose.yml e config.yaml e il volume Docker che contiene il database e le chiavi di crittografia. Eseguire il backup di entrambi insieme. config.yaml contiene la chiave che crittografa i dati nell'archivio, quindi una copia del database senza questa chiave non consente di ripristinare dati leggibili.

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 antepone ai nomi dei volumi il nome della directory del progetto, quindi il volume documentato come netbird_data di solito appare come netbird_netbird_data. Eseguire prima docker volume ls e usare il nome visualizzato, altrimenti docker run crea silenziosamente un volume vuoto e non archivia nulla. Conservare gli archivi fuori dal VPS. Se si dispone già di uno strumento di backup, restic o BorgBackup gestisce la parte relativa alla copia fuori sede.

L'aggiornamento del server consiste nel fare il pull e ricreare i container:

docker compose pull
docker compose up -d
docker compose ps

Prima di affidarsi a questa procedura, eseguire docker compose config | grep image:. Qualsiasi tag con valore latest deve essere fissato a una versione, per lo stesso motivo per cui è stato fissato lo script di installazione: è necessario sapere cosa è in esecuzione e avere una versione a cui tornare se un aggiornamento presenta problemi. I client si aggiornano tramite il package manager con cui sono stati installati.

FAQ

Ho un bisogno di un identity provider personale per eseguire NetBird in self-hosting?

No. Le versioni attuali includono un archivio utenti integrato. Puoi quindi creare il primo account amministratore nel browser all'indirizzo https://netbird.example.com e aggiungere successivamente gli utenti dal dashboard. Un provider OIDC esterno è facoltativo e può essere aggiunto in un secondo momento usando quattro valori: nome, client ID, client secret e issuer. Le guide che indicano di installare Zitadel o Keycloak prima di NetBird descrivono una configurazione che non è più necessaria. Seguirle comporta la gestione di un servizio aggiuntivo.

Perché tutti i peer mostrano Connection type: Relayed?

Le connessioni dirette non vengono stabilite. Il traffico passa quindi attraverso il relay sul tuo VPS. La causa più comune è il blocco di UDP 3478. Questa è la porta STUN usata dai peer per individuare il proprio indirizzo e la propria porta pubblici. Aprila nel firewall del VPS e nel firewall di rete separato del provider. Esegui nuovamente netbird status --detail e leggi la riga Direct:. In una rete il cui NAT assegna una porta diversa per ogni destinazione, il relay è l'unico risultato possibile e la configurazione è corretta.

Il client si è connesso, ma il dashboard non mostra alcun peer. Che cosa è successo?

Il client si è registrato presso il servizio hosted di NetBird invece che presso il tuo server. Questo accade quando --management-url non viene specificato. netbird status --detail stampa il server con cui comunica nella riga Management:. Un valore come https://api.netbird.io:443 lo conferma. Esegui sudo netbird down, quindi sudo netbird up --management-url https://netbird.example.com. Il peer verrà visualizzato nel tuo dashboard.

In che modo NetBird in self-hosting differisce da Headscale?

Entrambi sostituiscono un server di controllo hosted con un server gestito autonomamente. Headscale è solo un control plane: lo gestisci con il comando headscale e un file di configurazione. Non dispone di una console web ufficiale e controlla i client Tailscale ufficiali. NetBird include il proprio client, un dashboard amministrativo e l'integrazione con un identity provider nello stesso stack. Headscale è più semplice da gestire e conserva lo stato nei file. NetBird è più facile da affidare a persone che non usano un terminale.

Di quali dimensioni deve essere il VPS per un server NetBird in self-hosting?

Il minimo documentato è 1 CPU e 2 GB di memoria. Il valore da acquistare è quindi 2 GB. Il limite pratico è sceso a circa 1 GB nelle versioni recenti, perché l'identity provider è ora integrato invece di essere installato come deployment separato. Durante l'installazione, non selezionare i servizi proxy e CrowdSec facoltativi. Mantieni inoltre l'archivio SQLite predefinito finché PostgreSQL non diventa realmente necessario.