Como alojar o servidor VPN NetBird num VPS

O que o servidor VPN NetBird oferece quando é alojado por si

Alojar o servidor VPN NetBird coloca o plano de controlo num VPS que lhe pertence: a parte que mantém a lista de peers, decide que máquina pode alcançar cada outra e ajuda dois peers a encontrar-se atrás de NAT (tradução de endereços de rede). Os túneis continuam a usar WireGuard, com encriptação direta entre as suas máquinas. A diferença é que nenhuma empresa externa mantém o inventário dos seus dispositivos ou gere o seu fluxo de autenticação. É importante perceber o que isto lhe oferece, porque um plano de controlo alojado também nunca possui as chaves que encriptam o seu tráfego, e o que um servidor de coordenação pode realmente fazer se for comprometido é uma lista mais limitada do que a maioria das pessoas imagina antes de a ler.

O NetBird situa-se entre duas soluções que talvez já conheça. É uma sobreposição em malha, por isso os peers ligam-se entre si em vez de enviarem tudo através de um único gateway. Também pode ser alojado por si de ponta a ponta, o que o coloca lado a lado com o servidor de controlo Tailscale alojado por si, o Headscale. Se só tiver usado um túnel com gateway único, leia primeiro a diferença entre WireGuard simples e uma sobreposição em malha, porque esse modelo mental torna o resto desta página útil.

Se o que pretende é um único servidor pelo qual saia todo o seu tráfego, uma malha oferece mais componentes do que a tarefa exige. Uma VPN WireGuard simples num único VPS ou um nó de saída Tailscale faz isso com muito menos componentes para manter. Se o objetivo for aceder a uma única rede privada, em vez de ligar máquinas entre si, um router de sub-rede Tailscale num VPS anuncia esse intervalo numa tailnet que já possui, sem precisar da pilha descrita abaixo.

O que a stack realmente executa

O layout mudou recentemente, e a maioria dos tutoriais antigos descreve o layout anterior. Em agosto de 2026, na release v0.76.2, o script de início rápido grava, por predefinição, um ficheiro Compose com três serviços.

• netbird-server fornece a API de gestão, o serviço de sinalização, o relay com um listener STUN integrado e um fornecedor de identidade integrado. Nas releases anteriores, estes componentes eram contentores separados, e o fornecedor de identidade era uma instalação independente do Zitadel que tinha de ser criada primeiro.
• dashboard é a consola Web de administração.
• traefik termina o TLS (Transport Layer Security) e solicita um certificado ao Let's Encrypt no primeiro arranque.

Existem mais dois serviços, que permanecem desativados até responder afirmativamente a um prompt. O serviço NetBird Proxy publica serviços internos em nomes de host públicos. O CrowdSec filtra tráfego abusivo. Nenhum dos dois é necessário para criar uma mesh funcional, e ambos consomem memória numa máquina pequena.

Se vem de wg-easy num único contentor Docker, isto representa um aumento no número de componentes. Em contrapartida, obtém políticas de acesso e contas por utilizador, além de peers que estabelecem ligação diretamente entre si em vez de passarem por um único gateway.

O que precisa antes de começar

Um nome de domínio público é obrigatório. O dashboard, a API e o relay usam HTTPS na porta 443, e o Traefik obtém o certificado do Let's Encrypt através de um desafio HTTP. Para isso, é necessário um nome que resolva para este VPS a partir da Internet pública. Um endereço IP isolado não funciona neste fluxo.

Crie um registo A, netbird.example.com apontado para o endereço IPv4 público do VPS, e aguarde antes de executar qualquer comando.

dig +short netbird.example.com

Esse comando tem de apresentar o endereço do servidor. Executar o instalador antes de a propagação do DNS terminar faz com que o pedido do certificado falhe no primeiro arranque. Validações falhadas repetidamente também atingem os limites de taxa do Let's Encrypt. Nesse caso, terá de aguardar uma hora para tentar novamente.

Três portas têm de estar acessíveis a partir da Internet: TCP 80 para o desafio do certificado e o redirecionamento para HTTPS, TCP 443 para o dashboard, a API, o tráfego de sinalização e o relay, e UDP 3478 para STUN.

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

Abra-as também na firewall de rede do seu fornecedor. Na maioria dos painéis de VPS, esse é um controlo separado. É por isso que uma máquina cujo próprio ufw status parece correto pode continuar a recusar ligações.

