Amazon Relational Database Service
User Guide

Oracle Management Agent for Enterprise Manager Cloud Control

Amazon RDS supports Oracle Enterprise Manager (OEM) Management Agent through the use of the OEM_AGENT option. Amazon RDS supports Management Agent for the following versions of OEM:

  • Oracle Enterprise Manager Cloud Control for 13c

  • Oracle Enterprise Manager Cloud Control for 12c

Management Agent is a software component that monitors targets running on hosts and communicates that information to the middle-tier Oracle Management Service (OMS). For more information, see Overview of Oracle Enterprise Manager Cloud Control 12c and Overview of Oracle Enterprise Manager Cloud Control 13c in the Oracle documentation.

Following are the supported Oracle versions for each Management Agent version.

Management Agent Version Oracle 19c Oracle 18c Oracle 12c version 12.2 Oracle 12c version 12.1 Oracle 11g

13.3.0.0.v1

Supported

Supported

Supported

Supported

Supported

13.2.0.0.v2

Supported

Supported

Supported

Supported

Supported

13.2.0.0.v1

Supported

Supported

Supported

Supported

Supported

13.1.0.0.v1

Supported

Supported

Supported

Supported

Supported

12.1.0.5.v1

Not supported

Supported

Supported

Supported

Supported

12.1.0.4.v1

Not supported

Supported

Supported

Supported

Supported

The following are some limitations to using Management Agent:

  • Administrative tasks such as job execution and database patching, that require host credentials, are not supported.

  • Host metrics and the process list are not guaranteed to reflect the actual system state.

  • Autodiscovery is not supported. You must manually add database targets.

  • OMS module availability depends on your database edition. For example, the database performance diagnosis and tuning module is only available for Oracle Database Enterprise Edition.

  • Management Agent consumes additional memory and computing resources. If you experience performance problems after enabling the OEM_AGENT option, we recommend that you scale up to a larger DB instance class. For more information, see Choosing the DB Instance Class and Modifying a DB Instance Running the Oracle Database Engine.

  • Because operating system access on the alert log isn't granted to the user running the OEM_AGENT on the Amazon RDS host, it isn't possible to collect metrics for DB Alert Log and DB Alert Log Error Status in OEM.

  • TCPS connectivity between the Management Agent and the DB instance isn't supported.

Prerequisites for Management Agent

The following are prerequisites for using Management Agent:

  • An Amazon RDS DB instance running Oracle version 19.0.0.0, 18.0.0.0, 12.2.0.1, 12.1.0.2, or 11.2.0.4.

  • At least 3.3 GiB of storage space for OEM 13c Release 3.

  • At least 3.3 GiB of storage space for OEM 13c Release 2.

  • At least 3 GiB of storage space for OEM 13c Release 1.

  • At least 2 GiB of storage space for OEM 12c.

  • For Oracle version 19.0.0.0, the minimum AGENT_VERSION is 13.1.0.0.v1.

  • An Oracle Management Service (OMS), configured to connect to your Amazon RDS DB instance.

    For an Amazon RDS DB instance running Oracle version 18.0.0.0 or higher, meet the following requirements:

    • For OMS 13c2, apply the Enterprise Manager 13.2 Master Bundle Patch List, which includes plugins 13.2.1, 13.2.2, 13.2.3, 13.2.4 (Oracle Doc ID 2219797.1).

    • For OMS 13c2, apply the OMS PSU System Patch 28970534.

    • For OMS 13c2, apply the OMS-Side Plugin System 13.2.2.0.190131 Patch 29201709.

    For an Amazon RDS DB instance running Oracle version 12.2.0.1 or lower, meet the following requirements:

    • For OMS 13c Release 2 with Oracle patch 25163555 applied, use OEM Agent 13.2.0.0.v2 or later.

      Use OMSPatcher to apply the patch.

    • For unpatched OMS 13c Release 2, use OEM Agent 13.2.0.0.v1.

    Use OMSPatcher to apply patches.

  • In most cases, you need to configure your VPC to allow connections from OMS to your DB instance. If you are not familiar with Amazon Virtual Private Cloud (Amazon VPC), we recommend that you complete the steps in Tutorial: Create an Amazon VPC for Use with a DB Instance before continuing.

Additional configuration is required to allow your OMS host and your Amazon RDS DB instance to communicate. You must also do the following:

  • To connect from the Management Agent to your OMS, if your OMS is behind a firewall, you must add the IP addresses of your DB instances to your OMS.

    Make sure the firewall for the OMS allows traffic from both the DB listener port (default 1521) and the OEM Agent port (default 3872), originating from the IP address of the DB instance.

  • To connect from your OMS to the Management Agent, if your OMS has a publicly resolvable host name, you must add the OMS address to a security group. Your security group must have inbound rules that allow access to the DB listener port and the Management Agent port. For an example of creating a security and adding inbound rules, see Tutorial: Create an Amazon VPC for Use with a DB Instance.

  • To connect from your OMS to the Management Agent, if your OMS doesn't have a publicly resolvable host name, use one of the following:

