Comment diagnostiquer et réparer les agents Medulla des postes hors ligne (OFF) ?

S'applique à : Medulla / Agents Windows
Version : Medulla 5.6.x (reset à partir de 5.6.4)
Environnement : On-Premise / Serveur Debian
Catégorie : Administration / Diagnostic / Maintenance des agents
Script : diagnostic_machines_v5.diagnostic_machines_v13.py

Le script diagnostic_machines_v5.diagnostic_machines_v13.py permet d'identifier les causes pour lesquellespourquoi certains postes Windows apparaissent OFF (hors ligne) dans Medulla,Medulla alorset, qu'ilssi sontnécessaire, potentiellementde allumés.corriger les anomalies détectées directement depuis le serveur Medulla.

Il permet de :

• Identifier les postes déclarés OFF dans Medulla.
• Vérifier leur accessibilité réseau (ping et SSH).
• Contrôler l'étatle fonctionnement du système et la configuration de l'agent Medulla.

Tester les connexions réseau vers le serveur Medulla et les relais. Comparer les fichiers de l'agent avec ceux du serveur (taille et empreinte SHA256). Corriger automatiquement certaines anomalies connues.et mettre à niveau les fichiers de l'agent. Redémarrer le service de l'agentmedullaagent lorsque cela est nécessaire. Demander une réinitialisation de l'agent sous certaines conditions. Générer des rapports CSV détaillés.détaillés et des journaux de diagnostic.

Information : Le script fonctionne par défaut en mode audit permet d'analyser les postesaudit, sans modifiermodification leurdes configuration.postes. Les opérations de réparation nécessitent une confirmation explicite. Aucune installation supplémentaire n'est nécessaire sur les postes Windows.

Important : Les postes Linux sont identifiés mais ne sont ni audités ni réparés. Des scripts spécifiques seront proposés ultérieurement.

Quels sont les prérequis ?

Le script doit être exécuté sur le serveur Medulla avec les droits root.

• Medulla 5.6 ou supérieur.
• Python 3.9 ou supérieur.

Accès root au serveur Medulla. Commandes mysql, ssh et ping. Accès SSH par clé aux postes concernés, via le compte pulseuser. Droits administrateur sur les postes pour les opérations de réparation.

Le script nécessite Python 3.9 ou supérieur ainsi que les commandes mysql, ssh et ping. Si certaines commandes sont absentes, ille script peut proposer leur installation avec apt-get.

Le script utilise les fichiers de référence de l'agent disponibles sur le serveur :

/var/lib/pulse2/xmpp_baseremoteagent/

La version du serveur est lue dans :

/var/lib/mmc/version

Comment télécharger le script de diagnostic ?

Le script diagnostic_machines_v5.diagnostic_machines_v13.py est disponible sur le serveur de téléchargement Medulla.

Depuis le serveur Medulla, exécutez la commande suivante avec les droits root :

wget https://dl.medulla-tech.io/ma/diagnostic_machines_v5.diagnostic_machines_v13.py

Important – Utiliser la dernière version du script :
Le script est régulièrement mis à jour afin d'intégrer de nouveaux contrôles et desles 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, afin de bénéficier des améliorations et des mécanismes de réparation les plus récents.

Pour actualiser une copie existante, utilisezexistante :

wget -N https://dl.medulla-tech.io/ma/diagnostic_machines_v5.diagnostic_machines_v13.py

Une fois le téléchargement terminé, lancez le diagnostic :

python3 diagnostic_machines_v5.diagnostic_machines_v13.py

Comment lancer le diagnostic ?

Depuis le serveur Medulla, exécutez :

python3 diagnostic_machines_v5.diagnostic_machines_v13.py

Un menu interactif permet de choisir le mode d'exécution :

Choix	Mode	Périmètre
1	Audit uniquement	Tous les postes OFF
2	Audit uniquement	Une ou plusieurs IP
3	Audit et réparation	Tous les postes OFF
4	Audit et réparation	Une ou plusieurs IP (reset possible sur une seule IP)
q	Quitter	Aucune action

Recommandation : Commencez par le choix 1 – Audit uniquement, sélectionné par défaut, afin d'identifier les anomalies avant toute intervention.

Quelles sont les options disponibles ?

Option	Description	Valeur par défaut

