Why isn’t a computer registering?
When installing a Medulla agent, the computer must register with the server in order to appear correctly in the console and use Medulla’s various features.
If a computer fails to register, registers incompletely, or takes an unusually long time to appear, there are several factors to check.
The main documented causes are:
- an inconsistency between the computer’s information and its network interfaces;
- a blacklisted network interface;
- a duplicate MAC address;
- an orphaned network entry in the Medulla database;
- an issue with the
subscriptionagent responsible for participating in the registration process.
Note:
This procedure primarily applies to computers on which the agent is installed but whose registration in Medulla does not complete normally. If a computer was previously registered correctly and simply appears offline, please refer to the FAQ Why does a computer appear offline? instead.
1. Check the registration logs
The first step is to review the Medulla registration logs.
Look specifically for the name of the affected computer and messages containing:
Registering machine
incoherence between machines and network tables
Interface missing on machine
Registration incomplete for machine
For example, a registration error might produce a sequence similar to:
INFO - Registering machine poste-client-02@medulla-interne/...
WARNING - incoherence between machines and network tables
ERROR - Interface missing on machine poste-client-02@medulla-interne/...
ERROR - Registration incomplete for machine poste-client-02@medulla-interne/...
Caution:
The message Registration incomplete is a symptom of the problem. The lines preceding it usually help identify the cause of the registration failure.
2. Inconsistency between the machines and network tables
The message:
incoherence between machines and network tables
indicates an inconsistency between the computer’s information and that of its network interfaces as recorded in Medulla.
It may be followed by:
Interface missing on machine
Registration incomplete for machine
The Medulla operations guide identifies several possible causes:
- a blacklisted network interface;
- a duplicate MAC address;
- an entry in the
networktable for a computer that no longer exists in themachinestable.
3. Verify the computer’s network information
To diagnose an inconsistency, start by comparing the information known to Medulla with the computer’s actual configuration.
The information to check includes:
- the hostname;
- the IP address;
- the MAC address;
- the network interfaces present on the computer.
An inconsistency in the MAC address or the interface used may prevent Medulla from completing the registration correctly.
Tip:
When the logs display Interface missing on machine, first compare the MAC address listed in the logs with the interfaces actually present on the computer.
4. Check for orphaned network entries
An entry may exist in the network table even though the computer it was associated with no longer exists in the machines table.
To search for these entries:
SELECT *
FROM xmppmaster.network
WHERE machines_id NOT IN (
SELECT id
FROM xmppmaster.machines
);
If this query returns any rows, orphaned network entries are present in the database.
Caution:
The presence of an entry returned by this query should not automatically lead to its deletion. First verify that it corresponds to data that is no longer needed, and perform a backup of the database before making any corrections.
5. Correct orphaned network entries
After confirming that the identified entries are indeed orphaned, the Medulla operations guide provides the following query to delete them:
DELETE FROM xmppmaster.network
WHERE machines_id NOT IN (
SELECT id
FROM xmppmaster.machines
);
Important:
This command directly deletes data from the Medulla database. It should only be used by a Medulla administrator, after verifying the results of the previous SELECT query and performing a backup of the database.
After making the corrections, let the computer perform a new registration and check the logs.
6. Search for a duplicate MAC address
A duplicate MAC address can also cause an inconsistency during registration.
This issue can occur, in particular, after:
- duplicating a computer;
- creating a computer from an image;
- a change in the network card or interface;
- retaining an old entry corresponding to the computer.
When the logs indicate an interface inconsistency, check whether the MAC address in question is associated with multiple entries.
Note:
The operations guide identifies MAC address duplication as a possible cause of Registration incomplete, but does not provide a generic correction query for this scenario. It is therefore recommended to identify the source of the duplicate before deleting any entries.
7. Check whether an interface is blacklisted
A blacklisted interface is also among the documented causes that can result in:
Interface missing on machine
If the MAC address reported by the agent is correct but Medulla does not retain the corresponding interface, verify whether this interface matches any of the exclusion rules used by the installation.
Note:
The operations guide identifies a blacklisted interface as a possible cause but does not provide, in this procedure, the exact configuration of the blacklist or a command to modify it. It is therefore best not to modify the configuration without first identifying the relevant rule.
8. Case of a computer that takes a long time to register
Another documented situation is when a computer eventually registers, but only after a significant delay of up to about one hour.
In this case, the problem may stem from the corresponding subscription agent, which is not available on XMPP.
In the computer agent’s log, you can find a subscription attempt:
subscribe to master_subsX agent
as well as the computer’s presence:
presence_available poste-client-01@... available
Under normal operation, a line corresponding to the subscription agent’s presence should also appear.
presence_available agent@... Available
If this presence does not appear, check the status of the subscription component.
9. Check the XMPP presence of the subscription agent
From the ejabberd server, use:
ejabberdctl connected_users | grep master_subsX
Replace master_subsX with the name of the relevant subscription agent.
If the command returns no lines, the expected subscription agent is not connected to ejabberd.
This may explain why computers are taking an unusually long time to complete their registration.
Caution:
A process or service may appear active at the system level but may not be properly connected to XMPP. Checking with connected_users therefore allows you to verify its actual presence in ejabberd.
10. Restart the subscription component
If the expected subscription agent is not present in:
ejabberdctl connected_users
the operations guide recommends restarting the subscription agent and then verifying its connection to ejabberd again.
After the restart, check:
ejabberdctl connected_users | grep master_subsX
and then monitor the computer’s registration.
Note:
If the component is still missing from connected_users despite being restarted, the problem lies with the subscription component or its XMPP connection and requires further troubleshooting.
11. Check a computer’s registrations
To monitor registration activity, search for the computer’s name in the registration logs.
Lines containing:
Registering machine
indicate registration attempts.
An unusually high number of attempts for a single computer may indicate that it is consistently failing to complete its registration process.
In this case, look for the following messages in the subsequent lines:
incoherence between machines and network tables
Interface missing on machine
Registration incomplete for machine
12. Do not confuse the main scenarios
| Symptom | Priority cause to investigate |
|---|---|
| The computer has never been properly registered | Agent, network information, and registration process |
Interface missing on machine |
Blacklisted interface, duplicate MAC address, or machines/network inconsistency |
Registration incomplete for machine |
Analyze the errors preceding this message |
| The computer eventually appears after a long delay | Check the subscription agent |
| The subscription agent is running, but the computer is not registering | Check if it appears in ejabberdctl connected_users |
| The computer was registered correctly but now appears offline | Diagnose the agent and its communication rather than the initial registration |
13. Quick diagnostic procedure
When a computer fails to register with Medulla, perform the following checks in this order:
- verify that the Medulla agent is installed and running on the computer;
- review the registration logs;
- look for
Registration incompleteand any preceding errors; - if
Interface missingappears, check the interfaces and MAC addresses; - check for inconsistencies between the
machinesandnetworktables; - check for a duplicate MAC address or a blacklisted interface;
- if registration eventually succeeds but only after a long delay, check the
subscriptionagent; - verify its presence using
ejabberdctl connected_users; - after making the correction, let the agent attempt registration again and check the logs.
14. Quick diagnostic table
| Message or symptom | Possible cause | Initial check |
|---|---|---|
incoherence between machines and network tables |
Inconsistent computer/network data | Check the machines and network tables |
Interface missing on machine |
Missing or blacklisted interface, or incorrect MAC address | Compare interfaces and MAC addresses |
Registration incomplete for machine |
Registration interrupted by a previous error | Read the previous lines of the log |
network entries without a computer |
Orphaned network data | Run the verification query |
| MAC address used multiple times | Duplicate computer or interface | Identify entries using the same MAC |
| Registration after a long delay | Subscription agent unavailable | Check connected_users |
master_subsX missing from XMPP |
Subscription agent not connected | Restart the component and check its connection |
15. Information to collect if the problem persists
If the computer still does not register, collect the following information before continuing with troubleshooting or opening a support ticket:
- the computer’s hostname;
- its IP address;
- its MAC addresses;
- the log entries corresponding to
Registering machine; - any
Interface missingmessages; - any
Registration incompletemessages; - the result of the search for orphaned entries in
network; - if registration is simply very slow, whether or not the
subscriptionagent is present inejabberdctl connected_users.
Recommendation:
When a computer fails to register, start by searching for Registration incomplete in the logs, then analyze the messages preceding it. An Interface missing error typically points to network interfaces, MAC addresses, or data inconsistencies. If registration works but only after a significant delay, check first to ensure the subscription component is present in XMPP.