Cómo Configurar Headscale en un VPS KVM: Servidor de Control Privado para Tailscale sin Intermediarios

4/10/202633 min de lectura

Tropic

headscale vps servidor tailscale
instalar headscale vps docker
servidor control tailscale privado
red mesh wireguard vps
headscale config yaml

Resumen rápido: Para desplegar Headscale en un VPS KVM como servidor de control privado y soberano para Tailscale, la especificación de referencia para sostener hasta 250 nodos concurrentes exige un dimensionamiento base de 1 vCPU (núcleo dedicado ≥3.5 GHz), 1 GB de RAM ECC (2 GB si se activa DERP relay integrado), 20 GB de almacenamiento NVMe PCIe 4.0 y enlace simétrico de 1 Gbps con algoritmo TCP BBR. La arquitectura mantiene el plano de datos completamente distribuido mediante túneles cifrados WireGuard peer-to-peer (UDP 41641/51820), eliminando cuellos de botella en el nodo central. El plano de coordinación gestiona el intercambio de claves Noise y la topología de red sobre HTTPS/gRPC (TCP 443) junto con STUN (UDP 3478), garantizando una penetración NAT traversal determinista sin depender de la nube propietaria de terceros.

Tabla de contenidos

Ventajas de Headscale frente a Tailscale SaaS: Privacidad y Rendimiento
Configuración del Sistema Operativo y Activación de Reenvío de Paquetes IP
Despliegue de Headscale en Docker Compose con SQLite y config.yaml
Configuración de Nginx Reverse Proxy con TLS 1.3 y WebSockets
Gestión de Nodos, Usuarios y Rutas Exit-Node desde la Terminal
Automatización de Respaldos de SQLite y Plan de Recuperación ante Desastres
Preguntas frecuentes (FAQ)

Ventajas de Headscale frente a Tailscale SaaS: Privacidad y Rendimiento

La arquitectura de Tailscale se divide rígidamente en dos capas operativas: el plano de datos (data plane), que canaliza el tráfico encapsulado punto a punto mediante el protocolo WireGuard (utilizando el handshake criptográfico Noise_IKpsk2 con curvas Curve25519 y cifrado ChaCha20-Poly1305), y el plano de control (coordination plane), responsable de la distribución de llaves públicas, el mapeo de direcciones IP virtuales (CGNAT 100.64.0.0/10), la resolución DNS interna (MagicDNS), la gestión de listas de control de acceso (ACLs) y la coordinación del bypass de cortafuegos mediante STUN y el protocolo propietario Disco (Discovery).

Al utilizar la infraestructura SaaS comercial de Tailscale Inc., el plano de control opera como una caja negra multinquilino alojada en nubes públicas propietarias. La sustitución de este componente mediante el despliegue de Headscale en un servidor VPS permite desacoplar por completo la red privada de dependencias externas, eliminando las restricciones de gobernanza de datos y resolviendo cuellos de botella críticos de latencia en entornos corporativos.

┌────────────────────────────────────────────────────────────────────────┐
│                        ARQUITECTURA DE CONTROL                         │
│                                                                        │
│   Tailscale SaaS:       [ Clientes ] ──(Telemetría / ACLs)──> [ AWS SaaS ] │
│                                                                        │
│   Headscale Self-Host:  [ Clientes ] ──(gRPC / HTTPs mTLS)─> [ KVM VPS ]  │
│                                                               [ SQLite/PG ]│
└────────────────────────────────────────────────────────────────────────┘

Soberanía criptográfica y mitigación de fuga de metadatos

Aunque la implementación de WireGuard garantiza que las claves privadas (/var/lib/tailscale/tailscaled.state) residan exclusivamente en los nodos terminales y que el contenido del tráfico permanezca cifrado de extremo a extremo, el plano de control de Tailscale SaaS procesa y almacena metadatos críticos de infraestructura:

Topología de red y mapeo de identidades: El grafo completo de interconexión entre hosts, subredes publicitadas (subnet routers), endpoints de salida (exit nodes) y etiquetas de dispositivos.
Historial de autenticación y rotación de claves: Marcas de tiempo de renovación de credenciales de máquina, direcciones IP públicas de origen y puertos efímeros de negociación NAT.
Telemetría y registros de resolución MagicDNS: Consultas de nombres de host internos transmitidas al resolvedor coordinado centralmente.

Para infraestructuras sujetas a esquemas regulatorios estrictos (GDPR, PCI-DSS v4.0, directiva NIS2 o entornos de computación confidencial), la exposición de esta topología a una entidad externa bajo jurisdicción del CLOUD Act estadounidense representa un vector de riesgo operacional inaceptable.

Al implementar Headscale en un VPS como servidor alternativo a Tailscale, la totalidad del estado de coordinación se persiste en un motor de base de datos local (SQLite con transacciones WAL para entornos de hasta 500 nodos, o un cluster PostgreSQL dedicado para cargas de alta concurrencia). El administrador mantiene el control criptográfico absoluto:

Gestión autónoma de claves de preautenticación: Generación de tokens de registro con caducidad determinista sin intermediación de proveedores OAuth comerciales: bash headscale preauthkeys create --reusable --expiration 24h --user infra-core
Aislamiento de proveedores de identidad (IdP): Integración nativa mediante OpenID Connect (OIDC) contra instancias locales de Authentik, Keycloak o Vaultwarden, evitando el paso forzado por cuentas corporativas de Google Workspace, Microsoft Entra ID o GitHub.
Cero telemetría externa: Desactivación radical de reportes de diagnóstico a servidores centrales de métricas.

Eliminación de restricciones operativas y escalado horizontal

El modelo de suscripción de Tailscale SaaS segmenta características esenciales de red mediante barreras comerciales restrictivas. En su nivel gratuito y planes iniciales, impone cuotas estrictas sobre el número de usuarios, la cantidad de máquinas registradas (limitando severamente topologías dinámicas donde los pods de Kubernetes o contenedores efímeros de CI/CD se registran como nodos de red) y el control granular de políticas de filtrado.

Headscale elimina de raíz estas restricciones artificiales:

Nodos y subredes ilimitadas: Sin costes por dispositivo añadido. Es posible orquestar despliegues con miles de microservicios, nodos de borde (edge computing), sensores IoT y estaciones de trabajo dentro del mismo espacio de direccionamiento.
Namespaces y tenencia múltiple real: Aislamiento total entre entornos (e.g., produccion, staging, secops) mediante namespaces independientes gestionados por CLI o API gRPC/REST.
Políticas de filtrado HuJSON avanzadas sin sobrecoste: Aplicación de reglas ACL completas basadas en usuarios, grupos y etiquetas (tagOwners), procesadas localmente por el motor de Headscale sin auditorías de uso externas.

Optimización de rendimiento: El factor crítico de los relays DERP

Cuando dos nodos de una red WireGuard no pueden establecer un enlace directo UDP punto a punto debido a la presencia de NAT simétrico en ambos extremos (Carrier-Grade NAT / CGNAT RFC 6598 o cortafuegos corporativos que reescriben puertos dinámicamente), el protocolo recurre a servidores de retransmisión denominados DERP (Designated Encrypted Relay for Packets).

Un nodo DERP encapsula los paquetes WireGuard sobre conexiones TCP a través del puerto 443 (o HTTP/2 y WebSockets) para atravesar firewalls estrictos. En la red pública de Tailscale SaaS, los nodos DERP están distribuidos globalmente pero sometidos a una densa contención multinquilino. Esto introduce penalizaciones severas:

Latencia de cola (p99) volátil: Ráfagas de jitter que superan con frecuencia los 150–250 ms en horas pico debido a la congestión de buffers (bufferbloat) en los servidores públicos compartidos.
Limitación de ancho de banda: El tráfico retransmitido vía DERP público suele estrangularse para priorizar la disponibilidad global del servicio SaaS.

┌────────────────────────────────────────────────────────────────────────┐
│                        TRAYECTORIA DE TRÁFICO DERP                     │
│                                                                        │
│  Tailscale SaaS:   Nodo A ──(TCP/TLS)──> [ DERP Público Saturado ] ──> Nodo B │
│                                          (Latencia p99: 180-280 ms)    │
│                                                                        │
│  Headscale VPS:    Nodo A ──(BBR/10G)──> [ DERP KVM Propio ] ─────────> Nodo B │
│                                          (Latencia p99: 12-25 ms)      │
└────────────────────────────────────────────────────────────────────────┘

