Oracle Cloud Infrastructure Documentation

Management Agents Administration Tasks

Management Agents are deployed to collect log and metric data from different sources. In order to do that, some administration tasks may need to be performed.

The following sections describe some common administration tasks:

Management Agents Console Overview

The Management Agents console is the user interface for the OCI Management Agent service that allows you to view and administer Management Agents and Management Gateways.

You can perform basic and advanced operations depending on your needs. The overview page provides important information and links to the resources configured on the Management Agents service. Console also provides access to the Management Agents (agents) and Management Gateways (gateways) configured, and also dashboards to visualize relevant data in charts.

To open the Management Agents console:

  • Sign in to OCI and open the navigation menu from the OCI Console.

  • Under Observability & Management, click Management Agent.

  • Go to the left menu and select a compartment from the Compartment dropdown list.

    The Management Agents console is displayed.

The Management Agents console has a menu on the left with the following options:

Overview

The Overview page displays useful information about the Management Agent service and the Management Agents and Management Gateways installed.

The Overview page provides summary information about the Management Agents and Management Gateways in your environment. It consists of the following charts:

  • Agents: Number of Management Agents installed.

  • Agent Availability: Management Agent availability status. The following are the statuses available:

    • Active: The Management Agent service is communicating with the Management Agent.

    • Silent: The Management Agent service is not communicating with the Management Agent. The communication with the agent was established after the agent installation, but something happened and there might be a communication problem between the Management Agent service and the agent.

    • Not Available: The Management Agent installation process is running and the Management Agent service hasn't established communication with the agent yet.

    Note

    Starting May 9, 2022, Management Agents that remain in SILENT availability status for more than 90 days will not be shown in the Console. You may use OCI CLI to review such agents by lifeCycleState, and delete as needed. Management Agents that remain in SILENT availability status for more than 180 days will be automatically DELETED.

  • Alarms: Management Agents and Gateways alarm details from OCI Monitoring service. For information about setting up alarms and notifications, see:

  • Agent Operating Systems: Operating system versions of the Management Agents installed.

  • Agent Versions: Management Agent versions.

  • Agent Service Plug-ins: Service plug-ins that have been deployed by the Management Agents.

  • Data Sent by Agents: Amount of data that is being sent to the service plug-ins by the Management Agents.

  • Gateways: Number of Management Gateways installed.
  • Gateway Availability: Management Gateways availability status.

  • Data Sent by Gateways: Amount of data that is being sent to the service plug-ins by the Management Gateways.

You can click on each chart to see more details.

The following screenshot is an example of the Management Agents Overview page.

Overview page that shows information about management agents installed.

Dashboards

You can use dashboards to visualize, explore, and analyze data in easy-to-interpret charts. For information, see Work with Dashboards.

Agents

The Agents page lists all the Management Agents (agents) and Management Gateways (gateways) installed in a selected compartment.

The Agents page has the following options:

Agents and Gateways

To select a compartment:
  • Go to the left pane. Under Scope, select the desired compartment from the Compartment dropdown list.
    • If a root compartment is selected, the Include subcompartments checkbox is available.

      Use the checkbox to list all the accessible agents in subcompartments.

      The default maximum number of agents and gateways listed is 1,000. To customize your selection, go to the left pane and use Filters.

      Policy requirement: Ensure you have the inspect management-agents permission at the tenancy root compartment to be able to list all the subcompartments from the root compartment. For example: ALLOW GROUP <group_name> TO INSPECT management-agents IN TENANCY

    • If a non-root compartment is selected, the Include subcompartments checkbox is disabled.

The Agents and Gateways page displays a table listing all the Management Agents and Management Gateways installed.

The table consists of the following columns:

  • Name: Shows the Management Agent or Gateway name.

  • Host: Shows the host name where the Management Agent or Gateway is installed.

  • Availability: Shows the Management Agent or Gateway status.

  • Operating system: Shows the operating system of the host where the Management Agent or Gateway is installed.

  • Version: Shows the version of the installed Management Agent or Gateway.

  • Plug-ins: Shows the name of the service plug-in that has been deployed by the Management Agent.

  • Created: Shows the date when the Management Agent or Gateway was installed.

  • Action Item : Shows more actions available for a specific Management Agent or Gateway.

The following screenshot is an example of the Agents and Gateways list.

Agents and Gateways page that shows all management agents and management gateways installed.

You can click on a specific agent or gateway to open up the details page and quickly go and get more information.

Note

Ensure you have READ management-agents permission to be able to see the agent or gateway details.

Agents Details

The Agents Details page shows information about the selected agent.

  • Use Deploy plug-ins to deploy a plug-in on the selected agent.

  • Use Enable Agent Logs to enable Logging Analytics service to gather Management Agent log files for the selected agent. For information, see Enable Agent Logs.

  • Use Manage DataSources to view or edit properties and dimensions of the datasource type configured with the selected agent. For information, see Manage DataSources.

  • Use More actions to Add tags or Delete an agent.
  • The Agent Information tab shows detailed agent information. It displays the host name, compartment name, agent version, operating system, service plug-ins deployed on it, work requests, datasoruces and more.
    • Service Plug-ins: Use the Service Plug-ins link to list all the service plug-ins deployed on this specific Management Agent. For more information, see Deploy Service Plug-ins.
    • DataSources: Use the DataSources link to list all the datasources configured on this specific Management Agent. For more information, see Manage DataSources.

Agent details page that shows information about a management agent installed.

Gateway Details

The Gateway Details page shows detailed information about a gateway.

The Gateway Information tab shows detailed gateway information. It displays the host name, compartment name, gateway version, operating system, associated agents and more.

Associated Agents: Use the Associated Agents link to list all the Management Agents configured to use this specific Management Gateway. The Associated Agents pane displays the id, host, availability and operating systems information of the Management Agents.

Gateway details page that shows information about a management gateway installed.

Agents with DataSource

The Agents with DataSource page displays a table listing all the agents with datasources configured.

The table consists of the following columns:

  • Name: Name of the agent.

  • DataSource type: Type of the datasource. For example: Prometheus.

  • DataSource: Name of the datasource.

  • Availability: Agent availability.

  • Created: Timestamp when the agent was created.

You can click on a specific agent to open up the details page and quickly go and get more information.

Downloads and Keys

The Downloads and Keys page displays information about the Management Agent download file and the Management Agent install keys created.

It consists of the Agent Software Download pane at the top and the Agent Install Keys pane at the bottom.

Agent Software Download

The Software Download pane has a table consisting of the following columns:

  • Download: Shows the Management Agent download file name.

  • Package type: Shows the package type: ZIP or RPM.

  • Version: Shows the Management Agent version installed.

  • Size (MB): Shows the Management Agent size.

  • SHA-256 Checksum: Shows the information to confirm file integrity.

The following screenshot is an example of the Software Download pane.

Software Download pane

Agent Install Keys

The Agent Install Keys pane has a Create Key button to create an Agent Install Key. It also displays a table consisting of the following columns:

  • Key Name: Shows the Management Agent install key name.

  • Compartment: Shows the compartment name where the Management Agent install key was created.

  • Created by: Shows information about the user who created the Management Agent install key.

  • Created: Shows the date of the Management Agent install key creation.

  • Days Remaining: Shows the number of days remaining until the Management Agent install key expires.

  • Agents Installations Remaining: Shows the number of installations remaining for each Management Agent install key.

  • Action Item Action Item Menu: It shows more actions available for an Agent Install Keys like, Copy Key to Clipboard, Download Key to File, and Delete Key.