STUN (session traversal utilities for NAT) permite que um peer descubra o endereço público e a porta atribuídos pelo respetivo NAT. Assim, dois peers podem tentar estabelecer um túnel direto. Se bloquear UDP 3478, os peers continuam a ligar-se através do relay em TCP 443, pelo que nada parece estar avariado. Em vez disso, obtém Connection type: Relayed em todos os peers, e todo o tráfego atravessa o VPS, em vez de circular diretamente entre os peers.

No software, precisa de Docker com o plugin Compose v2, além de jq e curl. O script verifica todos estes requisitos e para se algum estiver em falta. Se o Docker for recente nesta máquina, configure primeiro o Docker Compose no VPS.

Instalar o servidor NetBird com o script de instalação rápida

O comando de uma linha documentado envia a versão mais recente diretamente para uma shell:

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

Fixe a versão. latest muda, pelo que o mesmo comando executado com duas semanas de intervalo produz duas instalações diferentes, sem registar no disco qual delas escreveu a sua configuração. Transfira uma versão identificada, leia o script e execute-o depois.

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

O script pergunta primeiro pelo domínio:

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

Depois pergunta como o TLS será gerido:

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

Escolha [0]. As opções 2 a 5 escrevem um trecho de configuração e deixam a integração a seu cargo. Isso é correto num servidor que já executa um proxy e inadequado num servidor novo. A opção 0 pede um endereço de email do Let's Encrypt, utilizado para enviar avisos de expiração.

Na primeira instalação, responda não ao serviço NetBird Proxy. Ele requer mais 2 registos DNS, proxy.netbird.example.com e o wildcard *.proxy.netbird.example.com, e não acrescenta nada a uma rede mesh simples. Responda também não ao CrowdSec. Ambos podem ser adicionados mais tarde.

O script escreve no diretório atual: docker-compose.yml, config.yaml com modo 600, dashboard.env e traefik-dynamic.yaml quando escolheu o Traefik incluído. Trate esse diretório como estado persistente, porque config.yaml contém a chave que cifra os dados no armazenamento. Reinstalar o sistema não corrige a perda dessa chave.

docker compose ps
docker compose logs -f netbird-server

Todos os serviços devem ler running, e o log do servidor deve estabilizar, sem reiniciar continuamente. Monitorize o certificado separadamente:

docker compose logs traefik | grep -i acme

ACME (ambiente de gestão automática de certificados) é o protocolo que o Traefik utiliza para obter o certificado. Os erros aqui devem-se quase sempre ao DNS ou à porta 80 fechada.

Criar a primeira conta de administrador

Abra https://netbird.example.com. Numa instalação nova, é apresentada uma página de configuração em vez de um formulário de início de sessão. Introduza um endereço de e-mail, um nome e uma palavra-passe. Em seguida, clique em Create Account. Essa conta torna-se a primeira conta de administrador e a página redireciona para o formulário de início de sessão.

Essa conta fica armazenada no repositório de utilizadores do próprio NetBird, gerido por um fornecedor de identidade integrado no contentor netbird-server. Não há qualquer componente externo envolvido. Esta é a maior alteração em relação ao NetBird self-hosted de há um ano. Nessa altura, uma instalação funcional exigia configurar primeiro o Zitadel ou o Keycloak e copiar quatro valores OIDC (OpenID Connect) para setup.env antes de qualquer componente arrancar.

Se o navegador apresentar um aviso sobre o certificado em vez da página de configuração, o certificado não foi emitido. Corrija o problema antes de continuar. O dashboard comunica com a API através do mesmo nome de host e pode falhar de formas confusas quando o certificado está incorreto.

Associe o seu primeiro peer

Instale o cliente em qualquer máquina Linux, incluindo o próprio VPS, se quiser incluí-lo na malha:

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

No Debian e no Ubuntu, esse script configura o repositório de pacotes do NetBird e instala o cliente através do apt. Assim, o gestor de pacotes fica responsável pelo software. Se não quiser encaminhar um script para um shell, guarde-o primeiro com curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh e leia-o antes de executar sh install.sh. Em qualquer dos casos, confirme o que foi instalado:

apt-cache policy netbird

netbird é o cliente de linha de comandos e o daemon. netbird-ui é a aplicação na área de notificação do ambiente de trabalho. Um servidor headless não precisa dela.

