Migrar de Tailscale a Headscale: el punto de equilibrio

Por qué replantear la red mesh en 2026

• Control total de los datos: ninguna lista de sus máquinas, direcciones IP internas, nombres de nodos o registros de conexión pasa por un servidor de terceros.
• Sin límites de nodos ni usuarios impuestos por el software: Headscale está limitado únicamente por los recursos de su VPS.
• Compatibilidad total con los clientes oficiales de Tailscale: la bandera --login-server es suficiente para apuntar a su propio plano de control.
• MagicDNS en su propio dominio: cada nodo es accesible por su nombre corto bajo el sufijo que elija.
• OIDC opcional: delegue la autenticación a Keycloak, Authelia o cualquier proveedor OIDC compatible.
• Durabilidad operativa: su red mesh ya no depende de una decisión de precios o una interrupción externa.
• Mantenimiento razonable: una actualización de paquete cada pocas semanas, una copia de seguridad de SQLite programable en una línea de cron.

Análisis financiero: el punto de equilibrio

Tailscale Standard vs Headscale en VPS

Desplace la tabla

Requisitos técnicos detallados

• VPS con Debian 11/12 o Ubuntu 22.04/24.04 — 1 vCPU, 512 MB RAM mínimo (Headscale funciona con menos de 64 MB en reposo; se recomiendan 1 GB para mayor margen).
• Puerto TCP 443 abierto para tráfico entrante: los clientes se conectan aquí para el registro y la recuperación de configuración vía HTTPS.
• Puerto UDP 3478 abierto: se usa para la negociación STUN (descubrimiento de direcciones candidatas para conexiones directas).
• Puerto UDP 41641 abierto: puerto de señalización WireGuard que los clientes Tailscale usan para contactar con el coordinador.
• Un nombre de dominio o subdominio apuntando al VPS: necesario para un certificado TLS válido. Let's Encrypt funciona mediante certbot o el módulo nginx integrado.
• SQLite integrado: Headscale no necesita ninguna base de datos externa — un único archivo SQLite en /var/lib/headscale/ es suficiente para cientos de nodos.

Instalar Headscale en un VPS de ServOrbit

1. 01

   Actualizar el sistema e instalar dependencias

   Conéctese por SSH y actualice los paquetes:

   apt update && apt upgrade -y

   Instale nginx y certbot para el reverse proxy HTTPS:

   apt install -y nginx certbot python3-certbot-nginx

2. 02

   Descargar e instalar el paquete Headscale

   Headscale v0.29.4 (septiembre 2026) proporciona paquetes .deb para amd64 y arm64. Descargue e instale:

   curl -Lo /tmp/headscale.deb https://github.com/juanfont/headscale/releases/download/v0.29.4/headscale_0.29.4_linux_amd64.deb

   dpkg -i /tmp/headscale.deb

   Verifique la instalación: headscale version debe devolver 0.29.4. En ARM64, sustituya linux_amd64 por linux_arm64.

3. 03

   Configurar Headscale

   El paquete crea el usuario del sistema headscale y el directorio /etc/headscale/. Edite la configuración mínima:

   nano /etc/headscale/config.yaml

   Defina como mínimo: server_url: https://headscale.your-domain.com, listen_addr: 0.0.0.0:8080, db_type: sqlite3, db_path: /var/lib/headscale/db.sqlite, y en dns_config: magic_dns: true, base_domain: your-domain.com. Cree el directorio de datos: mkdir -p /var/lib/headscale && chown headscale:headscale /var/lib/headscale.

4. 04

   Activar e iniciar el servicio

   El paquete instala la unidad de systemd automáticamente:

   systemctl enable --now headscale

   Compruebe el estado: systemctl status headscale. La salida debe mostrar Active: active (running). Si hay un error, consulte los registros: journalctl -u headscale -f. El error más frecuente en el primer inicio es un server_url malformado — debe comenzar con https://.

5. 05

   Configurar el reverse proxy HTTPS

   Obtenga un certificado Let's Encrypt y configure nginx:

   certbot --nginx -d headscale.your-domain.com

   En el vhost de nginx generado, añada en el bloque location /:

   proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;

   Recargue nginx: systemctl reload nginx. Verifique que https://headscale.your-domain.com/health devuelve {"status":"pass"}.

6. 06

   Crear el primer usuario y una clave de autenticación previa

   Headscale organiza los nodos por usuarios. Cree su primer usuario:

   headscale users create mi-equipo

   Genere una clave de autenticación previa (preauthkey) para registrar máquinas sin aprobación manual:

   headscale preauthkeys create --user mi-equipo --expiration 24h

   Copie la clave devuelta — la necesitará al migrar los clientes. La opción --reusable permite reutilizar la misma clave para varias máquinas.