Al desplegar una instancia propia de Headscale con su servidor DERP integrado (o emparejado con un daemon derper autónomo) en un servidor VPS con KVM, se obtiene una ruta de retransmisión privada de alto rendimiento. En este escenario, la selección de la infraestructura de alojamiento resulta determinante.

Plataformas en la nube como tropic.host proporcionan el estándar técnico requerido para esta topología: virtualización KVM pura sin sobreasignación de recursos (CPU Steal Time %st = 0.0%), procesadores de alta frecuencia (AMD EPYC, Ryzen 9) y enlaces simétricos de 1 a 10 Gbps con el algoritmo de control de congestión TCP BBR habilitado por defecto a nivel de kernel. La interconexión directa mediante BGP en los principales puntos de intercambio de tráfico de Europa (Frankfurt, Ámsterdam, Londres) y Asia/Oriente Medio permite que el tráfico retransmitido por DERP mantenga métricas de latencia p99 inferiores a 25 ms, eliminando el impacto perceptible de la retransmisión sobre túneles SSH, transferencias de archivos vía rsync o bases de datos replicadas.

Matriz comparativa: Tailscale SaaS vs. Headscale sobre VPS Dedicado

La siguiente matriz desglosa las discrepancias técnicas, arquitectónicas y financieras entre ambas soluciones:

Vector Técnico / Operativo	Tailscale SaaS (Personal/Free)	Tailscale SaaS (Enterprise)	Headscale sobre KVM VPS (tropic.host)
Custodia del Plano de Control	Externa (Tailscale Inc. en AWS)	Externa (SaaS dedicado/multi-tenant)	100% On-Premise / Servidor Propio
Límite de Nodos (Dispositivos)	100 máquinas	Ilimitado (facturación por usuario)	Ilimitado (escalabilidad por hardware)
Usuarios / Cuentas de Acceso	3 usuarios	Ilimitado (mínimo contractual alto)	Ilimitados (Namespaces sin cuotas)
Infraestructura de Relay (DERP)	Nodos públicos compartidos	Nodos públicos + Custom DERP	Servidor DERP privado dedicado
Latencia p99 en Tráfico DERP	180 ms – 320 ms (alta contención)	120 ms – 200 ms	12 ms – 25 ms (enlace 1–10 Gbps BBR)
Throughput Máximo DERP	~20–40 Mbps (congestión TCP)	Variable según región	Line-rate de interfaz (hasta 10 Gbps)
Fuga de Metadatos y Telemetría	Sí (nombres de host, IPs, rutas)	Sujeta a DPA / Parcial	Cero (aislamiento local de métricas)
Persistencia de Base de Datos	Propietaria distribuida	Propietaria distribuida	SQLite (WAL) / PostgreSQL gestionado
Integración SSO / IdP	Proveedores públicos (Google/MS)	Okta, Entra ID, PingFederate	Cualquier IdP compatible con OIDC
CPU Steal Time (%st) de la Red	N/A (Plano de control cerrado)	N/A	0.0% garantizado en KVM dedicado
Modelo de Coste	Gratuito con límites severos	Alto ($18–$24+ por usuario/mes)	Coste fijo predecible de la instancia VPS

Ajuste de Kernel para Maximizar Rendimiento de Headscale y DERP

Para garantizar que el servidor VPS soporte miles de paquetes concurrentes por segundo sin incurrir en pérdidas de paquetes UDP ni estrangulamiento de buffers durante las operaciones de retransmisión, el host debe configurarse con parámetros de red optimizados.

En un host con Linux (Debian 12 o Ubuntu 24.04 LTS), aplique los siguientes valores en /etc/sysctl.d/99-headscale-network.conf:

# Habilitar reenvío de paquetes IPv4 e IPv6 a nivel de kernel
net.ipv4.ip_forward = 1
net.ipv6.conf.all.forwarding = 1

# Optimización de buffers de recepción y envío para sockets de red de alto tráfico
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216

# Aumentar la cola de paquetes pendientes para interfaces de 1-10 Gbps
net.core.netdev_max_backlog = 10000
net.core.somaxconn = 8192

# Control de congestión moderno para minimizar latencia en enlaces WAN
net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr

# Mitigación de agotamiento de puertos efímeros en pasarelas DERP concurrentes
net.ipv4.ip_local_port_range = 1024 65535
net.ipv4.tcp_tw_reuse = 1

Cargue la configuración inmediatamente sin reiniciar el nodo:

sysctl --system

La adopción de TCP BBR (Bottleneck Bandwidth and RTT) junto con la disciplina de encolado FQ (Fair Queueing) resulta mandatoria en el host que alberga la pasarela DERP. A diferencia del algoritmo tradicional CUBIC, que interpreta la pérdida de paquetes como un indicador directo de congestión reduciendo la ventana de transmisión (cwnd) de forma drástica, BBR modela dinámicamente la velocidad real de entrega del cuello de botella y el tiempo mínimo de ida y vuelta (RTT). Esto permite que el tráfico de retransmisión WireGuard fluya a través del VPS a la máxima velocidad física del enlace sin degradarse ante fluctuaciones transitorias de red.

Configuración del Sistema Operativo y Activación de Reenvío de Paquetes IP

El despliegue de un plano de control Headscale sobre un entorno Linux en producción exige que la pila de red del kernel no opere como un simple host terminal (endpoint), sino como una entidad de conmutación y tránsito de paquetes L3/L4. Cuando un nodo actúa como servidor Headscale en un VPS y coordina la topología de red Tailscale, o asume roles concurrentes de pasarela DERP (Designated Encrypted Relay for Packets), enrutador de subred (subnet router) y nodo de salida (exit node), el sistema operativo debe gestionar el reenrutamiento inter-interfaz sin alterar encabezados de forma destructiva y sin degradar la latencia de conmutación.

1. Desbloqueo del Reenvío de Paquetes a Nivel de Kernel (IPv4 e IPv6)

Por omisión, las distribuciones Linux orientadas a servidores (Debian, Ubuntu LTS, AlmaLinux) compilan el kernel con el reenviador deshabilitado (net.ipv4.ip_forward = 0). En este estado, cualquier paquete IP entrante por una interfaz física (como eth0) o virtual (como tailscale0) cuya dirección de destino no coincida exactamente con una IP asignada localmente es descartado de inmediato en la etapa PREROUTING de Netfilter mediante la llamada de descarte silencioso del subsistema de red.

Para permitir que el tráfico encriptado de la malla circule entre clientes externos y recursos corporativos aislados, es obligatorio habilitar el reenvío tanto en la pila IPv4 como en la pila nativa IPv6:

# Validación inmediata en memoria de los descriptores del kernel
cat /proc/sys/net/ipv4/ip_forward
cat /proc/sys/net/ipv6/conf/all/forwarding

Si el comando retorna 0, el kernel descarta el tráfico de tránsito. La activación persistente y determinista se implementa creando un archivo dedicado en /etc/sysctl.d/, evitando modificar directamente el monolítico /etc/sysctl.conf para no colisionar con actualizaciones de paquetes del sistema.

Cree el archivo de configuración de enrutamiento:

cat <<'EOF' | sudo tee /etc/sysctl.d/99-headscale-routing.conf
# ==============================================================================
# Habilitación de reenvío L3 para Headscale / Tailscale Subnet Router & Exit Node
# ==============================================================================
net.ipv4.ip_forward = 1
net.ipv6.conf.all.forwarding = 1
net.ipv6.conf.default.forwarding = 1

# ==============================================================================
# Mitigación de asimetría de enrutamiento (Reverse Path Filtering)
# El valor 2 (Loose Mode) es crítico en topologías overlay/mesh con múltiples rutas
# ==============================================================================
net.ipv4.conf.all.rp_filter = 2
net.ipv4.conf.default.rp_filter = 2

# ==============================================================================
# Prevención de redirecciones ICMP no deseadas en nodos de tránsito
# ==============================================================================
net.ipv4.conf.all.send_redirects = 0
net.ipv4.conf.default.send_redirects = 0
net.ipv4.conf.all.accept_redirects = 0
net.ipv6.conf.all.accept_redirects = 0

# ==============================================================================
# Algoritmo de control de congestión TCP BBR y disciplina de encolado FQ
# ==============================================================================
net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr

# ==============================================================================
# Preservación y descubrimiento de MTU en trayectorias con encapsulamiento
# ==============================================================================
net.ipv4.ip_no_pmtu_disc = 0
net.ipv4.tcp_mtu_probing = 1
EOF

Aplique las modificaciones en tiempo de ejecución:

sudo sysctl --system

Análisis del Modo Loose en Reverse Path Filtering (`rp_filter = 2`)