Option Settings for Management Agent

Amazon RDS supports the following settings for the Management Agent option.

Note

All of the settings are required.

Option Setting Valid Values Description

Version (AGENT_VERSION)

13.3.0.0.v1

13.2.0.0.v2

13.2.0.0.v1

13.1.0.0.v1

12.1.0.5.v1

12.1.0.4.v1

The version of the Management Agent software.

The AWS CLI option name is OptionVersion.

Note

In the AWS GovCloud (US-West) Region, 12.1 and 13.1 versions aren't available.

Port (AGENT_PORT)

An integer value

The port on the DB instance that listens for the OMS host. The default is 3872. Your OMS host must belong to a security group that has access to this port.

The AWS CLI option name is Port.

Security Groups

Existing security groups

A security group that has access to Port. Your OMS host must belong to this security group.

The AWS CLI option name is VpcSecurityGroupMemberships or DBSecurityGroupMemberships.

OMS_HOST

A string value, for example my.example.oms

The publicly accessible host name or IP address of the OMS.

The AWS CLI option name is OMS_HOST.

OMS_PORT

An integer value

The HTTPS upload port on the OMS Host that listens for the Management Agent.

To determine the HTTPS upload port, connect to the OMS host, and run the following command (which requires the SYSMAN password):

emctl status oms -details

The AWS CLI option name is OMS_PORT.

AGENT_REGISTRATION_PASSWORD

A string value

The password that the Management Agent uses to authenticate itself with the OMS. We recommend that you create a persistent password in your OMS before enabling the OEM_AGENT option. With a persistent password you can share a single Management Agent option group among multiple Amazon RDS databases.

The AWS CLI option name is AGENT_REGISTRATION_PASSWORD.

Adding the Management Agent Option

The general process for adding the Management Agent option to a DB instance is the following:

  1. Create a new option group, or copy or modify an existing option group.

  2. Add the option to the option group.

  3. Associate the option group with the DB instance.

If you encounter errors, you can check My Oracle Support documents for information about resolving specific problems.

After you add the Management Agent option, you don't need to restart your DB instance. As soon as the option group is active, the OEM Agent is active.

If your OMS host is using an untrusted third-party certificate, Amazon RDS returns the following error.

You successfully installed the OEM_AGENT option. Your OMS host is using an untrusted third party certificate. Configure your OMS host with the trusted certificates from your third party.

If this error is returned, the Management Agent option isn't enabled until the problem is corrected. For information about correcting the problem, see the My Oracle Support document 2202569.1.

Console

To add the Management Agent option to a DB instance

  1. Determine the option group you want to use. You can create a new option group or use an existing option group. If you want to use an existing option group, skip to the next step. Otherwise, create a custom DB option group with the following settings:

    1. For Engine choose the oracle edition for your DB instance.

    2. For Major engine version choose the version of your DB instance.

    For more information, see Creating an Option Group.

  2. Add the OEM_AGENT option to the option group, and configure the option settings. For more information about adding options, see Adding an Option to an Option Group. For more information about each setting, see Option Settings for Management Agent.

  3. Apply the option group to a new or existing DB instance:

AWS CLI

The following example uses the AWS CLI add-option-to-option-group command to add the OEM_AGENT option to an option group called myoptiongroup.

For Linux, OS X, or Unix:

aws rds add-option-to-option-group \ --option-group-name "myoptiongroup" \ --options OptionName=OEM_AGENT,OptionVersion=13.1.0.0.v1,Port=3872,VpcSecurityGroupMemberships=sg-1234567890,OptionSettings=[{Name=OMS_HOST,Value=my.example.oms},{Name=OMS_PORT,Value=4903},{Name=AGENT_REGISTRATION_PASSWORD,Value=password}] \ --apply-immediately

For Windows:

aws rds add-option-to-option-group ^ --option-group-name "myoptiongroup" ^ --options OptionName=OEM_AGENT,OptionVersion=13.1.0.0.v1,Port=3872,VpcSecurityGroupMemberships=sg-1234567890,OptionSettings=[{Name=OMS_HOST,Value=my.example.oms},{Name=OMS_PORT,Value=4903},{Name=AGENT_REGISTRATION_PASSWORD,Value=password}] ^ --apply-immediately

Using the Management Agent

After you enable the Management Agent option, take the following steps to begin using it.

