hampusstrom.headscale
Rol de Ansible: Headscale
Un rol de Ansible para instalar y configurar Headscale, una implementación de código abierto y autoalojada del servidor de control de Tailscale.
Es increíble, échale un vistazo: juanfont/Headscale
Aviso
El autor de este proyecto no tiene ninguna relación con el proyecto Headscale o Tailscale Inc.
EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO, PERO NO LIMITÁNDOSE A, LAS GARANTÍAS DE COMERCIALIDAD, ADECUACIÓN A UN PROPÓSITO PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO EL AUTOR SERÁ RESPONSABLE POR CUALQUIER RECLAMO, DAÑOS U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRA MANERA, QUE SURJA DE O, O EN CONEXIÓN CON EL SOFTWARE O EL USO O OTRAS INTERACCIONES EN EL SOFTWARE.
ÚSALO BAJO TU PROPIA RESPONSABILIDAD
Compatibilidad
Este rol ha sido probado en las siguientes plataformas:
- CentOS 8 x64
- Debian 10 x64
- Debian 11 x64
- Ubuntu Server 20.04 x64
- Ubuntu Server 22.04 x64
Instalación
ansible-galaxy
ansible-galaxy install hampusstrom.headscale
Instalación manual
Solo para el usuario actual:
git clone https://github.com/hampusstrom/ansible-role-headscale.git ~/.ansible/roles/hampusstrom.headscale
A nivel de sistema:
git clone https://github.com/hampusstrom/ansible-role-headscale.git /etc/ansible/roles/hampusstrom.headscale
Requisitos
Este rol no tiene requisitos fuera de lo común y debería funcionar en cualquier lugar donde se ejecute Ansible, Headscale y systemd.
API de GitHub
Este rol utiliza la API de GitHub.
La API de GitHub tiene límites de tasa.
Los usuarios no autenticados solo pueden hacer 60 solicitudes por hora.
Si eres desarrollador, podrías alcanzar este límite fácilmente.
Para solucionarlo, puedes obtener un Token de Acceso Personal en: https://github.com/settings/tokens/new
Completa los detalles del token de acceso en las variables headscale_github_api_*.
headscale_github_api_username: tu_nombre_de_usuario_en_github
headscale_github_api_password: tu_token_de_acceso_personal
headscale_github_api_auth: true
Sistema(s) de inicio: systemd
Se requiere acceso root: sí
Dado que necesitamos acceso root, usa este rol en un playbook que tenga become: yes definido globalmente o llama a este rol usando la palabra clave become: yes.
- hosts: headscale
become: yes
roles:
- role: hampusstrom.headscale
# O
- hosts: headscale
roles:
- role: hampusstrom.headscale
become: yes
Variables del rol
Una descripción completa de todas las variables disponibles se puede encontrar en defaults/main.yaml.
Convención de nombres de variables
Las variables relacionadas con este rol siempre están precedidas por headscale_.
headscale_version
Define la versión de Headscale para descargar e instalar en las máquinas objetivo. Puede ser un número de versión (sin el prefijo 'v'). Es decir, 0.16.4 o latest.
Latest recuperará automáticamente la última etiqueta de lanzamiento del repositorio de GitHub juanfont/headscale.
predeterminado: latest
headscale_config
El contenido del archivo config.yaml de Headscale expresado como un objeto YAML. Consulta la configuración predeterminada en el proyecto Headscale para inspiración. A partir de este escrito, los siguientes valores mínimos son necesarios para la versión 0.20.0 de Headscale.
headscale_config:
server_url: "http://127.0.01:8080"
listen_addr: 127.0.0.1:8080
private_key_path: "{{ headscale_lib_dir_path }}/private.key"
db_type: sqlite3
unix_socket: "{{ headscale_run_dir_path }}/headscale.sock"
ip_prefixes:
- 100.64.0.0/10
noise:
private_key_path: "{{ headscale_lib_dir_path }}/noise_private.key"
headscale_acl
El contenido del archivo acl.yaml de Headscale expresado como un objeto YAML.
headscale_github_repository
Define el usuario/repositorio a utilizar al buscar y descargar el binario de Headscale. Se puede cambiar a otro repositorio para permitir instalaciones de bifurcaciones, por ejemplo.
predeterminado: juanfont/headscale
headscale_remove_unmanaged_users
Si se establece en verdadero, cualquier usuario no especificado en headscale_users será eliminado permanentemente.
Úsalo bajo tu propio riesgo
predeterminado: false
headscale_users
Una lista de usuarios que deben ser creados, y no eliminados si se usa junto con headscale_remove_unmanaged_users.
predeterminado: []
headscale_binary_path
Define dónde se descargará e instalará el binario de Headscale.
predeterminado: /usr/local/bin/headscale
headscale_user_name
Define el nombre del usuario del sistema que debe ejecutar el daemon de systemd de Headscale. Se creará si no existe ya.
predeterminado: headscale
headscale_user_group
Define el nombre del grupo principal del usuario headscale_user_name.
predeterminado: {{ headscale_user_name }}
headscale_user_uid
Define el ID de usuario del usuario headscale_user_name.
predeterminado: 777
headscale_user_gid
Define el ID de grupo del grupo headscale_user_group.
predeterminado: {{ headscale_user_uid }}
headscale_etc_dir_path
Define la ruta en la que deben residir los datos de configuración de Headscale. Normalmente no deberías cambiar esto, pero para algunas configuraciones/p bifurcaciones personalizadas, la opción está disponible.
predeterminado: /etc/headscale
headscale_lib_dir_path
Define la ruta en la que deben residir los datos de la biblioteca de Headscale. Normalmente no deberías cambiar esto, pero para algunas configuraciones/p bifurcaciones personalizadas, la opción está disponible.
predeterminado: /var/lib/headscale
headscale_run_dir_path
Define la ruta en la que debe residir el socket UNIX de Headscale. Normalmente no deberías cambiar esto, pero para algunas configuraciones/p bifurcaciones personalizadas, la opción está disponible. La entrada de configuración unix_socket debe apuntar a un archivo .sock en este directorio. es decir. unix_socket: /var/run/headscale/headscale.sock
predeterminado: /var/run/headscale
headscale_db_path
Ruta del archivo de base de datos sqlite.
predeterminado: {{ headscale_lib_dir_path }}/db.sqlite
headscale_backup_dir_path
Ruta donde se almacenarán las copias de seguridad de la base de datos. Las copias de seguridad se crean automáticamente antes de cualquier actualización de Headscale. Si eliges retroceder Headscale, se recomienda encarecidamente también restaurar tu base de datos. Para hacerlo, simplemente detén Headscale, copia el archivo db a headscale_db_path y reinicia Headscale.
predeterminado: {{ headscale_lib_dir_path }}/backups
Ejemplo de Playbook
Ten en cuenta que siempre debes consultar la documentación oficial de Headscale para asegurarte de que tienes todos los valores requeridos completados para tu versión de Headscale. Recomiendo encarecidamente copiar El ejemplo de configuración oficial y usarlo como base para tu configuración.
---
---
# Ejecuta con el comando:
# ansible-playbook -i "tuarchivo_de_inventario" -K ejemplo-playbook.yml
- hosts: all
become: yes
vars:
headscale_version: 0.20.0
headscale_config:
# Headscale buscará un archivo de configuración llamado `config.yaml` (o `config.json`) en el siguiente orden:
#
# - `/etc/headscale`
# - `~/.headscale`
# - directorio de trabajo actual
# La URL a la que los clientes se conectarán.
# Típicamente esto será un dominio como:
#
# https://myheadscale.ejemplo.com:443
#
server_url: http://127.0.0.1:8080
# Dirección para escuchar / enlazar en el servidor
#
# Para producción:
# listen_addr: 0.0.0.0:8080
listen_addr: 127.0.0.1:8080
# Dirección para escuchar /metrics, es posible que desees
# mantener este punto final privado para tu red interna
#
metrics_listen_addr: 127.0.0.1:9090
# Dirección para escuchar gRPC.
# gRPC se usa para controlar un servidor de Headscale
# de forma remota con la CLI
# Nota: El acceso remoto _solo_ funciona si tienes
# certificados válidos.
#
# Para producción:
# grpc_listen_addr: 0.0.0.0:50443
grpc_listen_addr: 127.0.0.1:50443
# Permitir que la interfaz de administración de gRPC se ejecute en MODO INSEGURO.
# Esto no es recomendable, ya que el tráfico no estará cifrado.
# Solo habilítalo si sabes lo que estás haciendo.
grpc_allow_insecure: false
# Clave privada utilizada para cifrar el tráfico entre Headscale
# y los clientes de Tailscale.
# El archivo de clave privada se generará automáticamente si falta.
#
# Para producción:
# /var/lib/headscale/private.key
private_key_path: ./private.key
# La sección Noise incluye una configuración específica para el
# protocolo Noise TS2021
noise:
# La clave privada Noise se utiliza para cifrar el
# tráfico entre Headscale y los clientes de Tailscale cuando
# se utiliza el nuevo protocolo basado en Noise. Debe ser diferente
# de la clave privada heredada.
#
# Para producción:
# private_key_path: /var/lib/headscale/noise_private.key
private_key_path: ./noise_private.key
# Lista de prefijos IP para asignar direcciones tail.
# Cada prefijo consiste en una dirección IPv4 o IPv6,
# y la longitud de prefijo asociada, delimitada por una barra.
# Aunque esto parece aceptar valores arbitrarios, debe
# estar dentro de los rangos IP soportados por el cliente Tailscale.
# IPv6: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#LL81C52-L81C71
# IPv4: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#L33
ip_prefixes:
- fd7a:115c:a1e0::/48
- 100.64.0.0/10
# DERP es un sistema de retransmisión que Tailscale utiliza cuando no se puede establecer una conexión directa.
# https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp
#
# Headscale necesita una lista de servidores DERP que se pueden presentar
# a los clientes.
derp:
server:
# Si se habilita, ejecuta el servidor DERP integrado y lo fusiona con el resto de la configuración DERP
# La URL del servidor Headscale definida arriba DEBE estar usando https, DERP requiere que TLS esté en su lugar
enabled: false
# ID de región para usar para el servidor DERP integrado.
# El DERP local prevalece si el ID de región choca con otros ID de región provenientes
# de la configuración regular de DERP.
region_id: 999
# El código de la región y el nombre se muestran en la interfaz de usuario de Tailscale para identificar una región DERP
region_code: "headscale"
region_name: "Headscale Embedded DERP"
# Escucha a través de UDP en la dirección configurada para conexiones STUN - para ayudar con la travesía NAT.
# Cuando el servidor DERP integrado está habilitado, stun_listen_addr DEBE estar definido.
#
# Para más detalles sobre cómo funciona esto, consulta este gran artículo: https://tailscale.com/blog/how-tailscale-works/
stun_listen_addr: "0.0.0.0:3478"
# Lista de mapas DERP disponibles externamente codificados en JSON
urls:
- https://controlplane.tailscale.com/derpmap/default
# Archivos de mapa DERP disponibles localmente codificados en YAML
#
# Esta opción es principalmente interesante para las personas que alojan
# sus propios servidores DERP:
# https://tailscale.com/kb/1118/custom-derp-servers/
#
# paths:
# - /etc/headscale/derp-example.yaml
paths: []
# Si se habilita, se configurará un trabajador para actualizar periódicamente
# las fuentes dadas y actualizar el derpmap
auto_update_enabled: true
# ¿Con qué frecuencia debemos verificar actualizaciones DERP?
update_frequency: 24h
# Deshabilita la verificación automática de actualizaciones de headscale al inicio
disable_check_updates: false
# ¿Tiempo antes de que un nodo epheméreo inactivo sea eliminado?
ephemeral_node_inactivity_timeout: 30m
# Período para verificar actualizaciones de nodos dentro de la tailnet. Un valor demasiado bajo afectará severamente
# el consumo de CPU de Headscale. Un valor demasiado alto (más de 60s) causará problemas
# para los nodos, ya que no recibirán actualizaciones ni mensajes de mantenimiento con suficiente frecuencia.
# En caso de duda, no toques el predeterminado de 10s.
node_update_check_interval: 10s
# Configuración de SQLite
db_type: sqlite3
# Para producción:
# db_path: /var/lib/headscale/db.sqlite
db_path: ./db.sqlite
# # Configuración de Postgres
# Si utilizas un socket Unix para conectarte a Postgres, establece la ruta del socket en el campo 'host' y deja 'port' en blanco.
# db_type: postgres
# db_host: localhost
# db_port: 5432
# db_name: headscale
# db_user: foo
# db_pass: bar
# Si se necesita otro 'sslmode' en lugar de 'require(true)' y 'disabled(false)', establece el 'sslmode' que necesitas
# en el campo 'db_ssl'. Refiérete a https://www.postgresql.org/docs/current/libpq-ssl.html Tabla 34.1.
# db_ssl: false
### Configuración de TLS
#
## Let's encrypt / ACME
#
# Headscale admite solicitar y configurar automáticamente
# TLS para un dominio con Let's Encrypt.
#
# URL del directorio ACME
acme_url: https://acme-v02.api.letsencrypt.org/directory
# Correo electrónico para registrarse con el proveedor ACME
acme_email: ""
# Nombre de dominio para solicitar un certificado TLS:
tls_letsencrypt_hostname: ""
# Ruta para almacenar certificados y metadatos necesitados por
# letsencrypt
# Para producción:
# tls_letsencrypt_cache_dir: /var/lib/headscale/cache
tls_letsencrypt_cache_dir: ./cache
# Tipo de desafío ACME a usar, tipos actualmente soportados:
# HTTP-01 o TLS-ALPN-01
# Consulta [docs/tls.md](docs/tls.md) para más información
tls_letsencrypt_challenge_type: HTTP-01
# Cuando se elige el desafío HTTP-01, letsencrypt debe establecer
# un punto final de verificación, y escuchará en:
# :http = puerto 80
tls_letsencrypt_listen: ":http"
## Usa certificados ya definidos:
tls_cert_path: ""
tls_key_path: ""
log:
# Formato de salida para los logs: texto o json
format: text
level: info
# Ruta a un archivo que contiene políticas de ACL.
# Las ACL pueden definirse como YAML o HUJSON.
# https://tailscale.com/kb/1018/acls/
acl_policy_path: ""
## DNS
#
# Headscale admite la configuración de DNS de Tailscale y MagicDNS.
# Consulta su KB para comprender mejor los conceptos:
#
# - https://tailscale.com/kb/1054/dns/
# - https://tailscale.com/kb/1081/magicdns/
# - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/
#
dns_config:
# Si se prefiere usar el DNS proporcionado por Headscale o usar el local.
override_local_dns: true
# Lista de servidores DNS a exponer a los clientes.
nameservers:
- 1.1.1.1
# NextDNS (consulta https://tailscale.com/kb/1218/nextdns/).
# "abc123" es un ejemplo de ID de NextDNS, reemplázalo con el tuyo.
#
# Con el intercambio de metadatos:
# nameservers:
# - https://dns.nextdns.io/abc123
#
# Sin el intercambio de metadatos:
# nameservers:
# - 2a07:a8c0::ab:c123
# - 2a07:a8c1::ab:c123
# DNS dividido (consulta https://tailscale.com/kb/1054/dns/),
# lista de dominios de búsqueda y el DNS a consultar para cada uno.
#
# restricted_nameservers:
# foo.bar.com:
# - 1.1.1.1
# darp.headscale.net:
# - 1.1.1.1
# - 8.8.8.8
# Dominios de búsqueda para inyectar.
domains: []
# Registros DNS extra
# hasta ahora solo se apoyan registros A (del lado de tailscale)
# Consulta https://github.com/juanfont/headscale/blob/main/docs/dns-records.md#Limitations
# extra_records:
# - name: "grafana.myvpn.ejemplo.com"
# type: "A"
# value: "100.64.0.3"
#
# # también puedes ponerlo en una línea
# - { name: "prometheus.myvpn.ejemplo.com", type: "A", value: "100.64.0.3" }
# Si se usará [MagicDNS](https://tailscale.com/kb/1081/magicdns/).
# Solo funciona si hay al menos un servidor de nombres definido.
magic_dns: true
# Define el dominio base para crear los nombres de host para MagicDNS.
# `base_domain` debe ser un FQDN, sin el punto final.
# El FQDN de los hosts será
# `hostname.user.base_domain` (por ejemplo, _mi_host.mi_usuario.ejemplo.com_).
base_domain: ejemplo.com
# Socket Unix utilizado para que la CLI se conecte sin autenticación
# Nota: para producción querrás establecer esto en algo como:
# unix_socket: /var/run/headscale.sock
unix_socket: ./headscale.sock
unix_socket_permission: "0770"
#
# Headscale admite soporte Experimental para OpenID connect,
# todavía se está probando y podría tener algunos errores, por favor
# ayúdanos a probarlo.
# OpenID Connect
# oidc:
# only_start_if_oidc_is_available: true
# issuer: "https://tu-emisor-oidc.com/ruta"
# client_id: "tu-id-de-cliente-oidc"
# client_secret: "tu-secreto-de-cliente-oidc"
# # Alternativamente, establece `client_secret_path` para leer el secreto del archivo.
# # Resuelve variables de entorno, facilitando la integración con `LoadCredential` de systemd:
# client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
# # client_secret y client_secret_path son mutuamente excluyentes.
#
# # El tiempo desde que un nodo se autentica con OpenID hasta que
# # expira y necesita reautenticarse.
# # Establecer el valor en "0" significará no vencer.
# expiry: 180d
#
# # Usa la expiración del token recibido de OpenID cuando el usuario inició sesión,
# # esto típicamente llevará a una necesidad frecuente de reautenticación y debería
# # habilitarse solo si sabes lo que estás haciendo.
# # Nota: habilitar esto hará que se ignore `oidc.expiry`.
# use_expiry_from_token: false
#
# # Personaliza los alcances utilizados en el flujo de OIDC, por defecto "openid", "profile" y "email" y agrega parámetros de consulta personalizados a la solicitud del endpoint de autorización.
# scopes: ["openid", "profile", "email", "custom"]
# extra_params:
# domain_hint: ejemplo.com
#
# # Lista de dominios y/o usuarios permitidos. Si el dominio de un usuario autenticado no está en esta lista, la
# # solicitud de autenticación será rechazada.
#
# allowed_domains:
# - ejemplo.com
# # Nota: Los grupos de keycloak tienen una barra inicial '/'
# allowed_groups:
# - /headscale
# allowed_users:
# - [email protected]
#
# # Si `strip_email_domain` se establece en `true`, se eliminará la parte del dominio de la dirección de correo electrónico del nombre de usuario.
# # Esto transformará `[email protected]` al usuario `nombre.apellido`
# # Si `strip_email_domain` se establece en `false`, la parte del dominio NO se eliminará resultando en lo siguiente
# usuario: `nombre.apellido.ejemplo.com`
#
# strip_email_domain: true
# Configuración de Logtail
# Logtail es la infraestructura de registro y auditoría de Tailscale, permite al panel de control
# instruir a los nodos de tailscale para que registren su actividad en un servidor remoto.
logtail:
# Habilita logtail para los clientes de este headscale.
# Como actualmente no hay soporte para anular el servidor de registros en headscale, esto está
# deshabilitado por defecto. Habilitar esto hará que tus clientes envíen registros a Tailscale Inc.
enabled: false
# Habilitar esta opción hace que los dispositivos prefieran un puerto aleatorio para el tráfico de WireGuard sobre
# el puerto estático predeterminado 41641. Esta opción está destinada como una solución para algunos dispositivos de
# firewall con errores. Consulta https://tailscale.com/kb/1181/firewalls/ para más información.
randomize_client_port: false
roles:
- hampusstrom.headscale
Etiquetas
install
Una instalación y configuración completa de Headscale y sus espacios de nombres.
configure
Solo actualiza el archivo de configuración y/o el archivo de unidad de systemd.
users
Solo configura espacios de nombres.
Licencia
MIT Licencia
Deploys Headscale, An open source, self-hosted implementation of the Tailscale control server.
ansible-galaxy install hampusstrom.headscale