Deploy Service Plug-ins

Management Agents allow you to deploy service plug-ins for different Oracle Cloud Infrastructure (OCI) services.

Service plug-ins can be deployed to management agents enabling to perform tasks for those services. Any given management agent can have multiple service plug-ins.

Available Service Plug-ins

The following service plug-ins are available:

  • Database Management and Operations Insights Service.
  • Java Management Service.
  • Java Usage Tracking.
  • Logging Analytics.
  • Operations Insights Host Service.
  • Stack Monitoring.

For more information about OCI services, see Oracle Cloud Infrastructure (OCI) services.

Note

If there's any OCI service plug-in update available, it will get updated automatically.

Deploy a Service Plug-in

You can deploy a service plug-in using any of the following methods:

Deploy a Service Plug-in Using the Agents Page

Use this method when the Management Agent is already installed as described in Install Management Agents.

To deploy a plug-in using the Agents page, do the following:

  1. From the left menu, click on Agents to open up the Agents page.

  2. From the Agents list, click on the desired agent where you want to deploy the plug-in.

    The Agent detail page is displayed.

    Agent details page that shows information about a management agent installed.

  3. Click Deploy Plug-ins.

    The Deploy Plug-ins window is displayed.

  4. Select the plug-in and click Update.

    The selected plug-in will be deployed on the desired agent.

Deploy a Service Plug-in During the Management Agent Installation

Use this method when a plug-in deployment is performed during the Management Agent installation process.

  1. Follow the instructions to download the agent software and create an agent install key as described in Download the Agent Software and Create Install Key.

  2. Download the agent install key file.

    Go to the Agent Install Keys page and from the action menu, select Download Key to File option.

    The Download Key to File option allows you to download a response file template. For details, Download Install Key.

  3. Edit the response file template using a text editor and create a custom response file.

    Follow the instructions to create a response file using the download a response file template option as described in Option 1: Download a response file template to create a response file.

    The response file template contains agent parameters, including the service plug-in parameter, which is required for deploying a plug-in.

    To deploy a service plug-in as part of the Management Agent installation process, customize the Service.plugin.<plugin_name>.download parameter.

    For example, if you want to deploy the DataSafe plug-in during the agent installation, the parameter value will be: Service.plugin.datasafe.download=true

    For more information about agent parameters supported in the response file, see Review Agent Parameters.

  4. Install the Management Agent as described in Install Management Agent to complete the installation.

Post Deployment Tasks

After deploying a service plug-in, you can do the following:

Check Service Plug-in Status

  • On the Agent Details page, go to Agent information and click the Service Plug-in link.

  • The Service Plug-ins pane is displayed with the following information: Name, Status and Message.

    If the Management Agent has more than one service plug-in deployed, information of all service plug-ins is displayed.

If the deployment is successful, you can see Running under Status.

If the deployment has issues, you can see Failed under Status with an error description under Message.

Check Work Request Status

When a service plug-in is being deployed, a work request is generated to track the deployment process.

To check the work request status, do the following:

  • On the Agent Details page, go to Agent information and click the Work request link.

  • The Work Requests pane is displayed with the following information: Id, Operation Type, Plugin Name, Status and Time Accepted.

    It shows all the work requests for the last 30 days.

If the deployment is successful, the work request shows Succeeded under Status.

If the deployment has issues, the work request shows Failed under Status . You can use the Id information for troubleshooting.

Enable Agent Logs

The Enable Agent Logs option allows you to enable continuous collection of the agent logs to the Logging Analytics service.

This feature onboards the selected agent with Logging Analytics, and enables automatic upload of the agent's log files to Logging Analytics. For information about Log Analytics OCI service, see Logging Analytics.

Prerequisites

  • The status of the selected agent is Active.
  • Tenancy has to be onboarded to Logging Analytics service.
  • Logging Analytics plugin has to be deployed to the selected agent.

Enable Agent Logs

To enable logs, do the following:

  • From the Agents list page, click on the desired agent.

    The Agent details page is displayed.

  • Click Enable Agent Logs.

    The Enable logs: Agent window for the selected agent is displayed.

  • Select a Log Group Compartment from the dropdown list.
  • Select a Log Group from the dropdown list.

    If you want to create a new Log group, click Create Log Group.

    At the Create Log Group window, enter the Log Group Name and a Description. After, click Create.

  • Click Enable.

Troubleshooting:

  • For each agent, there is a corresponding entity (resource) that gets created in Logging Analytics. If no matching entity is found for the selected agent, logging cannot be enabled. To enable logs in this case, retry after sometime or manually add the agent as an entity in Logging Analytics. For information, see Create an Entity to Represent Your Log-Emitting Resource from Logging Analytics.

Verify Agent Logs Source Association

Once the logs are enabled, the association can be viewed in Logging Analytics.
  • Navigate to Observability & Management and go to Logging Analytics.
  • On the Logging Analytics page, go to Administration.

    From the left menu, select Sources.

    From the center pane, select Oracle Management Agent Logs and verify the agent is listed under the Associated Entities list.

Logs are only enabled with the selected log group in Agent Details page.

To setup purge policy of the log data, see Purge Log Data from Logging Analytics.

Disable Agent Logs

Disabling agent logs stops the continuous upload of logs of the selected agent to Logging Analytics.

To disable logs, do the following:
  • Click Disable Agent Logs.

    The disable agent logs window for the selected agent is displayed.

  • Click Disable.

Manage DataSources

Manage DataSources allows you to view or edit the properties and dimensions of the datasources configured with the selected agent, such as the Prometheus datasource.

Prometheus DataSource Prerequisites:
  • The Management Agent was deployed using Management Agent version 231231.0001 or higher.
  • For Prometheus Exporter, the Management Agent should be on the same virtual machine (VM) or on a VM with access to the Node Exporter's endpoint. This Management Agent is configured to scrape metrics from the running Prometheus Node Exporter.
To manage datasources, do the following:

  • From the Agents list page, click on the desired agent.

    The Agent details page is displayed.

  • Click Manage DataSources.

    The DataSources window displays a table with the following columns:
    • Name: Name of the datasource.
    • Type: Type of the datasource. For example: Prometheus.
    • State: Status of the datasource.
    • Time Created: Timestamp when the datasource was created.
    • Action Item : Shows more actions available for a specific datasource.
  • If you click on a specific datasource name, the View DataSource window is displayed.

    Use the View DataSource to display all the information about a datasource.

    For example: You can view the metric data from Prometheus Exporter.

  • Use Add DataSource to add a datasource.
    • Select the DataSource type from the dropdown list. For example: Prometheus.
    • Use Name to enter the new datasource name.
    • Select Metric compartment from the dropdown list.
    • Enter Metric namespace.
    • Enter URL which Prometheus Exporter uses to publish its metrics.
    • Use the Custom metric dimensions to add a metric dimension.
    • Use Optional properties if needed.
  • Delete DataSource: Use the action menu Action Item to delete a datasource.
  • Edit DataSource: Use the action menu Action Item to edit properties a datasource.

    For example, you can modify the Prometheus exporter URL which publishes the metric data to OCI Monitoring service.

