Registration Failed for Instance or Management Station

An instance or management station can fail to register with OS Management Hub for several reasons.

See also Known Issue: Older platform images or Bring Your Own Images will not register.

Invalid profile was used

The following conditions might indicate that an instance tried to register with an invalid profile:

  • The status of the instance in the OS Management Hub is Registration failed.
  • The osmh-agent.logfile displays a message similar to:

    Message: Invalid Managed Instance osFamily ORACLE_LINUX_8 does not match Profile osFamily: ORACLE_LINUX_9 which indicates the profile has the wrong OS version.

    Message: Managed Instance location ON_PREMISE is not compatible with a Profile registration type of: OCI_LINUX which indicates the profile has the wrong instance type.

Check the osmh-agent.log file and identify the correct profile

  1. Determine the location of the osmh-agent.log file.
  2. Examine the log file, scanning for key words such as "Invalid" or "osFamily" or "compatible", to determine if a profile error exists.

    For example, for an on-premises instance:

    sudo grep -i -E "invalid|osfamily|compatible" /opt/oracle/mgmt_agent/plugins/osmh/stateDir/log/osmh-agent.log

    For example, for a Windows instance:

    Get-Content C:\Windows\ServiceProfiles\OCAOSMH\AppData\Local\OracleCloudAgent\plugins\oci-osmh\osmh-agent\stateDir\log\osmh-agent.log | Select-String -Pattern "invalid|osFamily|compatible"
  3. Determine the issue with the current profile:
    • Incorrect OS version: Message: Invalid Managed Instance osFamily ORACLE_LINUX_8 does not match Profile osFamily: ORACLE_LINUX_9

      In this example, the instance is Oracle Linux 8, but the profile was for Oracle Linux 9.

    • Incorrect instance type: Message: Managed Instance location ON_PREMISE is not compatible with a Profile registration type of: OCI_LINUX

      In this example, the instance is located on-premises or in a third-party cloud, but the profile was for an OCI instance type.

  4. Identify (or create) a profile that matches the OS version, architecture, and location of the instance you're registering.

    When creating a profile:

    • For on-premises or third-party cloud, select 'Other' for instance type.

    • For OCI instances, select 'Oracle Cloud Infrastructure' for instance type.

To resolve the issue for OCI instances

  1. Open the navigation menu and click Observability & Management. Under OS Management Hub, click Instances.
  2. Under List scope, select the compartment that contains the instance.
  3. Click the name of the instance.
  4. Click Set profile.
  5. Select the compartment and correct profile to use for registration.
  6. Click Set.

To resolve the issue for non-OCI instances:

  1. View the profile details.
  2. Copy the /etc/osmh-profile content.
  3. Log in to the instance as a user with sudo privileges.
  4. Replace the /etc/osmh-profile with the corrected profile. The instance will register the next time the OS Management Hub plugin checks in with the service.

Missing dynamic group rule

If the osmh-agent.log contains the following error, it could indicate that the dynamic group rule isn't set correctly.

ERROR: failed to update managed instance: Error returned by  Service. Http Status Code: 404.
                    Error Code: NotAuthorizedOrNotFound. Opc request id: <requestID>. Message: Authorization failed or requested resource not found.
                    ...
                    Request Endpoint: PUT https://osmh.<region>.oci.oraclecloud.com/20220901/agent/managedInstances/ocid1.managementagent.oc1.iad.<ocid>
To resolve the issue, verify that the dynamic group rules include the compartment that the instance resides in. Dynamic groups don't support compartment inheritance, so you might need to explicitly include subcompartments. See Required Dynamic Group.

System can't read /etc/sudoers.d

For management stations, on-premises or third-party cloud instances, the /etc/sudoers file must include /etc/sudoers.d for the Management Agent Cloud Service (MACS) to deploy the OS Management Hub plugin.

This is indicated by the following error:

/opt/oracle/mgmt_agent/agent_inst/bin/setup.sh opts=/tmp/input.rsp
...
Starting plugin deployment for: [osmh]
Deploying service plugin(s)...Failed.
        Requested external plugins [osmh] could not be deployed