--dry-run Exécute uniquement l'audit, sans menu ni modification des postes. — --ip IP[,IP] Limite le diagnostic aux adresses IP indiquées. Tous les postes OFF --oui Confirme automatiquement les actions, notamment pour une exécution automatisée. — --limite N Limite à N le nombre de corrections et de relances. Sans limite --timeout-ssh S Définit le délai de connexion SSHSSH. (15 secondes par défaut) --timeout-audit S Définit la durée maximale de l'audit d'un poste. 45 secondes --essais N Nombre de nouveaux essais après un timeout SSH ou audit (0 à 3). 1 --timeout-copie S Définit la durée maximale d'une copie de fichiers. Sans limite --inactivite-copie S Abandonne une copie si le poste ne répond plus pendant le délai indiqué. 120 secondes --serveur-pulse A Définit l'adresse du serveur Medulla utilisée pour les tests réseau. Adresse détectée --attente S Définit l'attente avant de vérifier le retour ON dans MedullaMedulla. (120 secondes par défaut) -v Active le mode verbeux et le journal détaillé trace.log. — --installer Installe automatiquement les commandes manquantes. —

Exemple : auditer tous les postes OFF sans modification :

python3 diagnostic_machines_v5.diagnostic_machines_v13.py --dry-run

Exemple : auditer un poste spécifique :

python3 diagnostic_machines_v5.diagnostic_machines_v13.py --dry-run --ip 192.168.1.100

Exemple : lancer un diagnostic interactifdétaillé sur plusieursun postesposte :

python3 diagnostic_machines_v5.diagnostic_machines_v13.py --ip 192.168.1.100,192.168.1.101100 -v

Exemple : augmenter le délai SSH :

python3 diagnostic_machines_v13.py --timeout-ssh 30

Il est également possible de préciser le dossier des relevés et le nombre de postes audités simultanément :

python3 diagnostic_machines_v13.py /root/analyse 100

Le parallélisme est de 50 postes par défaut, avec un maximum de 256.

Quels contrôles sont effectués sur les agents ?

PourLe chaquescript réalise plusieurs familles de contrôles, en lecture seule.

Catégorie Contrôles effectués Réseau Ping, connexion SSH et identification du poste. Système Identification de Windows et vérification de la plateforme. Medulla Vérification que le poste accessiblen'est enpas SSH,déjà leON scriptdans vérifieMedulla. :

• L'étatAgent État du service medullaagent.,
• LaPython présenceet version de l'agent.

Fichiers Comparaison des fichiers Pythonavec nécessairesla àréférence l'agent.serveur La: présencenom, taille et l'étatSHA256. Configuration Contrôle de agentxmpp.pyagentconf.ini., La présence et l'intégrité des fichiers de configuration. L'état du fichieragentconf.ini.local, kiosk.pid. Laet présencecollecte desAD. bibliothèques dansleDisque répertoire lib. La cohérence entre les versionsVérification de l'agent et du serveur. L'espace disque disponible sur C: (minimum 1 Go). Flux réseau Connectivité vers le serveur XMPP, le serveur Medulla et les relais. Journaux Recherche des erreurs dans xmpp-agent-machine.log.

LesLe bibliothèquesscript sontcompare comparéesles àfichiers de l'agent Windows avec la référence disponible sur le serveur :

/var/lib/pulse2/xmpp_baseremoteagent/lib/

Il contrôle également le dossier agentrescue\lib lorsqu'il est présent.

Information : Le ping et le SSH sont testés indépendamment. Un poste ne répondant pas au ping peut néanmoins être diagnostiqué et réparé s'il reste accessible en SSH.

Comment sont vérifiés les flux réseau ?

Le script teste directement depuis chaque poste Windows :

La résolution DNS du serveur XMPP déclaré dans agentconf.ini. La connexion TCP au serveur XMPP (délai de 5 secondes). 12 ports TCP vers le serveur Medulla. 8 ports TCP vers le relais Medulla. L'envoi UDP vers les ports 67, 69, 111 et 2049.

Ces contrôles permettent d'identifier les problèmes de connectivité pouvant empêcher l'agent de communiquer avec Medulla.

Important : Si le serveur XMPP est inaccessible depuis le poste, le script ne tente pas de redémarrer l'agent. Il signale un problème réseau, de pare-feu ou de service XMPP à résoudre.

Information : Les tests des autres ports sont indicatifs. Pour UDP, le statut ENVOYE signifie uniquement que l'envoi a été effectué, sans garantir que le port distant est ouvert.

Quelles anomalies peuvent être corrigées automatiquement ?

Anomalie	Action

Dossier var\log absent Création du dossier puis redémarrage du service. Fichiers de l'agent manquants ou différents Mise à niveau par delta depuis la référence serveur. Fichiers agentrescue\lib manquants ou différents Mise à niveau par delta lorsque le dossier existe. Appel de collecte Active Directory non protégé Correction du code de l'agent. Fichier kiosk.pid corrompu Réparation du fichier. Configuration absente ou endommagée Restauration si une sauvegarde valide existe. Bibliothèques lib manquantes Restauration uniquement si la version de l'agent correspond à celle du serveur. Service arrêté sans autre anomalie réparable Redémarrage du service medullaagent.

Les corrections spécifiques s'appuient notamment sur le code intégré de reparer-agent-medulla.ps1.