Note

For Prometheus Exporter, you must create policies. For details, see Configure Management Agent to Collect Metrics using Prometheus Node Exporter.

Control Management Agents

One of the administration tasks is to control the state of the Management Agents. You can start, stop and verify the status of the Management Agents.

Start Agents

To start the agent service, do the following:

On Linux:

  1. Login as a user with sudo permissions.

  2. Run the following command:

    For Oracle Linux 6: sudo /sbin/initctl start mgmt_agent

    For Oracle Linux 7: sudo systemctl start mgmt_agent

On Windows:

  1. Login as an Administrator user and open a Command Prompt window.

  2. Run the following command: net start mgmt_agent

On Solaris:

  1. Login as a user with sudo permissions to execute commands as the root user.

  2. Run the following command:

    sudo /etc/init.d/mgmt_agent start

Stop Agents

To stop the agent service, do the following:

On Linux:

  1. Login as a user with sudo permissions.

  2. Run the following command:

    For Oracle Linux 6: sudo /sbin/initctl stop mgmt_agent

    For Oracle Linux 7: sudo systemctl stop mgmt_agent

On Windows:

  1. Login as an Administrator user and open a Command Prompt window.

  2. Run the following command: net stop mgmt_agent

On Solaris:

  1. Login as a user that has sudo privilege to execute commands as root user.

  2. Run the following command:

    sudo /etc/init.d/mgmt_agent stop

Verify Agents

To verify the agent status, do the following:

On Linux:

  1. Login as a user with sudo permissions.

  2. Run the following command:

    For Oracle Linux 6: sudo /sbin/initctl status mgmt_agent

    For Oracle Linux 7: sudo systemctl status mgmt_agent

    For more details, check the log file: /opt/oracle/mgmt_agent/agent_inst/log/mgmt_agent.log.

On Windows:

  1. Login as an Administrator user and open a Command Prompt window.

  2. Run the following command: sc query mgmt_agent

    For more details, check the log file: C:\Oracle\mgmt_agent\agent_inst\log\mgmt_agent.log.

On Solaris:

  1. Login as a user that has sudo privilege to execute commands as root user.

  2. Run the following command: sudo /etc/init.d/mgmt_agent status

    For more details, check the log file: /opt/oracle/mgmt_agent/agent_inst/log/mgmt_agent.log.

Manage Install Keys

Create Install Key

You need to create an install key before performing the Management Agent installation.

An install key is issued against your identity domain and validates the authenticity of the installation. Ensure you have it created before starting the Management Agent installation process.

To create a key:

  1. On the Management Agents home page, click Download and Keys from the left menu to view the Install Keys pane.

    The Install Keys pane is displayed at the bottom of the page.

  2. On the Install Keys pane, click Create Key to create a key.

  3. Enter the required details in the Create Key window.

    1. In the Key Name field, specify a name to identify the key.

    2. In the Compartment field, select the compartment from the drop-down list. This is the compartment where the agent resource will be created.

    3. In the Maximum Installs field, specify a number that indicates the maximum number of installs that can be associated with the key. Default value is 1000.

    4. In the Valid for field, specify a number that indicates the period the key is valid for. Default value is 1 Week.

    5. The Unlimited checkbox is optional.

      If it's selected, the key can be used for an unlimited number of agent and gateway installations and the key never expires.

      Risks of using unlimited keys: Oracle recommends to keep the life time of an Install Key to a minimum required time and limited number of agents. Ensure that you keep the downloaded key in a secure location to protect confidentiality. If the unlimited install key is compromised, an attacker can install rogue agents in your tenancy. A regular audit of your tenancy's agents can help to mitigate any potential risks associated with unlimited install keys. When an unlimited install key is not needed anymore, make sure to delete it either using the Management Agents Console or CLI.

    Create Key dialog box.

    A new key is created.

The Install Keys pane offers different options available to manage the keys. During a later step, the Download Key to File option is useful to download a file that can be used as a response file template as described in Configure a Response File.

For more information about managing the install keys, see Manage Install Keys.

Note

If you are installing a Management Gateway, you can use the same install key to install Management Gateway and Management Agent. For information about Management Gateway, see Management Gateway.

Copy Install Key

You can copy an install key to clipboard from the Install Keys pane.

  1. On the Management Agents home page, click Download and Keys from the left menu to view the Install Keys pane.

    The Install Keys pane is displayed.

  2. From the list of install keys, select the key that you want to copy to clipboard.
  3. On the right side of the selected key, click the action menu Action Menu and select Copy Key to Clipboard.

    Install Keys list that shows the Copy Key to Clipboard option from the action menu list.

    The key is copied to clipboard.

The Copy Key to Clipboard option is useful to copy and paste the value of the key when creating the response file during the agent configuration process. For more details, see Create a Response File.

Download Install Key

You can download an install key from the Install Keys pane.

  1. On the Management Agents home page, click Download and Keys from the left menu to view the Install Keys pane.

    The Install Keys pane is displayed listing all the existing keys.

  2. From the list of install keys, select the key that you want to download.
  3. On the right side of the selected key, click the action menu Action Menu and select Download Key to File.

    Install Keys list that shows the Download Key to File option from action menu list.

    A file is downloaded.

The Download Key to File option is useful to download a file with the agent parameters that can be used as a response file during the agent installation process. For more details, see Create a Response File.

Delete Install Key

You can delete an install key from the Install Keys pane.

  1. On the Management Agents home page, click Download and Keys from the left menu to open the Install Keys pane.

    The Install Keys pane is displayed listing all the existing keys.

  2. From the list of install keys, select the key that you want to delete.

  3. On the right side of the selected key, click on the action menu Action Menu and select Delete Key.

    Install Keys list that shows the Delete Key option from the action menu list.

  4. Click on Delete Key.
  5. Press Delete to confirm the operation.

The Delete Key option is useful when you suspect that an unauthorized user has obtained the value of an agent install key.

Upgrade Management Agents

There are two methods available for upgrading the Management Agents:

Automatic Upgrade

Management Agents service supports automatic upgrade.

Enabling the auto upgrade feature is done at the tenancy level: Users can enable auto upgrade for all management agents residing in their current tenancy.

Requirements:

  • Permission: The MGMT_AGENT_UPDATE permission at the tenancy root compartment is required to enable auto upgrade feature. Use the following policy syntax: 

    ALLOW GROUP <group_name> TO USE management-agents IN TENANCY

    For information about Management Agent polices, see Details for Management Agent.

  • Minimum Management Agent Version: 210918.1427 or higher.

Default Auto Upgrade Status: Disable.

Topics

Enable Auto Upgrade

You can enable auto upgrade using the Management Agents console.

  • On the Management Agents home page, click Downloads and Keys from the left menu.

    The Agent Auto Upgrade pane is displayed at the top of the page.

    Enable Auto Upgrade

  • On the Agent Auto Upgrade pane, click Enable Auto Upgrade.

    The Enable Auto Upgrade window is displayed.

  • On the Enable Auto Upgrade window, click OK to enable auto upgrade for all management agents in the current tenancy

Disable Auto Upgrade

