La publicación original recoge los elementos esenciales para que un cliente Docker de Tailscale en ZimaOS se registre en un plano de control de Headscale autogestionado: estado persistente, una clave de un solo uso o de preautenticación, la URL personalizada de Headscale, acceso a TUN y las capacidades necesarias del contenedor.
La documentación actual de Tailscale y Headscale ofrece ahora un contrato ascendente más claro. Tailscale admite oficialmente una URL de servidor de control personalizado, y Headscale documenta tanto el registro interactivo como el registro mediante una clave de preautenticación. Usa esos métodos oficiales para validar el comando y la URL actuales, en lugar de depender únicamente de una captura de pantalla de 2025.
Headscale reemplaza el plano de control de coordinación de Tailscale
Headscale es una implementación autogestionada del protocolo de servidor de control de Tailscale. Los clientes de Tailscale siguen creando túneles cifrados entre pares, pero el registro y la coordinación son gestionados por la instancia de Headscale del usuario en lugar del plano de control predeterminado de Tailscale.
Conservar el directorio de estado de Tailscale
La fuente creó /DATA/AppData/tailscale/state y lo asignó a /var/lib/tailscale. Esto es importante porque la identidad y el estado del nodo deben sobrevivir a la recreación del contenedor y al reinicio del host.
La fuente también recomendaba permisos restrictivos en el directorio de estado del host. Es una medida sensata, ya que el estado forma parte de la identidad del nodo y no debería ser legible por cualquier usuario.
Usar la URL de Headscale como servidor de control personalizado
La documentación actual de Tailscale admite servidores de control personalizados mediante:
tailscale login --login-server=<URL>La documentación propia de Headscale utiliza el mismo modelo con tailscale up --login-server <YOUR_HEADSCALE_URL>.
Consulta la guía actual de Tailscale sobre servidores de control personalizados.
Usar una clave de preautenticación para el registro no interactivo
La fuente añadió temporalmente TS_AUTHKEY, registró el nodo y luego eliminó la variable. Actualmente, la documentación de Headscale describe cómo crear una clave de preautenticación y usarla con --authkey para el registro no interactivo.
Usa los métodos de registro actuales de Headscale.
No dejes una clave de autenticación reutilizable en la definición de la aplicación
Si la clave se puede reutilizar o tiene una duración prolongada, dejarla en el entorno de la aplicación de ZimaOS crea una exposición innecesaria. Después de almacenar correctamente la identidad del nodo, elimina el secreto de registro cuando ya no lo necesites.
Si una clave se publicó en un foro público o en una captura de pantalla, revócala y crea una nueva.
La TUN del kernel y las capacidades afectan al modo de red
El código fuente asigna /dev/net/tun y concede NET_ADMIN/NET_RAW, que corresponde al estilo de redes mediante el kernel, en lugar de las redes puramente en el espacio de usuario.
Los contenedores actuales de Tailscale también pueden operar en modo de espacio de usuario, así que elige el modo deliberadamente según necesites enrutamiento de subredes, comportamiento de nodo de salida o redes completas del kernel.
La red del host es potente
El código fuente usa la red del host de Docker. Esto elimina el aislamiento normal de puertos del contenedor y hace que Tailscale opere directamente en el espacio de nombres de red del host.
No cambies de red del host a red puente, ni viceversa, sin comprender cómo la aplicación actual de Tailscale almacena las rutas, los escuchas y los servicios anunciados.
La URL de Headscale debe ser accesible de forma fiable y estar protegida adecuadamente
Un servidor de control autohospedado se convierte en infraestructura crítica. Usa DNS estable, una configuración TLS válida y copias de seguridad de la base de datos y la configuración de Headscale. Si el servidor de control desaparece, es posible que los pares existentes sigan comunicándose temporalmente, pero los nuevos registros y los cambios de coordinación dejarán de estar disponibles.
El código fuente es una configuración funcional, no un contrato de soporte de IceWhale
La publicación no cuenta con la confirmación del personal de IceWhale. Es una configuración de la comunidad que coincide bien con los conceptos de Tailscale/Headscale originales, pero aun así debería probarse con el paquete actual de Tailscale para ZimaOS.
Preguntas frecuentes sobre Headscale en ZimaOS
¿Los clientes de Tailscale pueden usar un servidor de control Headscale personalizado?
Sí. La documentación actual de Tailscale admite oficialmente las URL de servidores de control personalizados.
¿TS_AUTHKEY debería permanecer para siempre en la aplicación?
No. El código fuente lo elimina después del registro, y los secretos de registro de larga duración no deberían quedar expuestos innecesariamente.
¿Por qué conservar /var/lib/tailscale?
Conserva la identidad y el estado de Tailscale del nodo al recrear el contenedor y reiniciarlo.
