Skip to main content

Diagnose and fix Medulla agents

Applies to: Medulla server and Windows agents
Script version: V54 — November 7, 2026
Environment: Medulla server running on Linux, executed as root
Category: Diagnostics, maintenance, and remediation

1. Overview

The medulla_agents_V54.py script allows you to audit Medulla agents installed on Windows workstations, identify anomalies, and automatically fix those that are supported, after confirmation.

In particular, it performs the following:

  • Auditing computers marked as OFF and ON in Medulla.
  • Diagnosing SSH and XMPP connections.
  • Checking agent services, files, and configurations.
  • Analyzing GLPI-Agent inventories.
  • Detecting DNS, network, and automatic update issues.
  • Repair of supported issues.
  • Optional repair of GLPI-Agent.
  • Discovery of workstations present on the network but missing from Medulla.
  • Generation of detailed HTML and CSV reports.

Important: An audit does not modify workstations or the Medulla database. However, the encrypted web report is published by default, even in audit mode. Use --sans-publication to disable this publication.

2. Download and install the script

The script is available on the Medulla download server, in the same location as previous versions.

Download version V54:

Download medulla_agents_V54.py

Log in to the Medulla server via SSH using an account with root privileges, then run:

cd /root
wget https://dl.medulla-tech.io/ma/medulla_agents_V54.py
chmod +x medulla_agents_V54.py
python3 -m py_compile medulla_agents_V54.py

Verify the file's integrity

sha256sum medulla_agents_V54.py | cut -c1-16

Reference hash provided for V54: cad3a35669f65186 (first 16 characters of the SHA-256 hash).

You can verify the published version by comparing this hash with that of the downloaded file. If there is a discrepancy, check whether the script has been republished before running it.

Prerequisites

The server must have the following commands available:

  • mysql
  • ssh
  • scp
  • ping
  • ip
  • openssl for encrypted publishing

If any dependencies are missing, the script will prompt you to install them. The --installer option allows you to install them without prompting.

3. Run the script

It is recommended that you always run the script in a screen session so that an SSH disconnection does not interrupt the data collection.

screen -S medulla
cd /root
./medulla_agents_V54.py

To detach from the session without interrupting the script, press Ctrl+A, then D.

To resume the session:

screen -r medulla

Without any options, the script displays menus that let you choose:

  1. Language.
  2. The scope: computers OFF, computers ON, all computers, or a targeted list.
  3. The mode: audit only, audit followed by actions, ON computers without inventory, or network discovery.

In action mode, an additional prompt allows you to decide whether ON computers that are functional but have a defect should also be addressed.

4. Main commands

Audit without correction

OFF computers:

./medulla_agents_V54.py --dry-run

Entire fleet:

./medulla_agents_V54.py --perimetre tout --dry-run

A specific computer:

./medulla_agents_V54.py --cible PC1068 --dry-run

Multiple computers:

./medulla_agents_V54.py --cible PC1068,10.0.0.12 --dry-run

Audit and correction

One computer:

./medulla_agents_V54.py --cible PC1068 --oui

The entire fleet, including functional computers with defects:

./medulla_agents_V54.py --perimetre tout --oui --full

Caution: --oui confirms actions without prompting, and --full also allows processing of functional computers that are ON. It is recommended to perform an audit first to review the repair plan.

GLPI-Agent repair

./medulla_agents_V54.py --cible PC1068 --reparer-glpi

For multiple workstations:

./medulla_agents_V54.py --cible PC1068,PC1069 --reparer-glpi

For workstations in the ON state:

./medulla_agents_V54.py --perimetre on --reparer-glpi

Other useful commands

Command Function
--sans-inventaire --dry-run Audit ON computers without a GLPI inventory UUID.
--fiche PC1068 Display the record of the last scan without performing a new audit.
--reconfigurer Propose reconfiguring the targeted agent.
--comparaison-complete --dry-run Compare all files on the agent to the server baseline.
--scan-reseau Search for computers on the network.
--scan-reseau --scan-blocs Display the discovery plan without scanning.
--publier-dernier Republish the latest report with new credentials.
--sans-publication Disable web report publishing.
--maj-script Check for and install the latest released version of the script.
--sans-maj-script Skip the update check at startup.
-v Enable detailed traces.

5. What's new in V54

V54 — GLPI-Agent repair without a Medulla package

