El problema: gestionar diez túneles WireGuard manuales
WireGuard es excelente — rápido, moderno, sólido criptográficamente. Pero su modelo de configuración es estático: cada par debe conocer la IP pública y la clave pública de todos sus homólogos. En un parque de diez clientes con estaciones de trabajo nómadas, oficinas detrás de CGNAT y VPS con IPs variables, se pasa más tiempo sincronizando archivos wg0.conf que haciendo trabajo productivo. Añadir un VPS implica modificar la lista de pares en nueve máquinas. Eliminar un técnico requiere revocar su clave en todas partes. ¿Cambió una subred? A empezar de nuevo. Esta es la pesadilla operativa que NetBird fue diseñado para eliminar.
- Mesh automático: NetBird gestiona el plano de control — cada nuevo par se anuncia, los demás lo descubren sin intervención manual.
- Traversal NAT y CGNAT: NetBird usa STUN para establecer conexiones directas entre pares a través de NATs residenciales y corporativos.
- Relé TURN automático: cuando la conexión directa es imposible, NetBird cambia silenciosamente a un relé cifrado.
- Auditoría de acceso granular: las políticas de control de acceso definen qué pares pueden alcanzar qué servicios.
- Open source (BSD-3 para el cliente, AGPLv3 para el servidor): sin vendor lock-in, posibilidad de autoalojamiento.
Requisitos previos
Antes de instalar NetBird, verifica que tu infraestructura cumple los siguientes requisitos.
- Un VPS ServOrbit con Ubuntu 22.04/24.04 o Debian 12, con acceso root.
- Una cuenta de NetBird Cloud (gratuita hasta 5 pares) o un plano de control self-hosted ya desplegado.
- Los puertos salientes 443 (HTTPS/WSS) y 3478 (STUN/UDP) no bloqueados desde el VPS.
- La función Peer Expose activada en tu cuenta (disponible en los planes Team y superiores).
Conectar un VPS ServOrbit a una red NetBird
Aquí está el procedimiento completo para conectar un VPS ServOrbit a tu red mesh NetBird.
Instalar el agente NetBird
En el VPS, añade el repositorio oficial e instala el paquete:
curl -fsSL https://pkgs.netbird.io/install.sh | sh
Verifica la versión:netbird versiondebe mostrar0.76.x.Generar una clave de configuración
En el panel de NetBird, ve a Setup Keys y crea una clave reutilizable o de un solo uso. Cópiala — solo se muestra una vez.
Conectar el par al plano de control
En el VPS:
netbird up --setup-key <TU_SETUP_KEY>
El par aparece en el panel en segundos.Añadir el par al grupo de red
En la interfaz NetBird, ve a Peers, selecciona el nuevo VPS y añádelo al grupo deseado. Las políticas de acceso se aplican inmediatamente.
Verificar la conectividad mesh
Desde otro par ya en la red:
netbird statusluegoping 100.x.x.x
Un ping que responde confirma que el túnel está establecido.
`netbird expose`: un servicio interno sin puerto público
El comando netbird expose permite hacer accesible un servicio que escucha localmente a través del proxy inverso de NetBird — sin abrir ningún puerto en el firewall del VPS. El servicio creado es efímero: desaparece automáticamente al detener el comando.
Ejemplo práctico: tu panel de supervisión escucha en localhost:3000 y solo debe ser accesible para miembros autorizados del mesh:netbird expose --protocol http --local-address localhost:3000 --with-user-groups supervision-admins
NetBird genera una URL pública en *.tunnel.netbird.io. El puerto 3000 del VPS permanece cerrado a nivel de firewall.
Para acceso protegido por contraseña sin SSO, añade --with-password: NetBird muestra una contraseña aleatoria que compartes con tus colaboradores. Útil para acceso de emergencia a un cliente sin cuenta en tu tenant NetBird.
Caso de uso agencia: conectar VPS cliente, oficina y estación admin
Topología NetBird recomendada para una agencia que gestiona diez clientes independientes: crea un grupo por cliente. El VPS de cada cliente es miembro de su grupo. Las estaciones de admin son miembros solo de su grupo de cliente. La oficina de la agencia está en un grupo agency-ops con acceso a todos los grupos de clientes.
Para SSH al VPS del cliente sin puerto público:ufw allow in on netbird0 to any port 22 luego ufw deny 22
Desplace la tabla
| Criterio | NetBird 0.76 | Tailscale | WireGuard manual |
|---|---|---|---|
| Gestión de pares | Automática (plano de control centralizado) | Automática (nube Tailscale) | Manual (archivos wg0.conf en cada nodo) |
| Traversal NAT/CGNAT | STUN + TURN automático | STUN + DERP automático | Requiere IP pública o port-forward |
| Modelo de precios | Gratuito hasta 5 pares; planes Team/Business; self-hosted gratuito | Gratuito hasta 3 usuarios; planes de pago | Gratuito (software), coste operativo en tiempo |
| Open source | Sí (BSD-3 cliente, AGPLv3 servidor) | Cliente open source (BSD-3), servidor propietario | Sí (GPLv2 kernel, MIT userland) |
| Exponer servicio sin puerto abierto | Sí (`netbird expose`) | No (Funnel disponible pero diferente) | No nativo (túnel SSH manual) |
| Auditoría y políticas de acceso | Interfaz web completa, grupos y políticas | ACL vía archivo HuJSON, interfaz web | Ninguna — solo AllowedIPs por par |
Resolución de problemas: 3 problemas frecuentes
1. Par inaccesible (Status: Disconnected) — Ejecuta netbird status --detail para ver el estado ICE. Verifica que el puerto 3478/UDP saliente esté abierto.
2. STUN/TURN bloqueado por firewall corporativo — NetBird soporta TURN sobre TCP/443. Configura Force TCP en el panel.
3. Leer los logs — En Linux con systemd:journalctl -u netbird -f --since '5 minutes ago'
Resolución de problemas: el proxy de NetBird se queda en «Issuing certificate…»
Desde que NetBird ofrece su proxy inverso autoalojado, un síntoma vuelve una y otra vez en los tickets: el servicio creado en el panel se queda indefinidamente en «Issuing certificate…» y nunca es accesible. El ticket netbird #5517, abierto el 5 de marzo de 2026 y todavía abierto en su última actividad del 19 de octubre de 2026, suma 35 comentarios. El log del proxy muestra con más frecuencia este mensaje: acme/autocert: unable to satisfy "https://acme-v02.api.letsencrypt.org/acme/authz/…" for domain "subdomain.site.tld": no viable challenge type found. Dice que la autoridad de certificación no recibió ninguna respuesta válida a sus desafíos; no dice por qué. No existe, pues, una causa única: los participantes describen varias y solo una está confirmada por el equipo de NetBird. Este es un orden de diagnóstico que descarta las causas una a una.
Leer el log del proxy
Ejecuta
docker compose logs proxy | grep -i acme: la documentación de NetBird señala este comando para los servicios que se quedan encertificate_pendingo pasan acertificate_failed. Anota el texto exacto del error antes de cambiar nada, porquepermission deniedyno viable challenge type foundno tienen el mismo remedio.Comprobar los permisos de la carpeta de certificados
Un error del tipo
open /certs/acme_account+key…: permission deniedes el único caso zanjado por un colaborador del repositorio, que responde que ninguna actualización lo corregirá y que el problema son los permisos. Un participante cuenta que lo resolvió entregando la carpetacertsal usuario 1000:1000 (chown 1000:1000) y montando una carpeta vacía en/var/lib/netbird. Es una corrección reportada para su instalación: comprueba con qué usuario corre tu contenedor antes de copiarla.Verificar el DNS, los registros CAA y los puertos
El nombre debe resolver a la dirección del proxy y ningún registro CAA debe excluir a la autoridad utilizada. El puerto 443 debe ser accesible desde Internet para el desafío
tls-alpn-01, que es el valor por defecto; el puerto 80 también lo debe ser parahttp-01. La documentación indica que Let's Encrypt valida desde varias ubicaciones del mundo, así que un filtrado geográfico aguas arriba puede hacer fallar la validación.Descartar un CDN que no retransmite el desafío
La documentación advierte de que un servicio situado delante del proxy, Cloudflare por ejemplo, puede no transmitir el protocolo ALPN
acme-tls/1. En ese caso, pasa aNB_PROXY_ACME_CHALLENGE_TYPE=http-01. Estas comprobaciones descartan causas sin garantizar el éxito: un participante verificó el DNS, Cloudflare en solo DNS, los puertos 80 y 443 abiertos y la ausencia de CAA, y obtiene el mismo error con los dos tipos de desafío.Examinar el Traefik situado delante
Si Traefik retransmite el TLS al proxy mediante un enrutador TCP con
tls.passthrough=true, comprueba que el punto de entrada HTTPS llevaallowACMEByPass=true. El recuadro siguiente explica qué hace esta opción y qué no demuestra.
- Confirmado por el equipo — un error
permission denieden la carpeta/certsviene de los permisos del sistema de archivos y no de la versión del proxy; la advertenciafailed to get active profile statesobre el perfil del cliente integrado no tiene relación con el proxy y no es crítica, y su mensaje se corregirá en una próxima versión. - Reportado por varios participantes — añadir
allowACMEByPass=trueal punto de entrada HTTPS de Traefik desbloquea la emisión. Varios lo confirman, pero otros dos indican que la opción ya estaba puesta en su caso y que el bloqueo persiste, uno de ellos con la versión 0.74.4 del proxy. - Reportado por un solo participante, sin verificar — en NetBird Cloud, una emisión lenta por parte de ZeroSSL, combinada con un plazo de 5 minutos de la biblioteca autocert de Go, explicaría los fallos. El autor aclara que razona desde fuera, sin confirmación del equipo.
- No establecido — ninguna causa única hasta hoy: el ticket sigue llevando la etiqueta
triage-neededen la lectura del 31 de octubre de 2026. No presentes ninguna de estas pistas como la causa de tu caso antes de haberla probado.
El script getting-started.sh del repositorio de NetBird pone --entrypoints.websecure.allowACMEByPass=true en Traefik. Según la documentación de Traefik, esta opción, desactivada por defecto, hace que tus propios enrutadores traten los desafíos ACME TLS y HTTP en lugar del enrutador ACME interno, y deja pasar el desafío TLS-ALPN hacia un enrutador TLS que tú defines. Usa el nombre de tu propio punto de entrada (websecure, https…): un participante tuvo que ponerla a la vez en el punto de entrada HTTP y en el HTTPS. No exime de leer el log.
Origen cerrado: obtener el certificado por DNS-01 con lego
Mientras el certificado dependa de un desafío tls-alpn-01 o http-01, la autoridad debe llegar a tu proxy desde Internet. Eso choca con un origen cerrado solo a los rangos de un CDN, con un firewall aguas arriba que no gestionas o con un filtrado geográfico. El desafío dns-01 elimina esa dependencia: demuestra el control del dominio con un registro TXT temporal creado mediante la API del proveedor DNS. A 31 de octubre de 2026, el proxy de NetBird no lo integra de forma nativa: la petición, ticket netbird #5450 abierto el 25 de febrero de 2026 y con 30 comentarios, sigue abierta. La documentación de NetBird sí describe una vía, «private proxy with lego»: lego obtiene y renueva un certificado wildcard por DNS-01, un hook de despliegue lo copia en un volumen compartido y el proxy lo carga y lo recarga en caliente tras cada renovación. Un participante del ticket dice haberla montado sin dificultad y que también sirve para servicios públicos.
- Variables del proxy —
NB_PROXY_WILDCARD_CERT_DIRseñala la carpeta del certificado wildcard yNB_PROXY_PRIVATE="true"activa el modo privado. Fija la versión de la imagen: debe conocer ambas variables. - El modo privado no cierra nada por sí solo —
NB_PROXY_PRIVATEno desactiva la escucha pública. Retira tú mismo los puertos públicos y las rutas de entrada hacia el proxy. - Alcance del wildcard — cubre un solo nivel de subdominio. Un nombre fuera de su cobertura vuelve al ACME integrado, que no puede completarse si el proxy es totalmente privado.
- Exposición del certificado — las autoridades públicas registran el wildcard y el dominio base en los registros de Certificate Transparency, y una clave wildcard comprometida afecta a todos los nombres cubiertos.
- Operación — usa el servidor ACME de producción, porque los certificados de prueba no son de confianza; haz copia de los volúmenes de lego y de los certificados; prevé un emisor único o una distribución segura del par de certificados para un clúster de varios hosts.
Política de control de acceso: crea una regla que solo permita al grupo agency-ops alcanzar el puerto 22 en los grupos de clientes. Esto evita que un equipo comprometido en el mesh sirva de pivote para acceder a todos los VPS de clientes.
Conclusión: menos reglas de firewall, más seguridad real
NetBird 0.76 representa un cambio de paradigma para gestionar un parque de VPS distribuido. En lugar de multiplicar reglas UFW y claves WireGuard estáticas, defines grupos y políticas una vez — y el plano de control se encarga del resto. El comando netbird expose va más lejos: elimina físicamente servicios de la exposición a Internet sin reconfigurar el firewall. Para una agencia que gestiona diez clientes o una empresa con oficinas distribuidas, esta es la reducción de superficie de ataque más impactante por hora invertida.
