Alojar Headscale en un VPS: servidor de control Tailscale

Por qué auto-alojar el servidor de control

Lo que le aporta Headscale auto-alojado

• Usuarios y dispositivos sin tope: ningún límite impuesto por el software ni tarifas por puesto; su red mallada crece con su equipo, limitada solo por los recursos del VPS.
• Los clientes oficiales de Tailscale en todas partes: Linux, macOS, Windows, iOS, Android; no hace falta ningún fork propio ni cliente alternativo.
• Túneles WireGuard punto a punto: Headscale solo gestiona el intercambio de claves y la distribución de las ACL; todo el tráfico real circula directamente por WireGuard entre los pares.
• Magic DNS: resuelva cada nodo de su red mallada por su nombre de host (portatil.mesh.su-dominio.com) sin tocar su DNS público.
• Políticas HuJSON: el mismo formato de archivo de política que Tailscale, con ACL y Grants; defina qué usuarios y qué dispositivos pueden acceder a qué servicios.
• Compatibilidad con los relés DERP: use el mapa DERP público de Tailscale para atravesar el NAT, o active el servidor DERP integrado en Headscale para mantener también los relés en casa.
• API y CLI headscale: cree usuarios, emita claves de preautenticación y gestione los nodos mediante programación.
• Registro sin cuenta en tailscale.com: sus colaboradores se unen a la red con una clave que usted genera, o a través del proveedor OpenID Connect que ya utiliza (Keycloak, Authelia, Google Workspace…).
• Subredes, exit nodes, Taildrop y Tailscale SSH: el servidor admite las funciones básicas de Tailscale.
• Menos de 50 MB de RAM en reposo: funciona con holgura en un VPS de 1 GB junto a otras cargas de trabajo.

Requisitos previos

Los puertos que hay que abrir en el VPS

• TCP 443: obligatorio. Por HTTPS se registran los clientes y reciben el mapa de la red; es el único puerto imprescindible para el servidor de coordinación.
• TCP 80: solo para la validación Let's Encrypt HTTP-01 y la redirección a HTTPS.
• UDP 3478: solo si activa el servidor DERP integrado, que lo necesita para STUN. Con el mapa DERP público de Tailscale no hace falta abrirlo.
• TCP 8080 (Headscale), 9090 (métricas) y 50443 (gRPC): déjelos en 127.0.0.1. El reverse proxy habla con 8080 en local; no exponga nunca la interfaz de administración gRPC si no la necesita.

Desplegar Headscale con Docker Compose

1. 01

   Redactar el archivo Compose

   La stack solo tiene un servicio: la imagen oficial docker.io/headscale/headscale:0.29.7, última versión estable a 7 de noviembre de 2026, lanzada con el comando serve. Headscale guarda todo (claves, base de datos, registros de los nodos) en dos carpetas del host: la configuración, montada en solo lectura en /etc/headscale, y los datos, en /var/lib/headscale. No hace falta ningún servicio externo de base de datos ni de caché; SQLite viene integrado.

   mkdir -p /opt/headscale/config /opt/headscale/lib
   cat > /opt/headscale/compose.yaml <<'EOF'
   services:
     headscale:
       image: docker.io/headscale/headscale:0.29.7
       container_name: headscale
       restart: unless-stopped
       read_only: true
       tmpfs:
         - /var/run/headscale
       ports:
         - "127.0.0.1:8080:8080"
       volumes:
         - /opt/headscale/config:/etc/headscale:ro
         - /opt/headscale/lib:/var/lib/headscale
       command: serve
       healthcheck:
         test: ["CMD", "headscale", "health"]
   EOF

   El puerto solo se publica en 127.0.0.1: es el reverse proxy el que da la cara a Internet.

