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 ilimitados: sin tope de 3 usuarios ni tarifas por puesto; su red mallada crece con su equipo.
• 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 (machine.headnet.local) sin tocar su DNS público.
• Listas de control de acceso HuJSON: el mismo formato de política de ACL que Tailscale; 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 despliegue su propio relé privado.
• API REST y CLI headscale: cree namespaces, emita claves de preautenticación y gestione los pares mediante programación.
• 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

Desplegar Headscale con Docker Compose

1. 01

   Redactar el archivo Compose

   Cree /opt/headscale/compose.yaml. La stack solo tiene un servicio: headscale/headscale:0.29.2. Headscale almacena todo (claves, base de datos, registros de los nodos) en volúmenes Docker con nombre, montados en /etc/headscale (configuración) y /var/lib/headscale (datos). No hace falta ningún servicio externo de base de datos ni de caché; SQLite viene integrado.

2. 02

   Generar la configuración

   Headscale lee su configuración desde /etc/headscale/config.yaml. El único campo obligatorio es server_url: la URL HTTPS a la que se conectarán sus clientes Tailscale (por ejemplo https://vpn.su-dominio.com). Defina listen_addr: 0.0.0.0:8080 y database.type: sqlite3 con una ruta bajo /var/lib/headscale. Las rutas de las claves privadas (private_key_path, noise.private_key_path) las genera Headscale automáticamente en el primer arranque si no existen. 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. Headscale genera automáticamente su clave privada WireGuard y su clave noise, y luego se pone a escuchar en el puerto 8080. Compruebe el endpoint de salud: curl -s http://localhost:8080/health debe devolver {"status":"pass"}. La CLI headscale está disponible dentro del contenedor: docker exec headscale headscale version para confirmar la versión en ejecución.

4. 04

   Crear un usuario y generar una clave de autenticación

   Tailscale organiza los dispositivos en «usuarios» (antes llamados namespaces). Cree uno: docker exec headscale headscale users create myteam. Genere después una clave de preautenticación para registrar los dispositivos: docker exec headscale headscale preauthkeys create --user myteam --reusable --expiration 24h. 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. Repita la operación con cada dispositivo. Una vez registrados, los dispositivos pueden comunicarse entre sí por su IP de malla (100.x.x.x) o por su nombre de host de magic DNS.

6. 06

   Definir las políticas de control de acceso

   Cree /etc/headscale/acls.hujson y referéncielo en config.yaml mediante acls_path. Headscale usa el mismo formato de ACL HuJSON que Tailscale Cloud: defina grupos de usuarios, etiquete los dispositivos como servidores o estaciones de trabajo, y escriba reglas que precisen qué grupos pueden alcanzar qué puertos. Una política mínima permite a todos los usuarios alcanzar todos los nodos; refuércela restringiendo el acceso a los servicios sensibles (bases de datos, paneles de administración) a grupos de usuarios concretos.

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 headscale preauthkeys create --user monuser --reusable --expiration 24h, y conecte sus máquinas con tailscale up --login-server https://<su-dominio> --authkey <clave>.

Headscale frente a Tailscale Cloud