You can disable auto upgrade using the Management Agents console.

  • On the Management Agents home page, click Downloads and Keys from the left menu.

    The Agent Auto Upgrade pane is displayed at the top of the page.

    Disable Auto Upgrade

  • On the Agent Auto Upgrade pane, click Disable Auto Upgrade.

    The Disable Auto Upgrade window is displayed.

  • On the Disable Auto Upgrade window, click OK to disable auto upgrade for all management agents in the current tenancy.

For a list of available CLI commands to enable and disable auto upgrade, see Oracle Cloud Infrastructure CLI Command Reference.

Manual Upgrade

Management Agent supports manual upgrade for the following operating systems:

Linux Manual Upgrade (RPM file)

To upgrade an agent on Linux using an RPM file, do the following:
  • Download the latest version of the RPM file containing the agent software download file. See Download the Agent Software.
  • To upgrade the agent, run the rpm command with the rpm -U upgrade option:
    sudo rpm -U <rpm_file_name.rpm>

Linux Manual Upgrade (ZIP file)

To upgrade an agent on Linux using a ZIP file, do the following:
  • Download the latest version of the ZIP file containing the agent software download file. See Download the Agent Software.
  • Navigate to the directory where you have downloaded the management agent software ZIP file and unzip it to any preferred location.
  • To upgrade the agent, run the installer.sh script with the -u option: 
    installer.sh -u
    The output looks similar to the following: 
    sudo ./installer.sh -u 
Checking pre-requisites
    Checking available disk space for agent upgrade    
    Checking agent version

Executing install
    Unpacking software zip
    Copying files to destination dir (/opt/oracle/mgmt_agent)
    Updating communication wallet
    Creating 'mgmt_agent' daemon
    Starting mgmt_agent
    Agent Install Logs: /opt/oracle/mgmt_agent/installer-logs/installer.log.0

Agent upgrade successful

Windows Manual Upgrade

To upgrade an agent on Windows, do the following:
  • Login as an Administrator user and open a command prompt window.
  • Download the latest version of the ZIP file containing the agent software download file. See Download the Agent Software.
  • Navigate to the directory where you have downloaded the management agent software ZIP file and unzip it to any preferred location.
  • To upgrade the agent, run the installer.bat script with the -u option: installer.bat -u.
    The output looks similar to the following: 
    C:\Users\test_agent>installer.bat -u 
Checking pre-requisites

     Checking if C:\Oracle\mgmt_agent\200821.0751 directory exists 
     Checking available disk space for agent install
     Checking Java version
              Java version: 1.8.0_261 found at C:\Program Files\Java\jdk1.8.0_261

Executing Upgrade
        Unpacking software zip
        Copying files to destination dir(C:\Oracle\mgmt_agent)
        Initializing software from template
        Creating mgmt_agent service

Agent Upgrade  successful

Solaris Manual Upgrade

To upgrade an agent on Solaris, do the following:
  • Download the latest version of the ZIP file containing the agent software download file. See Download the Agent Software.
  • Navigate to the directory where you have downloaded the management agent software ZIP file and unzip it to any preferred location.
  • To upgrade the agent, login as root user and run the installer.sh script with the -u option: 
    installer.sh -u
    The output looks similar to the following: 
    sudo ./installer.sh -u 
Checking pre-requisites
    Checking available disk space for agent upgrade    
    Checking agent version

Executing install
    Unpacking software zip
    Copying files to destination dir (/opt/oracle/mgmt_agent)
    Updating communication wallet
    Creating 'mgmt_agent' daemon
    Starting mgmt_agent
    Agent Install Logs: /opt/oracle/mgmt_agent/installer-logs/installer.log.0

Agent upgrade successful

AIX Manual Upgrade (ZIP file)

To upgrade an agent on AIX using a ZIP file, do the following:
  • Download the latest version of the ZIP file containing the agent software download file. See Download the Agent Software.
  • Navigate to the directory where you have downloaded the management agent software ZIP file and unzip it to any preferred location.
  • To upgrade the agent, run the installer.sh script with the -u option: 
    installer.sh -u
    The output looks similar to the following: 
    sudo ./installer.sh -u 
Checking pre-requisites
        Checking available disk space for agent upgrade
        Checking agent version

Executing install
        Unpacking software zip
        Copying files to destination dir (/opt/oracle/mgmt_agent)
        Updating communication wallet
        Creating mgmt_agent daemon
        Starting mgmt_agent
        Agent Install Logs: /opt/oracle/mgmt_agent/installer-logs/installer.log.0

Agent upgrade successful

Remove Management Agents

When removing a management agent associated with a host, the management agent is unregistered from Management Agents Cloud Service before it’s removed from the host.

You can remove an agent from a host for the following reasons:
  • An agent deployed on the target host is no longer necessary.
  • You no longer need to collect data, performance metrics or logs from a specific target host.
  • You modified your deployment topology.

This topic explains how to remove Management Agents.

Remove Agents from User Interface

To remove agents from the user interface, do the following:

  1. Select the agent from the Agents list and click on the Action Menu.

    Figure 4-1 Delete Agent

    Agents list page that shows the Delete Agent option from action menu list.

  2. Click on Delete Agent.

  3. Press Delete to confirm the selection.

The agent will get removed from Management Agent user interface, but the agent software won't get deleted from the target host. Users are required to connect to the host and manually remove the agent software from the host. For Linux, use the rpm command with -e option.

Remove Agents from Command Line Interface

When removing an agent from the command line interface, the agent and the agent software will be removed from the host.

Remove (uninstall) Management Agent from the following operating systems:

Linux using RPM command

Execute the rpm command with the -e option.
sudo rpm -e <rpm_name>

Linux using uninstaller script

Execute the uninstaller.sh script if you installed the agent using the ZIP files.

The output looks similar to the following:

$ sudo bash /opt/oracle/mgmt_agent/agent_inst/bin/uninstaller.sh
Executing pre-remove step from uninstall
Attempting to remove the agent from Management Agent Cloud service, please do not interrupt...
Attempting to remove the agent from Management Agent Cloud service, please do not interrupt...
Agent was removed from Management Agent Cloud service successfully.
Detected Oracle Linux Server (Red Hat family):
Stopping mgmt_agent...
Removing mgmt_agent daemon from systemd...
Removed symlink/etc/systemd/system/multi-user.target.wants/mgmt_agent.service.
Agent was removed from the host successfully.
Executing post-remove step from uninstall
Agent state directory was removed from the host successfully.
Note

If you installed the Management Agent using an external volume on Linux, the Management Agent uninstaller script removes all the data under the /opt/oracle/mgmt_agent directory, and in some operating systems, it also removes the target directory the symlink points to.

Windows

Open a Command Prompt window, navigate to the agent install base directory and execute the uninstaller.bat script.

The output looks similar to the following: 
C:\Oracle>mgmt_agent\uninstaller.bat
Removing agent from Management Agent Cloud Service
Attempting to remove the agent from Management Agent Cloud service, please do not interrupt...
Agent was removed from Management Agent Cloud service successfully.
Removing agent service from the host
Agent service was removed from the host successfully
Removing agent directories

Ensure that all other command prompt windows are closed or that they are not pointing to the agent home directory before running the uninstaller.bat script.

Solaris

