Oracle Management Agent for Enterprise Manager Cloud Control

Oracle Enterprise Manager (OEM) Management Agent is a software component that monitors targets running on hosts and communicates that information to the middle-tier Oracle Management Service (OMS). Amazon RDS supports Management Agent through the use of the OEM_AGENT option.

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.

Requirements for Management Agent

Following are general requirements for using Management Agent:

• Your DB instance must run Oracle Database 19c (19.0.0.0). You can use either the CDB or non-CDB architecture.

• You must use an Oracle Management Service (OMS) that is configured to connect to your DB instance. Note the following OMS requirements:

  • Management Agent version 13.5.0.0.v2 requires OMS version 13.5.0.23.

  • Management Agent version 13.5.0.0.v1 requires OMS version 13.5.0.0.

  • Management Agent version 13.4.0.9.v1 requires OMS version 13.4.0.9 or later and patch 32198287.

• In most cases, you must configure your VPC to allow connections from OMS to your DB instance. If you aren't familiar with Amazon Virtual Private Cloud (Amazon VPC), we recommend that you complete the steps in Tutorial: Create a VPC for use with a DB instance (IPv4 only) before continuing.

• You can use Management Agent with Oracle Enterprise Manager Cloud Control for 12c and 13c. Ensure that you have sufficient storage space for your OEM release:

  • At least 8.5 GiB for OEM 13c Release 5

  • At least 8.5 GiB for OEM 13c Release 4

  • At least 8.5 GiB for OEM 13c Release 3

  • At least 5.5 GiB for OEM 13c Release 2

  • At least 4.5 GiB OEM 13c Release 1

  • At least 2.5 GiB for OEM 12c

• If you're using Management Agent versions OEM_AGENT 13.2.0.0.v3 and 13.3.0.0.v2, and if you want to use TCPS connectivity, follow the instructions in Configuring third party CA certificates for communication with target databases in the Oracle documentation. Also, update the JDK on your OMS by following the instructions in the Oracle document with the Oracle Doc ID 2241358.1. This step ensures that OMS supports all the cipher suites that the database supports.

  Note

  TCPS connectivity between the Management Agent and the DB instance is supported for Management Agent OEM_AGENT 13.2.0.0.v3, 13.3.0.0.v2, 13.4.0.9.v1, and higher versions.

OMS host communication prerequisites

Make sure that your OMS host and your Amazon RDS DB instance can communicate. Do the following:

• To connect from the Management Agent to your OMS, if your OMS is behind a firewall, 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, 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 a VPC for use with a DB instance (IPv4 only).

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

  • If your OMS is hosted on an Amazon Elastic Compute Cloud (Amazon EC2) instance in a private VPC, you can set up VPC peering to connect from OMS to Management Agent. For more information, see A DB instance in a VPC accessed by an EC2 instance in a different VPC.

  • If your OMS is hosted on-premises, you can set up a VPN connection to allow access from OMS to Management Agent. For more information, see A DB instance in a VPC accessed by a client application through the internet or VPN connections.

Limitations for Management Agent

Following are some limitations to using Management Agent:

• You can't provide custom Oracle Management Agent images.

• Administrative tasks such as job execution and database patching, that require host credentials, aren't supported.

• Host metrics and the process list aren't guaranteed to reflect the actual system state. Thus, you shouldn't use OEM to monitor the root file system or mount point file system. For more information about monitoring the operating system, see Monitoring OS metrics with Enhanced Monitoring.

• Autodiscovery isn't 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 DB instance classes and Modifying an Amazon RDS DB instance.

• The user running the OEM_AGENT on the Amazon RDS host doesn't have operating system access to the alert log. Thus, you can't collect metrics for DB Alert Log and DB Alert Log Error Status in OEM.

Option settings for Management Agent

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

Option setting	Required	Valid values	Description
Version (AGENT_VERSION)	Yes	13.5.0.0.v2 13.5.0.0.v1 13.4.0.9.v1 13.3.0.0.v2 13.3.0.0.v1 13.2.0.0.v3 13.2.0.0.v2 13.2.0.0.v1 13.1.0.0.v1	The version of the Management Agent software. The minimum supported version is 13.1.0.0.v1. The AWS CLI option name is OptionVersion. Note In the AWS GovCloud (US) Regions, 13.1 versions aren't available.
Port (AGENT_PORT)	Yes	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	Yes	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	Yes	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	Yes	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	Yes	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.
ALLOW_TLS_ONLY	No	true, false (default)	A value that configures the OEM Agent to support only the TLSv1 protocol while the agent listens as a server. This setting is no longer supported. Management Agent versions 13.1.0.0.v1 and higher support Transport Layer Security (TLS) by default.
MINIMUM_TLS_VERSION	No	TLSv1 (default), TLSv1.2	A value that specifies the minimum TLS version supported by the OEM Agent while the agent listens as a server. Desupported agent versions only support the TLSv1 setting.
TLS_CIPHER_SUITE	No	See Option settings for Management Agent.	A value that specifies the TLS cipher suite used by the OEM Agent while the agent listens as a server.

