La publication source présente les éléments essentiels pour qu’un client Docker Tailscale sur ZimaOS s’enregistre auprès d’un plan de contrôle Headscale auto-hébergé : un état persistant, une clé à usage unique ou de pré-authentification, l’URL Headscale personnalisée, l’accès TUN et les capacités requises du conteneur.
La documentation actuelle de Tailscale et de Headscale fournit désormais un contrat amont plus clair. Tailscale prend officiellement en charge l’URL d’un serveur de contrôle personnalisé, et Headscale documente à la fois l’enregistrement interactif et l’enregistrement avec une clé de pré-authentification. Utilisez ces méthodes officielles pour vérifier la commande et l’URL actuelles plutôt que de vous fier uniquement à une capture d’écran de 2025.
Headscale remplace le plan de contrôle de coordination de Tailscale
Headscale est une implémentation auto-hébergée du protocole du serveur de contrôle Tailscale. Les clients Tailscale créent toujours des tunnels chiffrés de pair à pair, mais l’enregistrement et la coordination sont gérés par l’instance Headscale de l’utilisateur au lieu du plan de contrôle Tailscale par défaut.
Conserver le répertoire d’état de Tailscale
La source a créé /DATA/AppData/tailscale/state et l’a associé à /var/lib/tailscale. C’est important, car l’identité et l’état du nœud doivent être conservés lors de la recréation du conteneur et après un redémarrage de l’hôte.
La source recommandait également des autorisations restrictives sur le répertoire d’état de l’hôte. C’est pertinent, car l’état fait partie de l’identité du nœud et ne doit pas être accessible en lecture à tout le monde.
Utiliser l’URL Headscale comme serveur de contrôle personnalisé
La documentation actuelle de Tailscale prend en charge les serveurs de contrôle personnalisés via :
tailscale login --login-server=<URL>La documentation de Headscale utilise le même modèle avec tailscale up --login-server <YOUR_HEADSCALE_URL>.
Voir les recommandations actuelles de Tailscale concernant les serveurs de contrôle personnalisés.
Utiliser une clé de pré-authentification pour l’enregistrement non interactif
La source a temporairement ajouté TS_AUTHKEY, a enregistré le nœud, puis a supprimé la variable. Headscale documente actuellement la création d’une clé de pré-authentification et son utilisation avec --authkey pour l’enregistrement non interactif.
Utilisez les méthodes d’enregistrement actuelles de Headscale.
Ne laissez pas de clé d’authentification réutilisable dans la définition de l’application
Si la clé est réutilisable ou possède une longue durée de validité, la laisser dans l’environnement de l’application ZimaOS crée une exposition inutile. Une fois l’identité du nœud correctement enregistrée, supprimez le secret d’enregistrement lorsqu’il n’est plus nécessaire.
Si une clé a été publiée sur un forum public ou dans une capture d’écran, révoquez-la et créez-en une nouvelle.
Le TUN du noyau et les capacités influencent le mode réseau
La source mappe /dev/net/tun et accorde NET_ADMIN/NET_RAW, ce qui correspond au style de mise en réseau du noyau plutôt qu’à une mise en réseau purement en espace utilisateur.
Les conteneurs Tailscale actuels peuvent également fonctionner en mode espace utilisateur. Choisissez donc délibérément le mode selon que vous avez besoin du routage de sous-réseaux, du comportement de nœud de sortie ou d’une mise en réseau complète du noyau.
Le réseau de l’hôte est puissant
La source utilise le réseau de l’hôte Docker. Cela supprime l’isolation habituelle des ports du conteneur et fait fonctionner Tailscale directement dans l’espace de noms réseau de l’hôte.
Ne passez pas du mode hôte au mode pont, ou inversement, sans comprendre comment l’application Tailscale actuelle stocke les routes, les écouteurs et les services annoncés.
L’URL Headscale doit être accessible de manière fiable et correctement sécurisée
Un serveur de contrôle auto-hébergé devient une infrastructure critique. Utilisez un DNS stable, une configuration TLS valide et des sauvegardes de la base de données et de la configuration de Headscale. Si le serveur de contrôle disparaît, les pairs existants peuvent continuer à communiquer temporairement, mais les nouvelles inscriptions et les modifications de coordination deviennent indisponibles.
La source présente une configuration fonctionnelle, pas un contrat d’assistance d’IceWhale
L’article ne contient aucune confirmation du personnel d’IceWhale. Il s’agit d’une configuration communautaire qui s’aligne bien sur les concepts en amont de Tailscale/Headscale, mais elle doit tout de même être testée avec le paquet Tailscale actuel de ZimaOS.
FAQ sur Headscale sur ZimaOS
Les clients Tailscale peuvent-ils utiliser un serveur de contrôle Headscale personnalisé ?
Oui. La documentation actuelle de Tailscale prend officiellement en charge les URL de serveurs de contrôle personnalisés.
TS_AUTHKEY doit-il rester définitivement dans l’application ?
Non. La source l’a supprimé après l’enregistrement, et les secrets d’enregistrement persistants ne doivent pas rester inutilement exposés.
Pourquoi conserver /var/lib/tailscale ?
Il conserve l’identité et l’état Tailscale du nœud lors de la recréation et du redémarrage du conteneur.
