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 você 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 usando o desafio TLS-ALPN-01, respondido na porta 443. Esse processo precisa de um nome que resolva para este VPS na internet pública. Um endereço IP simples não funciona nesse fluxo.

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

dig +short netbird.example.com

Esse comando deve exibir o endereço do seu servidor. Executar o instalador antes da propagação do DNS faz a solicitação do certificado falhar na primeira inicialização. Validações repetidamente malsucedidas atingem os limites de requisições do Let's Encrypt. Nesse caso, você precisa aguardar a liberação do limite antes de tentar novamente.

Três portas precisam estar acessíveis pela internet: TCP 80 para o redirecionamento para HTTPS, TCP 443 para o dashboard, a API, o tráfego de sinalização 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 essas portas também no firewall de rede do seu provedor. Na maioria dos painéis de VPS, esse é um controle separado. Por isso, um servidor cujo ufw status próprio parece correto ainda pode recusar conexões.

STUN (session traversal utilities for NAT) permite que um peer descubra o endereço público e a porta atribuídos pelo próprio NAT. Assim, dois peers podem tentar estabelecer um túnel direto. Se você bloquear UDP 3478, os peers ainda se conectarão pelo relay em TCP 443, e nada parecerá quebrado. Peers que não conseguem encontrar um caminho direto exibem Connection type: Relayed, e o tráfego passa pelo seu VPS em vez de ir diretamente de um peer para outro. Peers na mesma LAN ainda podem se conectar diretamente usando seus endereços locais.

No software, você precisa do 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 deles estiver ausente. Ele usa curl sem verificar se está instalado, portanto instale-o primeiro. Se o Docker for novo neste servidor, consulte primeiro Como fazer o Docker Compose funcionar 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, por isso o mesmo comando executado com duas semanas de intervalo produz duas instalações diferentes, e nada no disco regista qual delas escreveu a sua configuração. Descarregue uma versão identificada, leia-a e execute-a 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á tratado:

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, enquanto a opção 5 escreve o ficheiro Compose, dashboard.env e config.yaml e apresenta a documentação de configuração no terminal. Isto está correto num servidor que já executa um proxy e está errado num servidor novo. A opção 0 pede depois um endereço de email, que Traefik regista na sua conta Let's Encrypt. A mensagem continua a chamá-lo de endereço para notificações de certificados, mas 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 sua caixa de entrada.

Responda não ao serviço NetBird Proxy na primeira instalação. Ele requer mais um registo DNS, um CNAME wildcard *.netbird.example.com que aponte para netbird.example.com, e não faz nada por uma mesh simples. A pergunta sobre CrowdSec só aparece quando o proxy está ativado, por isso recusar o proxy também a ignora. Ambos podem ser adicionados mais tarde.

O script escreve no diretório atual: docker-compose.yml, config.yaml com o modo 600 e dashboard.env. Com o Traefik incluído, adiciona traefik-dynamic.yaml e proxy.env apenas quando ativa o NetBird Proxy. Trate esse diretório como estado que deve preservar, porque config.yaml contém a chave que encripta os dados no armazenamento. Perdê-lo 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 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 disponibiliza o produto completo: o seu próprio cliente, o seu próprio dashboard, um provedor de identidade integrado e políticas de acesso editadas no navegador. Isso acrescenta mais componentes ao seu VPS e é muito mais fácil de delegar a um colega que nunca vai abrir um terminal. Se estiver realmente a comparar o NetBird com o Tailscale alojado, em vez de o comparar com o Headscale, ambos usam WireGuard internamente. Por isso, a comparação entre NetBird e Tailscale explica onde diferem na prática: quem gere o plano de controlo, como as regras de acesso são escritas e como os relays transportam o tráfego.

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.

Quantos recursos mínimos uma VPS precisa para executar isso?

O mínimo documentado é 1 CPU e 2 GB de memória. Compre 2 GB.

Três itens podem ser deixados de fora com segurança em um 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 conexão entre peers. Ignore o CrowdSec, que o script oferece apenas junto com o proxy e que vale a pena adicionar mais tarde a um servidor exposto, em vez de instalá-lo no primeiro dia. Mantenha o armazenamento SQLite padrão no volume netbird_data e migre para PostgreSQL somente quando distribuir a implantação entre várias máquinas ou enfrentar concorrência real. Essa migração está documentada e pode ser feita depois.

O relay é o único componente que não pode ser removido. Dois peers cujo NAT atribui uma porta diferente para cada destino nunca estabelecerão um túnel direto. Portanto, o relay é o único caminho que permite que eles funcionem. Desativá-lo economiza muito pouca memória e interrompe conexões de uma forma difícil de diagnosticar.

