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 executa

O esquema mudou recentemente, e a maioria dos artigos mais antigos descreve o anterior. Verificado em outubro de 2026 com a v0.80.0 e com a v0.76.2, a versão fixada neste guia, o script de início rápido escreve, por predefinição, um ficheiro Compose com três serviços.

• netbird-server disponibiliza 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 versões mais antigas, estes componentes eram contentores separados, e o fornecedor de identidade era uma instalação separada 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 à Let's Encrypt no primeiro arranque.

Existem mais dois serviços, mas permanecem desativados a menos que responda afirmativamente a uma pergunta. O serviço NetBird Proxy publica serviços internos em nomes de anfitrião 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 troca, 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 é necessário antes de começar

Um nome de domínio público não é opcional. 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 do desafio TLS-ALPN-01, respondido na porta 443. Para isso, é necessário um nome que resolva para este VPS a partir da internet pública. Um endereço IP direto não funciona neste fluxo.

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

dig +short netbird.example.com

Esse comando deve mostrar o endereço do servidor. Se executar o instalador antes de o DNS propagar, o pedido de certificado falha no primeiro arranque. Validações falhadas repetidamente atingem os limites de taxa do Let's Encrypt. Nesse caso, terá de aguardar até o limite ser reposto antes de tentar novamente.

Três portas têm de estar acessíveis a partir da internet: TCP 80 para o redirecionamento para HTTPS; TCP 443 para o dashboard, a API, o tráfego de signal e relay e o desafio do certificado; 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 provedor. Na maioria dos painéis de VPS, esse é um controlo separado. É por isso que um servidor cuja própria ufw status parece correta ainda pode 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 seu próprio 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 passar diretamente entre os peers.

No lado do software, precisa de Docker com o plugin Compose v2, além de jq e curl. O script verifica o Docker, o Compose e jq e para se algum estiver em falta. Usa curl sem o verificar, por isso instale-o primeiro. Se o Docker for recente neste servidor, consulte primeiro Configurar o Docker Compose no VPS.

Instale o servidor NetBird com o script de início rápido

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, portanto o mesmo comando executado com duas semanas de diferença produz duas instalações diferentes, sem que nenhum ficheiro no disco registe 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 pede primeiro o 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 4 escrevem um fragmento de configuração e deixam o encaminhamento a seu cargo. A opção 5 escreve apenas o ficheiro Compose e apresenta a documentação de configuração no terminal. Isto é adequado num servidor que já executa um proxy, mas está errado num servidor novo. A opção 0 pede um endereço de email, que o Traefik regista na sua conta Let's Encrypt. O prompt ainda o identifica como um endereço para notificações de certificados, mas o Let's Encrypt deixou de enviar emails de expiração em June 4, 2025. Por isso, os problemas de renovação aparecem no log do Traefik e não na caixa de entrada.

Na primeira instalação, responda não ao serviço NetBird Proxy. Ele precisa de mais um registo DNS: um CNAME wildcard *.netbird.example.com apontado para netbird.example.com. Esse serviço não faz nada por uma mesh simples. O prompt do CrowdSec só aparece quando o proxy está ativado, portanto recusar o proxy também o ignora. Pode adicionar ambos mais tarde.

O script escreve no diretório atual: docker-compose.yml, config.yaml com modo 600 e dashboard.env. Com o Traefik incluído, também adiciona traefik-dynamic.yaml e proxy.env, mas apenas quando ativa o NetBird Proxy. Trate esse diretório como estado persistente, porque config.yaml contém a chave que cifra os dados no armazenamento. Perder esse ficheiro não é algo que uma reinstalação resolva.

docker compose ps
docker compose logs -f netbird-server

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

docker compose logs traefik | grep -i acme

ACME (automatic certificate management environment) é o protocolo que o Traefik usa para obter o certificado. Os erros aqui são quase sempre causados por DNS ou pela porta 443 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 setup key

O login pelo browser não funciona numa máquina sem browser e sem ninguém à sua frente. Uma setup key é um token de pré-autenticação que regista uma máquina sem a etapa interativa. Crie uma no dashboard, em Setup Keys.

Existem dois tipos. Uma chave de utilização única autentica exatamente uma máquina e é consumida depois. Uma chave reutilizável regista várias máquinas, com um limite opcional para a quantidade. Ambas têm uma data de expiração 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 dashboard. Sem esta opção, o peer usa o nome atribuído pela própria máquina. Uma frota de entradas com o nome ubuntu não ajuda ninguém.

