Autoalojar Headscale en un servidor dedicado: paso a paso

Primero la respuesta: qué vas a construir

Un servidor pequeño con Headscale (la implementación open source del servidor de coordinación de Tailscale), con las apps oficiales de Tailscale en cada dispositivo apuntando a él en lugar de a la nube de Tailscale. El mismo mesh WireGuard, los mismos clientes, el mismo NAT traversal; el control plane (claves, listas de peers, ACL) vive en tu propio hardware, sin coste por usuario. Montarlo lleva aproximadamente media hora y necesitas:

• Una pequeña máquina Linux always-on con una IP pública: la huella de Headscale es diminuta; cualquier servidor modesto o slice de VPS es más que suficiente.
• Un nombre DNS que apunte a él (headscale.example.com, sustitúyelo por el tuyo en todo el documento).
• Puertos: 443 (o el puerto que elijas) para los clientes; 80 si usas el flujo por defecto de Let's Encrypt; 3478/udp si activas el relé integrado.

Vale la pena repetir lo que dijimos en nuestra comparativa de VPN mesh (donde esta opción se llevó el puesto de "UX de Tailscale, control autoalojado"): Headscale está deliberadamente limitado a un único tailnet, una red, un equipo o una organización. Es la respuesta autoalojada para infraestructura personal y organizaciones pequeñas, no un clon multi-tenant de Tailscale para empresas. A esa escala, es excelente.

Paso 1: instalación

El camino recomendado por el proyecto son sus paquetes .deb oficiales (Ubuntu 22.04+/Debian 12+), que crean el usuario headscale, el esqueleto de configuración y la unidad systemd por ti. Descarga la versión actual (v0.29.x en el momento de escribir esto, revisa los releases):

wget https://github.com/juanfont/headscale/releases/download/v0.29.2/headscale_0.29.2_linux_amd64.deb
apt install ./headscale_0.29.2_linux_amd64.deb

(Existen imágenes Docker, pero el proyecto no da soporte oficial al despliegue con Docker de forma explícita; en tu propio servidor, el paquete es a la vez más simple y el camino soportado.)

Paso 2: configuración

Todo vive en /etc/headscale/config.yaml. El delta mínimo funcional respecto al ejemplo que se incluye:

server_url: https://headscale.example.com:443
listen_addr: 0.0.0.0:443

# TLS, the simple way: built-in Let's Encrypt
tls_letsencrypt_hostname: headscale.example.com

Tres decisiones que vale la pena tomar de forma consciente:

• TLS: la integración incorporada con Let's Encrypt es la opción con menos piezas móviles. El challenge HTTP-01 por defecto necesita que el puerto 80 sea alcanzable; como alternativa, TLS-ALPN-01 valida directamente sobre el 443. Un reverse proxy (nginx/Caddy) delante también funciona y es habitual, pero ten en cuenta el aviso honesto de la documentación: la guía de reverse proxy la mantiene la comunidad, los upgrades de WebSocket hay que configurarlos, y el proxying a través de Cloudflare no tiene soporte de forma explícita. Menos capas, menos sorpresas: TLS directo es la recomendación aquí.
• Base de datos: SQLite es la opción por defecto y la respuesta correcta a esta escala, un solo archivo en /var/lib/headscale/db.sqlite.
• DNS: la sección dns: le da a tu mesh nombres MagicDNS (al estilo base_domain: ts.example.com); configúralo ahora, renombrarlo más adelante es molesto.

Después:

systemctl enable --now headscale
headscale users create jesse

Paso 3: conectar los clientes

En cada dispositivo, instala la app normal de Tailscale y apúntala a tu servidor:

tailscale up --login-server https://headscale.example.com

El comando muestra una URL; al visitarla obtienes la clave del node, que apruebas del lado del servidor (headscale nodes register --user jesse --key <key>). Para máquinas desatendidas (servidores que se unen al mesh) sáltate el paso interactivo con una pre-auth key:

headscale preauthkeys create --user jesse --expiration 1h
tailscale up --login-server https://headscale.example.com --authkey <key>

