Plugin SSH Manager (Jeedom)

IMPORTANT

S’il n’y a pas d’information sur la mise à jour, c’est que celle-ci concerne uniquement de la mise à jour de documentation, de traduction ou de texte.

---

Auteurs

TiTidom et Mips sont les co-développeurs de ce plugin.

Présentation

Ce plugin a deux finalités bien distinctes :

• Gérer des équipements pour se connecter, à distance, en SSH (via un login/mot de passe ou login/clé SSH), afin de pouvoir lancer tout type de commande Linux et récupérer le résultat dans le plugin

• S’intégrer à d’autres plugins qui ont besoin de se connecter à distance en SSH sur un équipement pour y lancer des commandes. Cela leur permet de ne pas gérer la couche connexion SSH et lancement des commandes, et de pouvoir se concentrer simplement sur les commandes à lancer et les informations à récupérer.

Cette documentation s’attache à décrire le point numéro 1 (documentation utilisateurs), la partie intégration pour d’autres plugins, dédiée aux développeurs, est quant à elle décrite dans un fichier README accessible ici : Documentation Intégration.

Compatibilité

IMPORTANT

La version minimum du core de Jeedom requise pour le plugin est la version 4.4

Le plugin n’est pas compatible avec l’OS Debian 10 (qui n’est plus maintenu par Debian depuis début juillet 2024). Si vous êtes encore sous cette version d’OS, il est vivement conseillé de prévoir la réinstallation de votre système sous Debian 11 minimum).

Ce plugin est compatible avec vos Jeedom installés sur des OS Debian 11 et Debian 12.

Demande d’aide sur Community

Pour toute demande d’aide concernant ce plugin sur le forum Community, merci de fournir systématiquement les informations suivantes :

• Une copie d’écran de la page Santé de Jeedom
• Une copie d’écran de la page de configuration du plugin (avec notamment la version du plugin)
• Les logs en mode debug, ajoutées dans votre message avec le bouton “Texte préformaté” (pas de capture d’écran surtout, car elles sont inexploitables)

Configuration du plugin

Dépendances

Il n’y a pas de dépendances à installer pour ce plugin, la librairie utilisée (PHPSeclib) est incluse avec ce plugin.

Version du Plugin

A chaque version du plugin qui sort, un numéro est attribué sous la forme “version_majeure.version_mineure.version_patch” (par ex. : “2.2.0”). Vous pouvez retrouver cette information sur la page de configuration du plugin. Pour toute demande sur le Community, merci de préciser dans vos messages ce numéro de version du plugin.

Option : Rafraichir les valeurs à la sauvegarde

A partir de la page du plugin, vous pouvez accéder à la Configuration du plugin qui se présente sous cette forme :

Par défaut :

• Rafraichir les valeurs à la sauvegarde est activée

Cette option, lorsqu’elle est désactivée, permet d’éviter de rafraîchir toutes les valeurs des commandes existantes d’un équipement à la sauvegarde de celui-ci.

ASTUCE

Si vous avez beaucoup de commandes gourmandes en ressources dans un même équipement, il est conseillé de désactiver cette option, afin d’éviter de surcharger l’équipement distant à chaque sauvegarde.

N’oubliez pas de cliquer sur le bouton “Sauvegarder” pour valider les options choisies.

Ajout d’un équipement

Pour configurer un nouvel équipement :

• Retourner sur la page du plugin :

• Puis cliquer sur le bouton en haut à gauche “Ajouter”
• Puis saisir le nom de l’équipement (ex. “MonEquipement - SSH”)

• Puis définir :
  • Objet parent
  • Catégorie (optionnelle)
• Cocher les options :
  • “Activer” (à cocher, sinon l’équipement ne sera pas utilisable)
  • “Visible” (optionnel)

• Sélectionner la méthode d’authentification “Mot de Passe” (par défaut) ou “Clé SSH”
  • “Mot de Passe” : permet de se connecter à un système Linux distant (installé sur une autre machine) via SSH en utilisant un identifiant (login) et un mot de passe
  • “Clé SSH” : permet de se connecter à un système Linux distant (installé sur une autre machine) via SSH en utilisant un identifiant (login) et une clé SSH
  • “Agent (non supporté)” : Méthode d’authentification non implémentée à date

IMPORTANT

Pour executer des commandes Linux à distance via SSH, vous devez choisir un compte (identifiant) avec des droits suffisants pour lancer les commandes (par ex. un utilisateur “sudo” ou bien à défaut le compte “root”).