Un error de arquitectura frecuente al configurar un servidor Headscale en un VPS bajo una topología Tailscale es mantener net.ipv4.conf.all.rp_filter = 1 (Strict Reverse Path Filtering, definido según RFC 3704). Bajo el modo estricto, el kernel comprueba si la interfaz por la que ingresó el paquete coincide exactamente con la interfaz que la tabla de rutas FIB (Forwarding Information Base) utilizaría para responder a la IP de origen.

En una red de malla WireGuard/Tailscale, el tráfico a menudo experimenta rutas asimétricas: un paquete puede ingresar por la interfaz del túnel (tailscale0) y la respuesta puede encaminarse a través de la interfaz WAN pública (eth0) hacia un nodo intermedio, o viceversa. Con rp_filter = 1, el kernel asume que el paquete es producto de una suplantación de identidad (IP spoofing) y lo descarta silenciosamente. Establecer rp_filter = 2 (Loose Mode) instruye al subsistema IP a validar únicamente si la dirección de origen es alcanzable a través de cualquier interfaz activa del host, erradicando caídas de conexión intermitentes sin comprometer la seguridad perimetral.

2. Verificación y Operativa de TCP BBR sobre KVM

La pila de enrutamiento configurada en el host se apoya directamente en la disciplina de encolado fq (Fair Queueing) y el algoritmo de congestión TCP BBR. Para verificar que el módulo del kernel se encuentra cargado y operativo en el espacio de ejecución, ejecute:

# Validar disponibilidad del módulo en el árbol de módulos del kernel
lsmod | grep bbr

# En caso de no estar cargado dinámicamente:
sudo modprobe tcp_bbr
echo "tcp_bbr" | sudo tee -a /etc/modules-load.d/bbr.conf

# Confirmar el algoritmo activo en el subsistema de red
sysctl net.ipv4.tcp_congestion_control
sysctl net.core.default_qdisc

La salida esperada debe ser inequívoca:

net.ipv4.tcp_congestion_control = bbr
net.core.default_qdisc = fq

Para inspeccionar cómo BBR modula el tráfico TCP en tiempo real (por ejemplo, en las sesiones HTTPS/WSS utilizadas por el protocolo DERP en el puerto 443), utilice la utilidad ss:

ss -tin '( dport = :443 or sport = :443 )'

La telemetría del comando expondrá parámetros dinámicos clave como bbr:(bw:<velocidad>,mrtt:<rtt_mínimo>,pacing_gain:<ganancia>) y la tasa de entrega efectiva (delivery_rate), confirmando que el transmisor ajusta el flujo según el ancho de banda del cuello de botella y no mediante la reducción ciega de la ventana ante descartes marginales.

En entornos virtualizados, esta optimización requiere acceso completo a las directivas del kernel. En tecnologías de virtualización basadas en contenedores compartidos (como OpenVZ o LXC heredados), la modificación de parámetros de red suele estar bloqueada a nivel de namespace del host o carece del módulo tcp_bbr. La infraestructura de virtualización KVM pura provista por tropic.host garantiza kernels independientes sin restricciones en /proc/sys/net/, con CPU Steal Time (%st = 0.0%) sobre procesadores AMD EPYC y Ryzen 9, y enlaces ascendentes simétricos de 1 a 10 Gbps donde BBR despliega su máxima eficiencia en transporte WAN intercontinental.

3. Ajuste de MTU y Pinzamiento de MSS (MSS Clamping)

El tráfico de red que atraviesa Headscale y la malla Tailscale se encapsula dentro de paquetes UDP estándar mediante el protocolo WireGuard. Esta encapsulación añade un costo estructural inevitable de bytes en cada datagrama:

Cabecera IPv4: 20 bytes (o 40 bytes en IPv6 nativo).
Cabecera UDP: 8 bytes.
Cabecera de transporte WireGuard: 16 bytes.
Tag de autenticación Poly1305: 16 bytes.

En un enlace Ethernet WAN estándar con una Unidad Máxima de Transferencia (MTU) de 1500 bytes, el túnel WireGuard reduce la MTU efectiva a 1420 bytes (en IPv4) o 1280 bytes (en IPv6 para garantizar compatibilidad con el límite mínimo estipulado por RFC 8200).

+-------------------------------------------------------------------------+
| MTU Física Ethernet: 1500 bytes                                         |
+------------------------------------+------------------------------------+
| Sobrecarga Encapsulado (60-80 bytes)| Carga Útil WireGuard (MTU: 1420)   |
| IP (20B) + UDP (8B) + WG (32B)     | Tráfico TCP/UDP de la Malla        |
+------------------------------------+------------------------------------+

Si un cliente dentro de la malla intenta transmitir segmentos TCP con un Tamaño Máximo de Segmento (MSS, Maximum Segment Size) calculado para una MTU de 1500 bytes ($MSS = 1500 - 20 - 20 = 1460 \text{ bytes}$), y en la ruta intermedia un cortafuegos o proveedor bloquea los paquetes ICMP de tipo 3, código 4 (Fragmentation Needed), se produce un fenómeno de «agujero negro» (PMTU Black Hole): las conexiones TCP completan el saludo three-way handshake (paquetes SYN pequeños), pero se congelan de inmediato al transferir datos de gran volumen (como transferencias TLS, SSH interactivo o payloads HTTP).

Para solucionar este escenario en el nodo que actúa como enrutador, es indispensable implementar una regla de pinzamiento de MSS (MSS Clamping) que reescriba al vuelo el valor MSS en los paquetes TCP SYN que atraviesen las interfaces de tránsito.

Implementación con `nftables` (Estándar Moderno)

Añada la regla de cálculo dinámico dentro de la tabla de filtrado de su cortafuegos:

sudo nft add table inet filter
sudo nft add chain inet filter forward { type filter hook forward priority 0 \; policy accept \; }
sudo nft add rule inet filter forward tcp flags syn tcp option maxseg size set rt mtu

Alternativa con `iptables` (Legado / Docker nativo)

Si el servidor opera bajo cadenas heredadas gestionadas por iptables o el demonio Docker:

# Pinzamiento automático de MSS respecto a la MTU de la interfaz de salida
sudo iptables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-mss-to-pmtu
sudo ip6tables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-mss-to-pmtu

La directiva --clamp-mss-to-pmtu evalúa de forma dinámica la MTU del enlace de salida específico por el que viajará el paquete y ajusta el encabezado TCP SYN a un valor seguro (típicamente $1420 - 40 = 1380 \text{ bytes}$ en IPv4), erradicando la fragmentación a nivel IP y garantizando transferencias de datos continuas y predecibles en toda la infraestructura de la red privada.

Despliegue de Headscale en Docker Compose con SQLite y config.yaml

Una vez resuelto el pinzamiento de MTU/MSS en la capa del kernel, la arquitectura del nodo de control requiere desacoplar el demonio de coordinación del sistema operativo base mediante contenedores OCI. Al desplegar Headscale en un VPS como servidor de control privado para Tailscale, la persistencia del estado y la latencia de las transacciones atómicas del motor de base de datos dictan el rendimiento del plano de control durante los eventos de reconexión masiva (thundering herd) de los nodos del mallado (tailnet).

Topología de almacenamiento y modelo de concurrencia en SQLite

Para infraestructuras que gestionan entre 1 y 500 nodos activos, el motor embebido SQLite 3 es la opción arquitectónica óptima frente a PostgreSQL, al eliminar la sobrecarga de conexiones TCP interproceso y consumo adicional de memoria en el host. Sin embargo, SQLite opera bajo un modelo de concurrencia basado en bloqueos a nivel de archivo. Cada actualización de ruta de red, rotación de llaves criptográficas WireGuard (node_key) o registro de sesión emite operaciones fsync() directas al sistema de archivos.

Si el hipervisor subyacente sufre de contención de E/S o utiliza almacenamiento distribuido en red (como Ceph con latencias variables), los bloqueos database is locked degradan el plano de control, provocando que los clientes Tailscale entren en bucles de reconexión exponencial. En las instancias KVM de tropic.host, el aprovisionamiento sobre unidades NVMe empresariales PCIe 4.0 con rendimiento sostenido superior a 50 000 IOPS en lectura/escritura aleatoria 4K QD1 y tiempos de CPU Steal nulos (%st = 0.0%) garantiza que los puntos de control del registro de transacciones (WAL checkpoints) se completen en tiempos submilimétricos ($p99 < 1.2\text{ ms}$).

Estructura de directorios y control de accesos POSIX