Execute the uninstaller.sh script as root user.

The output looks similar to the following: 

sudo bash /opt/oracle/mgmt_agent/agent_inst/bin/uninstaller.sh
Executing pre-remove step from uninstall
Attempting to remove the agent from Management Agent Cloud service, please do not interrupt...
Attempting to remove the agent from Management Agent Cloud service, please do not interrupt...
Agent was removed from Management Agent Cloud service successfully.
Detected Oracle Linux Server (Red Hat family):
Stopping mgmt_agent...
Removing mgmt_agent daemon from systemd...
Removed symlink /etc/systemd/system/multi-user.target.wants/mgmt_agent.service.
Agent was removed from the host successfully.
Executing post-remove step from uninstall
Agent state directory was removed from the host successfully.

AIX

Execute the uninstaller.sh script as root user.

The output looks similar to the following: 

sudo sh /opt/oracle/mgmt_agent/agent_inst/bin/uninstaller.sh
Executing pre-remove step from uninstall
Attempting to remove the Agent from Management Agent Cloud service, please do not interrupt...
Attempting to remove the Agent from Management Agent Cloud service, please do not interrupt...
Agent was removed from Management Agent Cloud service successfully.
Detected AIX:
Stopping mgmt_agent...
Waiting for mgmt_agent to exit...
Stopped mgmt_agent.
Removing mgmt_agent daemon...
0513-083 Subsystem has been Deleted.
Agent was removed from the host successfully.
Executing post-remove step from uninstall
Agent state directory was removed from the host successfully.

Use a Non-default OS User to Install Management Agent

Oracle recommends to perform the Management Agent installation using the default OS user: mgmt_agent, but depending on your requirements, you may need to perform the installation using a different OS user.

This section describes how to install the Management Agent using a different user from mgmt_agent, the default OS user.

Prerequisites

Note

When choosing an OS user other than mgmt_agent to perform the Management Agent installation on Linux or Unix systems, the following considerations need to be taken:

  • Select an OS user with limited privileges.

    The default mgmt_agent OS user is a least privilege OS user with no login shell. If you decide to select another OS user instead, ensure the chosen user has limited privileges.

  • Management Agent is a multi-threaded application and each thread (LWP) counts towards the OS user limit. Ensure that the user limit (ulimit) for max user processes is set accordingly by checking:
    ulimit -u

    Choosing an inadequate limit can result in instability of the Management Agent and applications running as the OS user selected.

  1. Identify a valid OS user to perform the Management Agent installation and use it as value for the RUN_AGENT_AS_USER variable.
    Oracle recommends that the selected OS user should have least privileges and no login shell.
    id -un <username>

    Example 1:

    id -un myexistinguser
    The myexistinguser OS user exists. The output returns the value of the selected user and looks similar to the following:
    myexistinguser
    Example 2:
    id -un mytestuser2
    The mytestuser2 OS user doesn't exist and it's not a valid user. The output returns no user value and looks similar to the following:.
    id: mytestuser2: no such user
  2. Identify the user's primary group to use as value for the AGENT_USER_GROUP variable.
    Ensure the value for AGENT_USER_GROUP is the primary user group of the selected OS user.
    Note

    Using a secondary group is not supported and it can result in a corruption of the Management Agent. 
    id -gn <username>
    Example:
    id -gn myexistinguser
    The output looks similar to the following:
    staff

Set Environment Variables and Install Management Agent

  1. Set the following environment variables:
    RUN_AGENT_AS_USER=<selected_OS_user_for_ManagementAgent_installation>
AGENT_USER_GROUP=<OS_primary_group_of_selected_OS_user>
    Example:
    RUN_AGENT_AS_USER=myexistinguser
AGENT_USER_GROUP=staff
  2. Ensure the above environment variable are accessible by the root OS user.

    By default, the environment variables are not shared with the root user.

  3. Verify the environment variables are set properly by running the following:
    sudo su
echo $RUN_AGENT_AS_USER
echo $AGENT_USER_GROUP
    For example, the output looks like the following:
    myexistinguser
staff
    If root is unable to access the environment variables, edit /etc/sudoers file and add the following:
    Defaults env_keep+=RUN_AGENT_AS_USER
Defaults env_keep+=AGENT_USER_GROUP

    The above ensures the RUN_AGENT_AS_USER and AGENT_USER_GROUP environment variables are preserved and accessible by the root user.

    After updating the /etc/sudoers file, set the environment variables again and verify root can access the environment variables.

  4. Once verification is complete, you can start the Management Agent installation: Log in as root, set the environment variables, and start the Management Agent installation.

    Depending on your preferred method, you can follow the instructions from Install Management Agent on Linux (RPM file) or Install Management Agent on Linux (ZIP file).

    For example, follow the instructions from Install Management Agent on Linux (RPM file). In this case, skip step 1 since you are already root and there's no need of sudo privileges. Start at step 2: rpm -ivh <rpm_file_name.rpm>

Management Agent Source Credentials

This section describes how to manage source credentials which may be needed to allow the Management Agent to collect data from certain data sources.

After deploying plug-ins on a Management Agent, you may need to configure source credentials to allow the agent to collect data from different sources.

Each source of data manages credentials in a different way. Configuring source credentials is specific to the type of plug-in or service that was deployed on the agent. Refer to the plug-in or service documentation for more information.

Credential Types

The agent's credential store can store credentials that are known and understood by the agent (for example, Oracle Database credentials), as well as credentials which are only understood by the specific service. The agent validates built-in credential types, but it also accepts other free-form types without any validation.

Free-Form Credentials

A user can define credentials of any type, containing one or more sensitive properties. Since they are free-form, they cannot be classified.

For example:

SSHKeyCreds

SSH RSA key credentials where SSH key credentials are needed by the agent.

This is an example of how the credentials might look. SSHUserName, SSHPrivateKey and SSHPublicKey are case-sensitive properties. 