The following table lists the TLS cipher suites that the Management Agent option supports.

Cipher suite	Agent version supported	FedRAMP compliant
TLS_RSA_WITH_AES_128_CBC_SHA	All	No
TLS_RSA_WITH_AES_128_CBC_SHA256	13.1.0.0.v1 and higher	No
TLS_RSA_WITH_AES_256_CBC_SHA	13.2.0.0.v3 and higher	No
TLS_RSA_WITH_AES_256_CBC_SHA256	13.2.0.0.v3 and higher	No
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA	13.2.0.0.v3 and higher	Yes
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA	13.2.0.0.v3 and higher	Yes
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256	13.2.0.0.v3 and higher	Yes
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384	13.2.0.0.v3 and higher	Yes

Step1: Adding the Management Agent option to your DB instance

To add the Management Agent option to your DB instance, do 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, 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 your 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:

   • For a new DB instance, you apply the option group when you launch the instance. For more information, see Creating an Amazon RDS DB instance.

   • For an existing DB instance, you apply the option group by modifying the instance and attaching the new option group. For more information, see Modifying an Amazon RDS 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, macOS, 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

Step 2: Unlocking the DBSNMP user account

The Management Agent uses the DBSNMP user account to connect to the database and report issues to Oracle Enterprise Manager. In a CDB, DBSNMP is a common user. This user account is necessary for both the Management Agent and OEM Database Express. By default, this account is locked. The procedure for unlocking this account differs depending on whether your database uses the non-CDB or CDB architecture.

To unlock the DBSNMP user account

1. In SQL*Plus or another Oracle SQL application, log in to your DB instance as your master user.

2. Do either of the following actions, depending on the database architecture:

   Your database is a non-CDB.

   Run the following SQL statement:

   ALTER USER dbsnmp IDENTIFIED BY new_password ACCOUNT UNLOCK;

   Your database is a CDB.

   Run the following stored procedure to unlock the DBSNMP account:

   EXEC rdsadmin.rdsadmin_util.reset_oem_agent_password('new_password');

   If you receive an error stating that the procedure doesn't exist, reboot your CDB instance to install it automatically. For more information, see Rebooting a DB instance.

Step 3: Adding your targets to the Management Agent console

To add a DB instance as a target, make sure you know the endpoint and port. For information about finding the endpoint for your Amazon RDS DB instance, see Finding the endpoint of your RDS for Oracle DB instance. If your database uses the CDB architecture, then add the CDB$ROOT container separately as a target.

To add targets to the Management Agent console

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

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 2: Unlocking the DBSNMP user account.

   • 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. If your database is a CDB, this name is RDSCDB.

8. Choose Test Connection.

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

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

Note

Tasks are executed asynchronously.

Tasks

• Getting the status of the Management Agent
• Restarting the Management Agent
• Listing the targets monitored by the Management Agent
• Listing the collection threads monitored by the Management Agent
• Clearing the Management Agent state
• Making the Management Agent upload its OMS
• Pinging the OMS
• Viewing the status of an ongoing task

Getting the status of the Management Agent

To get the status of the Management Agent, 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 creates a task to get the Management Agent's status and returns the ID of the task.

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

To view the result by displaying the task's output file, see Viewing the status of an ongoing task.

Restarting the Management Agent

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

The following procedure creates a task to restart the Management Agent and returns the ID of the task.

SELECT rdsadmin.rdsadmin_oem_agent_tasks.restart_oem_agent as TASK_ID from DUAL;    

To view the result by displaying the task's output file, see Viewing the status of an ongoing task.

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 creates a task to list the targets monitored by the Management Agent and returns the ID of the task.

SELECT rdsadmin.rdsadmin_oem_agent_tasks.list_targets_oem_agent as TASK_ID from DUAL;

To view the result by displaying the task's output file, see Viewing the status of an ongoing task.

Listing the collection threads monitored by the Management Agent

To list of all the running, ready, and scheduled collection threads monitored by the Management Agent, run the Amazon RDS procedure rdsadmin.rdsadmin_oem_agent_tasks.list_clxn_threads_oem_agent. This procedure is equivalent to the emctl status agent scheduler command.

The following procedure creates a task to list the collection threads and returns the ID of the task.

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

To view the result by displaying the task's output file, see Viewing the status of an ongoing task.

Clearing the Management Agent 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 creates a task that clears the Management Agent's state and returns the ID of the task.

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

To view the result by displaying the task's output file, see Viewing the status of an ongoing task.

Making the Management Agent upload its OMS

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

The following procedure creates a task that makes the Management Agent upload its associated OMS and return the ID of the task.

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

To view the result by displaying the task's output file, see Viewing the status of an ongoing task.

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 creates a task that pings the Management Agent's OMS and returns the ID of the task.

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

To view the result by displaying the task's output file, see Viewing the status of an ongoing task.

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 an Amazon RDS DB instance.