Méthode d’authentification : “Mot de passe”

Après avoir sélectionné ce mode, 5 champs supplémentaires s’affichent :

• Hôte distant : Saisir l’adresse IP ou le nom d’hôte de la machine distante
• Port SSH : Saisir le numéro du port SSH (par défaut il s’agit du port 22)
• Timeout SSH : Saisir la durée maximale d’une requête SSH avant expiration (par défaut : 30 secondes)
• Identifiant : Saisir le nom d’utilisateur qui sera utilisé pour se connecter en SSH sur le système distant
• Mot de passe : Saisir le mot de passe qui est associé au nom d’utilisateur

Méthode d’authentification “Clé SSH”

Après avoir sélectionné ce mode, 6 champs supplémentaires s’affichent :

• Hôte distant : Saisir l’adresse IP ou le nom d’hôte de la machine distante
• Port SSH : Saisir le numéro du port SSH (par défaut il s’agit du port 22)
• Timeout SSH : Saisir la durée maximale d’une requête SSH avant expiration (par défaut : 30 secondes)
• Identifiant : Saisir le nom d’utilisateur qui sera utilisé pour se connecter en SSH sur le système distant
• Passphrase : (Optionnel) Saisir la phrase secrète associée à la clé SSH, permettant de décoder celle-ci
• Clé SSH : Coller ici la clé privée SSH permettant de se connecter au système distant

ASTUCE

Le bouton orange avec le signe Play à côté du label Clé SSH permet de formater une clé SSH fournie sur une seule ligne en blocs de 64 caractères, voir la FAQ

IMPORTANT

Le plugin ne gère pas la génération de la clé SSH, ni la recopie de la clé publique sur le système distant (nécessaire pour permettre la connexion à ce système via une clé SSH).

Pour plus d’informations sur la génération d’une clé SSH, rendez-vous dans la FAQ.

Option : Auto-Actualisation

Optionnel

Pour chaque équipement, vous avez la possibilité de définir une fréquence personnalisée de mise à jour automatique des infos de l’équipement, disponible dans un champ spécifique : “Auto-Actualisation” :

Utilisez alors le bouton ?, à droite du champ, pour afficher “l’assistant Cron”, qui vous permettra de définir la fréquence souhaitée (toutes les minutes, toutes les 5 minutes, toutes les heures, une fois par jour, etc…)

Cliquez ensuite sur le bouton Sauvegarder et vos paramètres d’auto-actualisation sont alors définis.

IMPORTANT

L’auto-Actualisation (ainsi que la commande Rafraîchir globale d’un équipement) n’actualise QUE les commandes de type “info”, les commandes de type “action” ne sont pas concernées.

Ajout d’une commande standard

Pour ajouter une commande standard à votre équipement, rendez-vous sur l’onglet Commandes, et cliquez sur le bouton Ajouter une commande (en haut à droite)

Type de commande SSH

Dans la colonne Type d’une commande, vous avez deux choix dans une liste déroulante : Choisir SSH vous permettra de configurer une commande SSH à lancer sur l’équipement distant.

Dans la colonne Type Résultat, vous pouvez déterminer le type de la commande : Info (pour récupérer une information) ou bien Action (par ex: pour relancer un service, ou rebooter l’équipement).

• Le type résultat Info renverra une valeur qui sera affichée dans la colonne Etat.
• Le type résultat Action lancera la commande Linux sur l’équipement distant, mais ne retournera pas de valeur.

Paramètre Auto-Refresh

Une commande de type SSH possède un paramètre configurable : Auto-Refresh

Si l’option est :

• Activée : Cette commande sera rafraîchi lors de l’usage du bouton “Rafraîchir” (RefreshAll) présent dans chaque équipement.
• Désactivée : Cette commande ne sera PAS rafraîchi via la commande “Rafraîchir (RefreshAll) et il faudra alors utiliser une commande de type Refresh pour actualiser la valeur de cette commande.

Type de commande Refresh

Une commande de type Refresh permet de rafraîchir, à la demande, la valeur d’une autre commande de type SSH. Pour cela, ajoutez une commande est choisissez le type Refresh pour cette nouvelle commande :

Paramètre Commande à rafraîchir

Ce paramètre d’une commande Refresh permet de définir la commande à rafraîchir. Choisissez, dans la liste déroulante, la commande SSH à rafraîchir et sauvegardez. Vous pourrez ensuite utiliser cette commande Refresh à volonté pour actualiser la valeur de la commande correspondante.

