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:
mysqlsshscppingipopensslfor 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:
- Language.
- The scope: computers OFF, computers ON, all computers, or a targeted list.
- 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:
- The GLPI-Agent registry configuration is backed up in a
.regfile. - The MSI is installed.
- The configuration is verified after installation.
- If it has been modified, it is restored to its original state.
- 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_ATTENTEstatus and support for truncated NetBIOS names. - V41–V46: Fix for
medullanetnotifyand 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, andsshdaemonservices. - 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.iniandagentconf.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 fileserrors on the relay.- Missing or inconsistent deployment files.
- ejabberd errors and
c2s_shaperthroughput 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-glpioption. - 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.