WireGuard P2P, Headscale, Netbird: tres enfoques distintos
WireGuard estático (vea nuestra guía WireGuard P2P) obliga a distribuir un par de claves por túnel y a editar /etc/wireguard/wg0.conf con cada nuevo homólogo. Eficaz para dos o tres servidores fijos — inmanejable a escala de un parque de agencia.
Headscale reimplementa el servidor de coordinación de Tailscale: usted conserva los clientes oficiales de Tailscale y obtiene una red plana ilimitada en usuarios. Una sola red por instancia, sin aislamiento nativo entre clientes distintos. Es la opción adecuada para un equipo único que quiere permanecer en el ecosistema Tailscale.
Netbird toma el partido contrario: aporta su propio cliente, su propio plano de control (Management + Signal + relay) y una noción de red nombrada con reglas de acceso granulares. Una única instancia puede alojar varias redes totalmente aisladas, lo que la convierte en la herramienta natural para una agencia que gestiona parques de clientes separados. La interfaz web viene incluida de serie.
Arquitectura de Netbird: cuatro componentes
Un despliegue autoalojado de Netbird se apoya en cuatro componentes, todos incluidos en el mismo repositorio (netbirdio/netbird):
Management Server — el cerebro del plano de control. Distribuye las claves WireGuard, aplica las reglas de acceso y expone la API REST que consulta la interfaz web. Almacenamiento SQLite por defecto, MySQL o PostgreSQL como opción.
Signal Server — el servidor de señalización entre pares. Facilita el intercambio de descriptores de conexión ICE entre los nodos en el momento de establecer el túnel WireGuard. Ningún tráfico de aplicación lo atraviesa.
COTURN — el servidor relay STUN/TURN. Actúa de relé cuando una conexión directa entre dos pares es imposible (doble NAT, red corporativa restrictiva). El tráfico solo pasa por COTURN cuando falla el intento directo.
Dashboard — la interfaz web (SPA React) que consume la API de Management. Permite crear redes, añadir peers, definir reglas de acceso y generar claves de enrolamiento sin tocar la línea de comandos.
Todos los flujos entre clientes van en WireGuard cifrado de extremo a extremo: Management y Signal solo ven los metadatos de enrolamiento, nunca el tráfico de aplicación.
Requisitos previos
VPS dedicado al plano de control. Prevea un VPS distinto de sus nodos de cliente: 2 vCPU, 2 GB de RAM como mínimo. Un VPS {{vps.start.name}} sirve para empezar.
Puertos que abrir en el VPS de control:
443 (TCP) — Management y Dashboard detrás de un reverse proxy HTTPS.3478 (UDP) — COTURN STUN/TURN.49152-65535 (UDP) — rango dinámico de COTURN para las sesiones relay.
Los nodos de cliente no tienen ningún puerto entrante que abrir: el cliente Netbird establece conexiones salientes hacia el plano de control.
Software necesario en el VPS de control: Docker Engine 24+ y Docker Compose v2, un nombre de dominio que apunte a la IP del VPS y un certificado TLS (Let's Encrypt mediante el script incluido o su reverse proxy habitual).
En cada nodo de cliente: el binario netbird (paquete Debian/RPM o binario estático), acceso root o sudo.
Desplegar el plano de control y conectar tres nodos
Clonar el repositorio y lanzar el script de inicio
En el VPS de control, descargue el script oficial de Netbird y deje que genere la stack Docker Compose completa:
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh -o getting-started.sh bash getting-started.shEl script le pide su dominio (p. ej.
netbird.votre-domaine.com), generadocker-compose.yml,config.yaml,dashboard.envy la configuración de COTURN, y luego lanza la stack. Al final muestra la URL de la interfaz web y una primera Setup Key: consérvela.Comprobar que los cuatro servicios responden
Una vez terminado el script, confirme que los contenedores están levantados:
docker compose psDebe ver cuatro servicios
running:netbird-management,netbird-signal,netbird-coturnynetbird-dashboard. Pruebe el Management desde el propio VPS:curl -s https://netbird.votre-domaine.com/api/v1/peers \ -H 'Authorization: Token <votre-PAT>'Una respuesta JSON vacía
[]confirma que el servicio responde y que aún no hay ningún par enrolado.Crear una red y una Setup Key en la interfaz web
Abra
https://netbird.votre-domaine.comen un navegador. Inicie sesión con la cuenta creada durante el setup (o mediante el proveedor OIDC configurado).En el menú Setup Keys, haga clic en Create Setup Key. Póngale un nombre (
vps-client-a), elija el tipoReusable(para enrolar varias máquinas con la misma clave) y una duración de expiración. Copie la clave: la necesitará en cada nodo.Enrolar el nodo 1
En el primer VPS de cliente, instale el cliente Netbird:
curl -fsSL https://pkgs.netbird.io/install.sh | bashLuego conéctelo al plano de control apuntando a su instancia:
netbird up \ --management-url https://netbird.votre-domaine.com \ --setup-key <VOTRE_SETUP_KEY>Confirme la conexión:
netbird statusDebe leer
Status: Connectedy una IP mesh del rango100.64.x.xasignada por su servidor.Enrolar los nodos 2 y 3
Repita exactamente el mismo procedimiento en los otros dos VPS de cliente. El mismo comando
curlpara instalar el cliente y el mismo comandonetbird upcon el mismo--management-urly la misma--setup-key(si es de tipoReusable).Una vez enrolados los tres nodos, compruebe desde el nodo 1 que los pares son visibles:
netbird status --detailLa salida lista cada par con su IP mesh, su estado (
ConnectedoConnecting) y su latencia.Probar la conectividad mesh sin ningún puerto público abierto
Antes de probar, compruebe el estado del firewall en el nodo 1: no debe haber ningún puerto entrante abierto hacia los demás nodos:
sudo ufw status numberedSolo debe aparecer el puerto SSH (22). Ahora haga ping al nodo 2 mediante su IP mesh (visible en
netbird status --detail, p. ej.100.64.0.2):ping -c 3 100.64.0.2El ping atraviesa el túnel WireGuard establecido entre los pares. Si los dos nodos están tras un NAT estricto, COTURN se encarga del relay: el ping funciona en ambos casos sin ninguna regla UFW adicional.
Comprobar las conexiones directas frente al relay
Para distinguir una conexión directa de un paso por COTURN:
netbird status --detailLa columna
Connection typemuestraP2Ppara una conexión directa oRelayedcuando interviene COTURN.P2Pes el estado nominal entre dos VPS con IPv4 públicas directas.Relayedindica que Netbird ha tenido que pasar por el servidor COTURN: compruebe entonces que los puertos UDP 3478 y el rango 49152-65535 son accesibles desde los nodos.
Aislamiento multicliente: peers groups y reglas de acceso
La fuerza de Netbird frente a Headscale es su noción de red aislada por grupo. Por defecto, todos los peers enrolados con la misma Setup Key entran en un grupo común. Para aislar los servidores de un cliente A de los de un cliente B:
1. Cree un grupo por cliente en la interfaz web (Networks → Groups → Add Group). Llámelos client-a, client-b.
2. Asigne cada peer a su grupo. En la ficha del peer, sección Assigned Groups, añada el grupo correspondiente y quite el grupo All si no quiere comunicación entre grupos.
3. Defina las reglas de acceso (Access Control → Policies). Una política client-a-interne autoriza el tráfico entre peers del grupo client-a. No se crea ninguna regla entre client-a y client-b: las dos redes quedan herméticas.
También puede definir Network Routes: un peer hace de router para una subred privada (p. ej. 192.168.10.0/24) y expone esa red a los demás peers del grupo, sin que estos necesiten un cliente Netbird instalado en cada máquina de la subred.
Operaciones habituales
Renovar o revocar una Setup Key. En la interfaz web, Setup Keys → su clave → Revoke. Los peers ya enrolados conservan su conexión; los nuevos intentos de enrolamiento con esa clave serán rechazados. Cree una clave nueva para los próximos enrolamientos.
Revocar un peer. Peers → seleccione el peer → Delete. El nodo queda retirado del mesh de inmediato. En el lado cliente, netbird status pasa a Disconnected y los túneles WireGuard hacia ese par se destruyen.
Acceso API para la automatización. Netbird expone una API REST documentada. Genere un Personal Access Token (Settings → Access Tokens) y gobierne el conjunto desde sus scripts de Ansible o sus pipelines de CI:
curl -s https://netbird.votre-domaine.com/api/v1/peers \
-H 'Authorization: Token <PAT>'Monitorización. El Management Server expone métricas Prometheus en /metrics. Conecte Grafana a ese endpoint para seguir el número de peers conectados, las sesiones COTURN activas y la latencia de señalización.
Endurecimiento: 2FA en el Dashboard y copia de la base Management
El Dashboard de Netbird admite OIDC (Keycloak, Authentik, Azure AD): actívelo para imponer la MFA a todos los administradores del plano de control. Sin SSO, la cuenta local queda protegida únicamente por contraseña.
La base de datos SQLite del Management Server es el único estado persistente de su red: perder ese archivo significa volver a enrolar todos sus pares. Monte un volumen Docker con nombre (netbird_management) y haga una copia de seguridad diaria:
docker run --rm \
-v netbird_management:/data \
-v /opt/backups:/backup \
alpine tar czf /backup/netbird-$(date +%Y%m%d).tar.gz /dataRotación de las copias de 7 días como mínimo.
Resolución de problemas
COTURN inaccesible — los peers se quedan en Relayed o no se conectan nunca.
Compruebe que los puertos UDP 3478 y el rango 49152-65535 están abiertos en el firewall del VPS de control (ufw status). Pruebe desde un nodo de cliente: nc -u -z netbird.votre-domaine.com 3478. La ausencia de respuesta significa tráfico filtrado. En algunos proveedores, los rangos UDP amplios están bloqueados por defecto: ábralos explícitamente.
Peer bloqueado en Connecting.
Indica que la comunicación con Management/Signal ha funcionado (el peer se ha enrolado) pero que resulta imposible formar el túnel WireGuard. Causas frecuentes: la IP pública del VPS de control está mal indicada en config.yaml (campo --turn-external-ip de COTURN), o los puertos UDP del rango dinámico están cerrados. Vuelva a lanzar el script getting-started.sh con --external-ip explícito si el VPS está tras un NAT.
La resolución DNS falla entre peers.
Netbird integra un resolutor DNS que distribuye los nombres <hostname>.netbird.cloud a cada par. Si ping nœud2.netbird.cloud falla mientras que ping 100.64.0.2 funciona, compruebe que el servicio netbird está en ejecución en el peer (systemctl status netbird) y que su DNS está activo: resolvectl status | grep netbird.
Doble NAT — ninguna conexión directa, COTURN sobrecargado.
Si los dos pares están tras un NAT estricto (típicamente: VPS cloud detrás de un balanceador del proveedor), las conexiones directas WireGuard son imposibles y todo el tráfico pasa por COTURN. Solución: asegúrese de que el VPS de control tiene una IPv4 pública directa y de que --turn-external-ip apunta a esa IP. Para los nodos de cliente tras un NAT estricto, no hay nada que hacer: COTURN está pensado precisamente para ese caso.
Actualización de la stack — nodos temporalmente desconectados.
Una actualización del Management Server desconecta a los peers durante unos segundos, mientras se reinicia el contenedor. Planifique las actualizaciones fuera de la ventana de tráfico, o active la opción restart: always en todos los contenedores para minimizar el tiempo de parada.
Lo que el mesh cambia en la gestión de parques
Una red mesh Netbird autoalojada sustituye tres capas que usted mantenía a mano: la distribución de claves WireGuard, las reglas UFW entre servidores y la documentación de los accesos cruzados. Cada nuevo VPS de cliente se enrola con un solo comando; cada revocación es instantánea y central.
El aislamiento por grupo le permite crecer sin riesgo de colisión: los servidores de dos clientes distintos no pueden verse, aunque corran sobre la misma infraestructura. Y el plano de control sigue siendo suyo — sin dependencia de ningún SaaS de terceros, sin límite de seats, sin suscripción por nodo.
Para ir más lejos, plasme el aprovisionamiento de los nodos en Ansible (vea nuestra guía de Ansible): la instalación del cliente y el comando netbird up se convierten en tareas idempotentes dentro de un rol reutilizable.
