Skip to main content

Relay de NetBird con TLS usando los certificados de Caddy

Introducción

Este artículo aclara cómo habilitar correctamente un relay de NetBird con TLS válido reutilizando los certificados emitidos por Caddy, sin ocupar el puerto 443 (ya reservado por el propio proxy).

El objetivo principal es permitir el uso de QUIC y que el endpoint rels:// sea considerado válido por NetBird, manteniendo una separación clara entre el proxy HTTP(S) y el servicio de relay.

No se trata de un despliegue completo, sino de una aclaración técnica sobre un punto concreto que suele generar confusión cuando Caddy y NetBird conviven en el mismo host.

Contexto del problema

Con una configuración estándar de Caddy —como la utilizada inicialmente en el Caddyfile del repositorio— el relay no quedaba operativo, aun cuando el contenedor estaba levantado y los certificados eran válidos.

El estado podía comprobarse desde cualquier cliente con:

netbird status -d

La salida mostraba el relay TLS como no disponible:

Relays:
  [stun:tu.dominio.netbird:3478] is Available
  [turn:tu.dominio.netbird:3478?transport=udp] is Available
  [rels://tu.dominio.netbird:443/relay] is Unavailable, reason: relay client not connected

Esto indicaba que el relay TLS existía a nivel de configuración, pero no era alcanzable ni funcional desde los peers.

Tras aplicar los ajustes descritos en este artículo, el estado pasó a ser:

Relays:
  [stun:tu.dominio.netbird:3478] is Available
  [turn:tu.dominio.netbird:3478?transport=udp] is Available
  [rels://tu.dominio.netbird:33443/relay] is Available

La diferencia clave es que el relay TLS deja de competir con Caddy en el puerto 443 y pasa a exponerse de forma explícita en un puerto alternativo.

Requisitos previos

Para que este enfoque funcione, deben cumplirse las siguientes condiciones:

  • Caddy funcionando como reverse proxy y gestor de TLS
  • Certificados válidos emitidos por Caddy (Let's Encrypt)
  • Puerto TCP alternativo accesible desde Internet (ejemplo: 33443)
  • Docker operativo en el host

Enfoque adoptado

El relay de NetBird no se expone a través de Caddy. En su lugar:

  • Se reutilizan directamente los certificados generados por Caddy
  • El contenedor del relay escucha en un puerto dedicado
  • El endpoint rels:// apunta a ese puerto específico

Este enfoque evita conflictos con el proxy HTTP y respeta el diseño de NetBird para tráfico QUIC.

Configuración del contenedor Relay

El contenedor del relay se lanza indicando explícitamente:

  • Puerto de escucha alternativo
  • Dominio TLS
  • Ruta a los certificados emitidos por Caddy
  • Secreto compartido con el management

Ejemplo de servicio:

relay:
  image: netbirdio/relay:latest
  container_name: NetBirdRelay
  restart: unless-stopped
  environment:
    - NB_LOG_LEVEL=debug
    - NB_LISTEN_ADDRESS=:33443
    - NB_EXPOSED_ADDRESS=rels://tu.dominio.netbird:33443/relay
    - NB_AUTH_SECRET=22222222222nvxxxxxxxxxxxxxh666666So
    - NB_TLS_CERT_FILE=/certs/tu.dominio.netbird.crt
    - NB_TLS_KEY_FILE=/certs/tu.dominio.netbird.key
    - NB_RELAY_TLS_DOMAIN=tu.dominio.netbird
  ports:
    - 33443:33443
  volumes:
    - /var/lib/caddy/.local/share/caddy/certificates/acme-v02.api.letsencrypt.org-directory/tu.dominio.netbird:/certs:ro

El relay queda así completamente desacoplado de Caddy, pero sigue beneficiándose de su gestión automática de certificados.

Registro manual del relay en NetBird

El relay no se autodetecta. Debe declararse explícitamente en el management.json del servidor de NetBird:

"Relay": {
  "Addresses": [
    "rels://tu.dominio.netbird:33443/relay"
  ],
  "CredentialsTTL": "24h0m0s",
  "Secret": "22222222222nvxxxxxxxxxxxxxh666666So"
}

El valor de Secret debe coincidir exactamente con NB_AUTH_SECRET definido en el contenedor del relay.

Consideraciones de red (NAT / firewall)

  • El puerto TCP 33443 debe estar abierto y redirigido correctamente hacia el host
  • Si el puerto no es accesible externamente, el relay nunca será utilizable, aunque todo lo demás esté bien configurado

Este punto suele ser la causa más frecuente de fallos silenciosos.

Errores comunes y decisiones clave

  • No usar el puerto 443: ya está ocupado por Caddy
  • QUIC exige TLS válido: sin certificados correctos, rels:// se descarta
  • El relay no es automático: debe declararse en management.json
  • Caddy no actúa como proxy del relay: solo se reutilizan sus certificados

Resumen breve

  • El relay TLS de NetBird se expone en un puerto dedicado
  • Se reutilizan los certificados emitidos por Caddy
  • El endpoint rels:// apunta explícitamente a ese puerto
  • El relay debe registrarse manualmente en NetBird
  • El puerto debe estar accesible desde Internet

Enlaces de interés

Back to top