Agora aponte o cliente para o seu servidor:

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

Se omitir --management-url, o cliente será registado no serviço alojado do NetBird, porque essa é a predefinição compilada. O comando será executado com sucesso, a máquina receberá um endereço e o seu dashboard self-hosted continuará vazio. Isto apanha quase toda a gente pelo menos uma vez.

O comando apresenta um URL para abrir num navegador e concluir o início de sessão. Depois:

netbird status
ip addr show wt0

Leia quatro linhas de netbird status: Management: Connected, Signal: Connected, uma linha Relays: que apresenta todos os relays disponíveis e um NetBird IP: no intervalo da overlay network. wt0 é a interface WireGuard criada pelo NetBird e deve ter esse mesmo endereço.

Associar uma segunda máquina sem intervenção com uma chave de configuração

O início de sessão pelo navegador não funciona numa máquina sem navegador e sem ninguém a operá-la. Uma chave de configuração é um token de pré-autenticação que regista uma máquina sem a etapa interativa. Crie uma no painel, em Setup Keys.

Existem dois tipos. Uma chave de uso único autentica exatamente uma máquina e fica inutilizada depois. Uma chave reutilizável regista várias máquinas, com um limite opcional para a quantidade. Ambas têm uma validade e podem atribuir automaticamente o novo peer a um grupo, para que as regras de acesso desse grupo sejam aplicadas assim que a máquina aparece.

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

--hostname define o nome apresentado no painel. Sem esta opção, o peer usa o nome que a máquina atribui a si própria, e uma frota de entradas chamadas todas ubuntu não ajuda ninguém.

Para contentores e agentes de compilação de curta duração, marque a chave como efémera ao criá-la. Os peers registados com uma chave efémera são removidos automaticamente quando permanecem offline durante mais de 10 minutos, mantendo as entradas inativas fora da lista de peers.

Há um limite que deve compreender antes de planear com base em chaves de configuração: a expiração ou eliminação de uma chave impede novos registos, mas não desliga as máquinas que já foram registadas com ela. Para remover o acesso de uma máquina, é necessário remover esse peer.

Ainda precisa de um provedor de identidade separado?

Para uma instalação pequena, não. O armazenamento de utilizadores integrado gere as contas criadas no dashboard, o que é suficiente para poucas pessoas.

Precisa de um provedor de identidade externo quando já dispõe de um e não quer manter uma segunda lista de utilizadores. O NetBird aceita qualquer provedor compatível com OIDC. Registe um cliente OIDC confidencial no seu provedor e adicione-o no dashboard do NetBird com quatro valores: nome, ID do cliente, segredo do cliente e emissor. O NetBird fornece um URL de redirecionamento para colar novamente no provedor. Existem integrações específicas para Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik e Pocket ID. Qualquer outro provedor é configurado como OIDC genérico. Se já utiliza o Authentik como início de sessão único autoalojado, este é o caminho para manter uma única lista de contas em vez de duas.

O início de sessão local continua disponível depois de adicionar um provedor, e todos os provedores configurados aparecem na página de início de sessão. Mantenha uma conta de administrador local com uma palavra-passe forte. Se a configuração OIDC falhar, continuará a ter uma forma de aceder ao sistema.

NetBird ou Headscale: que plano de controlo deve executar?

Ambos removem a mesma dependência: o servidor de controlo alojado para o qual os seus clientes enviariam pedidos. Não são projetos com a mesma arquitetura.

O Headscale reimplementa o servidor de controlo do Tailscale, e continua a utilizar os clientes oficiais do Tailscale. Não existe uma consola Web oficial. Gere utilizadores e chaves de pré-autenticação com o comando headscale, utilizando um ficheiro de configuração. Existem interfaces Web da comunidade, mas não fazem parte do projeto. Esta opção é adequada para quem quer manter o estado em ficheiros e as alterações sob controlo de versões.

O NetBird fornece o produto completo: o seu próprio cliente, o seu próprio dashboard, um fornecedor de identidade integrado e políticas de acesso editadas num browser. Isso acrescenta mais componentes ao seu VPS e dá muito mais trabalho para entregar a um colega que nunca irá abrir um terminal.