To use the Management Agent

  1. Unlock and reset the DBSNMP account credential. Do this by running the following code on your target database on your DB instance and using your master user account.

    ALTER USER dbsnmp IDENTIFIED BY new_password ACCOUNT UNLOCK;
  2. Add your targets to the OMS console manually:

    1. In your OMS console, choose Setup, Add Target, Add Targets Manually.

    2. Choose Add Targets Declaratively by Specifying Target Monitoring Properties.

    3. For Target Type, choose Database Instance.

    4. For Monitoring Agent, choose the agent with the identifier that is the same as your RDS DB instance identifier.

    5. Choose Add Manually.

    6. Enter the endpoint for the Amazon RDS DB instance, or choose it from the host name list. Make sure that the specified host name matches the endpoint of the Amazon RDS DB instance.

      For information about finding the endpoint for your Amazon RDS DB instance, see Finding the Endpoint of Your DB Instance.

    7. Specify the following database properties:

      • For Target name, enter a name.

      • For Database system name, enter a name.

      • For Monitor username, enter dbsnmp.

      • For Monitor password, enter the password from step 1.

      • For Role, enter normal.

      • For Oracle home path, enter /oracle.

      • For Listener Machine name, the agent identifier already appears.

      • For Port, enter the database port. The RDS default port is 1521.

      • For Database name, enter the name of your database.

    8. Choose Test Connection.

    9. Choose Next. The target database appears in your list of monitored resources.

Modifying Management Agent Settings

After you enable the Management Agent, you can modify settings for the option. For more information about how to modify option settings, see Modifying an Option Setting. For more information about each setting, see Option Settings for Management Agent.

Performing Database Tasks with the Management Agent

You can use Amazon RDS procedures to run certain EMCTL commands on the Management Agent. By running these procedures, you can do the tasks listed following.

Getting the Management Agent's Status

To get the Management Agent's status, run the Amazon RDS procedure rdsadmin.rdsadmin_oem_agent_tasks.get_status_oem_agent. This procedure is equivalent to the emctl status agent command.

The following procedure gets the Management Agent's status,

SELECT rdsadmin.rdsadmin_oem_agent_tasks.get_status_oem_agent() as TASK_ID from DUAL;

Restarting the Management Agent

To restart the Management Agent, run the Amazon RDS procedure rdsadmin.rdsadmin_oem_agent_tasks.get_status_oem_agent. This procedure is equivalent to running the emctl stop agent and emctl start agent commands.

The following procedure restarts the Management Agent.

SELECT rdsadmin.rdsadmin_oem_agent_tasks.restart_oem_agent() as TASK_ID from DUAL;

Listing the Targets Monitored by the Management Agent

To list the targets monitored by the Management Agent, run the Amazon RDS procedure rdsadmin.rdsadmin_oem_agent_tasks.list_targets_oem_agent. This procedure is equivalent to running the emctl config agent listtargets command.

The following procedure lists the targets monitored by the Management Agent.

SELECT rdsadmin.rdsadmin_oem_agent_tasks.list_targets_oem_agent() as TASK_ID from DUAL;

Clearing the Management Agent's State

To clear the Management Agent's state, run the Amazon RDS procedure rdsadmin.rdsadmin_oem_agent_tasks.clearstate_oem_agent. This procedure is equivalent to running the emctl clearstate agent command.

The following procedure clears the Management Agent's state.

SELECT rdsadmin.rdsadmin_oem_agent_tasks.clearstate_oem_agent() as TASK_ID from DUAL;

Having the Management Agent Upload Its OMS

To have the Management Agent upload the Oracle Management Server (OMS) associated with it, run the Amazon RDS procedure rdsadmin.rdsadmin_oem_agent_tasks.upload_oem_agent. This procedure is equivalent to running the emclt upload agent command.

If you run the following procedure, the Management Agent uploads its associated OMS.

SELECT rdsadmin.rdsadmin_oem_agent_tasks.upload_oem_agent() as TASK_ID from DUAL;

Pinging the OMS

To ping the Management Agent's OMS, run the Amazon RDS procedure rdsadmin.rdsadmin_oem_agent_tasks.ping_oms_oem_agent. This procedure is equivalent to running the emctl pingOMS command.

The following procedure pings the Management Agent's OMS.

SELECT rdsadmin.rdsadmin_oem_agent_tasks.ping_oms_oem_agent() as TASK_ID from DUAL;

Viewing the Status of an Ongoing Task

You can view the status of an ongoing task in a bdump file. The bdump files are located in the /rdsdbdata/log/trace directory. Each bdump file name is in the following format.

dbtask-task-id.log

When you want to monitor a task, replace task-id with the ID of the task that you want to monitor.

To view the contents of bdump files, run the Amazon RDS procedure rdsadmin.rds_file_util.read_text_file. The following query returns the contents of the dbtask-1546988886389-2444.log bdump file.

SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-1546988886389-2444.log'));

For more information about the Amazon RDS procedure rdsadmin.rds_file_util.read_text_file, see Reading Files in a DB Instance Directory.

Removing the Management Agent Option

You can remove the OEM Agent from a DB instance. After you remove the OEM Agent, you don't need to restart your DB instance.

To remove the OEM Agent from a DB instance, do one of the following:

  • Remove the OEM Agent option from the option group it belongs to. This change affects all DB instances that use the option group. For more information, see Removing an Option from an Option Group.

  • Modify the DB instance and specify a different option group that doesn't include the OEM Agent option. This change affects a single DB instance. You can specify the default (empty) option group, or a different custom option group. For more information, see Modifying a DB Instance Running the Oracle Database Engine.