Skip to main content

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 subscription agent 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 network table for a computer that no longer exists in the machines table.

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:

  1. verify that the Medulla agent is installed and running on the computer;
  2. review the registration logs;
  3. look for Registration incomplete and any preceding errors;
  4. if Interface missing appears, check the interfaces and MAC addresses;
  5. check for inconsistencies between the machines and network tables;
  6. check for a duplicate MAC address or a blacklisted interface;
  7. if registration eventually succeeds but only after a long delay, check the subscription agent;
  8. verify its presence using ejabberdctl connected_users;
  9. 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 missing messages;
  • any Registration incomplete messages;
  • the result of the search for orphaned entries in network;
  • if registration is simply very slow, whether or not the subscription agent is present in ejabberdctl 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.