Por qué reemplazar el servidor de coordinación en la nube de Tailscale
Tailscale delega la orquestación WireGuard a un servicio en la nube de terceros. Headscale reproduce esta función como código abierto en tu VPS — sin dependencia externa, los datos de topología permanecen en tu infraestructura.
Tailscale no transporta su tráfico de red: los paquetes WireGuard viajan directamente de nodo a nodo, cifrados de extremo a extremo. Lo que Tailscale gestiona a través de su nube es el plano de control — intercambio de claves públicas, descubrimiento de pares, asignación de direcciones IP en la subred 100.x.x.x, resolución MagicDNS y distribución de relés DERP. Sin este servidor de coordinación, los nodos no pueden encontrarse. Headscale es la implementación de código abierto de este servidor: habla exactamente el mismo protocolo que el controlador Tailscale, lo que significa que sus clientes Tailscale existentes funcionan sin modificación — solo necesita indicarles una nueva URL de inicio de sesión.
- Privacidad de metadatos: ninguna lista de sus máquinas, direcciones IP internas o nombres de nodos pasa por un servidor de terceros. El plano de control permanece en su infraestructura.
- Sin límite de nodos impuesto: Headscale no fija un techo en el número de máquinas registradas — usted está limitado por los recursos de su VPS, no por una tabla de precios.
- Sin límite de usuarios: el plan gratuito de Tailscale está restringido a 3 usuarios; Headscale gestiona tantos usuarios como usted cree.
- BYOD sin cuenta Tailscale: sus colaboradores se conectan mediante la clave de pre-autenticación que usted genera, sin necesidad de crear una cuenta en tailscale.com.
- Integración OIDC opcional: Headscale admite la delegación de autenticación a un proveedor OIDC (Keycloak, Authelia, Google Workspace) para equipos que ya tienen SSO.
- Servidores DERP personalizables: puede configurar sus propios relés DERP en sus VPS para minimizar la latencia de conexiones que no pueden ser directas.
- Longevidad: su red mesh no depende de decisiones comerciales de un proveedor externo, ni de posibles interrupciones de su infraestructura.
Requisitos previos antes de comenzar
Antes de instalar Headscale, comprueba que tu entorno cumple los siguientes requisitos.
- Un VPS con Debian 11/12 o Ubuntu 22.04/24.04, con al menos 1 GB de RAM y acceso root — Headscale consume menos de 50 MB en funcionamiento normal.
- El puerto UDP 41641 accesible desde Internet en el VPS servidor: este es el puerto de señalización WireGuard que los clientes Tailscale usan para contactar al coordinador.
- El puerto TCP 443 u 8080 abierto para la API HTTP/HTTPS de Headscale.
- Cliente Tailscale instalado en cada nodo que desee conectar — la aplicación oficial Tailscale funciona tal cual con Headscale.
- Opcional: un nombre de dominio apuntando a su VPS si desea habilitar HTTPS con un certificado Let's Encrypt y MagicDNS en un sufijo personalizado.
Instalación de Headscale en el VPS Debian/Ubuntu
Headscale se instala mediante el paquete oficial .deb. La instalación incluye el binario, el servicio systemd y la configuración de nginx que sirve la API gRPC y la interfaz DERP.
Descargar e instalar el binario de Headscale
Headscale distribuye paquetes
.debpara amd64 y arm64. Obtenga la versión reciente desde las releases de GitHub e instálela condpkg:HEADSCALE_VERSION=$(curl -s https://api.github.com/repos/juanfont/headscale/releases/latest | grep tag_name | cut -d '"' -f4 | tr -d 'v') curl -Lo /tmp/headscale.deb \ https://github.com/juanfont/headscale/releases/latest/download/headscale_${HEADSCALE_VERSION}_linux_amd64.deb dpkg -i /tmp/headscale.debEn ARM64, reemplace
linux_amd64porlinux_arm64. Verifique la instalación:headscale versiondebe devolver el número de versión instalado.Crear el archivo de configuración YAML
El paquete crea automáticamente el usuario del sistema
headscaley el directorio/etc/headscale/. Edite el archivo de configuración principal:nano /etc/headscale/config.yamlConfiguración mínima funcional:
server_url: https://su-dominio.com listen_addr: 0.0.0.0:8080 metrics_listen_addr: 127.0.0.1:9090 grpc_listen_addr: 127.0.0.1:50443 grpc_allow_insecure: false private_key_path: /var/lib/headscale/private.key noise: private_key_path: /var/lib/headscale/noise_private.key ip_prefixes: - fd7a:115c:a1e0::/48 - 100.64.0.0/10 derp: server: enabled: false urls: - https://controlplane.tailscale.com/derpmap/default auto_update_enabled: true update_frequency: 24h db_type: sqlite3 db_path: /var/lib/headscale/db.sqlite dns_config: override_local_dns: true nameservers: - 1.1.1.1 magic_dns: true base_domain: su-dominio.comReemplace
su-dominio.compor su dominio real. El valorserver_urldebe corresponder a la URL que sus clientes pueden alcanzar desde Internet.Crear los directorios de datos y generar las claves
Cree el directorio de datos y asígnele los permisos correctos:
mkdir -p /var/lib/headscale chown headscale:headscale /var/lib/headscaleEjecute Headscale una vez para generar automáticamente las claves privadas:
headscale generate private-keyNunca comparta estos archivos y guarde una copia de seguridad — son la identidad de su servidor de coordinación.
Activar e iniciar el servicio systemd
El paquete
.debinstala la unidad systemd automáticamente. Actívela al inicio e inicie el servicio:systemctl enable --now headscale systemctl status headscaleLa salida debe mostrar
Active: active (running). Consulte los registros en tiempo real si el servicio no arranca:journalctl -u headscale -fLos errores frecuentes en el primer arranque son un
server_urlmal formado (debe comenzar porhttps://ohttp://) o un directorio/var/lib/headscaleinaccesible.Exponer Headscale mediante un proxy inverso HTTPS (recomendado)
Para que los clientes se conecten por HTTPS, coloque Headscale detrás de nginx con un certificado Let's Encrypt:
apt install -y nginx certbot python3-certbot-nginx certbot --nginx -d su-dominio.comConfiguración nginx para Headscale (
/etc/nginx/sites-available/headscale):server { listen 443 ssl; server_name su-dominio.com; ssl_certificate /etc/letsencrypt/live/su-dominio.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/su-dominio.com/privkey.pem; location / { proxy_pass http://localhost:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }Active el sitio y recargue nginx:
ln -s /etc/nginx/sites-available/headscale /etc/nginx/sites-enabled/ nginx -t && systemctl reload nginx
Conexión de los nodos cliente al servidor Headscale propio
Una vez que el servidor Headscale está operativo, cada máquina cliente ejecuta el daemon de Tailscale apuntando a tu URL de Headscale en lugar de los servidores de Tailscale Inc.
Crear un usuario en Headscale
Headscale organiza los nodos por usuarios. Cree un primer usuario desde el VPS servidor:
headscale users create mi-equipo headscale users listGenerar una clave de pre-autenticación (preauthkey)
Una preauthkey permite registrar un nodo sin intervención manual. Genere una para su usuario:
headscale preauthkeys create --user mi-equipo --expiration 24hLa opción
--reusablecrea una clave reutilizable múltiples veces. Copie el valor devuelto.Conectar un nodo cliente con la opción --login-server
En cada máquina cliente (Linux, macOS, Windows, iOS, Android), se usa el cliente oficial Tailscale. En la primera conexión, indique la URL de su servidor Headscale con el indicador
--login-server:En Linux:
tailscale up --login-server https://votre-domaine.com --authkey VOTRE_PREAUTHKEYEn macOS, ejecute desde el terminal:
tailscale up --login-server https://votre-domaine.com --authkey VOTRE_PREAUTHKEYEn Windows, cree una clave de registro nueva con
--authkeyy ejecute el cliente desde una ventana de PowerShell con privilegios de administrador. Tras el primer registro con la preauthkey, no es necesario repetir el comando — el nodo se conecta automáticamente al reiniciarse.Verificar el registro del nodo
Desde el VPS servidor, liste los nodos registrados:
headscale nodes listCada nodo registrado muestra su nombre, su IP mesh (en el prefijo
100.64.x.x), el usuario al que está asignado y su estado. Un estadoonlineconfirma que el nodo está activo y pudo contactar al coordinador. Un estadoofflineodisconnectedindica que el nodo aún no se conectó o que el servicio está detenido en él.
Verificación: ¿pueden los nodos verse entre sí?
Después de registrar los nodos, verifica la conectividad de extremo a extremo antes de enrutar tráfico real a través de la red mesh.
Consultar el estado de la red desde un nodo cliente
Desde cualquier nodo cliente registrado, ejecute:
tailscale statusEl comando lista todos los pares alcanzables con su IP mesh, nombre y estado de conexión (
active (direct)oactive (relay)). Un par endirectindica que la conexión WireGuard se establece sin relé — es el caso nominal cuando los dos nodos pueden alcanzarse directamente.Probar la conectividad con ping
Identifique la IP mesh del nodo objetivo desde
tailscale status(formato100.64.x.x) y haga ping:ping 100.64.0.2Un ping que responde confirma que el túnel WireGuard está establecido entre los dos nodos y que el plano de control Headscale funciona correctamente. Si el ping falla pero el nodo aparece en
tailscale status, consulte la sección de resolución de problemas.Probar la resolución MagicDNS
Si habilitó
magic_dns: trueen la configuración de Headscale y definió unbase_domain, cada nodo es alcanzable por su nombre corto:ping nombre-del-nodo # o con el FQDN completo ping nombre-del-nodo.su-dominio.comLa resolución DNS funciona a través de la subred mesh — no se requiere ningún registro DNS público para los nombres internos. Si la resolución falla, compruebe que
dns_config.base_domainesté configurado enconfig.yamly quenameserversincluya direcciones DNS válidas. Esta función solo opera en los nodos que ejecutan tailscaled con la configuración completa.
Tailscale gratuito vs Headscale: comparación factual
Desplace la tabla
| Criterio | Tailscale gratuito | Headscale (autogestionado) |
|---|---|---|
| Número de usuarios | 3 usuarios máximo | Sin límite impuesto por el software |
| Número de nodos | 100 nodos máximo | Sin límite impuesto por el software |
| Servidor de coordinación | Nube Tailscale (infraestructura de terceros) | Su propio VPS, bajo su control |
| Costo mensual | Gratuito dentro de los límites del plan | Solo el costo del VPS |
| Cliente utilizado | Cliente Tailscale oficial | Cliente Tailscale oficial (compatible, --login-server) |
| MagicDNS | Sí, en tailnet gestionada por Tailscale | Sí, en su dominio personalizado |
| OIDC / SSO | Disponible en planes de pago | Disponible gratuitamente mediante configuración YAML |
| Mantenimiento operacional | Ninguno (servicio gestionado) | Actualizaciones de paquetes, copia de seguridad de claves |
Caso de uso: acceso SSH entre VPS dev y prod sin exponer el puerto 22
La red mesh de Headscale permite el acceso SSH entre servidores sin abrir el puerto 22 en la interfaz pública — la conexión viaja a través de la IP interna de Tailscale a través del túnel WireGuard.
Uno de los casos de uso más habituales de una red mesh es el acceso SSH entre máquinas sin exponer el puerto 22 a Internet. Con Headscale, sus VPS de dev y prod están registrados en la misma red mesh. Así se restringe SSH para que solo sea accesible a través del mesh.
Identificar las interfaces y direcciones mesh
En cada VPS, la interfaz WireGuard creada por Tailscale se llama
tailscale0:tailscale ip -4Anote la IP mesh del VPS de prod (ej.
100.64.0.3) y la del VPS de dev (ej.100.64.0.2).Configurar UFW para restringir SSH a la red mesh
En el VPS de producción, modifique las reglas UFW para permitir SSH solo desde la subred mesh y bloquear el resto:
# Permitir SSH desde la subred mesh Headscale ufw allow in on tailscale0 to any port 22 proto tcp # Bloquear SSH desde Internet ufw deny 22 ufw enableVerifique el estado de las reglas:
ufw status verboseEl puerto 22 ya no es accesible desde Internet, pero sigue siendo alcanzable desde cualquier nodo de la red mesh.
Conectarse por SSH a través de la red mesh
Desde el VPS de dev o su estación de trabajo registrada en la misma red mesh:
ssh [email protected] # o vía MagicDNS si está habilitado ssh [email protected]La conexión transcurre completamente dentro del túnel WireGuard cifrado. Ningún puerto está abierto públicamente en el VPS de prod.
Endurecimiento: active las ACL de Headscale (acls: en config.yaml) para definir con precisión qué nodos pueden contactar a qué otros nodos y en qué puertos. Active los logs de auditoría (log: level: info). Actualice Headscale regularmente — la compatibilidad con versiones recientes del cliente Tailscale se mantiene en las versiones recientes del servidor.
Resolución de problemas: los errores más frecuentes
Los problemas más comunes al desplegar Headscale tienen que ver con la conectividad de red, los certificados TLS y la sincronización de claves WireGuard.
Puerto UDP 41641 cerrado. Es la causa más habitual de fallo en la conexión directa entre nodos. El puerto 41641 debe estar abierto en UDP en el VPS servidor para que los nodos puedan establecer sus túneles WireGuard. Verifique con ufw status y ábralo si es necesario: ufw allow 41641/udp. Si el puerto permanece cerrado, las conexiones pasan al modo relé DERP — los nodos funcionan pero con mayor latencia.
Problema de DERP: nodos visibles pero no alcanzables. Headscale usa la carta DERP pública de Tailscale por defecto (controlplane.tailscale.com/derpmap/default). Si su VPS está en una región no cubierta o si el HTTPS saliente está filtrado, los relés DERP son inaccesibles. Verifique con tailscale netcheck desde un nodo cliente — el comando mide la latencia hacia cada región DERP e indica las inaccesibles.
Clock skew: error de autenticación. Headscale usa tokens JWT con expiración corta. Si el reloj del VPS servidor o de un nodo cliente se desvía más de unos minutos, los tokens son rechazados con token is expired o token is not yet valid. Sincronice el reloj: systemctl enable --now systemd-timesyncd en Debian/Ubuntu.
Nodo que se registra pero aparece offline. El nodo contactó el servidor al registrarse pero no mantiene conexión continua. Verifique que el servicio Tailscale esté en ejecución: systemctl status tailscaled. Consulte los logs: journalctl -u tailscaled -f. El problema suele ser un cortafuegos local que bloquea las conexiones UDP salientes.
Headscale: recuperar el control de su red mesh
Headscale convierte una suscripción a un servicio en la nube propietario en infraestructura de red que operas, auditas y amplías tú mismo — sin cambiar la experiencia del lado del cliente.
Headscale traslada el servidor de coordinación Tailscale de la infraestructura de un tercero a su propio VPS. El resultado es una red WireGuard mesh funcionalmente idéntica — los mismos clientes, el mismo MagicDNS, el mismo comportamiento de traversal NAT — pero completamente bajo su control. Para los equipos que superan los 3 usuarios o 100 nodos del plan gratuito de Tailscale, Headscale es una alternativa directa sin cambios en las herramientas del lado del cliente. La instalación descrita aquí lleva menos de veinte minutos; el mantenimiento se reduce a actualizar un paquete Debian y hacer copias de seguridad de dos archivos de claves.
