Aller au contenu principal

Intégration domotique PiKVM, gratuite et open source

Intégration PiKVM pour Gladys Assistant

KVM IP PiKVM : alimentation ATX de la machine (allumer, éteindre, reset), voyants.

Commandez l'alimentation ATX de la machine reliée à un PiKVM et lisez ses voyants depuis Gladys, par l'API HTTPS locale du PiKVM (kvmd). Intégration non officielle, sans lien avec PiKVM. Jamais testé avec un vrai appareil : écrit d'après la documentation officielle de l'API (https://docs.pikvm.org/api/) et testé contre un PiKVM simulé.

Ce que vous obtenez​

Un appareil par PiKVM :

FonctionNatureOrigine
Alimentation (voyant)binaire, lecture seuleGET /api/atx, leds.power
Activité disque (voyant)binaire, lecture seule, sans historiqueGET /api/atx, leds.hdd
Température du PiKVM°C, lecture seuleGET /api/info?fields=hw, toutes les 5 min
ÉteindreboutonPOST /api/atx/power?action=off
Allumerbouton, désactivé par défautPOST /api/atx/power?action=on
Forcer l'extinctionbouton, désactivé par défautPOST /api/atx/power?action=off_hard
Resetbouton, désactivé par défautPOST /api/atx/power?action=reset_hard

Les voyants demandent la carte ATX du PiKVM (ou un câblage équivalent). Quand l'ATX est désactivé sur le PiKVM, les voyants restent inconnus (jamais affichés éteints) et le badge de l'appareil le signale.

Installation​

  1. Dans Gladys, ouvrez l'intégration, saisissez l'adresse du PiKVM (comme dans votre navigateur, ex. 192.168.1.20 ; HTTPS uniquement ; :port si vous l'avez déplacé), l'identifiant et le mot de passe de son interface web, puis enregistrez. Le mot de passe doit être en ASCII imprimable (il passe dans un en-tête HTTP).
  2. Cliquez deux fois sur Faire confiance au certificat. Le PiKVM présente un certificat auto-signé : le premier clic montre son empreinte SHA-256 et n'envoie rien d'autre. Comparez-la avec celle que votre navigateur affiche pour https://<adresse>/ (détails du certificat), puis cliquez de nouveau dans les 2 minutes. Vous pouvez aussi saisir l'empreinte dans la configuration. Ensuite, un autre certificat arrête tout (aucun mot de passe ne lui est envoyé) jusqu'à ce que vous lui fassiez confiance de la même façon.
  3. Lancez un Scan dans la Découverte et créez l'appareil.

Double authentification (2FA)​

Si le PiKVM demande un code, cochez Double authentification (2FA) active, enregistrez, puis cliquez sur Se connecter avec un code 2FA et saisissez le code du moment (6 caractères numériques) de votre application d'authentification. L'intégration envoie une fois le mot de passe suivi du code (comme le dit la documentation du PiKVM) et garde la session obtenue en mémoire seulement. Le code n'est jamais gardé. La session dure jusqu'au redémarrage du PiKVM ou de l'intégration (ou jusqu'à sa fermeture sur le PiKVM) : ensuite rien n'est lu ni envoyé, et le statut demande un nouveau code. En 2FA sans session, le bouton Éteindre ne peut pas partir non plus.

Les boutons​

Éteindre est un appui court sur le bouton d'alimentation (kvmd off, qui ne fait rien quand la machine est déjà éteinte) : le système s'arrête proprement, comme avec le bouton du boîtier. Il ne demande aucune option et n'est retenu ni par une pause, ni par une lecture, ni par une autre commande en cours. Il n'est non fait (« rien envoyé ») que si rien ne peut joindre le PiKVM sûrement, ou si le PiKVM le refuse : intégration non configurée, certificat non épinglé ou changé, identifiants refusés, 2FA sans session, réponse du PiKVM qui le refuse (redirection, 4xx comme ATX désactivé, droits ou introuvable) ou réponse non comprise. Quand le PiKVM ne le prend pas (occupé, erreur 5xx ou 429, injoignable), il est réessayé dans les 3,5 s qu'attend Gladys ; toujours pas pris, il est gardé (aussi après un redémarrage) et renvoyé par des lectures faites toutes les 10 s, seulement tant qu'elles montrent la machine allumée, 3 fois et 2 minutes après le clic au plus, puis abandonné dès qu'une lecture montre la machine éteinte, ou dès qu'un Allumer ou un Reset part (même sans réponse, ou refusé par le PiKVM : la machine démarre peut-être ; le statut le dit). Il n'est gardé que pour le PiKVM visé : enregistrer une autre adresse l'abandonne pour de bon (même si l'ancienne adresse revient), et ses essais gardent toujours l'adresse, le certificat et les identifiants du PiKVM cliqué. Un arrêt parti sans réponse est signalé « envoyé, sans confirmation » et n'est pas renvoyé de lui-même (un second appui pourrait être pris aussi).

Allumer, Forcer l'extinction (bouton d'alimentation maintenu 5 s : les données non enregistrées sont perdues) et Reset (redémarrage brutal) sont désactivés par défaut : cochez leur option dans la configuration. Chacun :

  • lit l'état ATX juste après votre clic et décide d'après lui : Allumer seulement quand le voyant se lit éteint (sinon « déjà allumée, rien envoyé »), Forcer l'extinction seulement quand il se lit allumé, Reset seulement sur une machine qui se lit allumée ;
  • est refusé quand l'ATX est occupé ou désactivé, pendant une pause 429/5xx et, pour Allumer et Reset, pendant 1 minute après un arrêt ou une extinction forcée ;
  • passe un à la fois, un par 30 secondes ;
  • est revérifié (option, arrêt arrivé entre-temps, pause) juste avant l'envoi, et part dans les 3,5 s du clic ou pas du tout.

Un arrêt annule un Allumer ou un Reset pas encore envoyé. La réponse d'un bouton est affichée dans le statut de l'intégration pendant 10 minutes (« pris par le PiKVM », « envoyé, sans confirmation », « rien envoyé »), et des relectures suivent pour confirmer le voyant.

Les boutons sont des boutons poussoirs, jamais des interrupteurs : un « tout éteindre » d'un assistant vocal ou d'une scène ne les atteint pas.

Lectures​

L'état ATX est lu à l'intervalle choisi (10 à 600 s, 30 s par défaut), jamais plus tôt après la lecture précédente, redémarrage du conteneur compris (hors lectures faites pour un bouton, pour le confirmer ou pour un arrêt gardé) ; les données du PiKVM (température) toutes les 5 minutes au plus. Une erreur 429 ou 5xx met les lectures en pause (1 minute à 6 heures, gardée au redémarrage). Un 403 sur la lecture ATX signifie que l'identifiant ou le mot de passe est refusé : rien n'est réessayé avant que vous en enregistriez d'autres ou cliquiez sur Tester la connexion. Un 401/403 sur les données du PiKVM n'est pas un refus (cette lecture est seulement espacée).

Confidentialité et sécurité​

Le mot de passe ne part que vers l'adresse configurée, dans les en-têtes X-KVMD-User / X-KVMD-Passwd, sur une connexion dont le certificat est celui épinglé (vérifié avant le premier octet). Il n'est jamais journalisé, ni écrit dans /data, un statut ou une erreur. /data ne garde que l'empreinte du certificat épinglé, une marque de 6 bits des identifiants refusés (qui ne permet pas de les retrouver), la fin d'une pause, l'heure de la dernière lecture, la garde d'arrêt et un arrêt gardé.

Limites​

  • Jamais testé avec un vrai PiKVM.
  • Un PiKVM par intégration.
  • Ni vidéo, ni clavier, ni souris, ni stockage, ni GPIO : alimentation ATX et voyants seulement.
  • L'identifiant de l'appareil vient de l'adresse saisie : changer d'adresse crée un nouvel appareil.

Licence​

Apache-2.0. kvmd, le logiciel du PiKVM, est sous GPL-3.0 : cette intégration appelle seulement son API HTTP documentée et ne contient rien de son code.

Paramètres de configuration​

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

ParamètreTypeObligatoireDescription
FonctionnementsectionNonGladys lit un PiKVM par son API HTTPS locale, avec un compte de son interface web : les voyants d'alimentation et de disque de la machine reliée à la carte ATX du PiKVM, et la température du PiKVM. Boutons : Éteindre (appui court sur le bouton d'alimentation, sans option), Allumer, Forcer l'extinction et Reset (chacun désactivé tant que vous ne l'autorisez pas plus bas). Sans carte ATX, seul le PiKVM est lu. Jamais testé avec un vrai appareil. Intégration non officielle, sans lien avec PiKVM.
Adresse du PiKVMstringOuiSon adresse IP sur votre réseau local (ou un nom d'hôte), comme pour ouvrir son interface web. HTTPS uniquement ; ajoutez :port si vous l'avez déplacé.
Empreinte du certificat (SHA-256, facultatif)stringNonUn PiKVM présente un certificat auto-signé. Vide : cliquez deux fois sur Faire confiance au certificat après l'enregistrement (le premier clic montre l'empreinte vue, rien d'autre n'est envoyé). Rempli : seul ce certificat est accepté (l'empreinte SHA-256 affichée par votre navigateur). Rien, ni le mot de passe, n'est envoyé à un autre certificat.
Nom d'utilisateurstringOuiUn utilisateur de l'interface web du PiKVM (kvmd).
Mot de passesecretOuiLe mot de passe de cet utilisateur (ASCII imprimable). Gardé par Gladys dans sa base, jamais réaffiché, envoyé seulement au PiKVM, et seulement une fois son certificat vérifié. Si le PiKVM le refuse, Gladys s'arrête jusqu'à l'enregistrement d'autres identifiants ou un clic sur Tester.
Double authentification (2FA) activebooleanNonCochez si le PiKVM demande un code. Utilisez alors le bouton Se connecter avec un code 2FA : la session dure jusqu'au redémarrage du PiKVM ou de l'intégration, puis un nouveau code est demandé (le code n'est jamais gardé).
Rafraîchissement (secondes)numberNonFréquence de lecture de l'état ATX (une requête). De 10 à 600 secondes.
Boutons d'alimentationsectionNonÉteindre ne demande aucune option (appui court : le système s'arrête proprement). Les trois boutons ci-dessous peuvent arrêter une machine brutalement ou la démarrer : chacun est désactivé par défaut, décidé sur une lecture fraîche du voyant d'alimentation, une commande par 30 s, et Allumer et Reset sont refusés 1 min après un arrêt.
Autoriser l'allumagebooleanNonDésactivé par défaut. Activé : le bouton Allumer appuie sur le bouton d'alimentation quand le voyant se lit éteint.
Autoriser l'extinction forcéebooleanNonDésactivé par défaut. Activé : le bouton Forcer l'extinction maintient le bouton d'alimentation 5 s (les données non enregistrées sont perdues).
Autoriser le resetbooleanNonDésactivé par défaut. Activé : le bouton Reset appuie sur le bouton reset d'une machine qui se lit allumée (redémarrage brutal).
Langue des noms et messagesselectNonLes noms des fonctions à leur création, et les messages des boutons.

Comment installer PiKVM dans Gladys​

  1. Dans Gladys, ouvrez Intégrations : PiKVM 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/lm1lc3n7/gladys-pikvm:0.1.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/LM1LC3N7/gladys-pikvm.

PiKVM 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​

PiKVM 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 LM1LC3N7, et non par l'équipe cœur de Gladys.

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 🙂