Comment fonctionne la mise à niveau des fichiers de l'agent ?

La version V13 introduit une mise à niveau par delta permettant de comparer les fichiers de l'agent Windows avec ceux du serveur Medulla.

Le script :

Compare les noms, tailles et empreintes SHA256 des fichiers. Identifie les fichiers manquants ou différents. Arrête le service medullaagent avant toute modification. Sauvegarde les fichiers devant être remplacés. Copie uniquement les fichiers nécessaires depuis le serveur. Vérifie les empreintes SHA256 après chaque copie. Redémarre le service et contrôle son état.

Aucun fichier présent uniquement sur le poste n'est supprimé.

Les sauvegardes sont conservées avec un nom horodaté :

<fichier>.<AAAA-MM-JJ_HH-MM-SS>.bak

Important : Si les versions des bibliothèques de l'agent et du serveur sont différentes ou incohérentes, leLe script ne copierétrograde pasjamais lesun fichiers. Une réinstallation de l'agent plus récent que la référence serveur. Dans ce cas, une vérification manuelle est alors nécessaire.

Comment fonctionne la réparation automatique ?

En mode réparation, le script :

1. RéaliseIdentifie un audit desles postes concernés.OFF et réalise leur audit.
2. Présente les corrections et relances prévues.
3. Demande une confirmation explicite en saisissant OUI.
4. Vérifie que chaque poste est toujours OFF et correspond au poste initialement audité.
5. AppliqueCrée le dossier var\log lorsqu'il est absent.

Met à niveau les fichiers différents ou manquants. Réalise un nouvel audit rapide et applique, si nécessaire, les corrections possiblesPowerShell. ou redémarreRedémarre le service.service et vérifie le résultat. VérifieAttend le120 résultatsecondes despar interventions.défaut Consulteavant àde nouveauconsulter Medulla pour identifier les postes revenus ON.

AvantChaque touteposte modification,reçoit lesau fichiers concernés sont sauvegardés. Leur intégrité est vérifiée après écriture etmaximum une restaurationaction, estmême prévuelorsqu'il enpossède casplusieurs d'échec.adresses IP.

Attention : L'option --oui supprime les demandes de confirmation. Elle doit être réservée aux opérations automatisées préalablement validées.

Comment réinitialiser un agent qui reste OFF ?

Si un poste reste OFF après les opérations de réparation ou de relance, le script peut proposer une demande de reset de l'agent.

Cette fonctionnalité nécessite :

• Medulla 5.6.4 ou supérieur.
• Un agent à jour, avec une version au moins égale à celle du serveur.
• Une seule fiche OFF correspondant au poste.
• Aucune demande de reset déjà en attente.
• Une seule adresse IP ciblée.

Le reset est demandé par une insertion dans la table :

xmppmaster.reset_machine

En mode interactif, une seconde confirmation OUI est nécessaire.

Information : Le reset est disponible uniquement lors du traitement d'une seule IP. Pour plusieurs postes, le script inscritindique les commandes individuelles à exécuter.

Comment sont gérés les délais d'attente et les postes qui ne répondent plus ?

La version V13 introduit une demandegestion renforcée des délais d'attente et des nouveaux essais.

Opération Délai par défaut Comportement Connexion SSH 15 secondes Nouvel essai après 5 secondes en cas de resettimeout dansou Medulla.de Sonconnexion traitementcoupée. effectif estensuiteAudit assuréd'un parposte 45 secondes Arrêt des processus bloqués puis nouvel essai. Copie de fichiers 120 secondes d'inactivité Abandon si le serveur.poste ne répond plus. Réparation PowerShell 300 secondes Arrêt de l'opération et contrôle du service. Création de var\log 180 secondes Arrêt de l'opération et contrôle du service. Relance du service 150 secondes Contrôle de l'arrêt et du démarrage. Nettoyage après timeout 60 secondes Abandon et signalement si le poste ne répond plus.

Le script affiche toutes les 20 secondes les postes encore en cours de traitement, avec l'étape et le temps écoulé.

Information : Les opérations de réparation ne sont jamais relancées automatiquement après un timeout, afin d'éviter de répéter une modification potentiellement déjà effectuée.

Quelles protections empêchent une intervention sur le mauvais poste ?

Le script intègre plusieurs mécanismes de sécurité :

• Un poste déjà ON dans Medulla est exclu des interventions.
• L'identité du poste est vérifiée avant chaque action.
• Seuls les postes Windows sont concernés par les réparations.

Un même poste possédant plusieurs IP n'est traité qu'une fois. Les modifications nécessitent les droits administrateur. Un verrou Global\MedullaLocalRepair empêche deux réparations simultanées sur un même poste. Le service est arrêté avant toute modification des fichiers. Les fichiers remplacés sont sauvegardés. Les empreintes SHA256 sont contrôlées après modification. Une restauration est prévue en cas d'échec de correction. UnAucun maximumfichier desupplémentaire 10présent actionssur le poste n'est exécuté simultanément.supprimé.