{"source":"<DATA_SOURCE_NAME>", 
"name":"OSCreds", 
"type":"SSHKeyCreds", 
"description":"<DESCRIPTION>", 
"properties":[
{"name":"SSHUserName","value":"<USER_NAME>"},               
{"name":"SSHPrivateKey","value":"<RSA_PRIVATE_KEY>"},
{"name":"SSHPublicKey","value":"<PUBLIC KEY>"]}

For example:

{"source":"host.myvm.example.com", 
"name":"OSCreds", 
"type":"SSHKeyCreds", 
"description":"SSH keys for a twoods user", 
"properties":[
{"name":"SSHUserName","value":"twoods"},               
{"name":"SSHPrivateKey","value":"-----BEGIN RSA PRIVATE KEY-----\nMIICXQIBAAKBgQCKWjoLfOKsjglGQcKwB0zm1o/OabClELjcOOTS1FJh6pzvrDeL\nn3IfIW9VUiyfGNkjnj4cuO0mVctaQgGVtT6H+4fL8HKjWqPg9S+uc0WBKBzaLi9H\nAoGACZctlORIVkvWSr9+PnOTGiFfgKCE9TxOhD2RZyf+ufjofhjDFPOtlojbzd9P\nZovzaWurxJPxJIon+Y6/y1/wAKUFisOlY2XJl76NKXm/00OGSfocQ3WsxapEsWwR\nalRL0l5FhXVpTV5OH3M4Dy5ksIcDqiV6r\nMejuJ++3AHlflzzoITtmS3RDlpSsd27ZH9vzV9HgFQU3volRgOZqnVm/oGXWwjl7\n-----END RSA PRIVATE KEY-----"},
{"name":"SSHPublicKey","value":"-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCKWjoLfOKsjglGQcKwB0zm1o/O\nabClELjcOOTS1FJh6pzvrDeLn3IfIW9VUiyfQAcfTWRwb0JtzMcRONQIDAQAB\n-----END PUBLIC KEY-----"]}
Built-in Credentials

The agent has several built-in credential types. Any service plug-in can deliver credentials to the agent using one of the following credential types:
Credential Type for Management Gateways and Proxies

ProxyCreds

These credentials are used for authenticating Management Gateway or network proxies.

Prerequisites: The agent should be configured with a Management Gateway or proxy using the following two properties:
  • GatewayServerHost. For example: GatewayServerHost=myproxy.example.com
  • GatewayServerPort. For example: GatewayServerPort=80
The below credentials properties are case-sensitive:
  • ProxyUser: the user name for authentication with the proxy.
  • ProxyPassword: the password used to authenticate the user. 

{"source":"<DATA_SOURCE_NAME>", 
"name":"ManagementAgent-Proxy", 
"type":"ProxyCreds", 
"description":"<DESCRIPTION>", 
"properties":[
{"name":"ProxyUser","value":"<USER_NAME>"},               
{"name":"ProxyPassword","value":"<USER_PASSWORD>"}]}

For example:

{"source":"agent.ocid1.managementagent.oc1.iad.amaabb", 
"name":"ManagementAgent-Proxy", 
"type":"ProxyCreds", 
"description":"Proxy Credentials", 
"properties":[
{"name":"ProxyUser","value":"joe"},               
{"name":"ProxyPassword","value":"welcome_1"}]}
Note

These credentials are used by the agent for communicating with Oracle Cloud Infrastructure services. Changing its format or removing the credential can have an adverse effect on the agent's ability to communicate back to Oracle Cloud Infrastructure services.

Credential Type for Databases

DBCreds

These credentials are used for authenticating to an Oracle database using TCP protocol.

The below properties are case-sensitive:
  • DBUserName: the database user name.
  • DBPassword: the database user's password.
  • DBRole: the database user's role. It can be: SYSDBA, SYSOPER, NORMAL. If it's not specified, NORMAL will be used. 
{"source":"<DATA_SOURCE_NAME>", 
"name":"SQLCreds", 
"type":"DBCreds", 
"description":"<DESCRIPTION>", 
"properties":[
{"name":"DBUserName","value":"<DB_USER_NAME>"},               
{"name":"DBPassword","value":"<DB_USER_PASSWORD>"},               
{"name":"DBRole","value":"<DB_ROLE>"}]}

For example:

{"source":"auditvault_db.myhost", 
"name":"SQLCreds", 
"type":"DBCreds", 
"description":"This is a credential that can be used for operations on DATASAFE databases.", 
"properties":[
{"name":"DBUserName","value":"sys"},               
{"name":"DBPassword","value":"sys"},               
{"name":"DBRole","value":"SYSDBA"}]}

DBANOCreds

These credentials are used for authenticating to an Oracle database using TCP protocol.

The below properties are case-sensitive:
  • DBUserName: the database user name.
  • DBPassword: the database user's password.
  • DBRole: the database user's role. It can be: SYSDBA, SYSOPER, NORMAL. If it's not specified, NORMAL will be used.
  • DBEncryptionTypes: the parenthesized, comma-separated list of encryption algorithms.
  • DBEncryptionLevel: the level of encryption specified by the client. It can be: REJECTED, ACCEPTED, REQUESTED, REQUIRED. If it's not specified, ANO services' default will be used.
  • DBChecksumTypes: the parenthesized, comma-separated list of checksum algorithms.
  • DBChecksumLevel: the level of integrity specified by the client (REJECTED, ACCEPTED, REQUESTED, REQUIRED). If it's not specified, ANO services' default will be used. 
{"source":"<DATA_SOURCE_NAME>", 
"name":"SQLCreds", 
"type":"DBANOCreds", 
"description":"<DESCRIPTION>", 
"properties":[
{"name":"DBUserName","value":"<DB_USER_NAME>"},               
{"name":"DBPassword","value":"<DB_USER_PASSWORD>"},               
{"name":"DBRole","value":"<DB_ROLE>"},               
{"name":"DBEncryptionTypes","value":"<DB_ENCRYPTION_TYPE>"},               
{"name":"DBEncryptionLevel","value":"<DB_ENCRYPTION_LEVEL>"},               
{"name":"DBChecksumTypes","value":"<DB_CHECKSUM_TYPE>"},               
{"name":"DBChecksumLevel","value":"<DB_CHECKSUM_LEVEL>"}]}

For example:

{"source":"auditvault_db.myhost", 
"name":"SQLCreds", 
"type":"DBANOCreds", 
"description":"This is a credential that can be used for operations on DATASAFE databases.", 
"properties":[
{"name":"DBUserName","value":"sys"},               
{"name":"DBPassword","value":"sys"},               
{"name":"DBRole","value":"SYSDBA"},               
{"name":"DBEncryptionTypes","value":"(AES256,AES192,AES128,3DES168,3DES112)"},               
{"name":"DBEncryptionLevel","value":"REQUIRED"},               
{"name":"DBChecksumTypes","value":"(SHA2)"},               
{"name":"DBChecksumLevel","value":"REQUESTED"}]}

DBTCPSCreds

These credentials are used for authenticating using TCPS.

The below properties are case-sensitive:
  • DBUserName: the database user name.
  • DBPassword: the database user's password.
  • DBRole: the database user's role. It can be: SYSDBA, SYSOPER, NORMAL. If it's not specified, NORMAL will be used.
  • ssl_trustStoreType: the type of the trust store.
  • ssl_trustStoreLocation: the location on the file system of the trust store wallet. It must be accessible to the agent user.
  • ssl_trustStorePassword: the password for the trust store wallet.
  • ssl_keyStoreType: the type of the key store.
  • ssl_keyStoreLocation: the location on the file system of the key store wallet. It must be accessible to the agent user.
  • ssl_keyStorePassword: the password for the key store wallet.
  • ssl_server_cert_dn: the domain name of the server cert.
    Note

    Starting with Management Agent version: 230207.1529 (February 2023), the ssl_server_cert_dn property is optional. (For example: {"name":"ssl_server_cert_dn","value":"<SERVER_CERT_DN>"}).

    If the server wallet contains a value for it, then the user can provide it in the credentials. If it is absent in the wallet, then the user doesn't have to provide it in the credentials at all.

    For earlier versions, the management agent expects the credentials to contain this property. However, to indicate that there is no value for ssl_server_cert_dn, the user needs to specify the "unknownDn” value. 

{"source":"<DATA_SOURCE_NAME>", 
"name":"SQLCreds", 
"type":"DBTCPSCreds", 
"description":"<DESCRIPTION>", 
"properties":[
{"name":"DBUserName","value":"<DB_USER_NAME>"},               
{"name":"DBPassword","value":"<DB_USER_PASSWORD>"},               
{"name":"ssl_trustStoreType","value":"<STORE_TYPE>"},               
{"name":"ssl_trustStoreLocation","value":"<STORE_LOCATION>"},               
{"name":"ssl_trustStorePassword","value":"<STORE_PASSWORD>"},               
{"name":"ssl_keyStoreType","value":"<KEY_STORE_TYPE>"},               
{"name":"ssl_keyStoreLocation","value":"<KEY_STORE_LOCATION>"},               
{"name":"ssl_keyStorePassword","value":"<KEY_STORE_PASSWORD>"},               
{"name":"ssl_server_cert_dn","value":"<SERVER_CERT_DN>"}]}

For example:

{"source":"auditvault_db.myhost_pdb1_regress", 
"name":"SQLCreds", 
"type":"DBTCPSCreds", 
"description":"This is a TCPS credential that can be used for operations on DATASAFE databases.", 
"properties":[
{"name":"DBUserName","value":"C#AUDIT"},               
{"name":"DBPassword","value":"welcome_1"},               
{"name":"ssl_trustStoreType","value":"JKS"},               
{"name":"ssl_trustStoreLocation","value":"/home/jks_wallets/ewalletT.jks"},               
{"name":"ssl_trustStorePassword","value":"welcome_1"},               
{"name":"ssl_keyStoreType","value":"JKS"},               
{"name":"ssl_keyStoreLocation","value":"/home/jks_wallets/ewalletK.jks"},               
{"name":"ssl_keyStorePassword","value":"welcome_1"},               
{"name":"ssl_server_cert_dn","value":"CN=myvm.example.com"}]}

Add or Update Credentials

To add credentials or update existing ones, use the credential_mgmt.sh script with the upsertCredentials operation.

The credential_mgmt.sh script is located in the /opt/oracle/mgmt_agent/agent_inst/bin directory.

Syntax

credential_mgmt.sh -o upsertCredentials -s [service-name]
Note

For Management Agents running on compute instances using the Oracle Cloud Agent plugin, the credential_mgmt.sh script location is under /var/lib/oracle-cloud-agent/plugins/oci-managementagent/polaris/agent_inst/bin.

  1. Create a JSON file with the credential information.

    The below example is a credential type format for a datasafe_db source named orcl123:

    {"source":"datasafe_db.orcl123", 
"name":"audit_cred", 
"description":"This is the audit credential for orcl123 Oracle RDBMS system.", 
"properties":[ 
{"name":"username","value":"CLEAR[scott]"}, 
{"name":"password","value":"CLEAR[tiger]"}]
}

    For example, you can save the file as my_credentials.json.

  2. Add credentials using a JSON file.

    credential_mgmt.sh -o upsertCredentials -s [service-name]

    For example, you can run the following for DataSafe service using my_credentials.json file: 

    cat my_credentials.json | sudo -u mgmt_agent /opt/oracle/mgmt_agent/agent_inst/bin/credential_mgmt.sh -o upsertCredentials -s datasafe

  3. Delete JSON file created in step 1.

    The credential JSON file contains sensitive information. Customers are responsible for deleting the credential JSON file after completing the add or update credential operation.

Delete Credentials

To delete credentials, use the credential_mgmt.sh script with the deleteCredentials operation.

The credential_mgmt.sh script is located in the /opt/oracle/mgmt_agent/agent_inst/bin directory.

Syntax

credential_mgmt.sh -o deleteCredentials -s [service-name]

  1. Create a JSON file using the following format: 

    {"source":"datasafe_db.orcl123"
 "name":"audit_cred"}

    For example, you can save the file as my_credentials.json.

  2. Delete credentials using a JSON file.

    credential_mgmt.sh -o deleteCredentials -s [service-name]

    For example, you can run the following for DataSafe service using my_credentials.json file: 

    cat my_credentials.json | sudo -u mgmt_agent /opt/oracle/mgmt_agent/agent_inst/bin/credential_mgmt.sh -o deleteCredentials -s datasafe

  3. Delete JSON file created in step 1.

    The credential JSON file contains sensitive information. Customers are responsible for deleting the credential JSON file after completing the delete credential operation.

Add or Update Credential Alias

To add a credential alias or update an existing one, use the credential_mgmt.sh script with the aliasCredentials operation.

The credential_mgmt.sh script is located in the /opt/oracle/mgmt_agent/agent_inst/bin directory.

Syntax

credential_mgmt.sh -o aliasCredentials -s [service-name]

  1. Create a JSON file using the following format: 

    {"alias":
 {"source":"datasafe_db.orcl123",
  "name":"audit_cred"},
 "credential":
  {"source":"datasafe_db.host.1521.orcl123",
   "name":"datasafe_cred"}}

    For example, you can save the file as my_credentials.json.

  2. Add a credential alias using a JSON file.

    credential_mgmt.sh -o aliasCredentials -s [service-name]

    For example, you can run the following for DataSafe service using my_credentials.json file: 

    cat my_credentials.json | sudo -u mgmt_agent /opt/oracle/mgmt_agent/agent_inst/bin/credential_mgmt.sh -o aliasCredentials -s datasafe

  3. Delete JSON file created in step 1.

    The credential JSON file contains sensitive information. Customers are responsible for deleting the credential JSON file after completing the add or update credential alias operation.

Delete Credential Alias

To delete a credential alias, use the credential_mgmt.sh script with the unaliasCredentials operation.

The credential_mgmt.sh script is located in the /opt/oracle/mgmt_agent/agent_inst/bin directory.

Syntax

credential_mgmt.sh -o unaliasCredentials -s [service-name]

  1. Create a JSON file using the following format: 

    {"source":"datasafe_db.orcl123",
 "name":"audit_cred"}

    For example, you can save the file as my_credentials.json.

  2. Delete a credential alias using a JSON file.

    credential_mgmt.sh -o unaliasCredentials -s [service-name]

    For example, you can run the following for DataSafe service using my_credentials.json file: 

    cat my_credentials.json | sudo -u mgmt_agent /opt/oracle/mgmt_agent/agent_inst/bin/credential_mgmt.sh -o unaliasCredentials -s datasafe

  3. Delete JSON file created in step 1.

    The credential JSON file contains sensitive information. Customers are responsible for deleting the credential JSON file after completing the delete credential alias operation.

Management Agent Audit Logs

The Management Agent service supports logging by the Audit service. This service automatically records calls to all supported Oracle Cloud Infrastructure public application programming interface (API) endpoints as log events.

Management Agents Auditing

The Management Agent service supports the management-agent keyword from the Audit service.

You can use the OCI Console to view the log events for the Management Agents service.

  • Open the navigation menu. Under Governance and Administration, go to Governance and click Audit.

    The Audit service is displayed.

To search for the Management Agents log events, select the desired compartment and enter management-agent under the KEYWORDS field.

For more information about Audit service, see Overview of Audit in the Oracle Cloud Infrastructure documentation.

Using Java with Management Agent

Management Agent requires a Java Runtime Environment (JRE) to be pre-installed in any environment where the Management Agent is being deployed. For information about Management Agent prerequisites, see Generic Prerequisites for Deploying Management Agents.

JRE is used to run Management Agent. Oracle recommends to upgrade to the latest JRE version available as new updates become available with bug fixes and security patches.

This section explains how to upgrade JRE for the Management Agent.

Upgrade JRE on Linux

These instructions describe how to upgrade JRE on Linux 64-bit platforms, including the following: Oracle Linux, CentOS, Ubuntu and SUSE Linux.

Upgrade JRE Using RPM Package

This is the preferred upgrade method. It installs the latest JRE version in the appropriate location.

To upgrade JRE using the RPM package file found on the Java download page, do the following:

  1. Download JRE.

    Download the latest JRE version from: https://www.oracle.com/java/technologies/downloads/#java8.

  2. Shutdown the Management Agent. 
    sudo systemctl stop mgmt_agent
  3. Upgrade JRE. 
    sudo rpm -Uvh jre-8u<VERSION>-linux-x64.rpm
  4. Update Java symbolic links.

    Change the system default Java symbolic links to refer to the new JRE location by using the update-alternatives command. 

    sudo update-alternatives --config java

    Alternatively, if the update-alternatives command is not available for your platform, you can change the default Java symbolic links manually

    To update the symbolic links to change the default Java manually, use the following: 

    sudo ln -s <path-to-java_home>/bin/java /usr/bin/java
  5. Verify the JRE upgrade.
    Verify the environment uses the new JRE as default by running the following:
    env -i java -version

    The output looks similar to:

    java version "1.8.0_xxx"
...
  6. Start the Management Agent.
    sudo systemctl start mgmt_agent
  7. Verify the Management Agent is running with the updated JRE.
    grep "java.runtime.version" /opt/oracle/mgmt_agent/agent_inst/log/startup.info

    The output looks similar to:

    java.runtime.version=1.8.0_<VERSION>
Upgrade JRE Using Compressed Archive

To upgrade JRE using the compressed archive (tar file), do the following:

  1. Download latest JRE file.

    Download the latest version from https://www.oracle.com/java/technologies/downloads/#java8.

  2. Shutdown Management Agent. 
    sudo systemctl stop mgmt_agent
  3. Extract the JRE Java compressed file to the Java location.

    In the below example, the Java target location is /usr/lib/jvm/ directory 

    sudo tar -xvfz jre-8u<VERSION>-linux-x64.tar.gz -C /usr/lib/jvm/
  4. Update Java symbolic links.

    Change the system default Java symbolic links to refer to the new JRE location by using the update-alternatives command. 

    # install/register the new java with alternatives
sudo update-alternatives --install "/usr/bin/java" "java" "<path-to-java_home>/bin/java" 1

# set executables as default using update-alternatives command
sudo update-alternatives --set java "<path-to-java_home>/bin/java"

    Alternatively, if the update-alternatives command is not available for your platform, you can change the default Java symbolic links manually.

    To update the symbolic links to change the default Java manually, use the following: 

    sudo ln -s <path-to-java_home>/bin/java /usr/bin/java
  5. Verify the JRE upgrade.
    Verify the environment uses the new JRE as default by running the following:
    env -i java -version

    The output looks similar to:

    java version "1.8.0_xxx"
...
  6. Start the Management Agent.
    sudo systemctl start mgmt_agent
  7. Verify the Management Agent is running with the updated JRE.
    grep "java.runtime.version" /opt/oracle/mgmt_agent/agent_inst/log/startup.info

The output looks similar to:

java.runtime.version=1.8.0_<VERSION>

Upgrade JRE on Windows

This topic explains how to upgrade JRE on supported Windows 64-bit platforms to run Management Agent.

Management Agent installations on Windows environments require to set the environment variable JAVA_HOME prior to the installation. For details, see Update Custom JAVA_HOME for Windows environment to set the JAVA_HOME variable to a location that can be changed in the future.

To upgrade JRE on Windows, do the following:

  1. Download the JRE installer file.

    Download the latest JRE version from https://www.oracle.com/java/technologies/downloads/#java8.

  2. Shutdown the Management Agent. 
    sc stop mgmt_agent
  3. Upgrade JRE.
    • Double-click the installer file downloaded in Step 1 to execute it and follow the interactive instructions provided by the installer.
      If you prefer to perform a silent install, use the following command: 
      # Optional Command Line Silent Install
# Start the installer with silent (/s) switch and store output to jre8-install.log file with log (/L) switch
jre-8u<VERSION>-windows-x64.exe /s /L C:/jre8-install.log

    Alternative: If you prefer not to use the installer file mentioned above, extract the compressed archive file to the desired location.

  4. Update the Junction (Java symbolic links).

    Delete the existing Junction and create a new one, pointing it to the new JRE location.

    rd C:\Oracle\jre8-latest
mklink /J "C:\Oracle\jre8-latest" "C:\Program Files\Java\jre1.8.0_<VERSION>
Junction created for C:\Oracle\jre8-latest <<===>> C:\Program Files\Java\jre1.8.0_<VERSION>
  5. Verify the JRE upgrade.
    Verify the environment uses the new JRE as default by running the following:
    echo %JAVA_HOME%
C:\Oracle\jre8-latest

%JAVA_HOME%/bin/java -version
# output example:
java version "1.8.0_<VERSION>"
...
  6. Start the Management Agent.
    sc start mgmt_agent
  7. Verify the Management Agent is running with the updated JRE.

    Confirm the java.runtime.version setting matches the newly installed JRE. 

    findstr "java.runtime.version" C:\Oracle\mgmt_agent\agent_inst\log\startup.info
java.runtime.version=1.8.0_<VERSION>

Update Custom JAVA_HOME

There are environments that don't have a system default Java location. In those cases, Oracle recommends updating the custom JAVA_HOME location before starting the JRE upgrade process.

When using a custom JAVA_HOME location for the Management Agent installation, upgrading the JRE can cause issues if the Java version is included in the JAVA_HOME path. The solution is to create a symbolic link for the JAVA_HOME path which should make no reference to the JRE version number.

Scenario: The environment has one JRE version, but the JAVA_HOME path has the version number included in the path, even though it points to a different JRE version after an upgrade.

  • Linux Scenario: The environment has JRE version: jre1.8.301 and the JAVA_HOME path is set as JAVA_HOME=/custom/jre1.8.301. When upgrading to a new JRE version, for example jre1.8.311, the new JRE gets installed with a JAVA_HOME variable that points to location: /custom/jre1.8.301.

  • Windows Scenario: The environment has JRE version: jre1.8.301 and the JAVA_HOME path is set as JAVA_HOME=C:\custom\jre1.8.301. When upgrading to a new JRE version, for example: jre1.8.311, the new JRE gets installed with a JAVA_HOME variable that points to location: C:/custom/jre1.8.301.

Problem: The above setup will result in JRE version confusion as the JAVA_HOME path refers to a value 'jre1.8.301' even though the actual JRE version after the upgrade is jre1.8.311.

Solution: Create a symbolic link with no version number included as part of it, and use it as the JAVA_HOME setting to install the Management Agent.

A symbolic link with no version number reference simplifies the JRE upgrade process. The upgrade will only require a change to where the symbolic link points to.

  • Linux Solution: JAVA_HOME=/custom/jre8-latest -> /custom/jre1.8.301

  • Windows Solution: JAVA_HOME=C:\custom\jre8-latest -> C:\custom\jre1.8.301