Oracle Cloud Infrastructure Documentation

Installing the Agent

Learn about how to install the Unified Monitoring Agent, whether for new instances, existing instances, or instances created from custom images, and non-Oracle Cloud Infrastructure instances.

On new Oracle Cloud Infrastructure instances with supported operating systems, you can enable the agent directly during creation time. For both new and existing instances with supported operating systems, the Custom Logs Monitoring plugin must be enabled, and all plugins must be running. See Available Plugins for more information.

Manual Installation

If you already have the Custom Logs Monitoring plugin enabled, then your instance will be automatically patched to install the agent. Otherwise, you can use the following manual installation instructions.

Run the following command to get more details on the latest agent download versions for each OS:

Command
oci os object get --namespace axmjwnk4dzjv --bucket-name unified-monitoring-agent-config --name versionInfoV2.yml --file versionInfoV2.yml --profile <profile-name> --auth security_token
The command downloads the versionInfoV2.yml file with the following contents:
versionInfoComposite:
  Oracle Linux Server:
    prefix: "unified-monitoring-agent-ol-"
    stableVersion: "0.1.39"
    postStableVersionComposite:
      default:
  CentOS Linux:
    prefix: "unified-monitoring-agent-cl-"
    stableVersion: "0.1.39"
    postStableVersionComposite:
      default:
  Ubuntu:
    prefix: "unified-monitoring-agent-ub-"
    stableVersion: "0.1.39"
    postStableVersionComposite:
      default:
  Windows:
    prefix: "unified-monitoring-agent-win-"
    stableVersion: "0.1.39"
    postStableVersionComposite:
      default:
  Debian GNU/Linux:
    prefix: "unified-monitoring-agent-deb-"
    stableVersion: "0.1.39"
    postStableVersionComposite:
      default:

The stableVersion field in versionInfoV2.yml shows the latest version number to use for each OS.

Note

For Red Hat Linux packages, use the Oracle Linux Server section to specify the version number.

After you have found the proper version number, perform the following setup steps, whether for Linux or Windows.

Linux:

  1. Connect to the instance.
  2. Set up token-based authentication for the CLI.

  3. Use the following command to download the non-FIPS or FIPS-enabled agent for your Linux OS, while replacing <bucket>, <name>, and <file> for the particular OS version:

    Command
    oci os object get --namespace axmjwnk4dzjv --bucket-name <bucket> --name <name> --file <file> --profile OC1 --auth security_token
    OS Version <Bucket> <Name> and <File>
    non-FIPS agent: x86
    Oracle Linux 7 unified-monitoring-agent-ol-bucket unified-monitoring-agent-ol-7-<version>.rpm
    Oracle Linux 8 unified-monitoring-agent-ol-bucket unified-monitoring-agent-ol-8-<version>.rpm
    Oracle Linux 9 unified-monitoring-agent-ol-bucket unified-monitoring-agent-ol-9-<version>.rpm
    CentOS 7 unified-monitoring-agent-cl-bucket unified-monitoring-agent-cl-7-<version>.rpm
    Red Hat Enterprise Linux 8 unified-monitoring-agent-rl-bucket unified-monitoring-agent-rhel-8-<version>.rpm
    Red Hat Enterprise Linux 9 unified-monitoring-agent-rl-bucket unified-monitoring-agent-rhel-9-<version>.rpm
    Ubuntu 16.04 unified-monitoring-agent-ub-bucket unified-monitoring-agent-ub-16-<version>.deb
    Ubuntu 18.04 unified-monitoring-agent-ub-bucket unified-monitoring-agent-ub-18-<version>.deb
    Ubuntu 20.04 unified-monitoring-agent-ub-bucket unified-monitoring-agent-ub-20-<version>.deb
    Ubuntu 22.04 unified-monitoring-agent-ub-bucket unified-monitoring-agent-ub-22-<version>.deb
    non-FIPS agent: ARM
    Oracle Linux 7 unified-monitoring-agent-ol-bucket unified-monitoring-agent-ol-7-<version>.aarch64.rpm
    Oracle Linux 8 unified-monitoring-agent-ol-bucket unified-monitoring-agent-ol-8-<version>.aarch64.rpm
    Oracle Linux 9 unified-monitoring-agent-ol-bucket unified-monitoring-agent-ol-9-<version>.aarch64.rpm
    Red Hat Enterprise Linux 8 unified-monitoring-agent-rl-bucket unified-monitoring-agent-rhel-8-<version>.aarch64.rpm
    Red Hat Enterprise Linux 9 unified-monitoring-agent-rl-bucket unified-monitoring-agent-rhel-9-<version>.aarch64.rpm
    FIPS-enabled agent: x86
    Oracle Linux 7 unified-monitoring-agent-ol-bucket unified-monitoring-agent-ol-7-fips-<version>.rpm
    Oracle Linux 8 unified-monitoring-agent-ol-bucket unified-monitoring-agent-ol-8-fips-<version>.rpm
    Red Hat Enterprise Linux 8 unified-monitoring-agent-rl-bucket unified-monitoring-agent-rhel-8-fips-<version>.rpm
    FIPS-enabled agent: ARM
    Oracle Linux 7 unified-monitoring-agent-ol-bucket unified-monitoring-agent-ol-7-fips-<version>.aarch64.rpm
    Oracle Linux 8 unified-monitoring-agent-ol-bucket unified-monitoring-agent-ol-8-fips-<version>.aarch64.rpm
    Red Hat Enterprise Linux 8 unified-monitoring-agent-rl-bucket unified-monitoring-agent-rhel-8-fips-<version>.aarch64.rpm
  4. Run the following command to install the RPM:
    yum install -y <rpm-name>

    For Ubuntu:

    dpkg -i <deb-package-name>

