Oracle Cloud Infrastructure Documentation

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.

1. Add Registration Profile to the Instance

  1. 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.
  2. Connect to the instance by using SSH.
  3. Create the /etc/osmh-profile file (with no file extension on the filename) using a text editor. For example: 
    sudo vi /etc/osmh-profile
  4. Paste the profile contents into the /etc/osmh-profile file and save the file.

2. 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.
  1. Install the latest version of JDK8 or JRE8 (version 1.8u281 or later).

    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 8 or 9
    sudo dnf install -y java-1.8.0-openjdk
    Oracle Linux 7
    sudo yum install -y java-1.8.0-openjdk
  2. 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 dnf install -y <rpm_file_name>.rpm
    Oracle Linux 7
    sudo yum install -y <rpm_file_name>.rpm

3. 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.

  1. 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
  2. Set the permissions of the file to 440. 
    sudo chmod 440 /etc/sudoers.d/mgmt_agent
  3. 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.
  4. 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 = <MANAGEMENT_STATION_HOST_NAME>
GatewayServerPort = <MANAGEMENT_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.
    • 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.
  5. 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.

4. Verify Instance Registration and Details

Verify the instance registered with OS Management Hub.

  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. Confirm the instance appears in the table, and verify the status is Active.

    To troubleshoot registration issues, see Registration Failed for Instance or Management Station.

  4. Click the name of the instance to view its details.

    Under Instance information, you can view details about the instance, such as the management station it's using, 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.