2. 02

   Generar la configuración

   Parta del archivo de ejemplo de la versión exacta que despliega y modifique solo las claves siguientes. server_url es la URL HTTPS a la que se conectarán sus clientes Tailscale; listen_addr debe escuchar en 0.0.0.0 dentro del contenedor. La base de datos se declara bajo database (type: sqlite). Solo queda indicar la ruta de la clave noise: Headscale la genera en el primer arranque si el archivo no existe.

   curl -Lo /opt/headscale/config/config.yaml \
     https://raw.githubusercontent.com/juanfont/headscale/v0.29.7/config-example.yaml

   server_url: https://vpn.su-dominio.com
   listen_addr: 0.0.0.0:8080
   noise:
     private_key_path: /var/lib/headscale/noise_private.key
   database:
     type: sqlite
     sqlite:
       path: /var/lib/headscale/db.sqlite
   dns:
     magic_dns: true
     base_domain: mesh.su-dominio.com

   En ServOrbit, el job de aprovisionamiento escribe config.yaml a partir de su dominio automáticamente.

3. 03

   Arrancar el contenedor y verificar

   Ejecute docker compose up -d desde /opt/headscale. Headscale genera su clave noise y luego se pone a escuchar en el puerto 8080. Compruebe el endpoint de salud: curl -s http://127.0.0.1:8080/health debe devolver {"status":"pass"}. La imagen se basa en una base distroless, sin shell, pero la CLI headscale se invoca directamente: docker exec headscale headscale version confirma la versión en ejecución y docker logs --follow headscale muestra los registros.

4. 04

   Crear un usuario y generar una clave de autenticación

   Headscale organiza los dispositivos en «usuarios» (antes llamados namespaces). Cree uno y anote su identificador numérico: la opción --user de preauthkeys create espera ese ID, no el nombre.

   docker exec headscale headscale users create myteam
   docker exec headscale headscale users list
   docker exec headscale headscale preauthkeys create --user 1 --reusable --expiration 24h

   Sin --reusable, la clave solo sirve una vez, y sin --expiration caduca al cabo de una hora. Copie la clave que se muestra: la usará para registrar cada dispositivo.

5. 05

   Registrar un dispositivo

   En cualquier dispositivo que tenga el cliente oficial de Tailscale, apúntelo a su instancia de Headscale: tailscale up --login-server https://vpn.su-dominio.com --authkey <su-clave-preauth>. El dispositivo aparece en la lista de nodos de Headscale en unos segundos: docker exec headscale headscale nodes list. Sin clave, el cliente abre una página que muestra un identificador de autenticación; apruébelo en el servidor con docker exec headscale headscale auth register --user myteam --auth-id <AUTH_ID>. Una vez registrados, los dispositivos se comunican por su IP de malla (100.64.x.y) o por su nombre de host de magic DNS.

6. 06

   Definir las políticas de control de acceso

   Mientras no se cargue ninguna política, Headscale deja pasar todo el tráfico entre los nodos: aceptable para un equipo pequeño de confianza, no cuando conviven portátiles de desarrolladores, proveedores externos y servidores de producción. Cree /opt/headscale/config/policy.hujson y declárelo en config.yaml con policy.path: /etc/headscale/policy.hujson. Headscale usa el mismo formato HuJSON que Tailscale: defina grupos de usuarios, etiquete los dispositivos como servidores o estaciones de trabajo y escriba reglas que precisen qué grupos pueden alcanzar qué puertos. El proyecto recomienda los Grants antes que las ACL, que Tailscale considera heredadas. Valide el archivo con headscale policy check --file <archivo> y luego recargue: la política solo se relee al recargar (docker kill --signal=HUP headscale, o systemctl reload headscale en una instalación nativa). Versione este archivo en un repositorio Git privado para conservar el historial de accesos.

7. 07

   Conectarse por primera vez

   Headscale no tiene interfaz web ni cuenta: es el servidor de control de su red privada, y se pilota desde la línea de comandos. Por SSH: docker exec -it headscale headscale users create monuser, después la clave con preauthkeys create --user <ID> --reusable --expiration 24h, y conecte sus máquinas con tailscale up --login-server https://<su-dominio> --authkey <clave>. Las aplicaciones gráficas también pueden apuntar a un servidor personalizado: en macOS, Opción + clic en el icono de Tailscale, menú Debug y luego Custom Login Server; en iOS, Use custom coordination server en el menú de inicio de sesión; en Android, Use an alternate server; en Windows, tailscale login --login-server en PowerShell.

Sin Docker: el paquete .deb oficial

Instalar Headscale con el paquete .deb

