Como hospedar o servidor VPN NetBird em uma VPS

O que a hospedagem própria do servidor VPN NetBird oferece

Hospedar o servidor VPN NetBird por conta própria coloca o plano de controlo numa VPS que você possui: a parte que mantém a lista de peers, decide qual máquina pode alcançar qual outra e ajuda dois peers a encontrarem-se atrás de NAT (tradução de endereços de rede). Os próprios 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 o fluxo de início de sessão.

O NetBird combina dois conceitos que talvez já conheça. É uma sobreposição em malha, por isso os peers ligam-se uns aos outros em vez de enviarem tudo através de um único gateway. Também pode ser hospedado por conta própria de ponta a ponta, o que o coloca em alternativa ao Headscale, o servidor de controlo Tailscale hospedado por conta própria. Se só executou um túnel com um único gateway, leia primeiro a diferença entre o WireGuard simples e uma sobreposição em malha, porque é esse modelo mental que torna o restante desta página útil.

Se o que realmente pretende é um único servidor através do qual saia todo o seu tráfego, uma malha fornece mais componentes do que essa tarefa exige. Uma VPN WireGuard simples numa única VPS ou um nó de saída Tailscale fazem isso com muito menos componentes em execução.

O que a stack realmente executa

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

• netbird-server inclui a API de gestão, o serviço de sinalização, o relay com um listener STUN incorporado e um fornecedor de identidade incorporado. 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 (segurança da camada de transporte) e solicita um certificado à Let's Encrypt no primeiro arranque.

Existem mais dois serviços, que permanecem desligados, a menos que responda afirmativamente a uma pergunta. 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 do número de componentes. Em contrapartida, obtém políticas de acesso, contas por utilizador e 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 não é opcional. O dashboard, a API e o relay usam HTTPS na porta 443, e o Traefik obtém o seu certificado do Let's Encrypt através de um desafio HTTP. Esse desafio precisa de um nome que resolva para este VPS a partir da Internet pública. Um endereço IP simples 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 apresentar o endereço do servidor. Executar o instalador antes de o DNS propagar faz o pedido do certificado falhar no primeiro arranque. Validações falhadas repetidamente atingem os limites de taxa do Let's Encrypt, e 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, um servidor cujo ufw status local parece correto 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, por isso nada parece estar avariado. Em vez disso, verá Connection type: Relayed em todos os peers, e todo o tráfego atravessará o VPS em vez de passar 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 foi instalado recentemente neste servidor, consulte primeiro Configurar o Docker Compose no VPS.

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

O comando de uma linha documentado envia diretamente a versão mais recente 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 registar no disco qual delas escreveu a configuração. Transfira uma versão identificada por uma tag, 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 5 escrevem um trecho de configuração e deixam o encaminhamento a seu cargo. Isto é correto num servidor que já executa um proxy, mas está errado num servidor novo. A opção 0 pede depois um endereço de email para o Let's Encrypt, usado para avisos de expiração.