Paramètre commande Cron

Une commande de type Refresh peut aussi actualiser la valeur de la commande correspondante de manière automatisée, en configuration un “Cron” (Auto-Actualisation de la commande) personnalisé.

Définissez la valeur du cron personnalisé pour cette commande (en utilisant l’assistant accessible via le bouton ?) et sauvegardez. La valeur de la commande SSH correspondante sera alors actualisée automatiquement suivant la fréquence définie.

Ajout d’une commande à partir d’un template

Il est également possible d’ajouter une commande à partir d’un template. Le plugin possède des commandes pré-définies (template) que vous pouvez sélectionner via le bouton prévu à cet effet dans l’interface :

Choisissez, dans la liste déroulante, la commande souhaitée parmi celles proposées, adaptez si besoin la commande directement dans le champ Commande (comme indiqué dans le champ Description le cas échéant) :

Enfin, cliquez sur le bouton Ajouter pour confirmer votre choix. La commande est alors crée automatiquement avec les paramètres définis.

N’oubliez pas de sauvegarder pour conserver cette commande et vos choix.

ASTUCE

Les commandes Linux proposées dans la fenêtre template sont fournies avec le plugin (on peut donc facilement les retrouver et les ajouter) et la liste est amenée à évoluer avec vos retours. N’hésitez pas à venir partager vos commandes les plus courantes sur Community, pour les ajouter dans une prochaine version.

FAQ

Comment générer une “clé SSH” permettant de se connecter à un équipement distant ?

Il existe beaucoup de tutoriels sur internet expliquant comment générer ces clés, nous ne verrons ici que quelques principes :

• Le principe de base est de générer un couple “clé privée + clé publique”, en général en utilisant la commande ssh-keygen sur un système Linux.
• La “clé privée” sera à rentrer dans la page de configuration de votre équipement. On peut afficher la clé privée qui a été générée sur un système Linux, via la commande cat .ssh/id_rsa.
• La “clé publique” sera à ajouter à la liste des clés autorisées de l’utilisateur sur le système que vous souhaitez monitorer. En général, on utilise la commande ssh-copy-id user@mamachinedistante pour ajouter cette clé publique sur le système distant.
• La “Passphrase” (phrase secrète) permet de renforcer la sécurité d’une clé SSH en ajoutant un mot de passe qui sera utilisé pour déchiffrer la clé SSH lorsqu’elle est utilisée. Cette phrase secrète est définie au moment de la génération de la clé SSH.

La clé SSH fournie par “Putty KeyGen” n’est pas valide dans le plugin

En effet, le format natif de putty pour les clés SSH est de type .ppk (putty private key), format qui n’est pas supporté dans le plugin.

Dans Putty Key Generator, après avoir généré votre clé SSH avec le bouton Generate, rendez-vous dans la menu Conversions (en haut) et choisissez l’option Export OpenSSH Key ou bien Export OpenSSH Key (force new file format) (les deux options sont supportées par le plugin).

En utilisant ce menu Export OpenSSH Key, la clé exportée sera ainsi compatible et utilisable avec le plugin SSH-Manager.

Comment formater une clé SSH d’une seule ligne en blocs de 64 caractères ?

Un bouton est prévu à cet effet dans la configuration de votre équipement. Il s’agit du bouton de couleur orange avec le signe “play” à côté du label “Clé SSH”.

Après avoir collé votre clé SSH (fournie en une seule ligne) dans le champ correspondant, cliquez sur ce bouton pour formater la clé en blocs de 64 caractères. Un message s’affichera pour vous informer du résultat :

Si le format de la clé est valide et que le plugin a réussi à l’interpréter alors ce message s’affichera :

Si une erreur s’est produite, notamment car le format de la clé n’était pas valide (il doit toujours commencer par -----BEGIN * PRIVATE KEY----- et se terminer par -----END * PRIVATE KEY-----, le signe * pouvant prendre plusieurs valeurs comme “RSA” ou “OpenSSH” par ex.), alors un message de “warning” s’affichera à l’écran :

Si la clé SSH était déjà au bon format (blocs de 64 caractères), le plugin vous l’indiquera également à travers le message suivant :

Changelog

Voir le fichier dédié (version stable) : Changelog (Stable)

Voir le fichier dédié (version beta) : Changelog (Beta)