1. 08

   Descargar e instalar el paquete

   Descargue el paquete de la versión deseada desde la página de releases de GitHub, para su arquitectura (amd64 o arm64), e instálelo con apt, que resuelve las dependencias:

   HEADSCALE_VERSION="0.29.7"
   HEADSCALE_ARCH="amd64"
   wget --output-document=headscale.deb \
     "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
   sudo apt install ./headscale.deb

   Compruebe después: headscale version debe mostrar 0.29.7.

2. 09

   Adaptar la configuración

   El paquete deja la configuración en /etc/headscale/config.yaml y un ejemplo actualizado en /usr/share/doc/headscale/examples/config-example.yaml. Modifique las mismas claves que para Docker (server_url, database, dns.base_domain), pero mantenga listen_addr: 127.0.0.1:8080: el servicio se ejecuta en el host y solo el reverse proxy debe alcanzarlo. Los datos residen en /var/lib/headscale.

3. 10

   Reiniciar y verificar el servicio

   Reinicie el servicio para que relea la configuración y compruebe su estado y sus registros:

   sudo systemctl restart headscale
   sudo systemctl status headscale
   sudo journalctl -u headscale -f

   La salida debe mostrar Active: active (running). En el primer arranque, los errores más frecuentes son una server_url sin el esquema https:// y un dominio MagicDNS idéntico al del servidor.

4. 11

   Usar la CLI sin ser root

   La CLI habla con el servicio a través del socket Unix /var/run/headscale/headscale.sock, al que por defecto solo acceden el usuario headscale y root. Use sudo, ejecute los comandos como usuario headscale o añada su cuenta al grupo headscale. Compruebe el acceso con headscale users list.

Servir Headscale en HTTPS detrás de Nginx

map $http_upgrade $connection_upgrade {
  default keep-alive;
  ''      close;
}