7. 07

   Abrir los puertos necesarios en el cortafuegos

   Si su VPS usa ufw, abra los puertos necesarios:

   ufw allow 443/tcp
ufw allow 3478/udp
ufw allow 41641/udp

   Si usa iptables directamente o un panel de seguridad (CSF, Imunify360), añada estos puertos a la lista de puertos entrantes permitidos. Verifique desde una máquina externa que los puertos UDP son accesibles antes de migrar sus clientes.

Migrar los clientes desde Tailscale en 3 pasos

1. 08

   Desconectar el cliente de la red Tailscale existente

   En cada máquina a migrar, desconecte el cliente de la red Tailscale:

   tailscale logout

   En macOS y Windows, use el menú de la bandeja del sistema: clic derecho en el icono de Tailscale → Log out. En iOS y Android, vaya a los ajustes de la aplicación → Log out. Este paso revoca la autenticación en la red antigua pero no desinstala el cliente.

2. 09

   Reconectar el cliente a su servidor Headscale

   Reconecte el cliente apuntando a su nuevo servidor Headscale. En Linux:

   tailscale up --login-server https://headscale.your-domain.com --authkey SU_PREAUTHKEY

   En macOS, desde el terminal:

   tailscale up --login-server https://headscale.your-domain.com --authkey SU_PREAUTHKEY

   Si no pasa una preauthkey, el cliente muestra una URL de autenticación para validar en el lado del servidor con: headscale nodes register --user mi-equipo --key <NODE_KEY>. Verifique el registro: headscale nodes list debe mostrar el nodo con estado online.

3. 10

   Verificar la conectividad entre los nodos migrados

   Desde un nodo migrado, verifique que los demás nodos son visibles:

   tailscale status

   La lista debe mostrar todos los nodos registrados en su servidor Headscale con sus IPs mesh (100.64.x.x). Pruebe la conectividad directa con un ping: ping 100.64.0.2. Un estado active (direct) confirma que la conexión WireGuard está establecida sin relé. Si activó MagicDNS, pruebe la resolución: ping nombre-nodo.your-domain.com.

4. 11

   Migrar los nodos restantes y cerrar la cuenta de Tailscale

   Repita los dos pasos anteriores para cada máquina. Migre primero las máquinas de desarrollo o prueba para validar el proceso, luego las de producción. Una vez migrados y verificados todos los nodos, puede cerrar su cuenta de Tailscale o degradar al plan Personal si aún tiene casos de uso personal (seis usuarios máximo, gratuito). Conserve la preauthkey utilizada o genere una nueva para futuros nodos.

Configuración de ACLs y DNS internos

• Edite el archivo de política: headscale policy set --policy-file /etc/headscale/policy.hujson
• Defina grupos de usuarios (groups) y ACLs por puerto para segmentar el acceso entre los entornos dev, staging y prod.
• Active el split DNS para resolver nombres internos: en dns_config, defina nameservers con sus servidores DNS internos y search_domains para los sufijos de búsqueda.
• Exporte y versione su archivo de política en un repositorio Git privado — esto facilita las auditorías y los retrocesos.
• Pruebe los cambios de política en un nodo de prueba antes de aplicarlos a toda la red: headscale policy check.

Resolución de problemas frecuentes

• El nodo aparece como offline en headscale nodes list: verifique que los puertos UDP 3478 y 41641 están abiertos en el VPS. Pruebe desde una máquina externa con nc -vzu headscale.your-domain.com 41641.
• La conexión muestra relay en lugar de direct: las conexiones indirectas vía DERP ocurren cuando los dos nodos no pueden alcanzarse directamente (NAT estricto, cortafuegos). Ejecute tailscale netcheck en ambos nodos para identificar las restricciones de red.
• MagicDNS no resuelve los nombres: verifique que magic_dns: true y base_domain están definidos en la configuración de Headscale, y que el cliente recuperó la nueva configuración DNS tras la reconexión (tailscale status --self).
• Certificado TLS inválido al iniciar: el server_url en config.yaml debe coincidir exactamente con el dominio del certificado. Una URL que empieza con http:// cuando nginx espera https:// genera un bucle infinito de redirección.
• Los clientes de macOS o Windows no ven la opción --login-server en la interfaz gráfica: use siempre el terminal para la migración. La interfaz gráfica de Tailscale no permite cambiar el servidor de coordinación; solo la línea de comandos lo admite.

Lo que Headscale no reemplaza