Intégration domotique Tailscale, gratuite et open source

Surveillez les machines de votre réseau Tailscale : connexion, mises à jour, clés.

• Publiée par prohand
• Appareils
• Version 1.0.1
• Nécessite Gladys >=5.1.0
• ★ 0

Voir sur GitHubToutes les intégrations

Cette intégration connecte Gladys à votre réseau Tailscale (votre « tailnet ») : chaque machine du tailnet — un serveur, un NAS, un téléphone, un routeur de sous-réseau — devient un appareil Gladys qui indique si elle est en ligne, si une mise à jour de Tailscale l'attend et quand sa clé expire.

Elle lit le tailnet via l'API Tailscale, dans le cloud (api.tailscale.com). Rien à installer sur vos machines, et Gladys n'a pas besoin d'être lui-même sur le tailnet.

Nécessite Gladys 5.1 ou plus récent.

Avant de commencer

Il faut être administrateur du tailnet (rôle Owner, Admin ou IT admin) pour créer les identifiants ci-dessous.

L'intégration se connecte avec l'un de ces deux moyens :

Méthode	Où le créer	Expiration
Jeton d'accès API	Settings → Keys	après 1 à 90 jours
Client OAuth	Settings → OAuth clients	jamais (recommandé)

Jeton d'accès API

1. Ouvrez Settings → Keys dans la console d'administration Tailscale.
2. Sous API access tokens, cliquez sur Generate access token, donnez une description (« Gladys ») et une durée de validité.
3. Copiez le jeton (tskey-api-…) : Tailscale ne l'affiche qu'une fois.

Quand le jeton expire, l'intégration affiche « Tailscale refuse les identifiants » et les appareils passent injoignables : générez-en un nouveau et collez-le dans la configuration.

Client OAuth (recommandé)

Un client OAuth n'expire jamais, et vous choisissez précisément ce qu'il peut faire.

1. Ouvrez Settings → OAuth clients.
2. Cliquez sur Generate OAuth client.
3. Cochez le droit Devices → Core :
   • Read suffit pour surveiller les machines ;
   • Write est aussi nécessaire pour activer ou désactiver l'expiration de la clé d'une machine depuis Gladys.
4. Copiez le Client ID et le Client secret (tskey-client-…) : le secret n'est affiché qu'une fois.

Configuration

1. Ouvrez l'onglet Configuration de l'intégration.
2. Choisissez la Méthode de connexion et remplissez ses champs :
   • jeton d'accès API : collez-le dans Jeton d'accès API ;
   • client OAuth : collez ID du client OAuth et Secret du client OAuth.
3. Tailnet : laissez -, le tailnet des identifiants. Ne le changez que si votre jeton peut atteindre plusieurs tailnets : mettez l'ID du tailnet affiché dans Settings → General de la console d'administration.
4. Intervalle de rafraîchissement : fréquence de lecture du tailnet, toutes les 60 secondes par défaut (30 secondes minimum). Chaque lecture est une seule requête, quel que soit le nombre de machines.
5. Alerte d'expiration des clés : combien de jours avant l'expiration d'une clé la machine est signalée (14 par défaut).
6. Inclure les machines partagées avec vous : les machines qu'un autre tailnet partage avec le vôtre sont masquées par défaut, puisque vous ne les gérez pas.
7. Enregistrez, puis cliquez sur Tester la connexion : le message indique combien de machines l'intégration voit.
8. Ouvrez l'onglet Découverte et ajoutez les machines à suivre.

Ce que vous obtenez

Chaque machine devient un appareil avec quatre fonctionnalités :

Fonctionnalité	Signification
En ligne (Online)	La machine est connectée au tailnet en ce moment
Mise à jour (Update available)	Une version plus récente de Tailscale existe pour cette machine
Expiration (Key expiry)	Jours restants avant l'expiration de sa clé (pas mis à jour quand l'expiration est coupée)
Expiration désactivée	L'interrupteur du menu Disable key expiry de la console — vous pouvez le changer

Activer Key expiry disabled depuis Gladys revient à cliquer sur Disable key expiry dans la console d'administration : la machine n'aura plus jamais à se reconnecter. Il faut un jeton d'accès API, ou un client OAuth avec le droit Devices → Core : Write.

Chaque appareil porte un badge cloud tant que l'API Tailscale répond, et injoignable sinon : les valeurs affichées sont alors les dernières lues.

Les machines sont reconnues par leur identifiant Tailscale : renommer une machine dans la console garde son appareil et son historique dans Gladys.

Scènes

L'intégration ajoute ses propres cartes à l'éditeur de scènes, dans la catégorie Intégrations.

Déclencheurs

• Machine en ligne ou hors ligne — une machine s'est connectée au tailnet ou s'en est déconnectée. Choisissez si besoin la machine et le nouvel état ; laissés vides, toute machine et tout changement conviennent. Variables : device_name, state (online ou offline), ip, last_seen.
• Nouvelle machine dans le tailnet — une machine a rejoint le tailnet. Filtrez sur Approbation pour n'être prévenu que des machines en attente d'approbation (si l'approbation des appareils est activée). Variables : device_name, authorization (authorized ou pending), os, user, ip.
• Mise à jour Tailscale disponible — une version plus récente de Tailscale est disponible pour une machine. Variables : device_name, client_version.
• Clé bientôt expirée — la clé d'une machine entre dans le délai d'alerte de la configuration. Variables : device_name, days_left, expires.

Les actions suivantes de la scène lisent une variable sous la forme {{triggerEvent.data.device_name}}.

Chaque déclencheur se produit une fois par changement, quand l'intégration le remarque (à l'intervalle de rafraîchissement). Le démarrage de l'intégration ne déclenche rien : elle prend d'abord note du tailnet tel qu'il est.