V54 improves the --reparer-glpi option by adding a fallback method when the server does not have a Medulla deployment package for GLPI-Agent.

The script first searches for the GLPI-Agent package among the Medulla packages, in particular under:

/var/lib/pulse2/packages/

If no suitable package is found, it searches for the latest GLPI-Agent MSI, version 1.8 or higher, published by the Medulla server at:

http://<server>/downloads/win/downloads/

The workstation downloads the MSI and installs it over the existing version.

Configuration protection:

  1. The GLPI-Agent registry configuration is backed up in a .reg file.
  2. The MSI is installed.
  3. The configuration is verified after installation.
  4. If it has been modified, it is restored to its original state.
  5. The installed version is checked and must be at least 1.8.

The GLPI_MSI variable allows you to specify a particular MSI.

If no compatible package or MSI is available, the script does not attempt installation.

V53 — Repair results in computer records

Each computer’s record includes a “GLPI-Agent repair” line with one of the following statuses:

Status Meaning
PAS_LANCEE Repair not requested or audit only.
AUCUN_PAQUET No compatible installer available.
ANNULE Repair canceled.
OK Repair completed.
ECHEC Repair failed.

After a successful repair, the version displayed in the initial audit data may remain unchanged until the next scan.

V52 — Fix for reading the deviceid

Reading the GLPI-Agent deviceid from a .dump file now removes the initial length byte, regardless of its value. This prevents a workstation from being incorrectly identified as a clone.

Other important improvements

  • V50–V51: Exclusion of obsolete log entries.
  • V49: Detailed diagnostics of SSH port 22 and Windows firewall rules, without modification.
  • V47–V48: RESET_EN_ATTENTE status and support for truncated NetBIOS names.
  • V41–V46: Fix for medullanetnotify and introduction of --reparer-glpi.
  • V34–V35: Optimized network discovery and cross-checking with XMPP sessions.
  • V32: Automatic updates verified using SHA-256.
  • V30: Network discovery, targeted file comparison, and improved SSH fallback.
  • V29: Fixed false positive diagnostics of a cloned deviceid.
  • V28: An outdated or missing GLPI-Agent no longer blocks Medulla repairs.
  • V27: Encrypted report publishing by default.

6. Connection behavior

The script selects the most appropriate transport for each computer.

Workstation status Method
Computer OFF in Medulla SSH using the pulseuser account and a key.
Computer ON in Medulla XMPP using a temporary ejabberd account and the shellcommand plugin.
Computer ON, silent in XMPP Fallback to SSH.
Record OFF but workstation actually ON Using XMPP.
Task scheduler refusing to launch XMPP Fallback to SSH.

A computer that is ON and whose agent responds correctly via XMPP is audited but is not modified by default. To address its issues, you must confirm the prompt or use the --full option.

7. Checks performed on workstations

Access and system

  • Workstation response via ping, SSH, or XMPP.
  • True identity of the workstation.
  • Administrator privileges for the login account.
  • Windows version and compatibility.
  • OFF or ON status in Medulla.

Medulla agent

  • Python and agent installed.
  • Status of the medullaagent, medullanetnotify, and sshdaemon services.
  • Specific causes of service startup failures.
  • Detection of legacy registrations under Python 2.7.
  • Comparison of versions and files with the server reference.
  • Automatic update diagnostics.
  • Presence of required libraries, modules, and scripts.

Configuration and network

  • Validity of agentconf.ini and agentconf.ini.local.
  • Active Directory collection.
  • Log directory present.
  • Available disk space.
  • DNS resolution for the Medulla server.
  • Connection to the XMPP server on port 5222.
  • Connectivity to the server and relay.
  • Diagnosis of SSH port 22, local rules, and GPO rules.

Inventory and logs

  • Presence and operation of GLPI-Agent.
  • GLPI-Agent version 1.8 or higher.
  • Consistency of the deviceid with the workstation name.
  • Age of the last inventory.
  • Recent log errors.
  • Reconfiguration or reboot loops.
  • Automatic update errors.

8. Checks performed on the server

Server checks are performed in read-only mode.

  • Investigation of unreachable computers.
  • Status of the SSH port on computers reachable via XMPP.
  • Automatic update configuration.
  • Too many open files errors on the relay.
  • Missing or inconsistent deployment files.
  • ejabberd errors and c2s_shaper throughput issues.
  • Missing modules and plugins.
  • Duplicate inventory UUIDs and deviceid values.
  • Shared or blacklisted MAC addresses.
  • ON computers without inventory.
  • Pending resets and reconfigurations.
  • Repeated reconnections.
  • Status of Medulla substitutes.
  • SSH rejections related to AllowGroups.

