NetBird: VPN Mesh Self-Hosted com WireGuard para PME

Uma equipa em teletrabalho, dois servidores no escritório e uma impressora que só aceita ligações da rede interna. A VPN clássica resolve o problema com um concentrador: todo o tráfego remoto entra por um único servidor VPN e sai para a rede local. O caminho entre dois dispositivos da mesma organização passa sempre por esse servidor, com a largura de banda e o ponto de falha concentrados no mesmo sítio.

O NetBird segue a lógica oposta. Cada dispositivo com o cliente instalado — um peer — estabelece túneis WireGuard directamente com os outros, sem os dados passarem por um servidor central. O servidor central, o control-plane, só decide quem pode falar com quem e distribui as chaves. A diferença para o Tailscale está no controlo: o NetBird é open-source e o control-plane pode ficar num VPS da PME, com o dashboard, o serviço de gestão e o serviço de sinal a correr em Docker.

Este guia percorre a instalação self-hosted com o script quickstart oficial, liga o primeiro cliente, cria políticas de acesso por grupos, publica a rede interna através de uma rota e liga o SSO com Entra ID. O servidor precisa de pouco: uma máquina Linux com 2 GB de RAM, Docker e um nome de domínio público.

Neste artigo

1. O que é o NetBird e como funciona
2. Requisitos para o servidor self-hosted
3. Instalar o servidor com o script quickstart
4. Primeiro cliente e verificação com o CLI
5. Chaves de setup para servidores headless
6. Políticas de acesso por grupos (ACLs)
7. Rotas de rede para aceder à LAN interna
8. SSO com Entra ID
9. NetBird vs Tailscale vs Headscale
10. Erros Comuns
11. Checklist

1. O que é o NetBird e como funciona

Quatro serviços compõem o lado do servidor, todos dentro do mesmo container na instalação actual. O Management guarda a configuração da rede e entrega a cada peer apenas a lista de pares com que tem permissão para comunicar. O Signal coordena o estabelecimento das ligações entre pares. O Relay reencaminha o tráfego quando dois pares não conseguem ligar-se directamente, por exemplo atrás de um NAT restritivo do operador, e inclui um servidor STUN embutido que ajuda os pares a descobrir o caminho uns para os outros. O Dashboard é a interface web de administração.

O tráfego entre dois peers é cifrado ponto-a-ponto com WireGuard. O servidor entrega as credenciais e o mapa da rede, mas não descodifica os dados que circulam entre os dispositivos. Numa VPN clássica de acesso remoto, todo o tráfego passa pelo servidor. Na rede mesh, o caminho mais curto entre dois pontos é o túnel directo entre eles.

Na prática, uma PME usa o NetBird para três cenários: acesso remoto dos colaboradores aos servidores sem abrir portas no firewall, ligações site-to-site entre filiais e segmentação por equipas com políticas granulares. As políticas também aceitam posture checks, que condicionam a ligação ao estado de segurança do dispositivo.

2. Requisitos para o servidor self-hosted

A documentação oficial pede uma máquina virtual Linux com pelo menos 1 vCPU e 2 GB de memória, acessível da Internet nas portas TCP 80 e 443 e na UDP 3478. Qualquer VPS com IP público serve — Hetzner, DigitalOcean, AWS, Google Cloud ou Azure — e o servidor não precisa de estar dentro da rede da PME.

No software: Docker com o plugin docker compose, os utilitários jq e curl, e um nome de domínio público — por exemplo netbird.empresa.pt — a apontar para o IP do servidor, porque os certificados TLS são emitidos por Let’s Encrypt e a validação passa pelo domínio.

A porta 443 concentra quase tudo: desde a versão 0.29, os serviços de gestão e de sinal partilham as portas através de negociação HTTP/2, o que reduz o número de portas a abrir na firewall do VPS.

3. Instalar o servidor com o script quickstart

Num servidor Ubuntu limpo, comece pelo Docker e pelos dois utilitários:

curl -fsSL https://get.docker.com | sudo bash
sudo apt install -y jq curl

Depois descarregue e execute o script de instalação oficial do projecto:

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

