--- title: "Cómo instalar NetBird VPN self-hosted en Ubuntu 24.04" description: "Despliega el servidor de NetBird con Docker en Ubuntu 24.04, conecta peers Linux con setup keys y controla el tráfico de la red mesh con políticas de acceso." category: "Herramientas de Servidor" language: es source: https://cubepath.com/es/docs/herramientas-de-servidor/instalacion-y-configuracion-de-netbird-vpn updated: 2026-09-25 --- # Cómo instalar NetBird VPN self-hosted en Ubuntu 24.04 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: ```bash dig +short your_domain ``` ```output 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: ```bash 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: ```bash sudo ufw status ``` ```output 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 ... ``` > Nota: si 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`: ```bash 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: ```bash sudo mkdir -p /opt/netbird sudo chown "$USER": /opt/netbird cd /opt/netbird ``` Descarga el script y revísalo antes de ejecutarlo: ```bash 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: ```bash 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: ```output 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: ```bash 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: 1. Ve a **Setup Keys** y pulsa **Create Setup Key**. 2. Ponle un nombre descriptivo, por ejemplo `servidores`. 3. 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. 4. 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. 5. 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: ```bash 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: ```bash 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: ```bash 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`): ```bash sudo netbird up --management-url https://your_domain --setup-key your_setup_key ``` ```output Connected ``` Comprueba el estado de la conexión: ```bash netbird status ``` ```output 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`: ```bash ip -brief address show wt0 ``` ```output 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: ```bash 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: 1. Ve a **Access Control** > **Policies** y pulsa **Add Policy**. 2. En **Source**, elige el grupo `servidores-web`; en **Destination**, el grupo `bases-de-datos`. 3. En **Protocol**, elige `TCP` e indica solo los puertos necesarios, por ejemplo `5432` para PostgreSQL. 4. Ponle un nombre como `web-a-postgresql` y 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: ```bash nc -zv 100.92.200.41 5432 ping -c 2 -W 2 100.92.200.41 ``` ```output 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: 1. Abre la sección de rutas (**Network Routes**, o **Networks** en las versiones recientes del panel) y crea una nueva. 2. Indica el rango de red, por ejemplo `10.0.0.0/24`, y elige como enrutador el peer que tiene acceso a esa red. 3. Deja activado el enmascaramiento (**Masquerade**) para que las máquinas de la red privada no necesiten una ruta de vuelta hacia la red NetBird. 4. 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: ```bash 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: ```bash 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.