Na primeira instalação, responda não ao serviço NetBird Proxy. Ele requer mais dois registos DNS, proxy.netbird.example.com e o wildcard *.proxy.netbird.example.com, e não faz nada para uma 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 o 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. Uma reinstalação 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 (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 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 e, 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 próprio repositório de utilizadores do NetBird, fornecido por um fornecedor de identidade incorporado no contentor netbird-server. Não há qualquer componente externo envolvido. Esta é a maior alteração em relação ao NetBird autoalojado de há um ano, quando uma instalação funcional exigia primeiro configurar o Zitadel ou o Keycloak e copiar quatro valores OIDC (OpenID Connect) para setup.env antes de qualquer componente conseguir 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 esse problema antes de continuar, porque o dashboard comunica com a API através do mesmo nome de anfitrião e pode falhar de formas difíceis de diagnosticar quando o certificado é inválido.

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. Em ambos os casos, o gestor de pacotes passa a gerir o pacote. 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 caso, 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 sem interface gráfica 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 autoalojado continuará vazio. Isto apanha quase toda a gente pelo menos uma vez.

O comando apresenta um URL para abrir num browser e concluir o login. Depois disso:

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 uma linha NetBird IP: no intervalo da rede overlay. 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 utilização única autentica exatamente uma máquina e é consumida depois disso. 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, fazendo com 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 essa opção, o peer usa o nome atribuído pela própria máquina, e uma frota de entradas com o nome ubuntu não é útil.

Para contentores e agentes de compilação 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, mantendo as entradas inativas fora da lista de peers.

Tenha em conta uma limitação antes de basear o planeamento nas 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, remova esse peer.

Ainda precisa de um fornecedor de identidade separado?

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

Precisa de um fornecedor de identidade externo quando já utiliza um e não quer manter uma segunda lista de utilizadores. O NetBird aceita qualquer fornecedor compatível com OIDC. Registe um cliente OIDC confidencial no seu fornecedor 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 fornecedor. Existem integrações específicas para Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik e Pocket ID. Qualquer outro fornecedor pode ser configurado como OIDC genérico. Se já utiliza o Authentik como solução de single sign-on autoalojada, esta é a opção que mantém uma única lista de contas em vez de duas.

O início de sessão local continua disponível depois de adicionar um fornecedor, e todos os fornecedores 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 ficar incorreta, continuará a ter uma forma de aceder ao sistema.

NetBird ou Headscale: que plano de controlo deve executar?

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

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 os utilizadores e as chaves de pré-autenticação com o comando headscale contra 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 controlar as alterações com um sistema de 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, mas exige muito menos 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.

Qual o menor VPS capaz de 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, em comparação com os 2 GB a 4 GB necessários no esquema antigo, quando uma implementação completa do Zitadel fazia parte da stack. Escolha 2 GB. Essa margem adicional permite que uma atualização transfira novas imagens enquanto as antigas ainda estão no disco.

Há três componentes que pode deixar de fora com segurança num servidor pequeno. Recuse o serviço NetBird Proxy, que existe 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 vale a pena 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 distribuir a implementação por várias máquinas ou atingir 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 remover. Dois peers cuja NAT atribua 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 deixar de ser suficiente, os relays são os primeiros componentes a mover para fora dela. 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 possíveis. Ou dig +short netbird.example.com ainda não aponta para este VPS, ou a porta TCP 80 está fechada em algum ponto entre o Let's Encrypt e o contentor, normalmente na firewall de rede do provedor e não em ufw. Corrija a causa antes de repetir a tentativa num ciclo, porque as validações falhadas estão sujeitas a limites de frequência e ficará impedido de fazer novas tentativas durante uma hora.

O cliente informa 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á realmente a comunicar. Se aparecer Management: Connected to https://api.netbird.io:443, significa que o cliente se ligou à cloud. Execute sudo netbird down e, em seguida, 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, portanto todo o tráfego atravessa o VPS e acrescenta um salto de latência. Verifique a porta UDP 3478 na firewall do VPS e na firewall do provedor, porque o STUN permite que um peer descubra o seu próprio endereço e 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é que ponto a tentativa avançou. 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 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 atualizações

A instalação depende de dois elementos: 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 cópias de segurança 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 nome 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 o comando docker run acima falha ao criar silenciosamente um volume vazio e não arquiva nada. Mantenha os arquivos fora do VPS. Se já utiliza uma ferramenta de cópias de segurança, restic ou BorgBackup trata da parte externa ao servidor.

A atualização do servidor consiste em descarregar a 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 pelo qual fixou o script de instalação: precisa de saber o que está em execução e de ter uma versão para a qual possa voltar se a atualização causar problemas. Os clientes são atualizados através do 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, pode criar a primeira conta de administrador no navegador em https://netbird.example.com e adicionar 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 é a porta UDP 3478 estar bloqueada. 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 a 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 que o cliente comunica 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 o próprio administrador executa. O Headscale fornece apenas o plano de controlo. É gerido com o comando headscale e um ficheiro de configuração, não tem uma consola Web oficial e 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 disponibilizar a pessoas que não usam um terminal.

De que tamanho precisa o VPS de um servidor NetBird alojado por si?

O mínimo documentado é 1 CPU e 2 GB de memória. Portanto, deve adquirir 2 GB. 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 implementação separada. Durante a instalação, recuse os serviços opcionais de proxy e CrowdSec. Mantenha o armazenamento SQLite predefinido até precisar efetivamente do PostgreSQL.