Oracle Cloud Infrastructure Documentation

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:

Common osmh-agent.log Error Messages

To troubleshoot registration issues, start by examining the osmh-agent.log file for the following error messages. See Examining Log Files on an Instance to identify the location of the log file.

Code and Message Possible cause and resolution

Http Status Code: 400. Error Code: MissingParameter.

Message: Registration profile is required for on-boarding instances, but none was provided.

Cause: For on-premises or third-party cloud, the /etc/osmh-profile is missing or invalid. For OCI instances, there wasn't a compatible default profile at registration.

Resolution: Identify and use a compatible profile. See Invalid profile was used.

Http Status Code: 404. Error Code: NotAuthorizedOrNotFound.

Message: Authorization failed or requested resource not found.

Cause: The current policies don't allow OS Management Hub to access the instance. Most commonly, the dynamic group doesn't include matching rules for the compartment that contains the instance. Or, there's a missing or incorrect policy statement.

Resolution: Verify policies are correct. See Incorrect policy statement or missing dynamic group rule.

Http Status Code: 409. Error Code: Conflict.

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

Cause: The profile has the wrong instance type. For example, the instance is located on premises or in a third-party cloud, but the profile is for an OCI instance type.

Resolution: Identify and use a compatible profile. See Invalid profile was used.

Http Status Code: 409. Error Code: Conflict.

Message: Invalid Managed Instance osFamily ORACLE_LINUX_8 does not match Profile osFamily: ORACLE_LINUX_7

Cause: The profile has the wrong operating system. For example, the instance is Oracle Linux 8 but the profile is Oracle Linux 7.

Resolution: Identify and use a compatible profile. See Invalid profile was used.

Http Status Code: 409. Error Code: IncorrectState.

Message: Station already has an instance associated

Cause: The profile is for a management station and is already in use by another station. A management station profile can only be used once.

Resolution: Identify and use a compatible profile for /etc/osmh-profile. See Invalid profile was used. Then, retry the registration.

TokenRefreshAuthenticationException: Token refresh failed due to authentication issues due to AuthenticationException

HTTP 401: NotAuthenticated

Unable to authenticate the request for ocid1.managementagent.oc1.iad.<ocid>

Cause: The Management Agent Cloud Service (MACS) agent isn't running as expected.

Resolution: Verify the MACS agent is correctly configured and restart the agent. See Troubleshooting MACS.

Common Oracle Cloud Agent Error Messages

For OCI instances, use the OS Management Hub Agent plugin status to troubleshoot registration issues. In the Console, on the Oracle Cloud Agent tab on the Compute instance details page, you might see one of the following error messages.

Error Message Possible cause and resolution

Plugin OS Management Hub Agent not present for instance ocid1.instance.oc1.iad.<ocid>

Cause: The OS Management Hub agent isn't installed on the instance. This usually occurs when the service can't access the instance because of a policy issue.

Resolution: Verify your policy statements are correct and that the instance is included in the dynamic group. See Incorrect policy statement or missing dynamic group rule.

failed to start osmh-agent with [lookup image failed. The instance could not register with OS Management Hub.

Cause: The OS Management Hub agent can't start on the instance. This usually occurs when the service can't access the instance because of a policy issue.

Resolution: Verify your policy statements are correct and that the instance is included in the dynamic group. If not using the default identity domain, verify you've specified the identity domain in the policy statements. See Incorrect policy statement or missing dynamic group rule.

rpc error: code = Unavailable desc = connection error: desc = "transport: error while dialing: dial unix /var/lib/oracle-cloud-agent/tmp/plugin162329539: connect: connection refused"

Cause: Multiple OCA plugins are running. The OS Management Hub and OS Management plugin can't run at the same time.

Resolution: Disable the OS Management plugin. See Multiple plugins running.

Invalid profile was used

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 the key word "Error Code", to determine if a profile error exists. See Common osmh-agent.log Error Messages.

    For example, for an Oracle Linux OCI instance:

    sudo grep -i "error code" /var/lib/oracle-cloud-agent/plugins/oci-osmh/osmh-agent/stateDir/log/osmh-agent.log

    For example, for an on-premises instance:

    sudo grep  -i "error code" /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 "Error Code"
  3. Identify (or create) a profile that matches the OS version, architecture, and location of the instance you're registering.

To update the profile for OCI instances

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

    It can take several minutes for the status of the instance to update.

To update the profile for on-premises or third-party cloud 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.

Incorrect policy statement or missing dynamic group rule

If you encounter the following errors when registering an instance, it might indicate that the policy statements or dynamic group rules aren't set correctly.

The osmh-agent.log contains:

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>

Or, the Oracle Cloud Agent tab on the Compute instance details page shows one of the following messages:

Plugin OS Management Hub Agent not present for instance ocid1.instance.oc1.iad.<ocid>
failed to start osmh-agent with [lookup image failed. The instance could not register with OS Management Hub.

To resolve the issue, verify you've correctly configured the policy statements and dynamic group rules. Most commonly the dynamic group doesn't include the instance.

Verify the following:

  • Ensure that you've included a dynamic group rule for each compartment and subcompartment containing instances that you want manged by the service. Dynamic groups don't support compartment inheritance.
  • If not using the default identity domain, ensure each policy statement has the identity domain before the group or dynamic group name (for example, <identity_domain_name>/<dynamic_group_name>).

See also: Troubleshooting: Policy Issues.

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, select Agents.
    2. Under Scope, select your compartment.
    3. Locate the correct agent by finding the hostname in the Name column. Select the name of the agent in the list.
    4. Select Deploy plug-ins.
    5. Select OS Management Hub and then select 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. 
    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.

    For example, run the following commands to verify the configuration:

    chronyc sources -a
    chronyc tracking

Multiple plugins running

The OS Management plugin and OS Management Hub plugin for the Oracle Cloud Agent can't be running at the same time. In the Console, on the Oracle Cloud Agent tab in Compute instance details, you might see the following error:

rpc error: code = Unavailable desc = connection error: 
desc = "transport: error while dialing: dial unix /var/lib/oracle-cloud-agent/tmp/plugin162329539: connect: connection refused"

Disable the OS Management plugin:

  1. Open the navigation menu, select Compute, and then select Instances.
  2. Select the name of the instance.
  3. Select the Oracle Cloud Agent tab.
  4. Disable the OS Management Service Agent plugin.