O script prepara os ficheiros do Docker Compose e faz duas perguntas. A primeira escolhe o reverse proxy que trata dos certificados:

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)
  ...
Enter choice [0-5] (default: 0):

A opção 0, que é o valor por omissão, inclui um container Traefik no Docker Compose que emite e renova os certificados Let’s Encrypt automaticamente. Só faz sentido escolher outra opção se a PME já tiver um reverse proxy a tratar do mesmo domínio. A segunda pergunta é sobre o NetBird Proxy, um serviço que expõe recursos internos na Internet sob controlo do dashboard:

Do you want to enable the NetBird Proxy service?
...
Enable proxy? [y/N]:

Para começar, responda N, que é a omissão — o serviço activa-se mais tarde. No fim, o script apresenta o URL do dashboard e cria um utilizador administrador. Abra o endereço no browser e inicie sessão com essa conta.

Na instalação actual, os serviços correm num único container netbird-server, configurado por um ficheiro config.yaml. A gestão do dia a dia faz-se com docker compose na pasta criada pelo script — docker compose ps lista os containers e o estado de cada um.

4. Primeiro cliente e verificação com o CLI

O dashboard não substitui o cliente: cada dispositivo que entra na rede precisa do cliente NetBird instalado, disponível para Windows, macOS, Linux, iOS e Android.

No Windows, a opção Connect no ícone da área de notificação abre o browser para autorizar o dispositivo. Em Linux, o mesmo efeito obtém-se com um comando:

sudo netbird up

O comando abre a autenticação no browser e, concluído o início de sessão, o terminal confirma a ligação. Para ver o estado dos serviços e a lista de pares visíveis:

netbird status

A partir de outro peer já ligado, teste a comunicação com um ping para o endereço IP da rede NetBird atribuído ao novo cliente. Sem alterações, a política Default criada na instalação permite a comunicação entre todos os dispositivos e o ping responde. Desactivar essa política no dashboard faz o ping falhar de imediato — a demonstração mais simples de que o controlo de acesso se aplica de imediato.

5. Chaves de setup para servidores headless

Nem toda a máquina tem browser: um NAS, um router ou um servidor de backup registam-se com uma setup key, um token que autoriza a entrada do dispositivo sem interacção. As chaves criam-se no dashboard, na secção Peers, e podem limitar o número de utilizações.

Uma setup key pode ainda atribuir automaticamente o novo peer a um grupo, o que poupa o passo manual de classificação: a nova máquina aparece desde logo na página de detalhes do grupo em causa. No servidor headless, depois de instalar o cliente:

sudo netbird up --setup-key 

O terminal confirma a ligação e o dispositivo aparece no dashboard já dentro do grupo atribuído pela chave, o que torna o método ideal para registar máquinas em lote ou dispositivos efémeros.

6. Políticas de acesso por grupos (ACLs)

Por omissão, a política Default permite a todos os peers comunicar entre si por qualquer protocolo — uma mesh completa. Serve para validar a instalação mas não é o estado a manter numa PME. O modelo de controlo assenta em dois conceitos: grupos, que reúnem peers, e políticas, que declaram que grupos podem comunicar com quais, por que protocolos e portas.

Crie os grupos em Access Control > Groups — por exemplo Contabilidade e Servidores-Ficheiros — e atribua cada peer no painel Peers, no campo Assigned Groups. Depois crie a política em Access Control > Policies: grupos de origem e destino, protocolo, portas e direcção. Desde a versão 0.48, as políticas aceitam intervalos de portas no formato 8000-9000.

A direcção importa: uma política bidirecional deixa qualquer um dos dois grupos iniciar a ligação, enquanto uma unidirecional só permite iniciar ao grupo de origem — o padrão Zero Trust para dar a clientes acesso a servidores sem caminho de regresso. Um exemplo para a contabilidade aceder ao servidor de ficheiros apenas por SMB:

Enquanto a política Default existir, as políticas novas não têm efeito prático — o NetBird processa apenas políticas de permissão, sem ordem de prioridade. Depois de criar e testar as políticas novas, elimine a Default para o tráfego ficar restrito ao que elas declaram. As políticas também aceitam posture checks — por exemplo, exigir antivírus ou firewall activa antes de permitir a ligação.

