hampusstrom.headscale
Rôle Ansible : Headscale
Un rôle Ansible pour installer et configurer Headscale, une implémentation open source et auto-hébergée du serveur de contrôle Tailscale.
C'est génial, allez voir : juanfont/Headscale
Avertissement
L'auteur de ce projet n'est en aucun cas affilié au projet Headscale ou à Tailscale Inc.
LE LOGICIEL EST FOURNI "EN L'ÉTA T", SANS GARANTIE D'AUCUNE SORTE, EXPRESSE OU IMPLICITE, Y COMPRIS MAIS SANS S'Y LIMITER AUX GARANTIES DE COMMERCIALISATION, D'ADAPTATION À UN USAGE PARTICULIER ET DE NON-VIOLATION. EN AUCUN CAS L'AUTEUR NE SERA RESPONSABLE D'UNE RÉCLAMATION, DE DOMMAGES OU D'UNE AUTRE RESPONSABILITÉ, QUE CE SOIT DANS LE CADRE D'UN CONTRAT, DÉLIT OU AUTRE, DÉCOULANT DE OU EN LIEN AVEC LE LOGICIEL OU L'UTILISATION OU D'AUTRES ÉCHANGES DANS LE LOGICIEL.
UTILISEZ À VOS RISQUES ET PÉRILS
Compatibilité
Ce rôle a été testé sur les plates-formes suivantes :
- CentOS 8 x64
- Debian 10 x64
- Debian 11 x64
- Ubuntu Server 20.04 x64
- Ubuntu Server 22.04 x64
Installation
ansible-galaxy
ansible-galaxy install hampusstrom.headscale
Installation Manuelle
Pour l'utilisateur actuel seulement :
git clone https://github.com/hampusstrom/ansible-role-headscale.git ~/.ansible/roles/hampusstrom.headscale
Pour l'ensemble du système :
git clone https://github.com/hampusstrom/ansible-role-headscale.git /etc/ansible/roles/hampusstrom.headscale
Exigences
Ce rôle n'a pas d'exigences particulières et devrait fonctionner sur toutes les machines où Ansible, Headscale et systemd fonctionnent.
API GitHub
Ce rôle utilise l'API GitHub.
L'API GitHub est limitée en nombre d'appels.
Les utilisateurs non authentifiés ne peuvent faire que 60 demandes par heure.
Si vous êtes un développeur, vous pourriez facilement atteindre cette limite.
Pour contourner cela, vous pouvez récupérer un token d'accès personnel à partir de : https://github.com/settings/tokens/new
Remplissez les détails du token d'accès dans les variables headscale_github_api_*.
headscale_github_api_username: votre_nom_utilisateur_github
headscale_github_api_password: votre_token_d'accès_personnel
headscale_github_api_auth: true
Système d'init : systemd
Accès root requis : oui
Puisque nous avons besoin des droits root, utilisez ce rôle dans un playbook qui a become:yes défini globalement ou appelez ce rôle en utilisant le mot-clé become: yes.
- hosts: headscale
become: yes
roles:
- role: hampusstrom.headscale
# OU
- hosts: headscale
roles:
- role: hampusstrom.headscale
become: yes
Variables de rôle
Une description complète de toutes les variables disponibles peut être trouvée sous defaults/main.yaml.
Convention de Nom des Variables
Les variables liées à ce rôle sont toujours préfixées par headscale_.
headscale_version
Définit la version de headscale à télécharger et à installer sur les machines cibles. Peut être soit un numéro de version (sans le préfixe 'v'). Par exemple : 0.16.4 ou latest
Le mot "latest" récupérera automatiquement le dernier tag de version publié dans le dépôt GitHub juanfont/headscale.
par défaut : latest
headscale_config
Le contenu du fichier config.yaml de headscale exprimé sous forme d'objet YAML. Consultez la configuration par défaut dans le projet headscale pour vous inspirer. Au moment de l'écriture, les valeurs minimales suivantes sont requises pour la version 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
Le contenu du fichier acl.yaml de headscale exprimé sous forme d'objet YAML.
headscale_github_repository
Définit l'utilisateur/repo à utiliser lors de la recherche et du téléchargement du binaire headscale. Peut être changé par un autre repo pour permettre l'installation de forks, par exemple.
par défaut : juanfont/headscale
headscale_remove_unmanaged_users
Si défini sur vrai, tous les utilisateurs non spécifiés dans headscale_users seront supprimés de manière permanente.
Utilisez à vos risques et périls
par défaut : false
headscale_users
Une liste d'utilisateurs qui devraient être créés et non supprimés s'ils sont utilisés avec headscale_remove_unmanaged_users.
par défaut : []
headscale_binary_path
Définit où le binaire headscale sera téléchargé et installé.
par défaut : /usr/local/bin/headscale
headscale_user_name
Définit le nom de l'utilisateur système qui doit exécuter le démon systemd de headscale. Sera créé s'il n'existe pas déjà.
par défaut : headscale
headscale_user_group
Définit le nom du groupe principal pour l'utilisateur headscale_user_name.
par défaut : {{ headscale_user_name }}
headscale_user_uid
Définit l'ID de l'utilisateur de l'utilisateur headscale_user_name.
par défaut : 777
headscale_user_gid
Définit l'ID de groupe du groupe headscale_user_group.
par défaut : {{ headscale_user_uid }}
headscale_etc_dir_path
Définit le chemin dans lequel les données de configuration de headscale devront se trouver. Vous ne devriez normalement pas avoir à changer cela, mais pour certaines configurations personnalisées/forks, l'option est là.
par défaut : /etc/headscale
headscale_lib_dir_path
Définit le chemin dans lequel les données de bibliothèque de headscale devront se trouver. Vous ne devriez normalement pas avoir à changer cela, mais pour certaines configurations personnalisées/forks, l'option est là.
par défaut : /var/lib/headscale
headscale_run_dir_path
Définit le chemin dans lequel le socket UNIX de headscale devra se trouver. Vous ne devriez normalement pas avoir à changer cela, mais pour certaines configurations personnalisées/forks, l'option est là. L'entrée de configuration unix_socket doit pointer vers un fichier .sock dans ce répertoire. c'est-à-dire : unix_socket: /var/run/headscale/headscale.sock
par défaut : /var/run/headscale
headscale_db_path
Chemin du fichier de base de données sqlite.
par défaut : {{ headscale_lib_dir_path }}/db.sqlite
headscale_backup_dir_path
Chemin où les sauvegardes de la base de données seront stockées. Les sauvegardes sont automatiquement créées avant toute mise à jour de headscale. Si vous choisissez de rétrograder headscale, il est fortement recommandé de restaurer également votre base de données. Pour ce faire, il vous suffit d'arrêter headscale, de copier le fichier de base de données à headscale_db_path et de redémarrer headscale.
par défaut : {{ headscale_lib_dir_path }}/backups
Exemple de Playbook
Notez que vous devriez toujours vérifier la documentation officielle de headscale pour vous assurer que vous avez toutes les valeurs nécessaires pour votre version de headscale. Je recommande fortement de copier l'exemple de configuration officiel et de l'utiliser comme base pour votre configuration.
---
---
# Exécutez avec la commande :
# ansible-playbook -i "votrefichierdinventaire" -K exemple-playbook.yml
- hosts: all
become: yes
vars:
headscale_version: 0.20.0
headscale_config:
# headscale cherchera un fichier de configuration nommé `config.yaml` (ou `config.json`) dans cet ordre :
#
# - `/etc/headscale`
# - `~/.headscale`
# - répertoire de travail actuel
# L'url à laquelle les clients se connecteront.
# Typiquement, ce sera un domaine comme :
#
# https://monheadscale.exemple.com:443
#
server_url: http://127.0.0.1:8080
# Adresse à écouter / à lier sur le serveur
#
# Pour la production :
# listen_addr: 0.0.0.0:8080
listen_addr: 127.0.0.1:8080
# Adresse à écouter pour /metrics, vous pourriez vouloir
# garder ce point de terminaison privé à votre réseau interne
#
metrics_listen_addr: 127.0.0.1:9090
# Adresse à écouter pour gRPC.
# gRPC est utilisé pour contrôler un serveur headscale
# à distance avec la CLI
# Remarque : L'accès à distance _seulement_ fonctionne si vous avez
# des certificats valides.
#
# Pour la production :
# grpc_listen_addr: 0.0.0.0:50443
grpc_listen_addr: 127.0.0.1:50443
# Autoriser l'interface d'administration gRPC à fonctionner en mode INSECURE.
# Il n'est pas recommandé d'activer cela car le trafic sera
# non chiffré. N'activez cela que si vous savez ce que vous faites.
grpc_allow_insecure: false
# Clé privée utilisée pour chiffrer le trafic entre headscale
# et les clients Tailscale.
# Le fichier de clé privée sera généré automatiquement s'il manque.
#
# Pour la production :
# /var/lib/headscale/private.key
private_key_path: ./private.key
# La section Noise inclut la configuration spécifique pour le
# protocole Noise TS2021
noise:
# La clé privée Noise est utilisée pour chiffrer le
# trafic entre headscale et les clients Tailscale lors de
# l'utilisation du nouveau protocole basé sur Noise. Elle doit être différente
# de la clé privée d'origine.
#
# Pour la production :
# private_key_path: /var/lib/headscale/noise_private.key
private_key_path: ./noise_private.key
# Liste des préfixes IP à partir desquels allouer des adresses.
# Chaque préfixe se compose soit d'une adresse IPv4 soit IPv6,
# et de la longueur du préfixe associée, délimitées par une barre.
# Bien que cela semble pouvoir prendre des valeurs arbitraires, cela
# doit être dans des plages d'IP prises en charge par le client 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 est un système de relais que Tailscale utilise lorsque
# une connexion directe ne peut être établie.
# https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp
#
# headscale a besoin d'une liste de serveurs DERP qui peuvent être présentés
# aux clients.
derp:
server:
# Si activé, exécute le serveur DERP embarqué et l'intègre dans le reste de la configuration DERP.
# L'url du serveur headscale définie ci-dessus DOIT utiliser https, le DERP nécessite que TLS soit en place.
enabled: false
# ID de région à utiliser pour le serveur DERP embarqué.
# Le DERP local prévaut si l'ID de région entre en conflit avec d'autres ID de région provenant de
# la configuration DERP régulière.
region_id: 999
# Le code de région et le nom sont affichés dans l'interface utilisateur de Tailscale pour identifier une région DERP.
region_code: "headscale"
region_name: "DERP intégré Headscale"
# Écoute sur UDP à l'adresse configurée pour les connexions STUN - pour aider au traversal NAT.
# Lorsque le serveur DERP embarqué est activé, stun_listen_addr DOIT être défini.
#
# Pour plus de détails sur le fonctionnement, consultez cet excellent article : https://tailscale.com/blog/how-tailscale-works/
stun_listen_addr: "0.0.0.0:3478"
# Liste des cartes DERP accessibles externes encodées en JSON
urls:
- https://controlplane.tailscale.com/derpmap/default
# Fichiers de carte DERP disponibles localement encodés en YAML
#
# Cette option est surtout intéressante pour les personnes hébergeant
# leurs propres serveurs DERP :
# https://tailscale.com/kb/1118/custom-derp-servers/
#
# paths:
# - /etc/headscale/derp-example.yaml
paths: []
# Si activé, un travailleur sera mis en place pour rafraîchir périodiquement
# les sources données et mettre à jour la carte derp.
auto_update_enabled: true
# À quelle fréquence devrions-nous vérifier les mises à jour DERP ?
update_frequency: 24h
# Désactive la vérification automatique des mises à jour de headscale au démarrage
disable_check_updates: false
# Temps avant qu'un nœud éphémère inactif soit supprimé ?
ephemeral_node_inactivity_timeout: 30m
# Période de vérification des mises à jour des nœuds dans le tailnet. Une valeur trop basse affectera gravement
# la consommation du CPU de Headscale. Une valeur trop élevée (plus de 60s) causera des problèmes
# pour les nœuds, car ils ne recevront pas des mises à jour ou des messages de maintien en vie suffisamment souvent.
# En cas de doute, ne modifiez pas la valeur par défaut de 10s.
node_update_check_interval: 10s
# Configuration SQLite
db_type: sqlite3
# Pour la production :
# db_path: /var/lib/headscale/db.sqlite
db_path: ./db.sqlite
# # Configuration Postgres
# Si vous utilisez un socket Unix pour vous connecter à Postgres, mettez le chemin du socket dans le champ 'host' et laissez 'port' vide.
# db_type: postgres
# db_host: localhost
# db_port: 5432
# db_name: headscale
# db_user: foo
# db_pass: bar
# Si un autre 'sslmode' est requis au lieu de 'require(true)' et 'disabled(false)', définissez le 'sslmode' dont vous avez besoin
# dans le champ 'db_ssl'. Se référer à https://www.postgresql.org/docs/current/libpq-ssl.html Tableau 34.1.
# db_ssl: false
### Configuration TLS
#
## Let's Encrypt / ACME
#
# headscale prend en charge la demande automatique et la configuration
# de TLS pour un domaine avec Let's Encrypt.
#
# URL du répertoire ACME
acme_url: https://acme-v02.api.letsencrypt.org/directory
# Email pour s'inscrire auprès du fournisseur ACME
acme_email: ""
# Nom de domaine pour demander un certificat TLS :
tls_letsencrypt_hostname: ""
# Chemin pour stocker les certificats et les métadonnées nécessaires à
# letsencrypt
# Pour la production :
# tls_letsencrypt_cache_dir: /var/lib/headscale/cache
tls_letsencrypt_cache_dir: ./cache
# Type de challenge ACME à utiliser, types actuellement supportés :
# HTTP-01 ou TLS-ALPN-01
# Voir [docs/tls.md](docs/tls.md) pour plus d'informations
tls_letsencrypt_challenge_type: HTTP-01
# Lorsque le challenge HTTP-01 est choisi, letsencrypt doit mettre en place un
# point de terminaison de vérification, qui écoutera sur :
# :http = port 80
tls_letsencrypt_listen: ":http"
## Utiliser des certificats déjà définis :
tls_cert_path: ""
tls_key_path: ""
log:
# Format de sortie pour les logs : texte ou json
format: text
level: info
# Chemin vers un fichier contenant des politiques ACL.
# Les ACL peuvent être définies en tant que YAML ou HUJSON.
# https://tailscale.com/kb/1018/acls/
acl_policy_path: ""
## DNS
#
# headscale prend en charge la configuration DNS de Tailscale et MagicDNS.
# Veuillez consulter leur KB pour mieux comprendre les concepts :
#
# - https://tailscale.com/kb/1054/dns/
# - https://tailscale.com/kb/1081/magicdns/
# - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/
#
dns_config:
# Que préférer utiliser le DNS fourni par Headscale ou utiliser le DNS local.
override_local_dns: true
# Liste des serveurs DNS à exposer aux clients.
nameservers:
- 1.1.1.1
# NextDNS (voir https://tailscale.com/kb/1218/nextdns/).
# "abc123" est un exemple d'ID NextDNS, remplacez-le par le vôtre.
#
# Avec partage de métadonnées :
# nameservers:
# - https://dns.nextdns.io/abc123
#
# Sans partage de métadonnées :
# nameservers:
# - 2a07:a8c0::ab:c123
# - 2a07:a8c1::ab:c123
# DNS fractionné (voir https://tailscale.com/kb/1054/dns/),
# liste des domaines de recherche et le DNS à interroger pour chacun.
#
# restricted_nameservers:
# foo.bar.com:
# - 1.1.1.1
# darp.headscale.net:
# - 1.1.1.1
# - 8.8.8.8
# Domaines de recherche à injecter.
domains: []
# Enregistrements DNS supplémentaires
# jusqu'à présent seuls les enregistrements A sont pris en charge (du côté tailscale)
# Voir https://github.com/juanfont/headscale/blob/main/docs/dns-records.md#Limitations
# extra_records:
# - name: "grafana.myvpn.example.com"
# type: "A"
# value: "100.64.0.3"
#
# # vous pouvez aussi le mettre sur une ligne
# - { name: "prometheus.myvpn.example.com", type: "A", value: "100.64.0.3" }
# Que utiliser [MagicDNS](https://tailscale.com/kb/1081/magicdns/).
# Ne fonctionne que s'il y a au moins un serveur de noms défini.
magic_dns: true
# Définit le domaine de base pour créer les noms d'hôtes pour MagicDNS.
# `base_domain` doit être un FQDN, sans le point traînant.
# Le FQDN des hôtes sera
# `hostname.user.base_domain` (par exemple, _monhôte.monutilisateur.exemple.com_).
base_domain: example.com
# Socket Unix utilisé par la CLI pour se connecter sans authentification
# Remarque : pour la production, vous voudrez définir cela sur quelque chose comme :
# unix_socket: /var/run/headscale.sock
unix_socket: ./headscale.sock
unix_socket_permission: "0770"
#
# headscale prend en charge le support OpenID connect expérimental,
# il est toujours en cours d'essai et pourrait avoir quelques bogues, veuillez
# nous aider à le tester.
# OpenID Connect
# oidc:
# only_start_if_oidc_is_available: true
# issuer: "https://votre-oidc.issuer.com/path"
# client_id: "votre-id-client-oidc"
# client_secret: "votre-secret-client-oidc"
# # Alternativement, définissez `client_secret_path` pour lire le secret à partir du fichier.
# # Cela résout les variables d'environnement, ce qui permet une intégration facile avec systemd.
# client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
# # client_secret et client_secret_path sont mutuellement exclusifs.
#
# # La durée pendant laquelle un nœud est authentifié avec OpenID avant qu'il
# # n'expire et doive se ré-authentifier.
# # Définir la valeur à "0" signifie pas d'expiration.
# expiry: 180d
#
# # Utilisez l'expiration du token reçu de l'OpenID lorsque l'utilisateur a
# # été connecté, cela entraînera généralement un besoin fréquent de ré-authentification
# # et ne doit être activé que si vous savez ce que vous faites.
# # Remarque : activer cela ignorera `oidc.expiry`.
# use_expiry_from_token: false
#
# # Personnalisez les scopes utilisés dans le flux OIDC, par défaut "openid", "profile" et "email" et ajoutez des paramètres de requête personnalisés
# # à la demande du point de terminaison d'autorisation. Les scopes par défaut sont "openid", "profile" et "email".
#
# scope: ["openid", "profile", "email", "personnalisé"]
# extra_params:
# domain_hint: example.com
#
# # Liste des domaines et/ou utilisateurs autorisés. Si le domaine d'un utilisateur authentifié n'est pas dans cette liste, la
# # demande d'authentification sera rejetée.
#
# allowed_domains:
# - example.com
# # Remarque : Les groupes de keycloak ont un '/' devant
# allowed_groups:
# - /headscale
# allowed_users:
# - [email protected]
#
# # Si `strip_email_domain` est défini sur `true`, la partie domaine de l'adresse e-mail de l'utilisateur sera supprimée.
# # Cela transformera `[email protected]` en utilisateur `prenom.nom`
# # Si `strip_email_domain` est défini sur `false`, la partie domaine ne sera PAS supprimée, ce qui donnera l'utilisateur suivant : `prenom.nom.example.com`
#
# strip_email_domain: true
# Configuration Logtail
# Logtail est l'infrastructure de journalisation et d'audit de Tailscale, elle permet au panneau de contrôle
# d'instruire les nœuds de Tailscale à journaliser leur activité sur un serveur distant.
logtail:
# Activer logtail pour les clients de ce headscale.
# Comme il n'y a actuellement aucun support pour remplacer le serveur de journaux dans headscale, cela est
# désactivé par défaut. L'activer fera en sorte que vos clients envoient des journaux à Tailscale Inc.
enabled: false
# Activer cette option fait que les appareils préfèrent un port aléatoire pour le trafic WireGuard plutôt que le
# port statique par défaut 41641. Cette option est prévue comme solution de contournement pour certains appareils de pare-feu défectueux. Voir https://tailscale.com/kb/1181/firewalls/ pour plus d'informations.
randomize_client_port: false
roles:
- hampusstrom.headscale
Tags
install
Une installation complète et la configuration de headscale et de ses espaces de noms.
configure
Met seulement à jour le fichier de configuration et/ou le fichier d'unité systemd.
users
Configure uniquement les espaces de noms.
Licence
MIT Licence
Deploys Headscale, An open source, self-hosted implementation of the Tailscale control server.
ansible-galaxy install hampusstrom.headscale