Oracle Cloud Infrastructure Documentation
Try Free Tier

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:

Add the 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 select Observability & Management. Under OS Management Hub, select Profiles.
    2. Select 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, select View.
    5. Copy the contents of the profile.
  2. Log in to the instance as a user with sudo privileges
  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 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.
  1. 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
  2. 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
  3. 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
  4. 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.

  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 select Observability & Management. Under Management Agent, select Downloads and Keys.
    2. Under Install keys, find the key that you want to use to register the instance.
    3. Select 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 = <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.

    To identify the host name and proxy port of the management station, follow these steps in the Console:

    1. Open the navigation menu and select Observability & Management. Under OS Management Hub, select Profiles.
    2. Select the profile associated with the instance.
    3. Within the Profile information section, select the Management station name.
    4. Select 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.

Verify Instance Registration and Details

Verify the instance registered with OS Management Hub.

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

  4. Select 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.

Was this article helpful?