Execute o Headscale se já utiliza clientes Tailscale ou se quer o plano de controlo mais pequeno possível. Execute o NetBird se várias pessoas precisarem de gerir peers e quiser uma consola e SSO sem ter de montar esses componentes. Antes de escolher uma das opções, consulte o que o plano gratuito do Tailscale inclui realmente, porque um grupo com até seis utilizadores e dispositivos ilimitados não paga nada por um plano de controlo alojado e pode não ter qualquer motivo para executar um. Acima desse limite, o custo aumenta com o número de pessoas, e não com o número de máquinas. Por isso, calcular quanto o Tailscale cobraria ao seu grupo fornece um valor para comparar com o VPS e com as horas que esta stack lhe custará.

Qual o tamanho mínimo de VPS para executar isto?

O mínimo documentado é 1 CPU e 2 GB de memória. As notas da NetBird indicam que o limite atual está próximo de 1 GB de RAM, agora que a gestão de utilizadores é local. O layout antigo precisava de 2 GB a 4 GB quando uma implementação completa do Zitadel fazia parte da stack. Contrate 2 GB. Essa margem adicional permite que uma atualização transfira novas imagens enquanto as antigas ainda estão no disco.

Num servidor pequeno, é seguro deixar três componentes de fora. Recuse o serviço NetBird Proxy, que serve para publicar serviços internos em nomes de host públicos e não tem relação com a ligação entre peers. Recuse o CrowdSec, que é útil adicionar mais tarde num servidor exposto, mas não no primeiro dia. Mantenha o armazenamento SQLite predefinido no volume netbird_data e migre para PostgreSQL apenas quando dividir a implementação por várias máquinas ou atingir uma concorrência real. A documentação indica que essa migração pode ser feita mais tarde.

O relay é o único componente que não pode ser removido. Dois peers cuja NAT atribui uma porta diferente para cada destino nunca conseguirão estabelecer um túnel direto. Nesse caso, o relay é o único caminho que permite a ligação. Desativá-lo poupa muito pouca memória e interrompe ligações de uma forma difícil de diagnosticar.

Quando uma máquina deixa de ser suficiente, os relays são os primeiros componentes a mover para outra máquina. Um relay autónomo é executado com NB_LISTEN_ADDRESS, NB_EXPOSED_ADDRESS, NB_AUTH_SECRET e NB_ENABLE_STUN. O segredo partilhado tem de ser idêntico no relay e no servidor principal. Caso contrário, os clientes não conseguem autenticar-se no relay.

Modos de falha e o que verá

O dashboard mostra um aviso de certificado. O Traefik não obteve um certificado. Execute docker compose logs traefik | grep -i acme. Há duas causas. Ou dig +short netbird.example.com ainda não aponta para este VPS, ou o TCP 80 está bloqueado em algum ponto entre o Let's Encrypt e o contentor, normalmente na firewall de rede do fornecedor e não no ufw. Corrija a causa antes de repetir a tentativa em ciclo, porque as validações falhadas estão sujeitas a limites de taxa e ficará impedido de tentar novamente durante uma hora.

O cliente indica que se ligou, mas o dashboard está vazio. O cliente foi registado no serviço alojado do NetBird, porque --management-url estava em falta. Execute netbird status --detail e leia a linha Management:, que identifica o servidor com o qual está efetivamente a comunicar. Ver Management: Connected to https://api.netbird.io:443 significa que o cliente se ligou à cloud. Execute sudo netbird down e depois sudo netbird up --management-url https://netbird.example.com novamente.

Todos os peers mostram Connection type: Relayed. Não estão a ser estabelecidos túneis diretos, pelo que todo o tráfego atravessa o VPS e acrescenta um salto de latência. Verifique o UDP 3478 na firewall do VPS e na firewall do fornecedor, porque o STUN permite que um peer descubra o seu próprio endereço público e a porta. netbird status --detail também apresenta Direct: false e os tipos de candidatos ICE (estabelecimento de conectividade interativa) de cada peer, mostrando até onde chegou a tentativa. Em algumas redes, relay é o único resultado disponível e não há nenhum problema.

Um peer entra na rede e não consegue alcançar nada. Fazer parte da mesh não significa que dois peers possam comunicar. As políticas de acesso determinam isso, e um grupo sem nenhuma política associada não alcança nada. Verifique a política no dashboard antes de começar a depurar rotas e firewalls.