El contenedor oficial de Headscale (headscale/headscale) ejecuta el binario bajo un usuario sin privilegios por razones de aislamiento de seguridad (típicamente UID/GID 1000:1000 o usuario interno headscale). Es mandatorio estructurar el árbol de directorios en el host y asignar los permisos antes de inicializar el servicio para evitar fallos de lectura durante la carga de las llaves privadas:

# Creación del árbol de directorios para configuración y base de datos
sudo mkdir -p /opt/headscale/config
sudo mkdir -p /opt/headscale/data
sudo mkdir -p /opt/headscale/run

# Inicialización del archivo de base de datos SQLite vacío
sudo touch /opt/headscale/data/db.sqlite

# Asignación de permisos al UID/GID interno del contenedor (1000:1000)
sudo chown -R 1000:1000 /opt/headscale/data
sudo chown -R 1000:1000 /opt/headscale/run
sudo chmod 750 /opt/headscale/data
sudo chmod 640 /opt/headscale/data/db.sqlite

Especificación técnica de `config.yaml`

El archivo de configuración /opt/headscale/config/config.yaml gobierna la asignación de subredes, la integración DERP y las interfaces de escucha. Cree el archivo con los parámetros de producción requeridos:

---
# URL pública canónica absoluta. Los clientes Tailscale se registran contra este endpoint
server_url: https://headscale.tropic-infra.net

# Enlace de escucha interno HTTP para el proxy inverso
listen_addr: 0.0.0.0:8080

# Exposición de métricas de Prometheus para scraping local
metrics_listen_addr: 127.0.0.1:9090

# Socket UNIX o dirección gRPC para administración remota por CLI
grpc_listen_addr: 0.0.0.0:50443
grpc_allow_insecure: false

# Asignación de prefijos IP del plano de datos (CGNAT RFC 6598 y ULA IPv6)
ip_prefixes:
  - 100.64.0.0/10
  - fd7a:115c:a1e0::/48

# Configuración del motor de persistencia SQLite
database:
  type: sqlite
  sqlite:
    path: /var/lib/headscale/db.sqlite
    # Habilitación de Write-Ahead Logging para maximizar lecturas/escrituras concurrentes
    write_ahead_log: true

# Configuración de servidores de relevo DERP (Disaster Emergency Relay Protocol)
derp:
  server:
    enabled: false  # Delegado si se utiliza un DERP dedicado o servidores públicos oficiales
  urls:
    - https://controlplane.tailscale.com/derpmap/default
  paths: []
  auto_update_enabled: true
  update_frequency: 24h

# Resolución de nombres interna de la malla (MagicDNS)
dns:
  magic_dns: true
  base_domain: mesh.internal
  nameservers:
    split: {}
    global:
      - 1.1.1.1
      - 9.9.9.9
  extra_records: []

# Parámetros de temporización de sesiones y seguridad
log:
  format: json
  level: info

logtail:
  enabled: false

# Generación automática de llaves criptográficas de la instancia
noise:
  private_key_path: /var/lib/headscale/noise_private.key
prefixes:
  allocation: sequential

Desglose de directivas críticas

server_url: Define la URL canónica inmutable. Los clientes Tailscale validan este valor durante la negociación Noise; si no coincide de forma exacta con la cabecera Host entregada por el proxy inverso TLS, el cliente rechaza la sincronización del mapa de red con errores de mismatch de certificado o handshake TLS.
ip_prefixes: Emplea el bloque 100.64.0.0/10 (definido por el RFC 6598 para Carrier-Grade NAT). Este rango previene colisiones con las subredes privadas RFC 1918 locales (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) de los clientes remotos.
write_ahead_log: true: Activa el modo WAL de SQLite (PRAGMA journal_mode=WAL;). En lugar de realizar escrituras directas sobre el archivo de base de datos bloqueando a todos los lectores, las escrituras se acumulan secuencialmente en el archivo -wal, permitiendo que las consultas del mapa de red operen en paralelo sin contención de bloqueos a nivel de kernel.

Manifiesto de orquestación `docker-compose.yml`

El contenedor debe desplegarse restringiendo capacidades del kernel Linux y definiendo límites estrictos de recursos bajo cgroups v2 para proteger el VPS frente a picos anómalos de tráfico. Guarde la siguiente definición en /opt/headscale/docker-compose.yml:

version: '3.8'