Where /opt/oracle/mgmt_agent/agent_inst/log/mgmt_agent.log shows the following:

[/bin/sudo, -n, /opt/oracle/mgmt_agent/agent_inst/bin/chown_recursive_ep.sh, chown_recursive, root:mgmt_agent, osmh], timeout=PT5M]

To resolve the issue:

  1. Edit the /etc/sudoers file.
    sudo visudo
  2. Add the following lines and save the file.
    ## Read drop-in files from /etc/sudoers.d (the # here does not mean a comment)
    #includedir /etc/sudoers.d
  3. Rerun setup.sh. See Registering a Non-OCI Instance or Registering a Management Station.

Instance was previously unregistered

If you've previously unregistered an instance from OS Management Hub, there are additional steps to re-register it with the service. The process depends on the instance location.

OCI instances

Re-registering an OCI instance that was unregistered will fail until you remove the unregistration file on the instance. This file prevents the instance from registering with the service. When you try to register an instance that contains this file, the agent plugin displays the following error: started oci-osmh under unregistered mode.

Remove the following file before registering the instance:

  • Oracle Linux

    /var/lib/oracle-cloud-agent/plugins/oci-osmh/osmh-agent-unregister
  • Windows 2019 and 2022

    C:\Windows\ServiceProfiles\OCAOSMH\AppData\Local\OracleCloudAgent\plugins\oci-osmh\osmh-agent-unregister
  • Windows 2016

    C:\Users\OCAOSMH\AppData\Local\OracleCloudAgent\plugins\oci-osmh\osmh-agent-unregister

On-premises or third-party cloud instances

Re-registering a non-OCI instance that was previously registered might require installation of the Management Agent or manual deployment of the OS Management Hub agent plugin.

To re-register the instance:

  1. Log in to the instance as a user with sudo privileges.
  2. Check the status of the Management Agent.

    sudo systemctl status mgmt_agent
  3. If the mgmt_agent isn't found, register the instance as if it were new. See Registering a Non-OCI Instance. Skip the remaining steps in this procedure.
  4. If the mgmt_agent is present, start the agent and create the /etc/osmh-profile file:
    1. Start the mgmt_agent:

      sudo systemctl start mgmt_agent
    2. Create the /etc/osmh-profile file using a text editor. Ensure the filename has no file extension.

      sudo vi /etc/osmh-profile
  5. In the Console, deploy the OS Management Hub agent plugin to the instance.

    1. In the Console, navigate to Observability & Management. Under Management Agent, click Agents.
    2. Under Scope, select your compartment.
    3. Locate the correct agent by finding the hostname in the Name column. Click the name of the agent in the list.
    4. Click Deploy plug-ins.
    5. Select OS Management Hub and then click Update.
    6. Wait a few minutes and then verify the instance has registered.

OS not set to current time

Timeout errors at registration can occur when the time on the instance is different from the time used in the OS Management Hub service. A clock skew of more than 5 minutes can cause these types of errors.

During management station or instance registration, the following error is reported when running the /opt/oracle/mgmt_agent/agent_inst/bin/setup.sh script:
Starting plugin deployment for: [osmh]
Deploying service plugin(s)..............................Timed out.
        Agent is unable to check if it deployed requested service plugin(s) successfully or not. Please check back later on the console.
  1. Determine if clock skew exists by checking the managementagent service endpoint date against the instance or management station using the following commands.
    curl -s --head https://managementagent.<region>.oci.oraclecloud.com | grep Date
    date -u

    For example:

    $ curl -s --head https://managementagent.us-phoenix-1.oci.oraclecloud.com | grep Date
    Date: Tue, 13 Jun 2023 15:42:17 GMT
    $ date -u
    Tue Jun 13 15:42:19 UTC 2023
  2. If the date or time on the instance or management station is different from the time reported by the service, update the OS time to match the service.
    If time synchronization facilities such as Chrony or Network Time Protocol (NTP) are used, verify their setup and operation.