Para contentores e build agents de curta duração, marque a chave como ephemeral ao criá-la. Os peers registados com uma chave ephemeral são removidos automaticamente depois de permanecerem offline durante mais de 10 minutos. Isto mantém as entradas inativas fora da lista de peers.

Antes de planear a utilização de setup keys, tenha em conta uma limitação: a expiração ou revogaçã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, remova 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: qual plano de controlo deve executar?

Ambos eliminam a mesma dependência: o servidor de controlo alojado para o qual os seus clientes comunicariam. Não são projetos com a mesma estrutura.

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 mantidas pela 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. Isto acrescenta mais componentes ao seu VPS e é muito mais fácil de delegar 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 as montar. Antes de escolher uma das opções, consulte o que o plano gratuito do Tailscale inclui efetivamente, porque um grupo não comercial que se mantenha dentro de seis utilizadores não paga nada por um plano de controlo alojado, com dispositivos de utilizador ilimitados e 50 recursos etiquetados desde o início, e pode não ter qualquer motivo para executar um plano próprio. 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 infraestrutura lhe exige.

Qual é o tamanho mínimo de VPS capaz de executar isto?

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

É seguro deixar três componentes de fora numa máquina pequena. 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. Ignore o CrowdSec, que o script só oferece juntamente com o proxy. É melhor adicioná-lo mais tarde a uma máquina exposta do que instalá-lo no primeiro dia. Mantenha o armazenamento SQLite predefinido no volume netbird_data e mude para PostgreSQL apenas quando separar a implementação por várias máquinas ou atingir problemas reais de concorrência. A documentação descreve essa migração como uma operação que pode ser feita mais tarde.

O relay é o único componente que não pode ser removido. Dois peers cujo 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. Existem duas causas. Ou dig +short netbird.example.com ainda não aponta para este VPS, ou a porta TCP 443 está fechada algures entre o Let's Encrypt e o contentor, normalmente na firewall de rede do fornecedor e não em ufw. O desafio é respondido na porta 443, por isso ter a porta 80 aberta não ajuda neste caso. Corrija a causa antes de repetir a tentativa num ciclo, porque o Let's Encrypt permite apenas cinco validações falhadas por nome de anfitrião por hora. Um ciclo impede novas tentativas até esse limite ser reposto.

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 formados túneis diretos, por isso 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 próprio endereço e a própria porta públicos. netbird status --detail também apresenta Direct: false e os tipos de candidatos ICE (interactive connectivity establishment) de cada peer, mostrando até onde chegou a tentativa. Em algumas redes, relayed é o único resultado disponível e não há qualquer problema.

Um peer entra na rede e não consegue aceder a 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 consegue aceder a nada. Verifique a política no dashboard antes de começar a depurar rotas e firewalls.

netbird status comunica 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, crie a primeira conta de administrador no navegador em https://netbird.example.com e adicione os utilizadores no dashboard depois. 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 implementar o Zitadel ou o Keycloak antes do NetBird descrevem uma configuração que já não é necessária. Segui-los obriga-o a manter mais um serviço.

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 no seu VPS. A causa habitual é o bloqueio do UDP 3478. Essa é a porta STUN que os peers usam para descobrir o próprio endereço e porta públicos. Abra-a na firewall do VPS e na firewall de rede separada do provedor. Depois, 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 registou-se no serviço alojado do NetBird em vez de se registar no seu servidor. Isto acontece quando --management-url fica 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 esse problema. Execute sudo netbird down e depois sudo netbird up --management-url https://netbird.example.com. O peer aparecerá no seu dashboard.

Qual é a diferença entre o NetBird alojado pelo próprio utilizador e o Headscale?

Ambos substituem um servidor de controlo alojado por um servidor que você executa. O Headscale fornece apenas o plano de controlo. É gerido com o comando headscale e um ficheiro de configuração. Não existe uma consola Web oficial, e ele 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 de executar e mantém o estado em ficheiros. O NetBird é mais fácil de entregar a pessoas que não usam um terminal.

Que tamanho de VPS é necessário para um servidor NetBird alojado pelo próprio utilizador?

O mínimo documentado é 1 CPU e 2 GB de memória. 2 GB é o valor que deve contratar. O limite prático baixou para cerca de 1 GB nas versões recentes, porque o provedor de identidade está agora integrado em vez de ser uma implementação separada. Recuse o serviço de proxy opcional durante a instalação. Isto também ignora o pedido relativo ao CrowdSec. Mantenha o armazenamento SQLite predefinido até precisar efetivamente do PostgreSQL.