services:
  headscale:
    image: headscale/headscale:0.23.0-alpha11 # Ajustar a la última versión inmutable probada
    container_name: headscale-server
    restart: always
    user: "1000:1000"
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    volumes:
      - /opt/headscale/config/config.yaml:/etc/headscale/config.yaml:ro
      - /opt/headscale/data:/var/lib/headscale:rw
      - /opt/headscale/run:/var/run/headscale:rw
    ports:
      # Puerto HTTP expuesto localmente para terminación TLS en Nginx/Caddy
      - "127.0.0.1:8080:8080"
      # Puerto gRPC expuesto en localhost para administración por socket/CLI
      - "127.0.0.1:50443:50443"
    environment:
      - TZ=UTC
    command: headscale serve
    deploy:
      resources:
        limits:
          cpus: '1.5'
          memory: 512M
        reservations:
          cpus: '0.2'
          memory: 128M
    healthcheck:
      test: ["CMD", "headscale", "status"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    logging:
      driver: "json-file"
      options:
        max-size: "20m"
        max-file: "5"

Inicialización y verificación del demonio

Ejecute el levantamiento del contenedor y verifique la integridad del socket de coordinación y las tablas del esquema SQLite:

cd /opt/headscale
sudo docker compose up -d

# Inspección de logs estructurados en JSON
sudo docker compose logs headscale-server | jq .

# Verificación del estado del healthcheck
sudo docker inspect --format='{{json .State.Health}}' headscale-server | jq .

Una inicialización exitosa reporta en los logs la creación del archivo de llave privada Noise en /var/lib/headscale/noise_private.key y la migración limpia de los esquemas en /var/lib/headscale/db.sqlite.

Para validar la operatividad del CLI interno y crear el espacio de nombres inicial para registrar clientes:

# Creación del usuario / espacio de nombres raíz para los nodos
sudo docker compose exec headscale headscale users create admin

# Verificación de la tabla de usuarios registrados
sudo docker compose exec headscale headscale users list

El plano de control de Headscale queda así vinculado de forma determinista en 127.0.0.1:8080, listo para recibir la terminación TLS mediante un proxy inverso perimetral con certificados automáticos y desacople total del plano criptográfico.

Configuración de Nginx Reverse Proxy con TLS 1.3 y WebSockets

El plano de control de Headscale delega la negociación criptográfica perimetral en un proxy inverso especializado para mitigar sobrecarga en el runtime de Go, gestionar la renovación no destructiva de certificados X.509 y sostener conexiones bidireccionales de larga duración. Los clientes Tailscale mantienen canales de sincronización de estado (long-polling y WebSockets persistentes en rutas como /ts2021 o /derp) que requieren ajustes específicos en los timeouts de transporte y en la gestión de encabezados hop-by-hop para evitar desconexiones continuas de la malla.

Para garantizar que el proxy procese el tráfico con mínima latencia y soporte miles de estados de conexión concurrentes sin incurrir en degradación de I/O, el despliegue sobre instancias KVM con núcleos dedicados de alta frecuencia (como las plataformas con AMD EPYC de tropic.host, donde el parámetro %st se mantiene inalterable en 0.0%) permite absorber la sobrecarga de los handshakes criptográficos y mantener lecturas síncronas en disco NVMe con tiempos de respuesta p99 inferiores al milisegundo.

Preparación del entorno de certificados con Certbot y ACME

Antes de estructurar el bloque de servidor, es necesario generar los certificados de producción. Utilizaremos el cliente oficial de EFF (certbot) mediante el validador webroot o el desafío autónomo HTTP-01.

Instale las dependencias base en distribuciones Debian 12 o Ubuntu 24.04 LTS:

sudo apt-get update && sudo apt-get install -y nginx certbot python3-certbot-nginx

Para evitar colisiones de bind en el puerto 80/tcp durante la obtención inicial del certificado si Nginx aún no cuenta con un bloque activo:

# Detención momentánea de Nginx si está ejecutándose por defecto
sudo systemctl stop nginx

# Emisión de certificado RSA de 4096 bits o ECDSA secp384r1
sudo certbot certonly --standalone \
  --preferred-challenges http \
  --agree-tos \
  --email [email protected] \
  -d vpn.su-dominio.com \
  --key-type ecdsa \
  --elliptic-curve secp384r1

# Reactivación inmediata del servicio web
sudo systemctl start nginx

El uso de curvas elípticas (ECDSA con curva secp384r1) optimiza radicalmente la velocidad del handshake TLS y reduce el tamaño de las tramas TCP frente a RSA tradicional, conservando compatibilidad completa con el motor de Tailscale.

Mapeo de WebSockets y optimización del núcleo en `nginx.conf`

Los clientes de la VPN negocian la actualización de protocolo mediante los encabezados HTTP Upgrade y Connection. Nginx descarta estos valores por defecto a menos que se defina explícitamente un bloque map dependiente del contexto HTTP.

Verifique y edite /etc/nginx/nginx.conf para asegurar la presencia del bloque de mapeo dinámico dentro de la directiva http { ... }:

http {
    # Mapeo determinista para actualización de transporte a WebSockets
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }

    # Desactivación de tokens de versión para reducir vector de fingerprinting
    server_tokens off;

    # Optimización de buffer de eventos y sockets
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;

    # Reutilización de conexiones keepalive y tuning de buffers
    keepalive_timeout 65;
    types_hash_max_size 2048;

    # Inclusión de configuraciones modulares
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

La variable $connection_upgrade evaluará si el cliente solicita explícitamente elevar el transporte a WebSocket (Upgrade: websocket), asignando la cadena upgrade a la cabecera Connection, o cerrando la cabecera en peticiones REST convencionales.

Definición del VirtualHost perimetral para Headscale

Cree el archivo de configuración dedicado en /etc/nginx/sites-available/headscale.conf:

# Upstream hacia el demonio local de Headscale
upstream headscale_backend {
    server 127.0.0.1:8080;
    keepalive 32;
}

# Redirección estricta de tráfico no cifrado
server {
    listen 80;
    listen [::]:80;
    server_name vpn.su-dominio.com;

    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

# Terminación TLS 1.3 de alto rendimiento
server {
    listen 443 ssl default_server;
    listen [::]:443 ssl default_server;
    http2 on;
    server_name vpn.su-dominio.com;

    # Certificados SSL emitidos con curva elíptica
    ssl_certificate /etc/letsencrypt/live/vpn.su-dominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/vpn.su-dominio.com/privkey.pem;

    # Política estricta de protocolos y suites criptográficas modernas
    ssl_protocols TLSv1.3 TLSv1.2;
    ssl_prefer_server_ciphers off;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305;

    # Gestión de sesiones TLS sin tickets para Perfect Forward Secrecy garantizado
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:50m;
    ssl_session_tickets off;

    # Verificación de estado de revocación mediante OCSP Stapling
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/letsencrypt/live/vpn.su-dominio.com/chain.pem;
    resolver 1.1.1.1 8.8.8.8 valid=300s;
    resolver_timeout 5s;

    # Encabezados de seguridad para mitigar MITM y Clickjacking
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "DENY" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Bloque de proxy inverso hacia el plano de control
    location / {
        proxy_pass http://headscale_backend;

        # Propagación de identidad y metadatos de red
        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;

        # Compatibilidad obligatoria con HTTP/1.1 para WebSockets y multiplexación
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        # Parámetros críticos de temporización para long-polling de Tailscale
        # Se establece en 3600 segundos para prevenir desconexiones TCP periódicas
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_connect_timeout 60s;

        # Desactivación deliberada de buffering para transmisión en tiempo real
        proxy_buffering off;
        proxy_request_buffering off;

        # Sintonización de buffers de encabezados
        proxy_buffers 8 32k;
        proxy_buffer_size 64k;
        proxy_busy_buffers_size 128k;
    }

    # Registro de auditoría con formato extendido
    access_log /var/log/nginx/headscale_access.log combined;
    error_log /var/log/nginx/headscale_error.log warn;
}

Análisis de directivas críticas de transporte

El funcionamiento continuo de una malla Tailscale depende críticamente de tres directivas configuradas en el bloque anterior:

proxy_buffering off;: Cuando un nodo cliente ejecuta el handshake Noise contra /ts2021, la respuesta de Headscale fluye como un stream JSON/protobuf continuado. Si Nginx retiene las respuestas en sus buffers internos esperando a llenar bloques de memoria de 4 KB o 16 KB, el cliente de control asume una desconexión por timeout o experimenta latencias inaceptables en el intercambio de llaves públicas.
proxy_read_timeout 3600s;: El mecanismo de heartbeat de Tailscale envía sondas para verificar si el nodo sigue vivo. Los valores predeterminados de Nginx (proxy_read_timeout 60s) cortan la sesión periódicamente cada minuto, forzando a todos los nodos conectados a renegociar el estado de la red, elevando el uso de CPU en el servidor y generando oscilaciones de rutas en tablas de enrutamiento distribuidas.
proxy_set_header Connection $connection_upgrade;: Al acoplarse con la directiva proxy_http_version 1.1;, asegura que las solicitudes entrantes que solicitan la elevación a canal bidireccional establezcan sockets TCP dúplex puros sin que el proxy interponga un cierre prematuro (FIN).

Activación, verificación sintáctica y recarga del servicio

Habilite la configuración creando el enlace simbólico correspondiente y valide la integridad estructural del archivo:

# Creación del enlace en sites-enabled
sudo ln -sf /etc/nginx/sites-available/headscale.conf /etc/nginx/sites-enabled/

# Desactivación del sitio por defecto de Nginx si aún existe
sudo rm -f /etc/nginx/sites-enabled/default

# Validación estricta de la configuración sintáctica
sudo nginx -t

Si la salida confirma que el test es exitoso (nginx: configuration file /etc/nginx/nginx.conf test is successful), aplique los cambios mediante una recarga en caliente que preserve las conexiones existentes:

sudo systemctl reload nginx

Validación de la terminación TLS y respuesta del endpoint

Ejecute un sondeo de verificación perimetral desde una terminal externa para inspeccionar la negociación de suites criptográficas y verificar el estado HTTP devuelto por el backend:

# Inspección de handshake TLS 1.3 con OpenSSL
openssl s_client -connect vpn.su-dominio.com:443 -tls1_3 -servername vpn.su-dominio.com < /dev/null 2>&1 | grep -E "Protocol|Cipher|Server public key"

La salida esperada debe confirmar el protocolo TLSv1.3 y el cifrado negociado:

    Protocol  : TLSv1.3
    Cipher    : TLS_AES_256_GCM_SHA384
Server public key is 384 bit

Para verificar que el proxy inverso redirige correctamente hacia el socket interno de Headscale:

curl -I https://vpn.su-dominio.com/health

El servidor debe responder con código HTTP/2 200 o HTTP/1.1 200 OK, demostrando que el plano perimetral de Nginx se comunica limpiamente con 127.0.0.1:8080, dejando el servidor listo para admitir el registro y la federación de clientes Tailscale en la red privada.

Gestión de Nodos, Usuarios y Rutas Exit-Node desde la Terminal

Una vez que el plano de control responde sobre HTTPS y la terminación TLS valida el tráfico entrante, la administración de la red privada pasa al control de identidades y topología mediante la interfaz de línea de comandos de Headscale. La arquitectura desacopla el plano de autenticación y coordinación del plano de datos: los clientes consultan al servidor únicamente para intercambiar claves públicas de WireGuard, direcciones de socket IP:Puerto descubiertas mediante STUN y directivas de enrutamiento; el tráfico punto a punto (P2P) fluye de forma directa entre los nodos sin transitar por el servidor central, salvo que se active un nodo de salida (exit-node) o intervenga un repetidor DERP ante firewalls simétricos.

Segmentación de identidades mediante usuarios

Headscale aísla dispositivos agrupándolos bajo usuarios lógicos (mecanismo que en versiones previas recibía la denominación de namespaces). Ningún nodo puede registrarse ni consultar rutas sin pertenecer explícitamente a un usuario del sistema.

Para aprovisionar los entornos de acceso en el servidor:

# Creación de identidades operativas
sudo headscale users create ops-infra
sudo headscale users create dev-workstations

# Verificación de identidades registradas en la base de datos
sudo headscale users list

La salida en consola refleja el estado del almacén SQLite/PostgreSQL subyacente:

ID | Name             | Created
1  | ops-infra        | 2026-10-04 14:10:02
2  | dev-workstations | 2026-10-04 14:10:15

Métodos de incorporación de nodos: Interactivo vs Pre-Auth Keys

Existen dos vías técnicas para registrar un cliente Tailscale contra una instancia de control Headscale: la negociación interactiva basada en Machine Keys y el aprovisionamiento automatizado mediante tokens preautenticados (pre-auth keys).

1. Registro interactivo asistido por el operador

Desde el equipo cliente (Linux, macOS o Windows) que ejecuta el binario oficial de Tailscale, inicie la solicitud de asociación forzando la URL del plano de control propio:

# Ejecución en el cliente destino
sudo tailscale up --login-server https://vpn.su-dominio.com --reset

El daemon tailscaled generará un par de claves efímeras y devolverá en la terminal una URL de autorización estructurada con la clave de máquina (mkey):

To authenticate, visit:
    https://vpn.su-dominio.com/register/mkey:a4f89d38c71b6329e4726bf01e859b2074e0d9b4b1a82f3c7e09214d026a7e58

En el servidor que aloja Headscale, extraiga el identificador mkey y autorice el registro asignándolo al usuario correspondiente:

sudo headscale nodes register \
  --user ops-infra \
  --key a4f89d38c71b6329e4726bf01e859b2074e0d9b4b1a82f3c7e09214d026a7e58

2. Registro desatendido mediante Pre-Auth Keys (Automatización CI/CD y despliegues headless)

Para aprovisionar servidores sin intervención interactiva, genere tokens de autenticación previa en el servidor. Estos tokens admiten límites de caducidad, restricciones de un solo uso o atributos de reutilización (reusable):

# Generación de token reutilizable con expiración a 48 horas
sudo headscale preauthkeys create \
  --user ops-infra \
  --reusable \
  --expiration 48h

Headscale retornará un hash alfanumérico de 48 caracteres (ej. 3a8f9c1b2e04d7...). Con este token, cualquier host cliente se conecta e ingresa a la malla de forma desatendida mediante una sola instrucción de arranque:

sudo tailscale up \
  --login-server https://vpn.su-dominio.com \
  --authkey 3a8f9c1b2e04d7... \
  --accept-routes \
  --accept-dns=true \
  --reset

Para validar el catálogo de nodos enlazados, sus direcciones IPv4/IPv6 virtuales asignadas en el pool CGNAT (100.64.0.0/10) y el estado de expiración de sus claves:

sudo headscale nodes list

ID | Hostname       | User      | IP addresses                  | Status  | Last seen
1  | srv-edge-01    | ops-infra | 100.64.0.1, fd7a:115c:a1e0::1 | online  | 2026-10-04 14:15:30
2  | workstation-adm| ops-infra | 100.64.0.2, fd7a:115c:a1e0::2 | online  | 2026-10-04 14:15:28

Configuración del Kernel del VPS como Subnet Router y Exit-Node

Transformar un nodo cliente dentro de la malla en una puerta de enlace hacia Internet (Exit-Node) o en un enrutador de subredes corporativas (Subnet Router) requiere preparar la pila de red del kernel Linux para permitir el reenvío de paquetes entre interfaces lógicas (tailscale0) y la interfaz WAN pública (eth0).

En este rol de enrutamiento concentrado, la virtualización subyacente impacta directamente la latencia p99 y el rendimiento de red. El procesamiento masivo de paquetes encriptados con ChaCha20-Poly1305 por WireGuard degrada drásticamente si el hipervisor incurre en contención de CPU. El despliegue de un headscale vps servidor tailscale sobre la infraestructura KVM de tropic.host garantiza una asignación de recursos dedicada con métricas estrictas de CPU Steal Time (%st = 0.0%) sobre procesadores AMD EPYC y Xeon de alta frecuencia. Esto, sumado a puertos uplink de 1 a 10 Gbps con TCP BBR activo a nivel de kernel, permite canalizar tráfico WireGuard a velocidad de cable sin estrangulamiento térmico ni pérdida de ráfagas UDP bajo saturación de clientes concurrentes.

1. Activación de Packet Forwarding en el sistema operativo

Habilite el reenvío de paquetes IPv4 e IPv6 persistente en /etc/sysctl.d/99-tailscale-routing.conf:

sudo tee /etc/sysctl.d/99-tailscale-routing.conf << 'EOF'
# Habilitación de reenvío de paquetes L3
net.ipv4.ip_forward = 1
net.ipv6.conf.all.forwarding = 1

# Optimización de búferes de recepción y envío para enlaces Gigabit
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216

# Prevención de ataques de spoofing y control de rutas
net.ipv4.conf.all.rp_filter = 1
net.ipv4.conf.default.rp_filter = 1
EOF

# Aplicar parámetros sin reiniciar
sudo sysctl -p /etc/sysctl.d/99-tailscale-routing.conf

2. Reglas de Enmascaramiento (NAT / MASQUERADE) y Clamping de MSS

Cuando el nodo actúa como pasarela a Internet para otros equipos, los paquetes que abandonan la interfaz eth0 deben enmascararse tras la IP pública del servidor. Asimismo, la encapsulación WireGuard añade una sobrecarga de 60 bytes en IPv4 y 80 bytes en IPv6; si no se ajusta el MSS (Maximum Segment Size) en el handshake TCP SYN, los paquetes que excedan la MTU de 1280 bytes estándar de Tailscale sufrirán fragmentación o descarte silencioso en redes intermedias.

Configure las reglas en iptables (o mediante su backend nftables):

# Identificación de la interfaz WAN predeterminada
WAN_IFACE=$(ip route show default | awk '{print $5}')

# Enmascaramiento de salida hacia la WAN
sudo iptables -t nat -A POSTROUTING -o "$WAN_IFACE" -j MASQUERADE
sudo ip6tables -t nat -A POSTROUTING -o "$WAN_IFACE" -j MASQUERADE

# TCP MSS Clamping para prevenir fragmentación sobre MTU reducida
sudo iptables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-mss-to-pmtu
sudo ip6tables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-mss-to-pmtu

Para asegurar la persistencia tras reinicios en distribuciones basadas en Debian/Ubuntu:

sudo apt-get install -y iptables-persistent
sudo netfilter-persistent save

Anuncio y aprobación de rutas en Headscale

Tailscale implementa un modelo de seguridad donde ningún cliente puede interceptar tráfico de red de forma unilateral. El nodo debe anunciar qué segmentos de red ofrece, y el administrador de Headscale debe ratificarlos explícitamente desde la terminal.

1. Anuncio de capacidades desde el nodo cliente

En el servidor configurado como pasarela, ordene a tailscaled que anuncie la ruta por defecto (0.0.0.0/0 y ::/0 para Exit-Node) o subredes de infraestructura local:

# Anuncio de nodo de salida total e interconexión a subred privada 192.168.10.0/24
sudo tailscale up \
  --login-server https://vpn.su-dominio.com \
  --advertise-exit-node \
  --advertise-routes=192.168.10.0/24 \
  --reset

2. Inspección y aprobación en el plano de control

En el host que aloja Headscale, liste las rutas anunciadas para identificar los identificadores internos asignados:

sudo headscale routes list

La consola expondrá las rutas y su estado booleano de aprobación:

ID | Node         | Route           | Enabled
1  | srv-edge-01  | 0.0.0.0/0       | false
2  | srv-edge-01  | ::/0            | false
3  | srv-edge-01  | 192.168.10.0/24 | false

Habilite selectivamente las rutas requeridas mediante el comando routes enable:

# Aprobación de la salida a Internet completa (IPv4 e IPv6)
sudo headscale routes enable -r 1
sudo headscale routes enable -r 2

# Aprobación del direccionamiento a la LAN interna
sudo headscale routes enable -r 3

Al repetir sudo headscale routes list, el parámetro Enabled debe alternar a true, propagando instantáneamente la nueva tabla de enrutamiento a todos los clientes suscritos al mapa de red a través de la conexión SSE/long-poll abierta con Headscale.

Conmutación del tráfico en los clientes y diagnóstico de enlace

Con las rutas autorizadas en el plano de control, cualquier estación de trabajo o servidor secundario conectado a la red puede redirigir todo su tráfico a través del nodo de salida o consumir los segmentos LAN corporativos.

Para ordenar al cliente que encamine su tráfico global por el Exit-Node:

# Enrutamiento de todo el tráfico WAN a través de srv-edge-01
sudo tailscale up \
  --exit-node=100.64.0.1 \
  --exit-node-allow-lan-access=true

Validación de transporte y calidad del enlace

Inspeccione el estado operativo y descarte que el tráfico esté pasando por nodos de relevo DERP (lo cual introduciría latencia innecesaria y cuello de botella de ancho de banda):

# Verificación de la tabla de adyacencias y saltos
tailscale status

100.64.0.1  srv-edge-01          ops-infra    linux   -
100.64.0.2  workstation-adm      ops-infra    linux   active; direct 198.51.100.24:41641, tx 18294020 rx 94820120

Si la conexión indica direct, la negociación STUN y el UDP hole punching en el puerto 41641/UDP resolvieron un socket directo entre pares. Realice un sondeo de latencia determinista:

tailscale ping 100.64.0.1

pong from srv-edge-01 (100.64.0.1) via 198.51.100.24:41641 in 14ms

Finalmente, valide en el cliente la IP pública de salida efectiva para certificar que el enmascaramiento en el Exit-Node opera correctamente:

curl -s https://ipinfo.io/json | grep -E "ip|org|country"

El JSON devuelto debe reflejar la dirección IP pública fija y el Sistema Autónomo (ASN) del VPS que hospeda el Exit-Node, confirmando la encapsulación integral del tráfico en la capa de transporte WireGuard gobernada por Headscale.

Automatización de Respaldos de SQLite y Plan de Recuperación ante Desastres

Al operar Headscale en un VPS como servidor de coordinación Tailscale, la disponibilidad de la red superpuesta (overlay network) depende íntegramente de la consistencia de su capa de persistencia y de la preservación de su material criptográfico. Si el nodo central colapsa sin una estrategia de respaldo transaccional y recuperación determinista, los clientes (tailnet nodes) pierden la capacidad de resolver el estado de la topología, renovar llaves públicas de sesión de WireGuard y coordinar túneles directos mediante STUN/DERP.

El almacenamiento por defecto de Headscale recae en SQLite configurado en modo WAL (Write-Ahead Logging). Respaldar esta base de datos mediante copias directas de archivos (cp db.sqlite) mientras el demonio headscale procesa peticiones concurrentes es una práctica de alto riesgo: copiar un archivo SQLite en caliente mientras existen transacciones activas en los ficheros temporales -wal y -shm produce réplicas con páginas corruptas o cabeceras fracturadas (torn writes).

Arquitectura de Estado: El Conjunto Crítico de Recuperación

Una restauración exitosa sin pérdida de adyacencias en la malla de red requiere respaldar dos componentes indisociables:

Base de datos relacional (db.sqlite): Contiene las tablas de usuarios, máquinas registradas (nodes), rutas subred anunciadas, llaves preautenticadas y mapeos de direcciones IP en el rango CGNAT (100.64.0.0/10).
Llave privada de control (noise_private.key): Es el secreto asimétrico que autentica criptográficamente la identidad del servidor Headscale frente a los clientes a través del protocolo Noise. Si este archivo se pierde tras un fallo catastrófico, aunque se restaure la base de datos, cada cliente Tailscale rechazará comunicarse con el servidor debido a discrepancias en el apretón de manos TLS/Noise, obligando a reautenticar manualmente nodo por nodo en la infraestructura.

En instancias KVM de alto rendimiento como las provistas por tropic.host, el almacenamiento en discos NVMe PCIe 4.0 empresariales garantiza operaciones de sincronización de disco (fsync) por debajo de los 100 microsegundos y un rendimiento aleatorio 4K QD1 superior a 50 000 IOPS. Esta solvencia de I/O permite ejecutar copias atómicas y vaciados de búfer sin penalizar la latencia p99 del plano de control ni inducir demoras en el tráfico de señalización.

Procedimiento Atómico de Copia con SQLite Online Backup API

Para garantizar la coherencia transaccional sin suspender la ejecución del servicio headscale, se debe emplear el mecanismo nativo VACUUM INTO de SQLite (disponible desde SQLite 3.27) o la API de respaldo en línea mediante la CLI. VACUUM INTO adquiere un bloqueo compartido de lectura, compila una copia defragmentada e integrada de todas las páginas de memoria (incluyendo las modificaciones no confirmadas del fichero WAL) y genera un único archivo plano consistente.

Cree el script de respaldo en /usr/local/bin/headscale-backup.sh:

#!/usr/bin/env bash
set -euo pipefail

# Definición de variables operativas
BACKUP_DIR="/var/backups/headscale"
HEADSCALE_DATA="/var/lib/headscale"
HEADSCALE_CONF="/etc/headscale"
TIMESTAMP="$(date +'%Y%m%d_%H%M%S')"
SNAPSHOT_DB="${BACKUP_DIR}/db_${TIMESTAMP}.sqlite"
ARCHIVE_OUT="${BACKUP_DIR}/headscale_backup_${TIMESTAMP}.tar.zst"
RETENTION_DAYS=14

# Verificar dependencias
for bin in sqlite3 tar zstd gpg; do
    if ! command -v "$bin" >/dev/null 2>&1; then
        echo "Error: Binario crítico no encontrado: $bin" >&2
        exit 1
    fi
done

mkdir -p "${BACKUP_DIR}"
chmod 0700 "${BACKUP_DIR}"

echo "[*] Generando snapshot atómico de SQLite..."
# Verificación de integridad previa al snapshot
sqlite3 "${HEADSCALE_DATA}/db.sqlite" "PRAGMA quick_check;" | grep -q "ok" || {
    echo "Fallo crítico: La base de datos de origen no pasó quick_check." >&2
    exit 2
}

# Ejecutar volcado atómico en línea sin bloquear escrituras WAL
sqlite3 "${HEADSCALE_DATA}/db.sqlite" "VACUUM INTO '${SNAPSHOT_DB}';"

echo "[*] Validando integridad del snapshot generado..."
INTEGRITY_RESULT=$(sqlite3 "${SNAPSHOT_DB}" "PRAGMA integrity_check;")
if [ "${INTEGRITY_RESULT}" != "ok" ]; then
    echo "Fallo crítico en integridad de snapshot: ${INTEGRITY_RESULT}" >&2
    rm -f "${SNAPSHOT_DB}"
    exit 3
fi

echo "[*] Empaquetando base de datos, configuraciones y llaves criptográficas..."
tar --create --zstd \
    --file="${ARCHIVE_OUT}" \
    --directory="/" \
    "${SNAPSHOT_DB#/}" \
    "${HEADSCALE_DATA#/}/noise_private.key" \
    "${HEADSCALE_CONF#/}/config.yaml"

# Eliminar snapshot transitorio una vez empaquetado
rm -f "${SNAPSHOT_DB}"

# Ajustar permisos del archivo resultante
chmod 0600 "${ARCHIVE_OUT}"

echo "[*] Purgando respaldos locales con antigüedad superior a ${RETENTION_DAYS} días..."
find "${BACKUP_DIR}" -type f -name "headscale_backup_*.tar.zst" -mtime +"${RETENTION_DAYS}" -delete

echo "[✓] Respaldo finalizado exitosamente en: ${ARCHIVE_OUT}"

Asigne permisos estrictos de ejecución para evitar exposición de credenciales:

sudo chmod 0700 /usr/local/bin/headscale-backup.sh
sudo chown root:root /usr/local/bin/headscale-backup.sh

Programación Determinista mediante Systemd Timers

Evite el uso del demonio Cron tradicional en entornos de producción. La integración con Systemd permite controlar cuotas de recursos vía cgroups, recolectar registros estructurados en journald y garantizar que el respaldo se lance incluso si el servidor estuvo temporalmente fuera de línea mediante la directiva Persistent=true.

Defina la unidad de servicio /etc/systemd/system/headscale-backup.service:

[Unit]
Description=Respaldo transaccional y criptografico de Headscale
After=network.target

[Service]
Type=oneshot
User=root
ExecStart=/usr/local/bin/headscale-backup.sh
Nice=19
IOSchedulingClass=idle
CPUSchedulingPolicy=other
MemoryMax=512M
ProtectSystem=full
ProtectHome=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

Defina el temporizador /etc/systemd/system/headscale-backup.timer:

[Unit]
Description=Disparador periodico de respaldo para Headscale
Requires=headscale-backup.service

[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=600
Persistent=true

[Install]
WantedBy=timers.target

Habilite y active la programación del temporizador:

sudo systemctl daemon-reload
sudo systemctl enable --now headscale-backup.timer

Inspeccione la cola de temporizadores del sistema para auditar el próximo disparo:

systemctl list-timers --all | grep headscale-backup

Protocolo de Recuperación ante Desastres (Disaster Recovery)

Ante una degradación física del hipervisor o pérdida total de la máquina virtual, el protocolo de recuperación en frío exige recrear el servicio en una nueva instancia KVM limpia. Desplegar sobre la infraestructura de tropic.host proporciona la ventaja técnica de operar sobre procesadores AMD EPYC o Intel Xeon con una tasa nula de robo de CPU (%st = 0.0%), impidiendo que fluctuaciones en el hipervisor retrasen el descifrado y la validación relacional durante una ventana de emergencia.

Paso 1: Aprovisionamiento del entorno de ejecución

En la nueva máquina virtual con Ubuntu 24.04 o Debian 12, instale el binario de Headscale y las utilidades requeridas:

# Instalación de utilidades base para el desempaquetado
sudo apt-get update && sudo apt-get install -y zstd sqlite3 tar curl

# Descarga e instalación del binario oficial de Headscale
HEADSCALE_VERSION="0.23.0"
curl -sSL -o headscale "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_amd64"
sudo chmod +x headscale
sudo mv headscale /usr/local/bin/

# Creación de usuario de sistema sin privilegios y directorios requeridos
sudo useradd --system --shell /usr/sbin/nologin --create-home --home-dir /var/lib/headscale headscale
sudo mkdir -p /etc/headscale /var/lib/headscale

Paso 2: Descompresión y aislamiento del material de respaldo

Transfiera el archivo .tar.zst desde su almacenamiento secundario (repositorio S3 o réplica cifrada off-site) al directorio /root/restore/:

mkdir -p /root/restore
cd /root/restore

# Descompresión del archivo tar con zstd
tar --zstd -xvf /root/restore/headscale_backup_20261004_033000.tar.zst

Paso 3: Validación forense de integridad estructural de SQLite

Nunca inicie Headscale sobre una base de datos restaurada sin validar previamente sus índices y claves foráneas:

# Comprobación de integridad exhaustiva
sqlite3 var/backups/headscale/db_*.sqlite "PRAGMA integrity_check;"
# Verificación de integridad referencial
sqlite3 var/backups/headscale/db_*.sqlite "PRAGMA foreign_key_check;"

Ambos comandos deben retornar sin errores y reportar ok. Cualquier salida divergente denota corrupción en el transporte y requiere recurrir a un punto de recuperación previo.

Paso 4: Inyección atómica de datos y material criptográfico

Mueva los ficheros validados a sus rutas absolutas finales y asigne rigurosamente los permisos de usuario del demonio:

# Detener el servicio si estuviese activo
sudo systemctl stop headscale || true

# Restauración de la base de datos
sudo mv var/backups/headscale/db_*.sqlite /var/lib/headscale/db.sqlite

# Restauración de la clave Noise original
sudo mv var/lib/headscale/noise_private.key /var/lib/headscale/noise_private.key

# Restauración de la configuración base
sudo mv etc/headscale/config.yaml /etc/headscale/config.yaml

# Aplicación estricta de propiedad y permisos (DAC)
sudo chown -R headscale:headscale /var/lib/headscale /etc/headscale
sudo chmod 0750 /var/lib/headscale /etc/headscale
sudo chmod 0640 /var/lib/headscale/db.sqlite
sudo chmod 0600 /var/lib/headscale/noise_private.key

Paso 5: Levantamiento del servicio y auditoría de adyacencias

Inicie el demonio y supervise que el motor SQLite active correctamente el modo WAL sobre el nuevo sistema de archivos:

sudo systemctl daemon-reload
sudo systemctl restart headscale
sudo systemctl status headscale --no-pager

Verifique la lista de nodos y el estado de expiración de las llaves registradas para confirmar que no se han extraviado registros de pares:

headscale nodes list

ID | Hostname       | User       | Machine Key | Node Key | Node IP      | Online
1  | srv-edge-01    | ops-infra  | [Xq8z...]   | [Y1p9...] | 100.64.0.1   | true
2  | workstation-adm| ops-infra  | [Ab3d...]   | [Z7k2...] | 100.64.0.2   | true

Paso 6: Telemetría de reconexión de pares en la red

Desde cualquier máquina cliente de la tailnet, valide que la sesión se reanuda de manera totalmente transparente sin requerir una nueva invocación del comando de inicio de sesión (tailscale up --login-server=...):

# Verificación en el cliente Tailscale
tailscale status
tailscale ping 100.64.0.1

Dado que el archivo noise_private.key y los pares de llaves WireGuard persistieron idénticos dentro de db.sqlite, los demonios tailscaled de los clientes reconocen la firma del plano de control, completan el apretón de manos Noise automáticamente y restablecen la topología de malla sin intervención humana ni interrupción de accesos remotos.

Preguntas frecuentes (FAQ)

¿Headscale transmite todo el tráfico de mis dispositivos?

No. Headscale solo actúa como servidor de coordinación y señalización. El tráfico real viaja directamente de punto a punto (P2P) entre tus dispositivos mediante túneles WireGuard cifrados.

¿Qué requisitos de servidor necesita Headscale?

Al ser un binario compilado en Go muy eficiente, un VPS KVM con 1 vCPU, 1 GB de RAM y almacenamiento NVMe es más que suficiente para coordinar cientos de dispositivos.

Volver al blog

Cómo Configurar Headscale en un VPS KVM: Servidor de Control Privado para Tailscale sin Intermediarios

Tabla de contenidos

Ventajas de Headscale frente a Tailscale SaaS: Privacidad y Rendimiento

Soberanía criptográfica y mitigación de fuga de metadatos

Eliminación de restricciones operativas y escalado horizontal

Optimización de rendimiento: El factor crítico de los relays DERP

Matriz comparativa: Tailscale SaaS vs. Headscale sobre VPS Dedicado

Ajuste de Kernel para Maximizar Rendimiento de Headscale y DERP

Configuración del Sistema Operativo y Activación de Reenvío de Paquetes IP

1. Desbloqueo del Reenvío de Paquetes a Nivel de Kernel (IPv4 e IPv6)

Análisis del Modo Loose en Reverse Path Filtering (rp_filter = 2)

2. Verificación y Operativa de TCP BBR sobre KVM

3. Ajuste de MTU y Pinzamiento de MSS (MSS Clamping)

Implementación con nftables (Estándar Moderno)

Alternativa con iptables (Legado / Docker nativo)

Despliegue de Headscale en Docker Compose con SQLite y config.yaml

Topología de almacenamiento y modelo de concurrencia en SQLite

Estructura de directorios y control de accesos POSIX

Especificación técnica de config.yaml

Desglose de directivas críticas

Manifiesto de orquestación docker-compose.yml

Inicialización y verificación del demonio

Configuración de Nginx Reverse Proxy con TLS 1.3 y WebSockets

Preparación del entorno de certificados con Certbot y ACME

Mapeo de WebSockets y optimización del núcleo en nginx.conf

Definición del VirtualHost perimetral para Headscale

Análisis de directivas críticas de transporte

Activación, verificación sintáctica y recarga del servicio

Validación de la terminación TLS y respuesta del endpoint

Gestión de Nodos, Usuarios y Rutas Exit-Node desde la Terminal

Segmentación de identidades mediante usuarios

Métodos de incorporación de nodos: Interactivo vs Pre-Auth Keys

1. Registro interactivo asistido por el operador

2. Registro desatendido mediante Pre-Auth Keys (Automatización CI/CD y despliegues headless)

Configuración del Kernel del VPS como Subnet Router y Exit-Node

1. Activación de Packet Forwarding en el sistema operativo

2. Reglas de Enmascaramiento (NAT / MASQUERADE) y Clamping de MSS

Anuncio y aprobación de rutas en Headscale

1. Anuncio de capacidades desde el nodo cliente

2. Inspección y aprobación en el plano de control

Conmutación del tráfico en los clientes y diagnóstico de enlace

Validación de transporte y calidad del enlace

Automatización de Respaldos de SQLite y Plan de Recuperación ante Desastres

Arquitectura de Estado: El Conjunto Crítico de Recuperación

Procedimiento Atómico de Copia con SQLite Online Backup API

Programación Determinista mediante Systemd Timers

Protocolo de Recuperación ante Desastres (Disaster Recovery)

Paso 1: Aprovisionamiento del entorno de ejecución

Paso 2: Descompresión y aislamiento del material de respaldo

Paso 3: Validación forense de integridad estructural de SQLite

Paso 4: Inyección atómica de datos y material criptográfico

Paso 5: Levantamiento del servicio y auditoría de adyacencias

Paso 6: Telemetría de reconexión de pares en la red

Preguntas frecuentes (FAQ)

¿Headscale transmite todo el tráfico de mis dispositivos?

¿Qué requisitos de servidor necesita Headscale?

Análisis del Modo Loose en Reverse Path Filtering (`rp_filter = 2`)

Implementación con `nftables` (Estándar Moderno)

Alternativa con `iptables` (Legado / Docker nativo)

Especificación técnica de `config.yaml`

Manifiesto de orquestación `docker-compose.yml`

Mapeo de WebSockets y optimización del núcleo en `nginx.conf`