9. Repairs handled

Action Resolution
Agent fix Back up, fix files or configurations, restart, and verify.
Repairing medullanetnotify Re-register the service using a healthy template, with a registry backup.
Repairing GLPI-Agent Only with the --reparer-glpi option, via the Medulla package or the fallback MSI.
AD collection Synchronize the relevant file with the server reference, without downgrading.
Service restart Controlled shutdown and restart.
SSH startup Starting sshdaemon from XMPP.
Inventory Inventory request when GLPI-Agent is available.
Reset Submit a request to reset_machine.
Reconfiguration Records need_reconf = 1.

A reset request for a computer that is OFF remains pending until it comes back ON. It then appears with the status RESET_EN_ATTENTE and is not considered a completed repair.

After the issue is resolved, the workstation is re-audited. If the first check fails because the agent is restarting or the antivirus is scanning files, a second attempt is made after 30 seconds with a doubled timeout.

10. Network discovery

Network discovery searches for computers present on Medulla’s known subnets, particularly those that are no longer correctly listed.

./medulla_agents_V54.py --scan-reseau

It identifies:

  • A computer that has changed its IP address.
  • A workstation that is reachable but marked as OFF in Medulla.
  • An agent installed on a workstation not listed in the database.
  • An SSH key rejection.
  • A Windows workstation without Medulla SSH access.
  • A computer connected via XMPP but inaccessible via SSH.

To view the expected blocks without running the scan:

./medulla_agents_V54.py --scan-reseau --scan-blocs

Caution: Although discovery is read-only, it generates network traffic that may be detected by security devices. Notify the network team before performing your first major scan.

11. HTML report and secure publishing

Each scan generates a file named rapport.html containing a summary of the fleet and a detailed record for each computer.

The report includes:

  • Metrics by status.
  • A summary of server anomalies.
  • Issues grouped by category.
  • Search by name, IP, or description.
  • Filters, sorting, and CSV exports.
  • A prioritized repair plan for each computer.
  • Diagnostic and correction commands to copy.

Access to the published report

By default, an encrypted copy is published at the following address:

https://<server>/medulla-rapports/rapport.html

At the end of the scan, the script displays a random username and password. These change with each publication and are not saved.

The report is compressed and encrypted using AES-256 with HMAC protection. The browser decrypts it after the credentials are entered.

Important: Open the page using HTTPS. Decryption is not supported over HTTP. Only the encrypted page is published; the CSV files and the unencrypted local report remain on the server.

Disable publication

./medulla_agents_V54.py --perimetre tout --dry-run --sans-publication

Republish the latest report

./medulla_agents_V54.py --publier-dernier

This command generates new credentials for the latest available report without running a new audit.

12. Generated files

The files are saved in:

/root/analyse/releve_<date>/
File Content
rapport.html Standalone, unencrypted HTML report.
fiches.json Individual computer records.
resultats.csv Detailed results by workstation.
statistiques.csv Scan statistics.
plan_de_remediation.csv Issues and recommended actions.
avant_apres_reparation.csv Comparison of statuses before and after intervention.
enquete_postes_injoignables.csv Diagnosis of unreachable workstations.
reconnexions_en_boucle.csv Repeated reconnections.
uuid_inventaire_en_double.csv Shared inventory UUIDs.
mac_partagees.csv Shared MAC addresses.
mac_blacklistees_a_reconfigurer.csv Computers requiring reconfiguration after being blacklisted.
reconfiguration_mac.csv Reconfiguration results.
reset_d_office.csv Results of resets.
fiches_off_obsoletes.csv Obsolete OFF records.
glpi_agent_sans_full.csv GLPI-Agent versions prior to 1.8.
decouverte_reseau.csv Network discovery results.
decouverte_xmpp_sans_ssh.csv XMPP computers without reachable SSH.
journaux/<workstation>.log Action log by computer.
trace.log Detailed logs with -v.

CSV files use a semicolon as the delimiter and UTF-8 encoding with BOM.

13. Additional tools

medulla_extract_logs.py