Headscale es compatible con las últimas diez releases del cliente de Tailscale en Linux, Windows, macOS, iOS y Android (las plataformas móviles y de escritorio tienen un pequeño paso extra para configurar un servidor personalizado; la documentación cubre cada una, y tu servidor incluso sirve páginas de ayuda en /windows y /apple). Con dos dispositivos dentro, ejecuta tailscale status y haz ping entre ellos: tienes un mesh.

Para SSO en lugar de gestión de usuarios por CLI, el soporte de OIDC de Headscale es sólido: apúntalo a Authentik, Keycloak, Entra ID o Google (activa PKCE, como recomienda la documentación) y el registro de dispositivos se convierte en un simple login por navegador.

Paso 4: las ACL

De fábrica, cada node llega a cada node, lo cual está bien para una sola persona, no para una red con servidores de distinta sensibilidad. La policy es un archivo HuJSON (JSON con comentarios), el mismo formato que usa Tailscale:

// /etc/headscale/policy.hujson
{
  "tagOwners": { "tag:server": ["jesse@"] },
  "acls": [
    // everyone reaches web things on servers
    { "action": "accept", "src": ["*"], "dst": ["tag:server:80,443"] },
    // only jesse reaches SSH anywhere
    { "action": "accept", "src": ["jesse@"], "dst": ["*:22"] }
  ]
}

Referéncialo mediante policy.path en la configuración y recarga el servicio para aplicar los cambios. Notas sobre el estado actual del proyecto: el motor de políticas es v2 (groups, tags, autogroups como autogroup:internet para el control de exit-nodes), la sintaxis más nueva de grants es hacia donde va el proyecto, y una carencia honesta: los groups de OIDC todavía no se pueden usar en las reglas de policy. El pensamiento default-deny aplica aquí exactamente igual que en cualquier firewall: escribe los accepts que quieres decir, nada más.

Paso 5: tu propio relé DERP (opcional, merece la pena)

Cuando dos peers no consiguen abrir una conexión directa (NAT estricto en ambos extremos, UDP bloqueado), el tráfico cae en un relé DERP. Por defecto eso significa la flota de relés públicos de Tailscale: funcional, pero el único momento en que tu mesh autoalojado depende silenciosamente de la infraestructura de otro, con la latencia que tenga su node más cercano. Headscale integra un servidor DERP; activarlo mantiene el tráfico relayado en tu propia máquina:

derp:
  server:
    enabled: true
    stun_listen_addr: "0.0.0.0:3478"

Abre 3478/udp directamente hacia el servidor (STUN no puede pasar por un reverse proxy). Los paquetes que pasan por el relé siguen cifrados con WireGuard de extremo a extremo (DERP solo reenvía texto cifrado; no puede leer nada), así que la ganancia aquí está en la latencia y la autosuficiencia, no en la confidencialidad. En una red bien peerada la diferencia se nota: tu peor escenario pasa a ser un salto a través de tu propio servidor de baja latencia en vez de un rodeo por un relé público lejano.

Gestionar Headscale

• Copias de seguridad: todo el estado se reduce a tres cosas: /var/lib/headscale/ (base de datos + noise key), /etc/headscale/ (config + policy). Haz snapshots o copias de esos archivos; restaurar en una máquina nueva es copiar y arrancar.
• Actualizaciones: lee el changelog (el proyecto es honesto sobre los breaking changes: la v0.26 reemplazó el motor de políticas; la v0.29 cambió la semántica de los wildcards), luego instala el nuevo .deb y reinicia. Los clientes se reconectan automáticamente.
• Recursos: el proyecto no publica cifras de dimensionamiento y no las necesita; coordina sin esfuerzo cientos de dispositivos con hardware mínimo. La única nota de los mantenedores sobre escalado: el coste es el recálculo del map ligado a CPU cuando la topología cambia mucho, así que lo que importa es el número y la rotación de conexiones, no el tráfico; los datos fluyen peer-to-peer y nunca pasan por el servidor de coordinación (salvo en el fallback a DERP, arriba).
• Visibilidad: deliberadamente no hay una web UI incluida; la CLI cubre la administración, y las UI de terceros (headscale-admin, Headplane y similares) existen como proyectos de la comunidad; trátalas como tal, y ten en cuenta que algunas requieren la policy en modo database.

Los límites, con honestidad

