Registration Failed for Instance or Management Station
An instance or management station can fail to register with OS Management Hub for several reasons.
- Invalid profile was used
- Incorrect policy statement or missing dynamic group rule
- System can't read /etc/sudoers.d
- Instance was previously unregistered
- OS not set to current time
- OS Management plugin running
See also: Known Issue: Older platform images or Bring Your Own Images will not register .
Common 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 |
---|---|
|
Cause: For on-premises or third-party cloud, the Resolution: Identify and use a compatible profile. See Invalid profile was used. |
|
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. |
|
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. |
|
Cause: The profile has the wrong operating system. For example, the instance is Oracle Linux 8 but the profile Oracle Linux 9. Resolution: Identify and use a compatible profile. See Invalid profile was used. |
|
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 |
HTTP 401: NotAuthenticated
|
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. |
Invalid profile was used
Check the osmh-agent.log
file and identify the correct profile
To update the profile for OCI instances
- Under List scope, select the compartment that contains the instance.
- Click the name of the instance.
- Click Set profile.
- Select the compartment and correct profile to use for registration.
- Click Set.
To update the profile for on-premises or third-party cloud instances:
- View the profile details.
-
Copy the
/etc/osmh-profile
content. - Log in to the instance as a user with sudo privileges.
-
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, it might indicate that the policy statements or dynamic group rule 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:
Plugin OS Management Hub Agent not present for instance ocid1.instance.oc1.iad.<ocid>
To resolve the issue, verify you've correctly configured the policy statements. See Required IAM Policy.
Most commonly the dynamic group rule doesn't 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:
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:
- Log in to the instance as a user with sudo privileges.
-
Check the status of the Management Agent.
sudo systemctl status mgmt_agent
- 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. - If the
mgmt_agent
is present, start the agent and create the/etc/osmh-profile
file:-
Start the
mgmt_agent
:sudo systemctl start mgmt_agent
-
Create the
/etc/osmh-profile
file using a text editor. Ensure the filename has no file extension.sudo vi /etc/osmh-profile
-
-
In the Console, deploy the OS Management Hub agent plugin to the instance.
- In the Console, navigate to Observability & Management. Under Management Agent, click Agents.
- Under Scope, select your compartment.
- Locate the correct agent by finding the hostname in the Name column. Click the name of the agent in the list.
- Click Deploy plug-ins.
- Select OS Management Hub and then click Update.
- 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.
/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.
OS Management plugin 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:
- Open the navigation menu, click Compute, and then click Instances.
- Click the name of the instance.
- Click the Oracle Cloud Agent tab.
- Disable the OS Management Service Agent plugin.