Comment diagnostiquer et réparer les agents Medulla via XMPP
S'applique à : Medulla / Agents Windows / GLPI-Agent
Version : Medulla 5.6.x (reset à partir de 5.6.4)
Environnement : On-Premise / Serveur Debian
Catégorie : Administration / Diagnostic / Maintenance des agents / Inventaire
Script : diagnostic_machines_XMPPV5.py
Le script diagnostic_machines_XMPPV5.py permet de diagnostiquer et de réparer les agents Medulla installés sur les postes Windows, directement depuis le serveur Medulla, sans utiliser SSH ni ping.
Contrairement au diagnostic classique par SSH, toutes les communications passent par le protocole XMPP, en utilisant la connexion existante entre l'agent Medulla et le serveur ejabberd.
Le script permet notamment de :
- Diagnostiquer un ou plusieurs postes Windows à partir de leur nom.
- Vérifier le fonctionnement de l'agent Medulla.
- Contrôler les fichiers, les configurations et les versions de l'agent.
- Tester les communications réseau vers les serveurs Medulla.
- Identifier les postes sans UUID d'inventaire.
- Vérifier la présence et la version de GLPI-Agent.
- Corriger automatiquement certaines anomalies.
- Relancer le service Medulla lorsque cela est nécessaire.
- Demander un nouvel inventaire des postes concernés.
- Générer des rapports CSV détaillés.
Information : Par défaut, le script fonctionne en mode diagnostic, sans modification des postes. Les corrections nécessitent une confirmation explicite.
Quelle est la différence avec le diagnostic par SSH ?
Medulla propose deux approches complémentaires pour diagnostiquer les agents Windows.
| Caractéristique | Diagnostic XMPP | Diagnostic SSH |
|---|---|---|
| Script | diagnostic_machines_XMPPV5.py |
diagnostic_machines_v13.py |
| Identification du poste | Nom du poste | Adresse IP |
| Communication | XMPP via ejabberd | SSH via pulseuser |
| Connexion SSH nécessaire | Non | Oui |
| Agent connecté à ejabberd | Obligatoire | Non obligatoire |
| Diagnostic des agents | Oui | Oui |
| Contrôle de GLPI-Agent | Oui | Non, dans la V13 décrite |
| Diagnostic des postes sans UUID d'inventaire | Oui | Non |
Recommandation : Privilégiez le diagnostic XMPP lorsque l'agent est connecté à ejabberd. Si l'agent ne répond plus ou n'est pas connecté, utilisez le diagnostic SSH pour rechercher la cause du problème.
Quels sont les prérequis ?
Le script doit être exécuté sur le serveur Medulla avec les droits root.
- Accès root au serveur Medulla.
- Accès à la commande
ejabberdctl. - Accès MySQL à la base
xmppmaster. - Présence des fichiers de référence de l'agent Medulla sur le serveur.
- Agent Medulla connecté à ejabberd pour les postes à diagnostiquer.
Les fichiers de référence sont disponibles dans :
/var/lib/pulse2/xmpp_baseremoteagent/Information : Aucun accès SSH aux postes Windows n'est nécessaire. Le script utilise les fonctionnalités de communication XMPP déjà présentes dans l'agent Medulla.
Comment télécharger le script de diagnostic ?
Le script est disponible sur le serveur de téléchargement Medulla.
Depuis le serveur Medulla, exécutez :
wget https://dl.medulla-tech.io/ma/diagnostic_machines_XMPPV5.pySi nécessaire, rendez le script exécutable :
chmod +x diagnostic_machines_XMPPV5.pyImportant – Utiliser la dernière version du script :
Le script est régulièrement mis à jour afin d'intégrer de nouveaux contrôles et les corrections correspondant aux problèmes les plus fréquemment rencontrés sur les agents Medulla.
Il est donc fortement recommandé de récupérer systématiquement la dernière version avant chaque utilisation.
Pour actualiser une copie existante :
wget -N https://dl.medulla-tech.io/ma/diagnostic_machines_XMPPV5.pyComment lancer le diagnostic ?
Depuis le dossier contenant le script, exécutez :
sudo ./diagnostic_machines_XMPPV5.py| Choix | Mode | Machines concernées |
|---|---|---|
| 1 | Diagnostic uniquement | Une ou plusieurs machines désignées par leur nom. |
| 2 | Diagnostic et correction | Une ou plusieurs machines désignées par leur nom. |
| 3 | Diagnostic uniquement | Toutes les machines ON sans UUID d'inventaire. |
| 4 | Diagnostic et correction | Toutes les machines ON sans UUID d'inventaire. |
| q | Quitter | Aucune action. |
Recommandation : Commencez par le choix 1 – Diagnostic uniquement pour un poste précis, ou le choix 3 pour identifier les problèmes d'inventaire sur l'ensemble du parc concerné.
Comment diagnostiquer un ou plusieurs postes sans modification ?
Pour auditer un poste spécifique :
sudo ./diagnostic_machines_XMPPV5.py --nom <Nom de la machine> --diagnosticPour auditer plusieurs postes :
sudo ./diagnostic_machines_XMPPV5.py --nom <Nom de la machine 1>,<Nom de la machine 2> --diagnosticPour obtenir le détail des échanges XMPP :
sudo ./diagnostic_machines_XMPPV5.py --nom <Nom de la machine> --diagnostic -vInformation : Les options --diagnostic et --dry-run exécutent uniquement les contrôles, sans correction.
Comment fonctionne la communication XMPP ?
Le script utilise la connexion XMPP existante entre les agents Medulla et le serveur ejabberd.
Lors de son exécution, il :
- Crée un compte XMPP temporaire de type
diagnostic-xxxx@pulse. - Génère un mot de passe aléatoire qui n'est jamais affiché.
- Communique avec les postes via le plugin
shellcommandde l'agent Medulla. - Dépose un petit programme de diagnostic dans
C:\Windows\Temp\mdxafin d'éviter de transmettre le code à chaque commande. - Supprime le compte XMPP temporaire à la fin de l'exécution.
Information : Un poste peut être diagnostiqué même s'il apparaît OFF dans Medulla, à condition que son agent soit toujours connecté à ejabberd et réponde aux commandes XMPP.
Quels contrôles sont effectués sur les postes Windows ?
Le script réalise plusieurs familles de contrôles.
| Catégorie | Contrôles effectués |
|---|---|
| XMPP | Connexion à ejabberd, réponse aux commandes et identification réelle du poste. |
| Agent Medulla | Présence de Python, état du service medullaagent, type de démarrage et version de l'agent. |
| Fichiers | Comparaison des fichiers de l'agent et de agentrescue\lib avec la référence serveur. |
| Configuration | Contrôle de agentconf.ini, agentconf.ini.local, kiosk.pid et de la collecte Active Directory. |
| Disque | Vérification de l'espace libre sur C: et présence du dossier Medulla\var\log. |
| Flux réseau | Connexion au serveur XMPP sur le port 5222 et tests TCP vers le serveur Medulla et les relais. |
| Inventaire | Présence et version de GLPI-Agent, avec contrôle de compatibilité à partir de la version 1.8. |
| Journaux | Recherche des lignes ERROR dans xmpp-agent-machine.log. |
Confidentialité : Le contenu du fichier agentconf.ini n'est jamais exporté ni affiché. Le diagnostic indique uniquement son état : VALIDE, INVALIDE, ABSENT, etc.
Pourquoi le script contrôle-t-il GLPI-Agent ?
La version V5 ajoute un contrôle spécifique de l'agent d'inventaire GLPI-Agent.
Medulla utilise GLPI-Agent pour collecter les informations d'inventaire des postes Windows.
Pour fonctionner correctement avec la commande d'inventaire utilisée par Medulla, GLPI-Agent doit être en version 1.8 ou supérieure.
En effet, l'option --full, utilisée par Medulla, est disponible à partir de GLPI-Agent 1.8.
Une version plus ancienne peut retourner l'erreur :
Unknown option: fullDans ce cas, l'inventaire ne peut pas être produit correctement et le poste peut rester sans UUID d'inventaire dans Medulla.
Important : Le script détecte les versions de GLPI-Agent antérieures à 1.8, mais ne réalise pas leur mise à jour automatiquement.
Comment la version de GLPI-Agent est-elle détectée ?
Le script lit directement la version dans le fichier :
C:\Program Files\GLPI-Agent\perl\agent\GLPI\Agent\Version.pmSi ce fichier ne peut pas être lu, le script utilise :
glpi-agent.bat --versionCette commande est limitée à 20 secondes afin d'éviter de bloquer le diagnostic.
Le résultat apparaît directement dans le bilan :
GLPI 1.20: version compatible.GLPI 1.6.1: version trop ancienne.GLPI absent: agent d'inventaire non détecté.
Les anomalies sont signalées en jaune dans l'affichage du diagnostic.
Comment diagnostiquer les postes sans UUID d'inventaire ?
La sélection correspond à la requête suivante :
SELECT id, hostname
FROM machines
WHERE uuid_inventorymachine = ''
AND enabled = 1
AND agenttype = 'machine';Le script réalise ensuite un audit de l'agent Medulla et de GLPI-Agent sur chaque poste concerné.
Le choix 4 permet également de corriger les anomalies réparables de l'agent Medulla, puis de demander un nouvel inventaire.
Attention : Le choix 4 nécessite deux confirmations distinctes : une première pour les corrections, puis une seconde pour les demandes d'inventaire.
Quelles anomalies peuvent être corrigées automatiquement ?
| Anomalie | Action |
|---|---|
| Fichiers de l'agent manquants ou différents | Copie des fichiers nécessaires depuis la référence serveur, via XMPP. |
agentconf.ini absent ou invalide |
Restauration depuis agentconf.ini_2, ou depuis le modèle .tpl, uniquement si la source est valide. |
| Collecte Active Directory non protégée | Correction du code concerné. |
Fichier kiosk.pid corrompu |
Réparation du fichier. |
Dossier Medulla\var\log absent |
Création du dossier. |
Service medullaagent arrêté |
Redémarrage du service. |
Le script ne supprime aucun fichier de l'agent et ne rétrograde jamais un agent plus récent que la référence serveur.
Comment fonctionne la réparation automatique ?
En mode correction, le script :
- Réalise un diagnostic complet des postes sélectionnés.
- Identifie les anomalies pouvant être corrigées.
- Présente le plan d'intervention.
- Demande une confirmation explicite en saisissant OUI.
- Vérifie à nouveau le nom réel du poste avant toute modification.
- Arrête le service
medullaagentet confirme son arrêt avant toute écriture. - Applique les corrections nécessaires.
- Redémarre le service et vérifie son état.
- Demande un nouvel inventaire lorsque les conditions sont réunies.
Information : L'option --relancer-tout permet également de relancer le service lorsque celui-ci est déjà démarré.
Pourquoi certains postes ne reçoivent-ils pas de demande d'inventaire ?
Depuis la V5, le script vérifie la version de GLPI-Agent avant d'envoyer une demande d'inventaire.
Si GLPI-Agent est absent ou si sa version est inférieure à 1.8, aucune demande n'est envoyée.
Le rapport peut alors indiquer :
NON_DEMANDE (GLPI-Agent 1.6.1 < 1.8)Cette protection évite de lancer une opération qui ne pourrait pas produire d'inventaire exploitable.
La mise à jour de GLPI-Agent doit être réalisée séparément, par exemple à l'aide d'un paquet de déploiement Medulla.
Pour un dépannage ponctuel avec une ancienne version, le script inventaire_sans_full.py peut être utilisé.
Comment réinitialiser un agent qui reste OFF ?
Le script peut proposer une demande de reset lorsque :
- Une seule machine est traitée.
- Le poste reste OFF dans Medulla.
- L'agent est à jour par rapport au serveur.
- Le serveur Medulla est en version 5.6.4 ou supérieure.
- Les autres conditions de sécurité du reset sont réunies.
La demande est enregistrée dans :
xmppmaster.reset_machineInformation : Le reset constitue la seule opération d'écriture réalisée directement dans la base Medulla. Il est limité à une seule machine.
Quelles sont les options disponibles ?
| Option | Description |
|---|---|
--nom PC1,PC2 |
Définit les machines à traiter par leur nom. Option répétable. |
--diagnostic / --dry-run |
Exécute uniquement le diagnostic, sans correction ni menu. |
--oui |
Sélectionne le mode correction et confirme automatiquement les actions. |
--sans-inventaire |
Sélectionne les machines ON sans UUID d'inventaire. |
--relancer-tout |
Relance également les services déjà démarrés. |
--limite N |
Limite le nombre de corrections et de relances. |
--attente-inventaire S |
Définit le délai maximal d'attente du rattachement après une demande d'inventaire. |
--timeout-ssh S |
Définit le délai de réponse à une commande XMPP (25 secondes par défaut). |
--timeout-audit S |
Définit la durée maximale d'audit d'un poste (45 secondes par défaut). |
--essais N |
Définit le nombre de nouveaux essais après un timeout de lecture. |
-v |
Active l'affichage détaillé des opérations. |
dossier |
Définit le dossier de destination des relevés. |
Attention : L'option --oui supprime les confirmations interactives. Elle doit être réservée aux opérations automatisées préalablement validées.
Quelles protections empêchent une intervention sur le mauvais poste ?
Le script intègre plusieurs mécanismes de sécurité :
- Les corrections nécessitent une confirmation explicite, sauf utilisation de
--oui. - Le nom réel du poste est revérifié avant toute modification.
- Le service est arrêté et son arrêt confirmé avant toute écriture.
- Un agent plus récent que la référence serveur n'est jamais rétrogradé.
- Aucun fichier de l'agent n'est supprimé.
- Une correction n'est jamais rejouée automatiquement.
- Le reset est limité à une seule machine.
- Le nettoyage final ne vise que les processus lancés par le script, jamais le Python de l'agent.
Où consulter les résultats du diagnostic ?
Chaque exécution crée un dossier horodaté dans :
/root/analyse/Le dossier porte un nom de type :
releve_AAAAMMJJ_HHMMSSLes principaux fichiers générés sont :
| Fichier | Contenu |
|---|---|
resultats.csv |
Une ligne par machine : diagnostic, corrections, relances, reset, inventaire et version de GLPI-Agent. |
statistiques.csv |
Synthèse des résultats et récapitulatif par famille de tests. |
inventaire.csv |
État de l'inventaire des machines sans UUID, pour les choix 3 et 4. |
Les fichiers CSV utilisent le séparateur ; et l'encodage UTF-8 avec BOM pour faciliter leur ouverture dans Excel.
La version V5 ajoute notamment les colonnes suivantes :
- Agent d'inventaire (
inventory.ini). - Présence du programme d'inventaire.
- Version de GLPI-Agent.
- Compatibilité GLPI-Agent 1.8 ou supérieur :
OUI,NONouINCONNU.
Comment interpréter le statut « Réparable » ?
| Statut | Signification |
|---|---|
OUI |
Toutes les anomalies identifiées peuvent être corrigées automatiquement. |
PARTIEL |
Une partie des anomalies peut être corrigée automatiquement. |
NON |
Une intervention manuelle est nécessaire. |
RIEN_A_CORRIGER |
Aucune anomalie réparable par le script n'a été détectée. |
Information : Une version de GLPI-Agent trop ancienne est comptabilisée comme une anomalie, mais ne déclenche pas à elle seule une correction ou une relance du service Medulla.
Quels sont les problèmes les plus fréquents ?
| Message | Cause probable | Action recommandée |
|---|---|---|
agent non connecte a ejabberd |
Poste éteint, hors réseau ou agent arrêté. | Vérifier le poste ou utiliser le diagnostic SSH. |
agent TIMEOUT |
Agent connecté mais ne répondant plus aux commandes. | Réessayer, puis envisager une commande restartbot. |
audit de l'inventaire impossible |
Réponse trop lente ou perdue. | Augmenter --timeout-audit et utiliser -v. |
GLPI-Agent < 1.8 |
Version incompatible avec l'option --full. |
Mettre à jour GLPI-Agent. |
GLPI-Agent absent |
Agent d'inventaire non installé. | Installer GLPI-Agent. |
l'agent repond un autre nom |
Nom demandé associé à un autre poste. | Vérifier les doublons dans Medulla. |
Serveur XMPP injoignable |
Problème réseau, pare-feu ou ejabberd. | Vérifier le flux TCP 5222 vers le serveur XMPP. |
Attention : Pour relancer un agent XMPP qui ne répond plus, la commande restartbot peut être utilisée lorsque cela est approprié. Ne pas la confondre avec restarfrommaster, qui redémarre le poste Windows.
Comment tester manuellement la réponse XMPP d'un poste ?
Le script test_agent_XMPP.py permet d'envoyer une commande de diagnostic à un poste précis.
Par exemple, pour consulter la version de GLPI-Agent :
sudo ./test_agent_XMPP.py <Nom de la machine> --attente 60 --commande 'findstr /r /c:"VERSION *=" "C:\Program Files\GLPI-Agent\perl\agent\GLPI\Agent\Version.pm"'Cette commande permet de vérifier directement la réponse du poste via XMPP.
Quelles versions de GLPI-Agent sont compatibles ?
| Version | Compatibilité avec l'inventaire Medulla |
|---|---|
| 1.6.1 | Non compatible avec l'option --full. |
| 1.8 | Première version compatible avec --full. |
| 1.16 | Compatible. |
| 1.20 | Compatible, version fournie avec Medulla. |
Quelles sont les limites connues ?
- Un agent non connecté à ejabberd ne peut pas être diagnostiqué par XMPP.
- Un agent connecté mais ne répondant plus aux commandes peut provoquer un timeout.
- Les postes dont le nom réel ne correspond pas au nom demandé sont exclus des corrections.
- Le script ne met pas GLPI-Agent à jour automatiquement.
- Une version de GLPI-Agent inférieure à 1.8 empêche l'envoi d'une demande d'inventaire.
- Les corrections ne garantissent pas le retour immédiat du poste dans Medulla.
- Le reset est limité au traitement d'une seule machine.
Recommandation : Avant chaque utilisation, récupérez la dernière version du script. Commencez par un diagnostic sans correction, puis vérifiez les résultats avant de lancer une intervention. Pour les postes sans UUID d'inventaire, utilisez le choix 3 afin d'identifier notamment les versions de GLPI-Agent incompatibles avant de procéder aux corrections nécessaires.