server {
  listen 80;
  server_name vpn.su-dominio.com;
  location = /generate_204 { return 204; }
  location / { return 301 https://$server_name$request_uri; }
}

server {
  listen 443 ssl;
  http2 on;
  server_name vpn.su-dominio.com;
  ssl_certificate     /etc/letsencrypt/live/vpn.su-dominio.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/vpn.su-dominio.com/privkey.pem;

  location / {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_pass http://127.0.0.1:8080;
  }
}

trusted_proxies:
  - 127.0.0.1/32
  - ::1/128

Comprobar que los nodos se ven

Controlar la malla desde un cliente

1. 12

   Leer el estado de la red

   En un nodo registrado, ejecute tailscale status. El comando lista los pares con su IP de malla, su nombre y el tipo de enlace: direct significa que el túnel WireGuard está establecido sin intermediario, relay que pasa por un relé DERP, funcional pero con una latencia mayor.

2. 13

   Probar la conectividad

   Tome la IP de un par en tailscale status y luego ping 100.64.0.2, o mejor tailscale ping <nombre-del-nodo>, que indica si la respuesta llega en directo o por un relé. Si el par aparece pero no responde, tailscale netcheck mide la latencia hacia cada región DERP y señala un UDP saliente filtrado.

3. 14

   Probar la resolución MagicDNS

   Con dns.magic_dns: true, cada nodo responde a su nombre corto y a su nombre completo: ping nombre-del-nodo o ping nombre-del-nodo.mesh.su-dominio.com. No hace falta ningún registro DNS público para estos nombres internos. Si la resolución falla, tailscale dns status muestra la configuración DNS que el cliente ha recibido del servidor.

Caso de uso: SSH entre VPS sin exponer el puerto 22

Restringir SSH a la red mallada

1. 15

   Localizar la interfaz y la dirección de malla

   En cada VPS, el cliente Tailscale crea la interfaz tailscale0. tailscale ip -4 muestra la dirección de malla de la máquina; anote la del servidor de producción, por ejemplo 100.64.0.3.

2. 16

   Permitir SSH solo por tailscale0

   En el VPS de producción, permita SSH en la interfaz de malla antes de denegarlo en el resto: UFW aplica la primera regla que coincide.

   ufw allow in on tailscale0 to any port 22 proto tcp
   ufw deny 22/tcp
   ufw enable
   ufw status verbose

   El puerto 22 ya no es accesible desde Internet, pero sigue abierto para todos los nodos de la malla que su política autorice.

3. 17

   Conectarse a través de la malla

   Desde el VPS de desarrollo o su equipo registrado, conéctese por la IP o el nombre MagicDNS: ssh [email protected] o ssh [email protected]. Todo transita dentro del túnel cifrado; después, restrinja en la política de Headscale qué grupos pueden alcanzar el puerto 22 de este servidor.

Migrar un equipo que ya usa Tailscale

Pasar los clientes a Headscale

1. 18

   Recuperar la política de acceso

   Copie el archivo de política de su tailnet desde el editor Access controls de la consola de Tailscale y parta de él: el formato HuJSON es el mismo. Revíselo con headscale policy check antes del cambio: algunas funciones, como los IP sets, no son compatibles, y solo existe un subconjunto de los autogroups.

2. 19

   Desconectar y volver a conectar cada cliente

   En Linux o desde la línea de comandos, encadene la desconexión y la reconexión con una clave de preautenticación:

   tailscale logout
   tailscale up --login-server https://vpn.su-dominio.com --authkey <PREAUTHKEY>

   En macOS, iOS, Android y Windows, cierre la sesión de la cuenta en la aplicación y añada después el servidor personalizado como se ha descrito más arriba.

3. 20

   Empezar por las máquinas de prueba

   Pase primero un equipo y un servidor de prueba, compruebe tailscale status y la resolución de nombres, luego las máquinas de desarrollo y, en último lugar, la producción. Mientras queden máquinas al otro lado, las dos redes no se ven: planifique el cambio de un servicio y de sus clientes en la misma ventana.

4. 21

   Cerrar o rebajar la cuenta de Tailscale

   Una vez migrados y verificados todos los nodos, cierre el tailnet o vuelva al plan Personal si mantiene un uso personal. Genere una clave de preautenticación nueva para los próximos registros en lugar de conservar indefinidamente la de la migración.

Headscale frente a Tailscale Cloud

Tailscale Personal, Tailscale Standard y Headscale

Desplace la tabla

Lo que Headscale no sustituye

Copias de seguridad y actualizaciones

• Haga una copia antes de cada actualización: Headscale aplica sus migraciones de base de datos al arrancar la nueva versión. Detenga el servicio, copie la configuración y los datos y vuelva a arrancarlo: cd /opt/headscale && docker compose stop, cp -aR /opt/headscale /opt/headscale.backup-$(date +%Y%m%d%H%M%S), docker compose up -d.
• La carpeta de datos contiene db.sqlite y noise_private.key: perder esa clave cambia la identidad del servidor y obliga a todos los nodos a registrarse de nuevo. Cópiela también fuera del VPS, por ejemplo en un almacenamiento de objetos.
• Suba de versión en versión: el proyecto exige pasar por cada versión menor estable (por ejemplo 0.27, luego 0.28, luego 0.29), siempre en su último parche, sin saltarse ninguna.
• Lea la nota de versión en GitHub antes de cada actualización: señala los cambios de configuración incompatibles. Después compare su config.yaml con el archivo de ejemplo de la nueva versión.

Resolución de problemas: los errores más frecuentes

• El cliente no consigue registrarse: compruebe que https://vpn.su-dominio.com/health responde desde fuera, que server_url coincide exactamente con el dominio del certificado y que el proxy transmite bien las cabeceras Upgrade y Connection.
• Conexiones en relay en lugar de direct: un NAT estricto o un cortafuegos bloquea el UDP entre los dos nodos. Ejecute tailscale netcheck en ambos lados para ver qué se filtra; el tráfico pasa igualmente, por los relés DERP.
• Nodo listado como offline: el cliente llegó al servidor pero no mantiene la sesión. Revise systemctl status tailscaled y journalctl -u tailscaled en el nodo; un cortafuegos local que corta las conexiones salientes es la causa más habitual.
• Headscale se niega a arrancar tras una actualización: se ha renombrado o retirado una clave de configuración. El registro la nombra; consulte el archivo de ejemplo de la versión instalada.
• MagicDNS no resuelve: compruebe que dns.magic_dns está en true y que dns.base_domain difiere del dominio de server_url, y vuelva a conectar el cliente para que recupere la nueva configuración DNS.