This tool collects and analyzes logs from workstations and the server in read-only mode. Secrets are masked in the data intended for support.

./medulla_extract_logs.py --depuis-releve /root/analyse
./medulla_extract_logs.py --cible NB554,NB648
./medulla_extract_logs.py --perimetre on --erreurs-seules
./medulla_extract_logs.py --sans-postes

The summary archive for support is named:

A_ENVOYER_<date>.tar.gz

medulla_reconf_delai.py

This tool analyzes reconfiguration delays and suggests a value for RECONF_ATTENTE.

./medulla_reconf_delai.py --appliquer medulla_agents_V54.py

A .bak backup is created before any changes are made.

14. Frequently asked questions

Can the script modify computers during an audit?

No. The --dry-run mode is read-only for workstations and the Medulla database. However, the publication of the encrypted web report remains enabled by default.

Why isn’t a functional ON computer repaired?

For security reasons, computers marked as ON whose agent responds correctly via XMPP are not modified by default. Use the --full option or confirm their processing in the menu.

GLPI-Agent is missing or older than 1.8: Are other fixes blocked?

No. Medulla agent repairs, resets, and reconfigurations are still possible. Only the inventory request is ignored until GLPI-Agent is operational.

How do I repair GLPI-Agent without the Medulla package?

Starting with V54, --reparer-glpi can use a compatible GLPI-Agent MSI published in /downloads/win/downloads/ on the Medulla server. The registry configuration is backed up and restored if necessary.

Why does the GLPI-Agent status show PAS_LANCEE?

The repair was not requested, or the scan was run in audit-only mode.

Why does pulseuser not allow the correction?

The account may have lost its membership in the local Administrators group, possibly due to a GPO or LAPS. Check these settings, and then, with the appropriate permissions, use:

Add-LocalGroupMember -SID S-1-5-32-544 -Member pulseuser

What does RESET_EN_ATTENTE mean?

The reset is recorded in Medulla, but the workstation is OFF. The operation is waiting for the workstation to come back ON and should not be considered complete.

What does ANNULE_SSH_PERDU mean?

The computer was responding during the audit, but the SSH connection was no longer available at the time of the operation. The action was canceled.

Why is port 22 inaccessible?

The record helps distinguish between a stopped SSH service, a Windows firewall rule, or network filtering. The script does not modify firewall rules.

Why does the agent’s automatic update appear to be stuck?

The diagnostic may detect a missing descriptor or a relay anomaly. If a Too many open files error occurs, it is recommended to resolve the relay issue before performing a forced reset.

Why won’t the web report open?

Verify that the URL uses HTTPS and that the credentials are those of the latest published scan.

How do I view a record without a browser?

./medulla_agents_V54.py --fiche PC1068

How do I rerun the verification after making a correction?

./medulla_agents_V54.py --cible PC1068 --dry-run

How do I update the script?

./medulla_agents_V54.py --maj-script

The mechanism checks the SHA-256 hash, syntax, and version before installation. The old copy is retained.

15. Security rules

  • An audit does not modify workstations or the database.
  • Any action requires explicit confirmation or --oui.
  • Operational computers are protected by default.
  • Corrections are applied only to the selected scope.
  • The workstation’s identity is verified before any action is taken.
  • Modified files are backed up.
  • No files are deleted, and the agent is never downgraded.
  • Corrections are never automatically reapplied.
  • GLPI-Agent is repaired only with the --reparer-glpi option.
  • The Windows firewall is diagnosed but never modified.
  • Administrative actions for the relay and ejabberd are recommended but not performed automatically.
  • Configuration secrets are protected.
  • The temporary XMPP account is deleted at the end of the process.

16. Locations and references

Element Address or path
Manual download V54 https://dl.medulla-tech.io/ma/medulla_agents_V54.py
Automatic update https://d.medulla-tech.io/ma/
Update manifest https://d.medulla-tech.io/ma/latest.json
GLPI-Agent MSI on the server http://<server>/downloads/win/downloads/
Medulla packages /var/lib/pulse2/packages/
Local reports /root/analyse/
Encrypted web report https://<server>/medulla-rapports/rapport.html
medullanetnotify template /root/analyse/reference_medullanetnotify.json

Documented version: Medulla Agents V54.
Reference SHA-256 hash (first 16 characters): cad3a35669f65186.
Medulla documentation: Diagnose and fix Medulla agents.