Limite de sécurité : Les clés d'hôte SSH ne sont pas vérifiées par le script. Son utilisation doit être limitée à un environnement réseau interne maîtrisé.

Où consulter les résultats du diagnostic ?

Chaque exécution crée un dossier horodaté dans :

/root/analyse/

Les principaux fichiers générés sont :

Fichier	Contenu
resultats.csv	DiagnosticDiagnostic, tests réseau et résultat des actions pour chaque IP.
statistiques.csv	Synthèse des postes, anomaliesanomalies, résultats et résultats.familles de tests.
journaux/<ip>.log	Journal détaillé des opérationscorrections, réaliséesrelances, surnettoyages leet poste.resets.

trace.log Journal détaillé des commandes et durées d'exécution lorsque l'option -v est utilisée.

Les fichiers CSV utilisent le séparateur ; et l'encodage UTF-8 avec BOM pour faciliter leur ouverture dans Excel.

Confidentialité : Les rapports contiennent des noms de postespostes, des adresses IP et des adressesinformations IP.techniques sur l'environnement. Leur diffusion doit être limitée aux équipes autorisées.

Quels sont les principaux statuts retournés ?

Statut	Signification
CORRIGE	CorrectionTous appliquéeles etproblèmes serviceréparables redémarré.ont été corrigés.

PARTIEL Une partie des anomalies a été corrigée, mais une intervention manuelle reste nécessaire. RIEN_A_CORRIGER Aucune correction nécessaire au moment de l'intervention. RELANCE_OK Service redémarré correctement. DEMANDE Demande de reset enregistrée. EXCLU_DEJA_ON Poste déjà ON, aucune action. EXCLU_PASSE_ONNON_TRAITE Poste repassénon ONWindows, avantexclu l'intervention.du traitement. DOUBLON_MEME_POSTENON_UTILE PosteRelance déjàinutile, traiténotamment vialorsque unele autreserveur IP.XMPP est ANNULE_POSTE_DIFFERENT Identité du poste différente de celle de l'audit.inaccessible. ECHEC_RESTAURE Échec de correction avec restauration. ECHEC_REDEMARRAGE / ECHEC_DEMARRAGEECHEC_RESTAURATION_INCOMPLETE Échec duavec redémarragerestauration incomplète, sauvegardes à vérifier. TIMEOUT_SERVICE_REDEMARRE Délai dépassé, service redémarré après contrôle. TIMEOUT_SERVICE_OK Délai dépassé, service trouvé démarré. TIMEOUT_A_VERIFIER Délai dépassé, état du service.poste à vérifier manuellement. A_FAIRE_POSTE_PAR_POSTE Reset possible, à lancer individuellement.

Important : Les statuts commençant par ECHEC ainsi que TIMEOUT_A_VERIFIER doivent être examinés en priorité, à l'aide du journal du poste concerné.

Quelles sont les limites connues ?

• Les réparationspostes WindowsLinux viasont OpenSSHidentifiés mais ne sont pas audités ni réparés.

Une copie interrompue peut laisser un fichier incomplet. Les sauvegardes restent disponibles pour restauration. Un poste corrigé ou relancé peut rester OFF si la cause de la déconnexion persiste. Le contrôle de l'espace disque et le nettoyage PowerShell doivent encore être validéesvalidés sur des postes réels avant un déploiement généralisé.réels. Le traitementnettoyage desaprès demandestimeout peut interférer avec une réparation PowerShell lancée manuellement au même moment. La règle de reset doitimpose êtreactuellement vérifiéun agent à jour. Son utilisation sur ledes serveuragents Medulla.ne parvenant plus à se mettre à jour reste à clarifier. Seuls certains

Sécurité des informations : Certains journaux ou fichiers de configuration peuvent contenir des informations sensibles, notamment des mots de passe. Les fichiers de configuration de l'agent ne sont comparéspas àexportés ladans référenceles serveur.rapports.

LesIl agentsconvient présentant des versions mélangées nécessitent une réinstallation. Une IP inconnuenéanmoins de Medulla,protéger cibléeles avec --ip, peut être considérée comme OFFjournaux et fairede l'objetcorriger d'unetoute relance.exposition Unde changementsecrets d'état du poste entre le dernier contrôle et l'action reste possible. identifiée.

Recommandation : Avant chaque utilisation, téléchargez la dernière version du script afin de bénéficier des corrections les plus récentes. Pour une première intervention, lancez un audit global avec --dry-run, analysez les résultats CSV, puis testez le mode réparation sur un seul poste avant d'intervenir sur plusieurs machines.