Quando um único servidor deixa de ser suficiente, os relays são os primeiros componentes a mover para fora dele. Um relay independente é executado com NB_LISTEN_ADDRESS, NB_EXPOSED_ADDRESS, NB_AUTH_SECRET e NB_ENABLE_STUN. O segredo compartilhado deve ser idêntico no relay e no servidor principal. Caso contrário, os clientes não conseguem se autenticar nele.

Modos de falha e o que você verá

O painel 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 retorna este VPS, ou a porta TCP 443 está fechada em algum ponto entre o Let's Encrypt e o contêiner, geralmente no firewall de rede do provedor, e não no ufw. O desafio é respondido na porta 443, portanto uma porta 80 aberta não ajuda nesse caso. Corrija a causa antes de tentar novamente em um loop, porque o Let's Encrypt permite apenas cinco autorizações com falha por hostname, por conta e por hora. Um loop bloqueia novas tentativas até que esse limite seja restaurado.

O cliente informa que se conectou, mas o painel está vazio. O cliente se registrou no serviço hospedado do NetBird porque --management-url estava ausente. Execute netbird status --detail e leia a linha Management:, que informa com qual servidor ele está realmente se comunicando. Ver Management: Connected to https://api.netbird.io:443 significa que ele acessou a nuvem. Execute sudo netbird down e depois sudo netbird up --management-url https://netbird.example.com novamente.

Todos os peers mostram Connection type: Relayed. Nenhum túnel direto está sendo formado, portanto todo o tráfego atravessa seu VPS e acrescenta um salto de latência. Verifique o UDP 3478 no firewall do VPS e no firewall do provedor, pois o STUN permite que um peer descubra o próprio endereço público e a própria porta. netbird status --detail também imprime Direct: false e os tipos de candidatos ICE (interactive connectivity establishment) de cada peer, mostrando até onde a tentativa avançou. Em algumas redes, relayed é o único resultado disponível, e não há nenhum problema.

Um peer entra na rede e não consegue acessar nada. Estar na mesh não significa que dois peers possam se 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 painel antes de começar a depurar rotas e firewalls.

netbird status informa 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 você não consiga identificar, netbird debug bundle --anonymize --system-info reúne logs, status, rotas, configurações de DNS e estado do firewall em um ú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 hospedar o NetBird?

Não. As versões atuais incluem um armazenamento de usuários integrado. Assim, você cria a primeira conta de administrador no navegador em https://netbird.example.com e depois adiciona usuários pelo painel. Um provedor OIDC externo é opcional e pode ser adicionado posteriormente com quatro valores: nome, ID do cliente, segredo do cliente e emissor. Os guias que orientam você a implantar o Zitadel ou o Keycloak antes do NetBird descrevem uma configuração que não é mais necessária. Segui-los obriga você a manter um serviço adicional.

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

As conexões diretas não estão sendo estabelecidas. Por isso, o tráfego passa pelo relay na sua VPS. A causa mais comum é o bloqueio da porta UDP 3478. Essa é a porta STUN usada pelos peers para descobrir o próprio endereço e a própria porta pública. Libere-a no firewall da VPS e no firewall de rede separado do seu provedor. Depois, execute netbird status --detail novamente e leia a linha Direct:. Quando os dois peers estão atrás de NAT que atribui uma porta diferente para cada destino, relayed é o resultado esperado. Nesse caso, não há erro de configuração.

Meu cliente se conectou, mas o painel não mostra nenhum peer. O que aconteceu?

O cliente foi registrado no serviço hospedado do NetBird, e não no seu servidor. Isso acontece quando --management-url não é informado. netbird status --detail exibe o servidor com o qual o cliente está se comunicando na linha Management:. Um valor como https://api.netbird.io:443 confirma isso. Execute sudo netbird down e depois sudo netbird up --management-url https://netbird.example.com. O peer aparecerá no seu painel.

Qual é a diferença entre o NetBird hospedado localmente e o Headscale?

Ambos substituem um servidor de controle hospedado por um servidor que você executa. O Headscale é apenas um plano de controle. Você o gerencia com o comando headscale e um arquivo de configuração. Não existe um console web oficial, e ele usa os clientes oficiais do Tailscale. O NetBird inclui o próprio cliente, um painel de administração e a integração com provedores de identidade na mesma pilha. O Headscale é menor para executar e mantém o estado em arquivos. O NetBird é mais fácil de entregar a pessoas que não usarão um terminal.

Qual deve ser o tamanho da VPS para um servidor NetBird hospedado localmente?

O mínimo documentado é 1 CPU e 2 GB de memória. Portanto, 2 GB é o valor que você deve contratar. Recuse o serviço de proxy opcional durante a instalação. Isso também ignora o prompt do CrowdSec. Mantenha o armazenamento SQLite padrão até que você realmente precise do PostgreSQL.