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.

Note

The agent, or Unified Monitoring Agent, is also known as the Oracle Cloud Agent plugin that is called "Custom Logs Monitoring".

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:

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.35"
    postStableVersionComposite:
      default:
  CentOS Linux:
    prefix: "unified-monitoring-agent-cl-"
    stableVersion: "0.1.35"
    postStableVersionComposite:
      default:
  Ubuntu:
    prefix: "unified-monitoring-agent-ub-"
    stableVersion: "0.1.35"
    postStableVersionComposite:
      default:
  Windows:
    prefix: "unified-monitoring-agent-win-"
    stableVersion: "0.1.35"
    postStableVersionComposite:
      default:
  Debian GNU/Linux:
    prefix: "unified-monitoring-agent-deb-"
    stableVersion: "0.1.35"
    postStableVersionComposite:
      default:

The stableVersion field in versionInfoV2.yml shows the latest version number to use for each OS. 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:

    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
    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
    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
    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
  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:
    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"