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_v13.py

Le script diagnostic_machines_v13.py permet d'identifier pourquoi certains postes Windows apparaissent OFF (hors ligne) dans Medulla et, si nécessaire, de 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 le fonctionnement du système et 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 et mettre à niveau les fichiers de l'agent.
• Redémarrer le service medullaagent lorsque cela est nécessaire.
• Demander une réinitialisation de l'agent sous certaines conditions.
• Générer des rapports CSV détaillés et des journaux de diagnostic.

Information : Le script fonctionne par défaut en mode audit, sans modification des 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.

Si certaines commandes sont absentes, le 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_v13.py 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_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 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, afin de bénéficier des améliorations et des mécanismes de réparation les plus récents.

Pour actualiser une copie existante :

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

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

python3 diagnostic_machines_v13.py

Comment lancer le diagnostic ?

Depuis le serveur Medulla, exécutez :

python3 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 SSH.	15 secondes
--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 Medulla.	120 secondes
-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_v13.py --dry-run

Exemple : auditer un poste spécifique :

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

Exemple : lancer un diagnostic détaillé sur un poste :

python3 diagnostic_machines_v13.py --ip 192.168.1.100 -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 ?

Le script 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 n'est pas déjà ON dans Medulla.
Agent	État du service medullaagent, Python et version de l'agent.
Fichiers	Comparaison des fichiers avec la référence serveur : nom, taille et SHA256.
Configuration	Contrôle de agentconf.ini, agentconf.ini.local, kiosk.pid et collecte AD.
Disque	Vérification de l'espace 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.

Le script compare les fichiers de l'agent Windows avec la référence disponible sur le serveur :

/var/lib/pulse2/xmpp_baseremoteagent/

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.
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 :

1. Compare les noms, tailles et empreintes SHA256 des fichiers.
2. Identifie les fichiers manquants ou différents.
3. Arrête le service medullaagent avant toute modification.
4. Sauvegarde les fichiers devant être remplacés.
5. Copie uniquement les fichiers nécessaires depuis le serveur.
6. Vérifie les empreintes SHA256 après chaque copie.
7. 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 : Le script ne rétrograde jamais un agent plus récent que la référence serveur. Dans ce cas, une vérification manuelle est nécessaire.

Comment fonctionne la réparation automatique ?

En mode réparation, le script :

1. Identifie les postes 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. Crée le dossier var\log lorsqu'il est absent.
6. Met à niveau les fichiers différents ou manquants.
7. Réalise un nouvel audit rapide et applique, si nécessaire, les corrections PowerShell.
8. Redémarre le service et vérifie le résultat.
9. Attend 120 secondes par défaut avant de consulter Medulla pour identifier les postes revenus ON.

Chaque poste reçoit au maximum une action, même lorsqu'il possède plusieurs 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 indique 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 gestion 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 timeout ou de connexion coupée.
Audit d'un poste	45 secondes	Arrêt des processus bloqués puis nouvel essai.
Copie de fichiers	120 secondes d'inactivité	Abandon si le 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.
• Aucun fichier supplémentaire présent sur le poste n'est 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	Diagnostic, tests réseau et résultat des actions pour chaque IP.
statistiques.csv	Synthèse des postes, anomalies, résultats et familles de tests.
journaux/<ip>.log	Journal détaillé des corrections, relances, nettoyages et 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 postes, des adresses IP et des informations techniques sur l'environnement. Leur diffusion doit être limitée aux équipes autorisées.

Quels sont les principaux statuts retournés ?

Statut	Signification
CORRIGE	Tous les problèmes réparables 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.
NON_TRAITE	Poste non Windows, exclu du traitement.
NON_UTILE	Relance inutile, notamment lorsque le serveur XMPP est inaccessible.
ECHEC_RESTAURE	Échec de correction avec restauration.
ECHEC_RESTAURATION_INCOMPLETE	Échec avec restauration 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 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 postes Linux sont identifié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és sur des postes réels.
• Le nettoyage après timeout peut interférer avec une réparation PowerShell lancée manuellement au même moment.
• La règle de reset impose actuellement un agent à jour. Son utilisation sur des agents ne parvenant plus à se mettre à jour reste à clarifier.

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 pas exportés dans les rapports. Il convient néanmoins de protéger les journaux et de corriger toute exposition de secrets 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.