Windows:

  1. Connect to the instance.
  2. Set up token-based authentication for the CLI.
  3. Use the following command to download the non-FIPS or FIPS-enabled agent for Windows Server 2012, 2016, 2019 and 2022, while replacing <name>, and <file> for the particular Windows OS version:
    Command
    oci os object get --namespace axmjwnk4dzjv --bucket-name unified-monitoring-agent-win-bucket --name <name> --file <file> --profile OC1 --auth security_token
    OS Version <Name> and <File>
    non-FIPS agent
    Windows 2012 unified-monitoring-agent-win-2012-<version>.msi
    Windows 2016 unified-monitoring-agent-win-2016-<version>.msi
    Windows 2019 unified-monitoring-agent-win-2019-<version>.msi
    Windows 2022 unified-monitoring-agent-win-2022-<version>.msi
    FIPS-enabled agent
    Windows 2012 unified-monitoring-agent-win-2012-fips-<version>.msi
    Windows 2016 unified-monitoring-agent-win-2016-fips-<version>.msi
    Windows 2019 unified-monitoring-agent-win-2019-fips-<version>.msi
    Windows 2022 unified-monitoring-agent-win-2022-fips-<version>.msi
  4. Open an elevated command prompt (as an Administrator), and run the MSI command. Installation can take up to five minutes to complete:
    C:\path\to\file\<unified monitoring agent msi>

    For a more advanced version of the preceding command to debug MSI installation issues, run:

    msiexec /i "C:\path\to\file\<unified monitoring agent msi>" /l*v "C:\unified-monitoring-agent_msi.log"

Instances Created from Custom Images and Non-Oracle Cloud Infrastructure Instances

  1. Install the agent according to the same steps in Manual Installation.
  2. Configure user API keys for the instance you're running on. To generate the user API key, follow the instructions described in How to Generate an API Signing Key.
    • (Linux). Place the ".oci" directory and its contents under /etc/unified-monitoring-agent.
    • (Windows). For Windows, some steps differ, so ensure to follow the appropriate steps. Create the ".oci" folder and its contents in the directory C:\oracle_unified_agent.
  3. Follow the instructions described in Creating a Profile in the Oracle Cloud Infrastructure CLI Configuration File, to create the configuration file with the modifications in the next step.
  4. After following the steps in Creating a Profile in the Oracle Cloud Infrastructure CLI Configuration File, ensure to name the profile (<profile-name>) for this section as "UNIFIED_MONITORING_AGENT".
    The following is an example configuration for the Unified Monitoring Agent to use for authentication with the service:
    [UNIFIED_MONITORING_AGENT]
user=ocid1.user.region..aaa...
fingerprint=<cert fingerprint>
key_file=/path/to/ocifolder/.oci/private.pem
tenancy=ocid1.tenancy.region..aaa...
region=<instances region>
pass_phrase="pashphrase1234"

Managed System Resources (Non-Instance)

  1. Install the agent according to the same steps in Manual Installation.
  2. Create a Dynamic Group with a matching rule targeting database resources, and apply it to your agent configuration. For more information, see About Dynamic Groups. Select a dynamic group from the Group list matching the rule for a resource of any resource type (database, dbsystem, cloudvmcluster).
    ALL {resource.type = <resource-type>, resource.id = <resource-ocid>}

    For example: ALL {resource.type = 'database', resource.id = 'ocid1.database.oc1.phx.<unique_ID>'}.

    If you're new to policies, see Getting Started with Policies and Common Policies. To learn more about writing policies for dynamic groups or other IAM components, see Details for IAM without Identity Domains.

  3. Create a policy granting the dynamic group you created access to the Logging service.
    Allow dynamic-group <dynamic-group> to use log-content in compartment <compartment-name>

    For example: Allow dynamic-group linuxdbvm to use log-content in compartment <compartment-name>.

  4. Create a file in the /etc/resource_principal_env directory on the host using the following format.
    OCI_RESOURCE_PRINCIPAL_VERSION=1.1
OCI_RESOURCE_PRINCIPAL_RPT_ENDPOINT=https://database.<oci_region>.oraclecloud.com //The endpoint for retrieving the resource principal token
OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem //PKI-provisioned certificate
OCI_RESOURCE_PRINCIPAL_REGION=<oci_region> // OCI region
OCI_RESOURCE_PRINCIPAL_RPST_ENDPOINT=https://auth.<oci_region>.oraclecloud.com //The endpoint for retrieving the resource principal session token

    The following is an example for the Oracle Exadata Database service in the us-phoenix-1 region:

    OCI_RESOURCE_PRINCIPAL_VERSION=1.1
OCI_RESOURCE_PRINCIPAL_RPT_ENDPOINT=https://database.us-phoenix-1.oraclecloud.com
OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem
OCI_RESOURCE_PRINCIPAL_REGION=us-phoenix-1
OCI_RESOURCE_PRINCIPAL_RPST_ENDPOINT=https://auth.us-phoenix-1.oraclecloud.com

    For more information, see Regions and Availability Domains.

  5. Restart the agent using the following command:
    sudo systemctl restart unified-monitoring-agent