netbird status indica um problema no daemon. O serviço não está em execução. Use sudo netbird service status e sudo netbird service start. Os logs do cliente estão em /var/log/netbird/client.log. Para qualquer problema que não consiga identificar, netbird debug bundle --anonymize --system-info recolhe os logs, o estado, as rotas, as definições de DNS e o estado da firewall num único arquivo.

Backups e upgrades

Duas coisas sustentam toda a instalação: o diretório que contém docker-compose.yml e config.yaml, e o volume Docker que contém a base de dados e as chaves de encriptação. Faça o backup dos dois em conjunto. config.yaml contém a chave que encripta os dados no armazenamento, por isso uma cópia da base de dados sem essa chave não restaura dados legíveis.

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

O Compose acrescenta o diretório do projeto ao prefixo dos nomes dos volumes. Por isso, o volume documentado como netbird_data normalmente aparece como netbird_netbird_data. Execute docker volume ls primeiro e use o nome apresentado, ou docker run falha ao criar silenciosamente um volume vazio e não arquiva nada. Mantenha os arquivos fora da VPS. Se já utiliza uma ferramenta de backup, restic ou BorgBackup trata da parte externa ao servidor.

A atualização do servidor consiste em obter a nova imagem e recriar o serviço:

docker compose pull
docker compose up -d
docker compose ps

Antes de depender desse procedimento, execute docker compose config | grep image:. Qualquer tag com o valor latest deve ser fixada numa versão, pelo mesmo motivo que fixou o script de instalação: é necessário saber o que está em execução e ter uma versão para a qual voltar se a atualização causar problemas. Os clientes são atualizados pelo gestor de pacotes que os instalou.

FAQ

Preciso do meu próprio provedor de identidade para alojar o NetBird?

Não. As versões atuais incluem um armazenamento de utilizadores integrado. Por isso, cria a primeira conta de administrador no navegador em https://netbird.example.com e adiciona os utilizadores posteriormente a partir do dashboard. Um provedor OIDC externo é opcional e pode ser adicionado mais tarde com quatro valores: nome, ID do cliente, segredo do cliente e emissor. Os guias que indicam a instalação do Zitadel ou do Keycloak antes do NetBird descrevem uma configuração que já não é necessária. Segui-los obriga-o a manter um serviço adicional.

Por que todos os meus peers mostram Connection type: Relayed?

As ligações diretas não estão a ser estabelecidas. Por isso, o tráfego passa pelo relay na sua VPS. A causa habitual é o bloqueio do UDP 3478. Essa é a porta STUN usada pelos peers para descobrir o próprio endereço e porta públicos. Abra-a na firewall da VPS e na firewall de rede separada do seu provedor. Em seguida, execute netbird status --detail novamente e leia a linha Direct:. Numa rede cujo NAT atribui uma porta diferente para cada destino, relayed é o único resultado possível. Nesse caso, não há uma configuração incorreta.

O meu cliente ligou-se, mas o dashboard não mostra peers. O que aconteceu?

O cliente foi registado no serviço alojado do NetBird em vez de no seu servidor. Isto acontece quando --management-url é omitido. netbird status --detail mostra o servidor com o qual está a comunicar na linha Management:. Um valor como https://api.netbird.io:443 confirma essa situação. Execute sudo netbird down e depois sudo netbird up --management-url https://netbird.example.com. O peer deverá aparecer no seu dashboard.

Em que difere o NetBird alojado por si do Headscale?

Ambos substituem um servidor de controlo alojado por um servidor que gere por conta própria. O Headscale é apenas um plano de controlo. A gestão é feita com o comando headscale e um ficheiro de configuração. Não existe uma consola web oficial, e o Headscale controla os clientes oficiais do Tailscale. O NetBird fornece o seu próprio cliente, um dashboard de administração e integração com provedores de identidade na mesma stack. O Headscale é mais pequeno e mantém o estado em ficheiros. O NetBird é mais fácil de disponibilizar a pessoas que não utilizam um terminal.

Que tamanho de VPS é necessário para um servidor NetBird alojado por si?

O mínimo documentado é 1 CPU e 2 GB de memória. Por isso, 2 GB é o valor recomendado para a compra. O limite prático desceu para cerca de 1 GB nas versões recentes, porque o provedor de identidade está agora integrado em vez de ser uma instalação separada. Recuse os serviços opcionais de proxy e CrowdSec durante a instalação. Mantenha também o armazenamento SQLite predefinido até precisar efetivamente do PostgreSQL.