# 19 Management Agent and Management Services

This chapter describes how to reconfigure Enterprise Manager if you later revisit your configuration decisions after you have installed the software.

## Reconfiguring the Oracle Management Agent

The following sections describe reconfiguration and tuning changes you can make to the Management Agent after you have installed Enterprise Manager. Refer to the following sections for more information:

### Configuring the Management Agent to Use a New Management Service

When you install the Management Agent on a managed host, you associate the Management Agent with a particular Management Service. The Management Agent uses the Management Service URL address and port to identify and communicate with the Management Service.

After you install the Management Agent, you can later reconfigure the Management Agent so it is associated with a different Management Service. Reconfiguring the Management Agent requires no changes to the Management Service. The reconfigured Management Agent will begin communicating with the new Management Service after the Management Agent is restarted.

If you are associating the Management Agent with a new Management Service that is locked in secure mode, then first associate the Management Agent with the new Management Service and then secure the Management Agent.

To associate the Management Agent with a new Management Service after you have installed the Management Agent:

1. Stop the Management Agent.

2. Locate the emd.properties file in the Management Agent home directory:

AGENT_HOME/sysman/config/emd.properties

3. Use a text editor to open the file and locate the REPOSITORY_URL property.

4. Modify the value for the REPOSITORY_URL property so it references the new Management Service. For example:

REPOSITORY_URL=http://mgmthost2.acme.com:4889/em/upload

5. Modify the value for the emdWalletSrcUrl property so it references the new Management Service. For example, if the new Management Service is on a host called mgmthost2.acme.com , modify the property as follows:

emdWalletSrcUrl=http://mgmthost2.acme.com:4889/em/wallets/emd

6. Save your changes and close the emd.properties file.

7. To ensure that the Management Agent is no longer holding any specific data or settings from the previous Management Service, delete all the files in the following directories:

AGENT_HOME/sysman/emd/upload/
AGENT_HOME/sysman/emd/state/
AGENT_HOME/sysman/emd/collection/*
AGENT_HOME/sysman/emd/lastupld.xml
AGENT_HOME/sysman/emd/agntstmp.txt
AGENT_HOME/sysman/emd/blackouts.xml
AGENT_HOME/sysman/emd/protocol.ini


Note that this action removes all user-defined metrics (UDM)s and custom changes to metric and policy collections.

Note:

You can use the emctl clearstate agent command to delete the files in the state directory.
8. Restart the Management Agent.

### Securing the Management Agent

To secure the Management Agent of the new Management Service, use the following command:

emctl secure agent [registration password] [-emdWalletSrcUrl <url>]


### Changing the Management Agent Port

The Management Agent uses a predefined port number to receive requests from the Management Service. This port number is defined by default when you install the Management Agent on a managed host. If you later need to modify this port, you can use the following procedure. You might need to modify this port number if you have existing software that uses the default Management Agent port.

To change the Management Agent port:

1. Stop the Management Agent.

2. Locate the emd.properties file in the Management Agent home directory:

AGENT_HOME/sysman/config/emd.properties

3. Use a text editor to open the file and locate the EMD_URL property.

For example:

EMD_URL=http://managed_host1.acme.com:1813/emd/main

4. Modify the port number in the EMD_URL property so the Management Agent uses a new unused port on the managed host.

For example:

EMD_URL=http://managed_host1.acme.com:1913/emd/main


You can also use the netstat command to check for the unused port:

On Windows:

netstat -an | findstr <new port number>


On UNIX:

netstat -an | grep <new port number>

5. Start the Management Agent.

Note:

After the changed URL is processed, the old Management Agent should not have any targets. Oracle recommends that you remove the old Management Agent from the Management Service to ensure that there are no unwanted targets in the Grid Control console .

### Controlling the Amount of Disk Space Used by the Management Agent

Oracle designed the Management Agent to work within a set of disk space limits. These limits prevent the Management Agent from using too much disk space and causing performance or resource issues on your enterprise systems. However, if disk space becomes an issue, you can adjust the default settings that are used to control the amount of disk space used by the Management Agent.

As the Management Agent on a particular host gathers management data about the targets on the host, it saves the collected data on the local disk until the data is uploaded to the Management Repository. The Management Agent saves this collected data and metadata in the following directory:

AGENT_HOME/sysman/emd/upload


By default, the Management Agent will save up to 50MB of collected data in the upload directory. If the amount of collected data exceeds 50MB, data collection is stopped temporarily until the data is uploaded to the repository and more disk space becomes available.

To verify how much space is available:

• Use the emctl status agent command. For example:

Available disk space on upload filesystem    : 1.18%
Collection Status                            : Disabled by Upload Manager
Last successful heartbeat to OMS             : 2007-07-31 11:22:07

• Investigate the <AGENT_HOME>/sysman/log/emagent.trc file. The file will have errors such as :

24.995519 MB Data. 34.06% of disk used. Disabling collections.
2006-10-19 10:41:23 Thread-19 WARN collector: Disable collector


In addition, the Management Agent checks to be sure that the percentage of disk space currently in use on the local disk does not exceed 98 percent. If this value is exceeded, the Management Agent stops collecting data and stops saving information to the Management Agent log and trace files.

You can modify these default settings as follows:

1. Stop the Management Agent.

2. Locate the emd.properties file in the Management Agent home directory:

AGENT_HOME/sysman/config/emd.properties

3. Use a text editor to open the file and modify the entries shown in Table 19-1.

4. Save your changes and exit the file.

5. Restart the Management Agent.

Table 19-1 Properties for Controlling the Disk Space Used by the Management Agent

Property Explanation

UploadMaxBytesXML

Use this property in the emd.properties file to specify the maximum number of megabytes (MB) used by the collected data in the Management Agent upload directory. When this limit is exceeded, the Management Agent will stop collecting additional management data until the next upload to the Management Repository reduces the amount of collected data in the upload directory.

UploadMaxDiskUsedPct

Use this property in the emd.properties file to specify the maximum percentage of disk space that can be in use on the local disk before the Management Agent temporarily stops collecting additional data and stops saving information to the Management Agent log and trace files.

The Management Agent will begin collecting data again when the percentage of disk space in use falls to less than the percentage specified in the UploadMaxDiskUsedPctFloor property in the emd.properties file.

UploadMaxDiskUsedPctFloor

Use this property in the emd.properties file to specify the amount (%) of disk space that can be used on the EMD filesystem before the following items are re-enabled after being disabled:

• Collection of data (upload manager)

• Logging and tracing

• Diagnosability tracing does minimal dumps above this limit

UploadMaxNumberXML

Use this property in the emd.properties files to specify the maximum number of files the upload manager will support in the upload directory. When this limit is exceeded, the Management Agent will temporarily disable collections, logging, and tracing.

### About the Management Agent Watchdog Process

The Management Agent is the Enterprise Manager component that gathers the data you need to manage your enterprise efficiently. As a result, Enterprise Manager includes software that keeps track of the Management Agent processes and makes sure the Management Agent stays running.

For example, if the Management Agent quits unexpectedly, this self-monitoring process—referred to as the watchdog process—will restart the Management Agent automatically.

In most situations, the watchdog process works in the background and requires no configuration or maintenance. The watchdog process is controlled by the emwd.pl script located in the following directory of the Management Agent home directory:

AGENT_HOME/bin


You can identify the watchdog process by using the following commands:

$PROMPT> ps -ef | grep emwd  ### Setting the Management Agent Time Zone In today's global economy, it is not uncommon for the systems you manage to reside in multiple locations throughout the world. For example, if your company headquarters are in New Hampshire, USA, you may need to manage systems that reside in California, Canada, and in Europe. As Enterprise Manager collects monitoring data from Management Agents running on these remote systems, it is important that the data is correlated accurately. A software failure on a machine in Ontario, Canada might be the cause of a performance problem on a machine in Hoboken, New Jersey. To correlate this data, it is important that Enterprise Manager obtains the correct time zone for each Management Agent that you install. The following sections describe how the Management Agent obtains the time zone and how to correct the problem if the time zone for a Management Agent is incorrect: #### Understanding How the Management Agent Obtains Time Zone Information When you install the Management Agent, the software attempts to obtain the current time zone of the host computer. If successful, the installation procedure updates the agentTZRegion property setting in the following configuration file: AGENT_HOME/sysman/config/emd.properties  The agentTZRegion property can be set to any of the values listed in the following file, which is installed in the Management Agent home directory: AGENT_HOME/sysman/admin/supportedtzs.lst  To reconfigure a different time zone, perform the following steps. These steps assume that the original time zone used was EST and the target time zone is CST. 1. Set the environment correctly. • On Windows XP - From the Start Menu, access the Control Panel. Click Date and Time, then click the Time Zone tab. - Select GMT-06:00 Central Time (US & Canada) from the list. - Click OK. - Open a command line screen (cmd.exe). - Set the following environment variables: SET TZ=CST SET ORACLE_HOME=< your oracle home directory > SET PATH=%ORACLE_HOME%\bin;%PATH%  • On UNIX - Login to your UNIX server as the Oracle user. - Set the following environment variables: $ export TZ=CST
$export ORACLE_HOME=< your oracle home directory >$ export PATH=%ORACLE_HOME%\bin;%PATH%

2. Execute the following commands:

• On Windows

%ORACLE_HOME%\bin\emctl config agent getTZ
%ORACLE_HOME%\bin\emctl stop iasconsole
%ORACLE_HOME%\bin\emctl resetTZ agent

• On UNIX

$ORACLE_HOME/bin/emctl config agent getTZ$ORACLE_HOME/bin/emctl stop iasconsole
$ORACLE_HOME/bin/emctl resetTZ agent  3. Delete all the files under the following directory: • On Windows %ORACLE_HOME%\sysman\logs  • On UNIX $ORACLE_HOME$/sysman/logs  4. Start the console again. • On Windows %ORACLE_HOME%\bin\emctl start iasconsole %ORACLE_HOME%\bin\emctl status iasconsole %ORACLE_HOME%\bin\emctl status agent %ORACLE_HOME%\bin\emctl config agent getTZ  • On UNIX $ORACLE_HOME\bin\emctl start iasconsole
$ORACLE_HOME\bin\emctl status iasconsole$ORACLE_HOME\bin\emctl status agent
$ORACLE_HOME\bin\emctl config agent getTZ  5. Check the timestamp in the log file. 6. Check the em.properties file. The agentTZRegion parameter should now look like this: • On Windows %ORACLE_HOME%\sysman\config\em.properties agentTZRegion=America/Chicago  • On UNIX $ORACLE_HOME/sysman/config/em.properties
agentTZRegion=America/Chicago


#### Resetting the Time Zone of the Management Agent Due to Inconsistency of Time Zones

You need to reset the time zone of the Management Agent when both of the following situations are true:

• The Management Agent has been running with a particular time zone

• Subsequently a change occurs to the time zone of the host where the Management Agent is running

To propagate the time zone change to the emd.properties file, perform the following:

1. Execute the following script:

ORACLE_HOME/bin/emctl resetTZ agent


This script updates ORACLE_HOME/sysman/config/emd.properties so that the value of agentTZRegion matches that of the current time zone setting of the machine.

Note:

The location of the emd.properties file depends on the Control Console being used:
• For the Database Control Console, the location is usually: ORACLE_HOME/<host>_<sid>/sysman/config

• For the Application Server Control Console, the location is: ORACLE_HOME/sysman/config

• For the Grid Control Management Agent, the location is ORACLE_HOME/sysman/config

• For the Real Application Cluster central Management Agent, the location is usually: ORACLE_HOME/<host>/sysman/config

2. In addition, this command prompts you to run a script against the Enterprise Manager Repository. You must log in to the database as the Enterprise Manager repository user and run the script mgmt_target.set_agent_tzrgn. An example follows:

SQL> exec mgmt_target.set_agent_tzrgn('em.oracle.com:1830','PST8PDT');
SQL> commit;
SQL> exit


em.oracle.com:1830 represents the name of the emd target.

#### Troubleshooting Management Agent Time Zone Problems

Sometimes, during the Management Agent installation, the time zone detected by the Management Agent configuration tool is not recognized by the Management Agent. In other words, the time zone obtained by the configuration tool is not listed in the Management Agent list of supported time zones.

This problem prevents the Management Agent from starting and results in an error similar to the following:

Could not determine agent time zone. Please refer to the file:
ORACLE_HOME/sysman/admin/supportedtzs.lst and pick a timezone region with a
standard offset of +5:0 from GMT and update the property 'agentTZRegion' in the
file: ORACLE_HOME/sysman/config/emd.properties


This error appears in one of the log files shown in Table 19-2, depending upon which Enterprise Manager product you are using.

Table 19-2 Location of Time Zone Error in the Enterprise Manager Log Files

If you are using... Look for the Time Zone Error in This File...

Grid Control console

emagent.nohup

Application Server Control Console

em.nohup

Database Control Console

emdb.nohup

To configure the Management Agent to use a valid time zone:

1. Enter the following command in the Management Agent home directory to identify the time zone currently being used by the host computer:

AGENT_HOME/bin/emctl config agent getTZ

2. Note the time zone that is returned by the emctl config agent getTZ command.

This is the time zone of the host computer.

3. Use a text editor to open the following file in the Management Agent home directory:

AGENT_HOME/sysman/admin/supportedtzs.lst


This file contains a list of all the time zones supported by the Management Agent.

4. Browse the contents of the supportedtzs.lst file and note the supported time zone closest to the time zone of the host computer.

5. Use a text editor to open the following Management Agent configuration file:

AGENT_HOME/sysman/config/emd.properties

6. Locate the following property near the end of the emd.properties file:

agentTZRegion=

7. Set the value of this property to the time zone you identified as closest to the host time zone in the supportedtzs.lst file.

For example:

agentTZRegion=Europe/Warsaw

8. Save your changes and close the emd.properties file.

You should now be able to start the Management Agent without generating the error in the log file.

### Adding Trust Points to the Management Agent Configuration

Perform these steps to add the relevant security certificate:

1. Obtain the certificate, which is in Base64encoded X.509 (.CER) format, in the b64SiteCertificate.txt file. (The file name may be different in your configuration.) An example of the contents of the file is as follows:

------BEGIN CERTIFICATE--------------
MIIDBzCCAnCgAw...
...... base 64 certificate content .....
------END CERTIFICATE-----------------

2. In the Oracle Home of the Management Agent monitoring the wallet, run the following command to add the certificate to the Management Agent:

${ORACLE_HOME}/bin/mkwallet -i welcome${ORACLE_HOME}/sysman/config/monwallet
\${ORACLE_HOME}/sysman/config/b64SiteCertificate.txt NZDST_CLEAR_PTP


## Reconfiguring the Oracle Management Service

The following sections describe configuration changes you can make to the Management Service after you install Enterprise Manager:

### Configuring the Management Service to Use a New Management Repository

When you install and deploy the Management Service, you associate the Management Service with a Management Repository. The Management Service uses the database host, database system identifier (SID), database port, management user, and management password to identify and communicate with the Repository.

The following sections describe how to modify the repository information and provide details about how Enterprise Manager keeps the Management Repository password secure.

#### Changing the Repository Properties

To associate the Management Service with a new repository, you must modify the repository properties:

1. Stop the Management Service.

2. Use the following commands:

emctl config oms -list_repos_details
emctl config oms -store_repos_details (-repos_host <host> -repos_port <port> -repos_sid <sid> | -repos_conndesc <connect descriptor>) -repos_user <username> [-repos_pwd <pwd>] [-no_check_db]

3. shows sample entries.

4. Restart the Management Service.

Table 19-3 Repository Properties

Property Description

- repos_user <username>

The Management Repository user name. The default value is SYSMAN.

- repos_pwd <pwd>

The Management Repository password. See "About Changing the Repository Password" for information of how to change the password value.

-repos_conndesc <connect description>

The Management Repository Oracle Net Connect String for the repository database. The values specified for properties -repos_sid, -repos_host, and -repos_port must be the same as that of HOST, PORT, and SERVICE_NAME in the connect string. If this property is not specified, then -repos_sid, -repos_host, and -repos_port properties are used to construct the connect descriptor. If the database hosting the repository is a RAC database, then the value must be configured as explained in "Configuring the Management Services".

Note: Connect descriptor should be enclosed in quotes, for example,'"<conn_descr>"' or "'<conn_descr>'"

-repos_sid <sid>

The System Identifier (SID) for the database where the Management Repository schema resides.

-repos_host <host>

The name of the server or host computer where the repository database resides.

-repos_port <port>

The port number for the repository database.

Example 19-1 Sample Repository Properties

oracle.sysman.eml.mntr.emdRepUser=SYSMAN
oracle.sysman.eml.mntr.emdRepPwd=sysman
oracle.sysman.eml.mntr.emdRepConnectDescriptor=(DESCRIPTION\=(ADDRESS_
LIST\=(ADDRESS\=(PROTOCOL\=TCP)(HOST\=system12.mycompany.com)(PORT\=1521)))
(CONNECT_DATA\=(SERVICE_NAME\=oemrep1)))
oracle.sysman.eml.mntr.emdRepSID=oemrep1
oracle.sysman.eml.mntr.emdRepServer=system12.mycompany.com
oracle.sysman.eml.mntr.emdRepPort=1521


#### About Changing the Repository Password

For security reasons, the password is encrypted as soon as you start the Management Service. To change the repository password, use the emctl config oms change_repos_pwd command line utility. This utility prompts you for the new password for the repository. When you press ENTER after supplying the password, the utility automatically updates the password.

To modify the repository password, do the following:

1. Stop the Management Service using the following command:

ORACLE_HOME/bin/emctl stop oms

2. Change the repository password by using the following command:

emctl config oms -change_repos_pwd [-change_in_db] [-old_pwd <old_pwd>] [-new_pwd <new_pwd>] [-use_sys_pwd [-sys_pwd <sys_pwd>]]

-change_in_db This option will change in repository too. If not specified, only Credential Store will be updated.

emctl config oms -change_view_user_pwd [-sysman_pwd <sysman_pwd>] [-user_pwd
<user_pwd>] [-auto_generate]

-auto_generate This option will generate a random password.

3. Restart the Management Service using the following command:

ORACLE_HOME/bin/emctl start oms


### Configuring the Management Service to Prompt You When Using Execute Commands

The Execute Host Command and Execute SQL applications enable you to execute commands against multiple hosts and multiple databases respectively.

The default, when you click the Execute button of these applications, is for the command execution to begin immediately on the specified targets. If desired, you can set up the Management Service so that a confirmation page displays when you click the Execute button.

To enable the confirmation page for each application, perform the following:

1. Stop the Management Service using the following command:

ORACLE_HOME/bin/emctl stop oms

2. Change the properties as follows:

• For the Execute Host Command:

emctl set property oracle.sysman.cmd.tgt.multiTarget.confirmExecuteHostCommand=true

• For Execute SQL:

emctl set property oracle.sysman.cmd.tgt.multiTarget.confirmExecuteSQL=true


Note:

The text in the commands is case-sensitive.
3. Restart the Management Service using the following command:

ORACLE_HOME/bin/emctl start oms

### Troubleshooting Management Service Time Zone Problems

Troubleshooting Management Agent Time Zone Problems describes how to correct potential problems that result when the Management Agent cannot determine the proper time zone. Similar problems can occur when the Management Agent finds the correct time zone, but the time zone is not recognized by the Management Service or the database where the Management Repository resides.

When the Management Service does not recognize the time zone established by the Management Agent, Enterprise Manager generates the following error:

OMS does not understand the timezone region of the agent.
Either start the OMS using the extended list of time zones supported by
the database or pick a value of time zone from
ORACLE_HOME/emdw/sysman/admin/nsupportedtzs.lst, update the property 'agentTZRegion' in the file
ORACLE_HOME/sysman/config/emd.properties and restart the agent.
A value which is around an offset of  -05:00 from GMT should be picked.


This error appears in one of the log files shown in Table 19-2, "Location of Time Zone Error in the Enterprise Manager Log Files", depending upon which Enterprise Manager product you are using.

There are two ways to correct this problem:

• Restart the Management Repository database using the more extensive list of time zones in the timezlrg.dat database configuration file, and then start the Management Agent.

See Also:

"Specifying the Database Time Zone File" in the Oracle Database Administrator's Guide
• Specify a new time zone for the Management Agent that the Management Repository database will recognize.

See Also:

"Troubleshooting Management Agent Time Zone Problems" for instructions on changing the time zone assigned to the Management Agent