7. Rotas de rede para aceder à LAN interna

Há dispositivos que não podem correr o cliente — uma impressora, uma câmara IP, um servidor antigo. A solução é um routing peer: uma máquina dentro da rede local que encaminha o tráfego entre a mesh e a LAN.

No dashboard, crie o recurso de rede com a opção Entire Subnet e indique a gama CIDR da rede interna — por exemplo 192.168.1.0/24. A criação do recurso gera automaticamente uma política, Users to My Subnet, que dá a todos os utilizadores autenticados acesso ao recurso. Antes de considerar o acesso pronto para produção, restrinja essa política ao grupo que realmente precisa dele.

O routing peer propaga a rota aos clientes. Para testar, ligue-se a partir de uma rede diferente — o ponto de acesso do telemóvel serve perfeitamente — e faça ping a um endereço interno da gama anunciada. Se a resposta chegar, o tráfego está a passar pelo routing peer e a política está activa. O mesmo mecanismo cobre o cenário site-to-site entre duas redes: um routing peer por localização, cada um a anunciar a sua gama.

8. SSO com Entra ID

A instalação quickstart usa um fornecedor de identidade incorporado, o caminho mais rápido para começar. Quando a PME já tem um IdP — Okta, Entra ID (Azure AD), Google Workspace ou outro fornecedor compatível com OIDC — o guia avançado de self-hosting documenta a integração manual, incluindo a sincronização SCIM de utilizadores e grupos, disponível na edição Enterprise.

Com o IdP externo, o início de sessão nos clientes passa a fazer-se com a conta institucional, as políticas de MFA aplicam-se pelo próprio IdP e pode exigir-se reautenticação periódica. Os grupos sincronizados do IdP aparecem no NetBird e usam-se nas políticas como quaisquer outros, mas não podem ser renomeados nem eliminados no dashboard — a gestão da adesão faz-se no IdP, e o NetBird reflecte-a.

A separação de conceitos importa: as setup keys registam máquinas, o SSO autentica pessoas, e ambos os tipos de entrada ficam sujeitos às mesmas políticas por grupos.

9. NetBird vs Tailscale vs Headscale

Para a PME que quer o control-plane dentro de portas próprias, com SSO e dashboard, o NetBird cobre as três camadas com um único script. O Tailscale é a via mais rápida, mas as contas, políticas e auditoria vivem na plataforma cloud. O Headscale elimina essa dependência, mas não inclui interface gráfica nem fornecedor de identidade, empurrando a gestão para a linha de comandos.

Erros Comuns

Os grupos sincronizados de um IdP não são editáveis no dashboard — a adesão dos utilizadores gere-se no IdP.

Checklist

• [ ] VPS com IP público e pelo menos 2 GB de RAM
• [ ] Docker com o plugin docker compose instalado
• [ ] jq e curl instalados
• [ ] Domínio com registo A para o IP do VPS
• [ ] Portas 80 e 443 TCP abertas na firewall
• [ ] Porta 3478/UDP aberta na firewall
• [ ] Script quickstart executado e dashboard acessível
• [ ] Primeiro cliente ligado e visível no dashboard
• [ ] Política Default substituída por políticas por grupos
• [ ] Rota de rede testada a partir de outra rede (telemóvel ou hotspot)
• [ ] SSO ligado ao IdP da PME, com setup keys para as máquinas headless

Artigos Relacionados

• Tailscale na PME: Rede Mesh como Alternativa à VPN Clássica
• Headscale: Tailscale Self-Hosted para PME sem Dependência Cloud
• WireGuard em 2026: VPN Leve e Rápida no Kernel Linux para PME
• Tailscale vs WireGuard vs OpenVPN: Qual a Melhor VPN para PME em 2026?

Fontes Oficiais

• NetBird — site oficial: https://netbird.io/
• Self-Hosting Quickstart Guide: https://docs.netbird.io/selfhosted/selfhosted-quickstart
• Advanced self-hosting guide: https://docs.netbird.io/selfhosted/selfhosted-guide
• Groups and Access Policies: https://docs.netbird.io/manage/access-control/manage-network-access
• Repositório GitHub: https://github.com/netbirdio/netbird