Registering a Non-OCI Instance

Register an on-premises or supported third-party cloud instance by installing necessary packages, adding a registration profile, and installing the Management Agent.

Important

Cloning a VM that's already registered with OS Management Hub isn't supported.

Before You Begin

Before you register an instance with OS Management Hub, you must do the following:

Complete the getting started section.
Register a management station.
Create a profile to register an instance with the content associated with a software source, group, or lifecycle environment.
Download the Management Agent software on the host system.
Create Management Agent Cloud Service (MACS) install keys in the compartments where you want the instances to reside.
Ensure the instance is synchronized with a time server (NTP). For example, you can configure Chrony.

Add Registration Profile to the Instance

In the Console, copy the contents of the software source, group, or lifecycle profile.
1. Open the navigation menu and click Observability & Management. Under OS Management Hub, click Profiles.
2. Click the name of the profile.
3. Verify the profile information identifies a Management Station. This confirms the profile is for on-premises or third-party cloud instances.
4. If the profile is the correct type, click View.
5. Copy the contents of the profile.
Log in to the instance as a user with sudo privileges
Create the /etc/osmh-profile file (with no file extension on the filename) using a text editor. For example:
```
sudo vi /etc/osmh-profile
```
Paste the profile contents that you copied from the Console and save the file.

Install the Management Agent

Install the Management Agent software on the instance. The Management Agent uses the OS Management Hub plugin to register instances with the OS Management Hub service.

Note

For more detailed steps about installing the Management Agent software, see Installing Management Agents.

Verify /etc/sudoers includes /etc/sudoers.d:
```
sudo visudo
```
Confirm the following lines are present. If not, add them and save the file.
```
## Read drop-in files from /etc/sudoers.d (the # here does not mean a comment)
#includedir /etc/sudoers.d
```
Install required packages. This includes JDK8 or JRE8 (minimum 1.8u281 or a later 1.8 version).
Java Development Kit (JDK) or Java Runtime Environment (JRE) must be installed on the instance before you install the Management Agent software. The Management Agent requires JDK8 only.
Oracle Linux 9
sudo dnf install -y java-1.8.0-openjdk chkconfig
Oracle Linux 8
sudo dnf install -y java-1.8.0-openjdk
Oracle Linux 7
sudo yum install -y java-1.8.0-openjdk
Set the JAVA_HOME environmental variable to use JDK8. Setting the variable ensures MACS uses the correct Java version when newer versions are on the system.
```
JAVA_HOME=/usr/lib/jvm/jre-1.8.0-openjdk ; export JAVA_HOME
```
Navigate to the directory that contains the downloaded Management Agent software RPM file and run the following command to install the RPM file:
Oracle Linux 8 or 9
sudo --preserve-env=JAVA_HOME dnf install -y <rpm_file_name>.rpm
Oracle Linux 7
sudo --preserve-env=JAVA_HOME yum install -y <rpm_file_name>.rpm

Set Up the Management Agent

Activate the Management Agent with the OS Management Hub plugin. Upon activation, the instance registers with the OS Management Hub service in the compartment specified in the install key and with the content associated with the profile.

Configure the Management Agent plugin to run as root. The OS Management Hub plugin needs to run as root to patch the instance. For example:

sudo tee /etc/sudoers.d/mgmt_agent <<EOF
## Allows Management Agent to change ownership of deployed External Plugin
mgmt_agent ALL=(ALL) NOPASSWD:/opt/oracle/mgmt_agent/agent_inst/bin/chown_recursive_ep.sh
## Allows Management Agent to run External Plugin under root user
mgmt_agent ALL=(root) NOPASSWD:SETENV: /opt/oracle/mgmt_agent/plugins/osmh/*/osmh
EOF

Set the permissions of the file to 440.

sudo chmod 440 /etc/sudoers.d/mgmt_agent

In the Console, copy the Management Agent install key to use to register the instance.
1. Open the navigation menu and click Observability & Management. Under Management Agent, click Downloads and Keys.
2. Under Install keys, find the key that you want to use to register the instance.
3. Click the Actions menu for the key and select Copy key to clipboard.
Create a response (input.rsp) file manually with a text editor and replace <MACS_KEY> with the install key that you copied in the previous step.
For example:
```
cat >/tmp/input.rsp <<EOF
ManagementAgentInstallKey = <MACS_KEY>
Service.plugin.osmh.download = true
GatewayServerHost = <STATION_OR_LOAD_BALANCER_HOSTNAME>
GatewayServerPort = <STATION_PROXY_PORT>
EOF
```
The input.rsp file requires the following mandatory parameters.
- ManagementAgentInstallKey: Install key required to validate the identity of the domain and the authenticity of the installation.
- Service.plugin.osmh.download = true: Deploys the OS Management Hub (osmh) plugin during the agent installation.
To use the management station as the proxy for all OS Management Hub communication with the instance, add the following parameters in the input.rsp file.
- GatewayServerHost: Host name or IP address of the management station (or load balancer if configuring high availability, see Configuring High Availability for Management Stations).
- GatewayServerPort: Proxy port number of the management station.
To identify the host name and proxy port of the management station, follow these steps in the Console:
1. Open the navigation menu and click Observability & Management. Under OS Management Hub, click Profiles.
2. Click the profile associated with the instance.
3. Within the Profile information section, click the Management station name.
4. Click the Configuration tab.
5. Record the Hostname and Proxy listening port values to use in the input.rsp file.
Configure the Management Agent by running the setup.sh script using the response file.
```
sudo /opt/oracle/mgmt_agent/agent_inst/bin/setup.sh opts=/tmp/input.rsp
```
A successful setup returns the following message: Agent setup completed and the agent is running. The setup of the OS Management Hub plugin can take another few minutes in the background.

Verify Instance Registration and Details

Verify the instance registered with OS Management Hub.

Open the navigation menu and click Observability & Management. Under OS Management Hub, click Instances.
Under List scope, select the compartment that contains the instance.
Confirm the instance appears in the table, and verify the status is Active.

Tip

To troubleshoot registration issues, see Registration Failed for Instance or Management Station.
Click the name of the instance to view its details.

Under Instance information, you can view details about the instance, such as the registration profile it used to register with the service and whether it's a member of a group or lifecycle environment, if applicable.

Note

The instance might take a few minutes to report the initial package and module inventory to the service.

What's Next

After registering an instance, consider:

For standalone instances, update the instance.
For an instance that's a member of group, update the instances in the group.
For an instance that's part of a lifecycle environment, promote content to a lifecycle stage.