Exemple : quand une machine passe hors ligne, m'envoyer le message « {{triggerEvent.data.device_name}} est hors ligne ».

Actions

• Actualiser le tailnet — lit toutes les machines maintenant. Renvoie machine_count, online_count et offline_count.
• Lire l'état d'une machine — renvoie name, online, ip, last_seen, os, client_version, update_available, key_expiry_disabled et key_expiry_days (-1 quand la clé n'expire jamais), pour les conditions et messages qui suivent.
• Modifier l'expiration de la clé — désactive l'expiration de la clé d'une machine, ou la réactive. Renvoie key_expiry_disabled.

Tableau de bord

Ajoutez le widget Réseau Tailscale à un tableau de bord. Il affiche :

• le nombre de machines en ligne et hors ligne ;
• si l'API répond, la dernière lecture du tailnet, le nombre de machines avec une mise à jour en attente, une clé qui expire bientôt ou en attente d'approbation ;
• une liste de machines, avec un badge pour le problème le plus urgent. Touchez une machine pour voir ses adresses, son propriétaire, ses tags et la date d'expiration de sa clé, avec un lien vers sa page dans la console.

Réglages de chaque widget :

• Machines listées : celles à traiter (par défaut), seulement celles hors ligne, ou toutes ;
• Lignes : nombre de machines affichées (0 à 8).

Le bouton Actualiser lit le tailnet tout de suite ; Console d'admin ouvre la console d'administration Tailscale.

Dépannage

Message	Que faire
Aucun identifiant Tailscale	Remplissez les champs de la méthode de connexion choisie
Tailscale refuse les identifiants	Le jeton a expiré ou a été révoqué, ou le client OAuth est faux : créez-en un nouveau
Accès refusé : il manque au jeton le droit « devices »	Donnez au client OAuth le droit Devices → Core
Tailnet introuvable	Remettez - dans Tailnet, ou l'ID exact de Settings → General
Tailscale limite les requêtes	Augmentez l'intervalle de rafraîchissement
L'API Tailscale est injoignable depuis Gladys	Vérifiez l'accès internet de la machine Gladys (api.tailscale.com, HTTPS)

Une machine apparaît hors ligne alors qu'elle fonctionne ? Elle est hors ligne pour Tailscale : le client est arrêté, déconnecté, ou sa clé a expiré. La console d'administration affiche la même chose.

L'intégration journalise tout ce qu'elle fait : ouvrez les logs de l'intégration dans Gladys. Elle n'écrit jamais un jeton ni un secret dans les logs.

Paramètres de configuration

Voici les paramètres demandés par Tailscale dans son écran de configuration dans Gladys.

Paramètre	Type	Obligatoire	Description
Pour commencer	section	Non	L'intégration lit votre tailnet via l'API Tailscale, dans le cloud : rien à installer sur vos machines. Créez un jeton d'accès API (Settings → Keys, il expire au plus tard après 90 jours) ou, mieux, un client OAuth avec le droit « devices:core » (Settings → OAuth clients, il n'expire jamais), puis collez-le ci-dessous.
Méthode de connexion	select	Oui
Jeton d'accès API	secret	Non	Uniquement pour la méthode « Jeton d'accès API ».
ID du client OAuth	string	Non	Uniquement pour la méthode « Client OAuth ».
Secret du client OAuth	secret	Non
Tailnet	string	Non	Laissez « - » pour le tailnet du jeton. Sinon son ID, affiché dans Settings → General.
Intervalle de rafraîchissement (s)	number	Non	Fréquence de lecture du tailnet, en secondes. Une requête par lecture, quel que soit le nombre de machines.
Alerte d'expiration des clés (jours)	number	Non	Une machine dont la clé expire dans ce délai déclenche « Clé bientôt expirée ».
Inclure les machines partagées avec vous	boolean	Non	Les machines qu'un autre tailnet partage avec le vôtre. Masquées par défaut : vous ne les gérez pas.

Comment installer Tailscale dans Gladys

1. Dans Gladys, ouvrez Intégrations : Tailscale apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
2. Cliquez sur Installer. Gladys télécharge l'image Docker (ghcr.io/prohand/gladys-tailscale:1.0.1), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration).
3. Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
4. Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/prohand/gladys-tailscale.

Tailscale nécessite Gladys >=5.1.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.

Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.

À propos des intégrations externes

Tailscale est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par prohand, et non par l'équipe cœur de Gladys.

• Parcourir toutes les intégrations, natives et communautaires
• Créer et publier votre propre intégration externe
• Code source sur GitHub — source de cette documentation

Inscrivez-vous à la newsletter Gladys Assistant

Quelques emails par mois sur les nouveautés et l'actualité du projet. Envoyés par Pierre-Gilles Leymarie, le fondateur du projet. Désinscription possible à tout moment 🙂