Elige Headscale sabiendo lo que no es. Un único tailnet: sin multi-tenancy, por diseño y según su propia FAQ. Gestionado por la comunidad: es una reimplementación open source independiente (con un empleado de Tailscale que ha contribuido a título personal, históricamente), no un producto de fabricante con un SLA; las funciones nuevas de Tailscale llegan cuando se reimplementan, no el día de su lanzamiento. Tú eres el operador: las renovaciones de TLS, las actualizaciones, las copias de seguridad y el aviso a las 3 de la madrugada son cosa tuya. Si esas contrapartidas te suenan a costes en vez de a la esencia del asunto, el nivel gratuito hospedado de Tailscale (o NetBird, según nuestra comparativa) es la herramienta que mejor encaja. Si te suenan a soberanía, adelante; este es uno de los proyectos autoalojados más gratificantes que hay: mucha utilidad, una superficie operativa mínima.

Preguntas frecuentes

¿Headscale está listo para producción?

Para el alcance previsto (el tailnet de una sola organización, gestionado por alguien cómodo administrando un servicio Linux) sí: el proyecto es maduro, se publica activamente, y se usa ampliamente exactamente para eso. Las salvedades son de alcance, no de calidad: sin multi-tenancy, sin contrato de soporte del fabricante, y de vez en cuando breaking changes entre versiones menores, que dan por hecho un administrador que lee los changelogs. Aplícalo a una flota de tus propios servidores y dispositivos y es sólido; estíralo hacia "producto para clientes" y te sales de su diseño.

¿Por qué mis dispositivos se conectan pero el tráfico va lento a través del servidor?

Han caído en el relaying de DERP, normalmente visible en tailscale status como una etiqueta relay en lugar de una dirección directa. Las rutas WireGuard directas nunca tocan tu servidor Headscale, así que "todo pasa por el servidor" significa que el NAT traversal falló (NAT estricto, UDP bloqueado) y los paquetes viajan por el relé. Soluciones en orden: comprueba que UDP no esté bloqueado en ninguno de los dos extremos, activa el DERP integrado (para que el fallback sea al menos tu propio relé rápido), y en pares relayados de forma permanente comprueba si un lado puede abrir un puerto directo; un servidor dedicado con UDP abierto es un anchor node ideal, siempre directo.

¿Puedo usar mi mesh para llegar a la red privada/de gestión de mis servidores?

Sí. Este es exactamente el caso de uso de operador que destacaba el artículo comparativo. Ejecuta un node dentro del segmento privado como subnet router (tailscale up --advertise-routes=10.0.0.0/24 ..., aprobado con headscale nodes approve-routes), y los miembros autorizados del mesh llegan a todo el segmento (IPMI, servicios internos) sin que nada de eso tenga un listener público. Protege la ruta detrás de una ACL estricta y trata el node subnet router con el mismo cuidado que un bastión; ahora es el puente hacia tu red más sensible.

¿Cómo se compara esto con simplemente usar WireGuard?

Headscale es WireGuard por debajo; lo que añades es el control plane: distribución automática de claves, NAT traversal, MagicDNS, ACL, y apps móviles que pueden usar quienes no son expertos. Para dos servidores estáticos, WireGuard puro sigue siendo más simple. El punto de cruce llega con dispositivos itinerantes, un número creciente de peers, o personas que merecen una app con un interruptor, momento en el que Headscale ofrece la experiencia de producto conservando la propiedad de WireGuard puro que de verdad importaba: la infraestructura de nadie más en tu control path.

Desplegar en Serverside

Un host de Headscale quiere exactamente lo que aquí ofrece un pequeño servidor dedicado o una instancia cloud: una máquina always-on con una IP pública estable en una red bien peerada (ASN 55285, donde tu relé DERP integrado de verdad se gana su ventaja de latencia) detrás de mitigación DDoS permanente, ya que el único listener público de tu servidor de coordinación merece protección. Los meshes más grandes que anclan subnet routers en redes privadas encajan de forma natural con la línea dedicada.

Lectura relacionada: la decisión de VPN mesh que esta guía lleva a la práctica, las reglas de firewall para el host de debajo, y la checklist de hardening que conviene repasar antes de todo esto.