NetBird es una VPN mesh basada en WireGuard: cada equipo (peer) se conecta directamente con los demás y un servidor de gestión central reparte las claves, las IPs y las reglas de acceso. En este tutorial desplegarás el servidor de gestión self-hosted de NetBird con Docker en Ubuntu 24.04, conectarás dos peers Linux mediante setup keys y sustituirás la política por defecto por reglas que solo permitan el tráfico que necesitas.
Requisitos previos
Para seguir esta guía necesitas:
- Un servidor con Ubuntu 24.04 LTS y una IP pública para el servidor de gestión, por ejemplo un VPS de CubePath, con al menos 1 vCPU y 2 GB de RAM.
- Un usuario no root con privilegios
sudo. - Docker Engine y el plugin Docker Compose instalados en ese servidor.
- Un dominio o subdominio (en esta guía,
your_domain) con un registro DNS A apuntando a la IP del servidor. El instalador obtiene el certificado TLS de Let's Encrypt, así que el DNS debe resolver antes de empezar. - Al menos un segundo equipo Linux que vaya a unirse a la red como peer.
Comprueba que el dominio resuelve a la IP del servidor:
dig +short your_domain
203.0.113.10
Paso 1: Abrir los puertos necesarios
El servidor de gestión necesita HTTP y HTTPS para el panel, la API y la emisión del certificado, el puerto UDP 3478 para STUN/TURN y el rango UDP 49152-65535 para los relés TURN que usan los peers que no pueden conectar de forma directa. Si usas UFW, permite SSH primero para no perder el acceso:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp
sudo ufw allow 49152:65535/udp
sudo ufw enable
Verifica las reglas:
sudo ufw status
Status: active
To Action From
-- ------ ----
OpenSSH ALLOW Anywhere
80/tcp ALLOW Anywhere
443/tcp ALLOW Anywhere
3478/udp ALLOW Anywhere
49152:65535/udp ALLOW Anywhere
...
Notasi el servidor tiene además un firewall externo (grupo de seguridad o firewall del proveedor), abre ahí los mismos puertos.
Paso 2: Desplegar el servidor de gestión
NetBird publica un script de inicio rápido que genera la configuración, el archivo docker-compose.yml y las credenciales, y arranca todos los componentes: el servicio de gestión, el servidor de señalización, el relé, el servidor TURN (coturn), el panel web y Zitadel como proveedor de identidad. El script necesita curl y jq:
sudo apt update
sudo apt install curl jq
Crea un directorio para el despliegue, ya que el script escribe sus archivos en el directorio actual:
sudo mkdir -p /opt/netbird
sudo chown "$USER": /opt/netbird
cd /opt/netbird
Descarga el script y revísalo antes de ejecutarlo:
curl -fsSL -o getting-started-with-zitadel.sh https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh
less getting-started-with-zitadel.sh
Ejecútalo indicando tu dominio en la variable NETBIRD_DOMAIN. Si tu usuario no pertenece al grupo docker, ejecútalo con sudo -E para que conserve la variable:
export NETBIRD_DOMAIN=your_domain
bash getting-started-with-zitadel.sh
El despliegue tarda unos minutos. Al terminar, el script muestra la URL del panel y el usuario y la contraseña iniciales del administrador:
You can access the NetBird dashboard at https://your_domain
Username: admin@your_domain
Password: ...
Guarda esas credenciales en un gestor de contraseñas: se muestran una sola vez y el primer inicio de sesión te pedirá cambiar la contraseña.
Comprueba que todos los contenedores están en marcha:
docker compose ps
Todos los servicios deben aparecer con estado running (o Up). Si alguno se reinicia en bucle, revisa sus logs con docker compose logs nombre_del_servicio.
Paso 3: Acceder al panel y crear una setup key
Abre https://your_domain en el navegador e inicia sesión con las credenciales del paso anterior. Cambia la contraseña cuando se te pida.
Una setup key permite registrar un peer sin abrir un navegador en él, que es lo habitual en servidores. Para crear una:
- Ve a Setup Keys y pulsa Create Setup Key.
- Ponle un nombre descriptivo, por ejemplo
servidores. - Deja desactivada la opción de clave reutilizable si solo vas a registrar un equipo: una clave de un solo uso es más segura. Actívala si vas a usarla en varios servidores o en automatizaciones.
- Fija una caducidad corta y, en Auto-assigned groups, crea o elige el grupo
servidores. Todos los peers que se registren con esta clave entrarán en ese grupo. - Copia la clave generada. No podrás volver a verla.
Paso 4: Instalar el cliente de NetBird en un peer
Ejecuta este paso en cada equipo Linux que vaya a unirse a la red, incluido, si quieres, el propio servidor de gestión.
Instala las dependencias y añade la clave del repositorio oficial de NetBird:
sudo apt update
sudo apt install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://pkgs.netbird.io/debian/public.key | sudo gpg --dearmor -o /etc/apt/keyrings/netbird.gpg
Añade el repositorio e instala el paquete:
echo 'deb [signed-by=/etc/apt/keyrings/netbird.gpg] https://pkgs.netbird.io/debian stable main' | sudo tee /etc/apt/sources.list.d/netbird.list
sudo apt update
sudo apt install netbird
Verifica la instalación:
netbird version
El comando devuelve el número de versión del cliente instalado.
Paso 5: Conectar el peer a tu servidor
Registra el peer apuntando a tu servidor de gestión con la opción --management-url y la setup key del paso 3 (sustituye your_setup_key):
sudo netbird up --management-url https://your_domain --setup-key your_setup_key
Connected
Comprueba el estado de la conexión:
netbird status
Daemon version: ...
CLI version: ...
Management: Connected
Signal: Connected
Relays: 2/2 Available
Nameservers: 0/0 Available
FQDN: peer1.netbird.selfhosted
NetBird IP: 100.92.14.3/16
Interface type: Kernel
Peers count: 0/0 Connected
Management y Signal deben aparecer como Connected. El cliente crea la interfaz wt0 con una IP del rango 100.64.0.0/10:
ip -brief address show wt0
wt0 UNKNOWN 100.92.14.3/16
Repite los pasos 4 y 5 en un segundo equipo. Después, desde el primer peer, lista los peers conocidos y haz ping a la IP NetBird del segundo:
netbird status --detail
ping -c 3 100.92.200.41
En la salida de netbird status --detail, el campo Connection type indica P2P cuando los peers hablan directamente y Relayed cuando el tráfico pasa por el relé. Los dos peers también aparecen ahora en la sección Peers del panel.
Paso 6: Restringir el tráfico con políticas de acceso
Una instalación nueva de NetBird incluye una política llamada Default que permite todo el tráfico entre todos los peers. Es cómoda para probar, pero en producción conviene sustituirla por reglas explícitas: sin ninguna política que lo permita, dos peers no pueden comunicarse.
Organiza primero los peers en grupos. En Peers, abre cada peer y asígnale un grupo, por ejemplo servidores-web o bases-de-datos. Los peers registrados con la setup key del paso 3 ya están en servidores.
Crea después una política:
- Ve a Access Control > Policies y pulsa Add Policy.
- En Source, elige el grupo
servidores-web; en Destination, el grupobases-de-datos. - En Protocol, elige
TCPe indica solo los puertos necesarios, por ejemplo5432para PostgreSQL. - Ponle un nombre como
web-a-postgresqly guárdala.
Cuando tengas las políticas que necesitas, desactiva o elimina la política Default.
Comprueba el efecto desde un peer del grupo servidores-web. La conexión al puerto permitido debe funcionar y el resto de tráfico, incluido el ping (ICMP), debe fallar:
nc -zv 100.92.200.41 5432
ping -c 2 -W 2 100.92.200.41
Connection to 100.92.200.41 5432 port [tcp/postgresql] succeeded!
PING 100.92.200.41 (100.92.200.41) 56(84) bytes of data.
--- 100.92.200.41 ping statistics ---
2 packets transmitted, 0 received, 100% packet loss, time 1024ms
Paso 7: Dar acceso a una red privada (opcional)
Si un peer tiene acceso a una red que no ejecuta NetBird, por ejemplo la red privada 10.0.0.0/24 de tu proyecto, puedes usarlo como pasarela para el resto de peers. Desde el panel:
- Abre la sección de rutas (Network Routes, o Networks en las versiones recientes del panel) y crea una nueva.
- Indica el rango de red, por ejemplo
10.0.0.0/24, y elige como enrutador el peer que tiene acceso a esa red. - Deja activado el enmascaramiento (Masquerade) para que las máquinas de la red privada no necesiten una ruta de vuelta hacia la red NetBird.
- Selecciona los grupos de peers que recibirán la ruta y guarda.
El acceso a la red enrutada también está sujeto a las políticas de acceso, así que añade una política cuyo destino incluya ese recurso o esa ruta. En un peer cliente, comprueba que la ruta aparece:
ip route show table all | grep 10.0.0.0/24
Debe aparecer una ruta hacia 10.0.0.0/24 por la interfaz wt0, y deberías poder hacer ping a una máquina de esa red.
Solución de problemas
netbird up se queda esperando o Management aparece como Disconnected. Comprueba desde el peer que el servidor responde por HTTPS con curl -I https://your_domain, y revisa los logs del cliente:
sudo journalctl -u netbird -n 50 --no-pager
Si el certificado no es válido, el despliegue no pudo obtenerlo de Let's Encrypt: revisa que el registro DNS apunta al servidor y que el puerto 80 está abierto, y consulta docker compose logs en /opt/netbird.
Los peers se ven en el panel pero no se comunican. Casi siempre es una política de acceso. Revisa que existe una política que permita ese tráfico entre los grupos de ambos peers y que el protocolo y los puertos coinciden.
La conexión funciona, pero con latencia alta. Si netbird status --detail muestra Relayed, los peers no han podido establecer una conexión directa, normalmente porque ambos están detrás de NAT restrictivos o de firewalls que bloquean UDP saliente. Permitir UDP saliente en al menos uno de los extremos suele bastar para pasar a P2P.
Conclusión
Tienes un servidor de gestión de NetBird propio, peers Linux conectados mediante setup keys y políticas que limitan el tráfico entre grupos en lugar de permitirlo todo. Como siguientes pasos, puedes instalar el cliente en equipos de escritorio (donde el inicio de sesión se hace con el navegador en lugar de con una setup key), añadir un proveedor de identidad externo en Zitadel para el inicio de sesión único y hacer copias de seguridad periódicas del directorio /opt/netbird y de los volúmenes de Docker del despliegue.