21 Enterprise Manager Configuration Assistant (EMCA)

This chapter describes the Enterprise Manager Configuration Assistant (EMCA).

Specifically, this chapter includes the following topics:

See Also:

Oracle Enterprise Manager Advanced Configuration for information about other advanced configuration topics.

Configuring Database Control with EMCA

When you use the Database Configuration Assistant (DBCA) to configure Oracle Database 11g, DBCA provides a graphical user interface to help you select Database Control options and to configure other aspects of your database.

However, if you want to use the operating system command line to configure Database Control, you can use the Enterprise Manager Configuration Assistant (EMCA).

To configure Database Control with EMCA:

  1. Set the following environment variables to identify the Oracle home and the system identifier (SID) for the database you want to manage:

    • ORACLE_HOME

    • ORACLE_SID

  2. Change directory to the ORACLE_HOME/bin directory.

  3. Start EMCA by entering the following command with any of the optional command-line arguments shown in Table 21-1:

    $PROMPT> ./emca 
    

    Depending upon the arguments you include on the EMCA command line, EMCA prompts you for the information required to configure Database Control.

    For example, enter the following command to configure Database Control so it will perform automatic daily backups of your database:

    $PROMPT> ./emca -config dbcontrol db -backup
    

EMCA commands are of the form:

emca [operation] [mode] [flags] [parameters]

Note:

To configure Database Console for single instance database using ASM, no extra parameters need to be passed along with the EMCA command. Run the following command to configure the Database Console which will automatically detect the ASM instance:
emca -config dbcontrol db -repos create

Note:

The Database Control repository is in secure mode, which means that Enterprise Manager data is encrypted. The file location of the encryption key depends upon the type of database, as follows:
  • For single instance databases:

    ORACLE_HOME/<host>_<sid>/emkey.ora
    
  • For Oracle RAC databases:

    ORACLE_HOME/<node>_<sid>/emkey.ora
    

Oracle strongly recommends that you ensure this file is backed up because the encrypted data will become unusable if this file is lost.

Table 21-1 describes the valid execution operations and modes, and lists the optional parameters in brackets. Table 21-2 discusses the flags and their behavior, while Table 21-3 defines the optional parameters in detail. EMCA parameters are of the form [ -parameterName parameterValue ]. Multiple parameters can be used in combination at the command line.

Table 21-1 EMCA Command-Line Operations

Command Description

emca -h | --h | -help | --help

Use this option to display the Help message for the EMCA utility. The options described in Table 21-1, Table 21-2, and Table 21-3, and the valid parameters you may include are listed.

emca –version

Prints the version information associated with EMCA.

emca -config dbcontrol db [-repos (create | recreate)] [-cluster] [-silent] [-backup] [parameters]

Configures Database Control for a database. Options include creating (or recreating) Database Control repository, configuring automatic backups, and performing these operations on a cluster database.

emca -config centralAgent (db | asm) [-cluster] [-silent] [parameters]

Configures central agent management for a database or an Automatic Storage Management (ASM) instance. Options include performing this operation on a cluster environment.This operation will configure the database so that it can be centrally managed by the Oracle Enterprise Manager Grid Control Console. To use this option, you must have previously installed the Oracle Management Service component of Enterprise Manager on a network host. In addition, the Oracle Management Agent must be installed on the host where you are running the database.

emca -config all db [-repos (create | recreate)] [-cluster] [-silent] [-backup] [parameters]

Configures both Database Control and central agent management for a database. The possible configuration options are similar to those described above.

emca -deconfig dbcontrol db [-repos drop] [-cluster] [-silent] [parameters]

Deconfigures Database Control for a database. Options include dropping the Database Control repository and performing these operations on a cluster database. For example, you might use this command to remove the Database Control configuration from a database you are planning to delete. In such a scenario, remove the Database Control configuration before physically deleting the database. This operation does not remove the actual database or its data files.

emca -deconfig centralAgent (db | asm) [-cluster] [ -silent] [parameters]

Deconfigures central agent management for a database or an ASM instance. Options include performing this operation on a cluster environment. For example, you might use this command to remove the central agent management configuration from a database you are planning to delete. In such a scenario, remove the central agent management configuration before physically deleting the database. This operation does not remove the actual database or its data files.

emca -deconfig all db [-repos drop] [-cluster] [-silent] [parameters]

Deconfigures both Database Control and central agent management for a database. The possible deconfiguration options are similar to those described above.

emca -addInst (db | asm) [-silent] [parameters]

Configures Enterprise Manager for a new cluster instance of a database or ASM storage. For more information, refer to Using EMCA With Oracle Real Application Clusters.

emca -deleteInst (db | asm) [-silent] [parameters]

Deconfigures Enterprise Manager for a specific instance of a cluster database or ASM storage. This is discussed further below, in Using EMCA With Oracle Real Application Clusters.

emca -reconfig ports [-cluster] [parameters]

Explicitly reassigns Database Control ports. Options include performing this operation on a cluster environment. For more information, refer to Specifying the Ports Used by EMCA.

emca -reconfig dbcontrol -cluster [-silent] [parameters]

Reconfigures Database Control deployment for a cluster database. Note that this command must be used with the "-cluster" option. For more information, refer to Using EMCA With Oracle Real Application Clusters.

emca -displayConfig dbcontrol -cluster [-silent] [parameters]

Displays information about the current deployment configuration of Database Control in a cluster environment. Note that this command must be used with the "-cluster" option. For more information, refer to Using EMCA With Oracle Real Application Clusters.

emca -upgrade (db | asm | db_asm) [-cluster] [-silent] [parameters]

Upgrades the configuration of an earlier version of Enterprise Manager to the current version. This operation can be performed for database, ASM, or database and ASM instances together simultaneously. This does not upgrade the actual database or ASM instances, nor does it upgrade the Enterprise Manager software. Instead, it upgrades the configuration files for the specified instance so that they are compatible with the current version of the Enterprise Manager software. EMCA will attempt to upgrade all instances of the specified database and/or ASM target on the host, across all Oracle Homes (since it is likely that certain target properties, such as listener port or Oracle Home, have changed).

emca -restore (db | asm | db_asm) [-cluster] [-silent] [parameters]

Restores the current version of Enterprise Manager configuration to an earlier version. This is the inverse of the "-upgrade" option (and will reverse any changes that result from an "-upgrade" operation), and as such, the options are similar.

emca -migrate -from dbcontrol -to centralAgent [-repos drop] [-cluster] [-silent] [parameters]

Migrates the Enterprise Manager configuration from Database Control to Central Agent.


Table 21-2 EMCA Command-Line Flags

Flag Description

db

Performs the operation for a database (including cluster databases). Use this option for databases that use Automatic Storage Management (ASM) to store the data files. If a database is using ASM, all the configuration operations and modes described above (except for "-upgrade" and "-restore") will detect this automatically and apply the changes to both the database and ASM instance(s).

asm

Performs the operation for an ASM-only instance (including cluster ASM instances).

db_asm

This flag can only be used in "-upgrade" and "-restore" mode. Performs the upgrade/restore operation for a database and an ASM instance together. Database and ASM instances may be upgraded or restored separately (that is, upgrading an ASM instance does not require upgrading the database instances it services). Hence, the Enterprise Manager configuration can be upgraded or restored separately for a database and its respective ASM instance.

-repos create

Creates a new Database Control management repository.

-repos drop

Drops the current Database Control management repository.

-repos recreate

Drops the current Database Control management repository and then recreates a new one.

-cluster

Performs the operation for a cluster database or ASM instance.

-silent

Performs the operation without prompting for additional information. If this mode is specified, all the required parameters must be entered at the command line or specified in an input file using the –respFile argument. You can view a list of the available parameters by entering emca -help at the command line.

-backup

Configures automatic backup for a database. EMCA will prompt for daily automatic backup options. The default Enterprise Manager settings will be used to backup the database files.

Note: If you use this option, EMCA will use the value of the db_recovery_file_dest initialization parameter to identify the flashback recovery area for the automated backups. If that parameter is not set, EMCA will generate an error. You can modify these settings later using the Maintenance page in Database Control. For more information, see the Database Control online Help.


Table 21-3 EMCA Command-Line Parameters

Parameter Description

-respFile

Specifies the path of an input file listing parameters for EMCA to use while performing its configuration operation. For more information, refer to Using an Input File for EMCA Parameters.

-SID

Database system identifier

-PORT

Port number for the listener servicing the database

-ORACLE_HOME

Database Oracle Home, as an absolute path

-ORACLE_HOSTNAME

Local Hostname

-LISTENER_OH

Oracle Home from where the listener is running. If the listener is running from an Oracle Home other than the one on which the database is running, the parameter LISTENER_OH must be specified.

-HOST_USER

Host machine user name (for automatic backup)

-HOST_USER_PWD

Host machine user password (for automatic backup)

-BACKUP_SCHEDULE

Schedule in the form of "HH:MM" (for daily automatic backups)

-EMAIL_ADDRESS

E-mail address for notifications

-MAIL_SERVER_NAME

Outgoing Mail (SMTP) server for notifications

-ASM_OH

Automatic Storage Management Oracle Home

-ASM_SID

System identifier for ASM instance

-ASM_PORT

Port number for the listener servicing the ASM instance

-ASM_USER_ROLE

User role for connecting to the ASM instance

-ASM_USER_NAME

User name for connecting to the ASM instance

-ASM_USER_PWD

Password for connecting to the ASM instance

-DBSNMP_PWD

Password for DBSNMP user

-SYSMAN_PWD

Password for SYSMAN user

-SYS_PWD

Password for SYS user

-SRC_OH

Oracle Home of the database with Enterprise Manager configuration to be upgraded/restored

-DBCONTROL_HTTP_PORT

Use this parameter to specify the port you use to display the Database Control Console in your Web browser. For more information, refer to Specifying the Ports Used by EMCA.

-AGENT_PORT

Use this parameter to specify the Management Agent port for Database Control. For more information, refer to Specifying the Ports Used by EMCA.

-RMI_PORT

Use this parameter to specify the RMI port for Database Control. For more information, refer to Specifying the Ports Used by EMCA.

-JMS_PORT

Use this parameter to specify the JMS port for Database Control. For more information, refer to Specifying the Ports Used by EMCA.

-CLUSTER_NAME

Cluster name (for cluster databases)

-DB_UNIQUE_NAME

Database unique name (for cluster databases)

-SERVICE_NAME

Database service name (for cluster databases)

-EM_NODE

Node from which Database Control console is to be run (for cluster databases). For more information, refer to Using EMCA With Oracle Real Application Clusters.

-EM_SID_LIST

Comma-separated list of SIDs for agent-only configurations, uploading data to –EM_NODE. For more information, refer to Using EMCA With Oracle Real Application Clusters.

-EM_SWLIB_STAGE_LOC

Software library location

-PORTS_FILE

Path to a static file specifying the ports to use. The default value is: ${ORACLE_HOME}/install/staticports.ini


Configuring Software Library With EMCA

As part of Database Control configuration, the software library will be configured and provisioning archives will be deployed. By default, the software library will be configured at the following location:

ORACLE_HOME/EMStagePatches_<db_unique_name>

You can also use the EMCA EM_SWLIB_STAGE_LOC command-line parameter to configure the software library after you have installed and configured Oracle Database 11g.

For Oracle Real Application Clusters (RAC), the software library will be configured and provisioning archives will be deployed only if ORACLE_HOME or the software library location passed to the EM_SWLIB_STAGE_LOC parameter is in shared storage.

Using an Input File for EMCA Parameters

Instead of answering a series of prompts when you run EMCA, you can use the -respFile argument to specify an input file. The input file you create must be in a format similar to the following example:

PORT=1521
SID=DB
DBSNMP_PWD=xpE234D
SYSMAN_PWD=KDOdk432

After you create an EMCA input file, you can use it on the command line as follows:

$PROMPT> ./emca -config dbcontrol db -respFile input_file_path

For example, to configure the Database Control to perform daily backups and create the Database Control Management Repository, create an input file similar to the one shown in Example 21-1 and enter the following command at the operating system prompt:

$PROMPT> ./emca -config dbcontrol db -repos create -backup -respFile input_file_path

Example 21-1 Sample EMCA Input File

PORT=1521
SID=DB
DBSNMP_PWD=dow3l224
SYSMAN_PWD=squN3243
HOST_USER=johnson
HOST_USER_PWD=diTf32of
SYS_PWD=qlKj4352
BACKUP_SCHEDULE=06:30

Using EMCA With Oracle Real Application Clusters

Oracle Real Application Clusters (RAC) provides a high availability database environment spanning multiple hosts. Each cluster may be made up of multiple cluster databases, each of which consists of multiple cluster database instances. A cluster database is available as long as one of its instances is available.

All EMCA commands can be used in Oracle RAC environments; certain commands are only applicable in cluster setups. To indicate that you have a cluster database, use the –cluster flag which is available in almost every EMCA operational mode.

When you use EMCA to configure Database Control for Oracle RAC, you configure the Database Control for each instance in the cluster. However, by default, the Database Control Console will only start on the local node. On every other node of the cluster, only the Enterprise Manager agent will start. This is because the Database Control Console opens a number of connections to the database. If an instance of the console is running on every host in the cluster, then you may easily exceed the maximum number of permitted open connections on a 32-node or 64-node environment.

To remedy this, the Database Control Console is only started on the local node. On every other node, the commands emctl start dbconsole and emctl stop dbconsole only start and stop the agent. Each of the remote agents will upload their respective data to the console running on the local node, from where you can monitor and manage all the targets in the cluster. On each instance of the RAC database, the following subdirectories will be created:

$ORACLE_HOME/hostname1.domainname_SID1
$ORACLE_HOME/hostname2.domainname_SID2
.
.
$ORACLE_HOME/hostnamen.domainname_SIDn

where <SID1>...<SIDn> are database system identifiers.

However, note that if you upgrade an Oracle 10g Release 2 Oracle RAC database configured with Database Control to Oracle 11g Release 1, the 10g Release 2 Database Control configuration will be retained. Database Control for Oracle10g Release 2 has a Database Console running on each Oracle RAC node. The console is still started on each individual node. If you want to modify this configuration, then use the following command:

emca -reconfig dbcontrol –cluster –EM_NODE <nodename> -EM_SID_LIST <SID list>

where <nodename> is the public name of the node and <SID list> is a comma-separated list of database system identifiers. This command reconfigures the current Database Control setup and:

  1. Starts a Database Control Console on <nodename>, if one has not been started yet.

  2. Redirects the agents monitoring the database instances in <SID list> so that they upload their data to the console running on <nodename>. Also, agents monitoring database instances on <nodename> will also upload their data to the local console. Note that if you do not pass -EM_NODE or -EM_SID_LIST at the command line, you will be prompted for them.

-EM_NODE defaults to the local node if not specified when prompted. -EM_SID_LIST defaults to all database instances if not specified.

You may use this command to start the console on more than one node. For instance, on an 8-node cluster with <node1, node2, node3, node4, node5, node6, node7, node8> and database instances <oradb1, oradb2, oradb3, oradb4, oradb5, oradb6, oradb7, oradb8>, you can run the following commands in succession:

$PROMPT> emca -reconfig dbcontrol –cluster –EM_NODE node1 -EM_SID_LIST oradb2,oradb3,oradb4
$PROMPT> emca -reconfig dbcontrol –cluster –EM_NODE node5 -EM_SID_LIST oradb6,oradb7,oradb8

In this scenario, there will be two Database Control consoles running, one on node1 and the other on node5. From either of these consoles, you can manage and monitor all targets in the cluster.

For information on the current cluster configuration, you can run:

emca -displayConfig dbcontrol –cluster

The above command prompts for the database unique name for the cluster database. This will print the current configuration onto the screen, indicating the nodes that have consoles running on them and the consoles where each agent is uploading.

For configuring Enterprise Manager for a new cluster instance of a database or ASM storage, use the following command:

emca -addInst db

On cluster databases, another common operation is the creation and deletion of database instances. After you create a new instance, you can run EMCA to configure Database Control or central agent management for that instance using the command emca -addInst db. Running EMCA does not create the actual database instance; it only configures Enterprise Manager so that you can manage the instance in a way consistent with the rest of the cluster database instances. When configuring Enterprise Manager for a new instance, run the EMCA command only after you have created the instance. Also, run the command from a node in the cluster that already has Enterprise Manager configured for its associated database instance, as these configuration settings will be propagated to the new instance. Do not run this command from the node on which the new instance was created. Note that this option can be used only in an Oracle RAC environment, so you do not need to use the -cluster option on the command line. After running the command emca -addInst db, enter the following information for the node and database:

Node name: node2
Database Unique Name: EM102
Database SID: EM1022

To deconfigure Enterprise Manager for a specific database instance (typically before the database instance is deleted), use the inverse command, emca -deleteInst db. Running EMCA does not delete the database instance; it only removes the Enterprise Manager configuration so that you will no longer be able to manage the instance with Enterprise Manager. Ensure that you run the EMCA command before you delete the actual cluster database instance. Also, ensure that you run the command from a different node and not from the node on which the database instance will be deleted. Note that this option can be used only in an Oracle RAC environment, so you do not need to use the -cluster option on the command line.

For more information, see Table 21-1 which describes EMCA command-line operations.

Caution:

If you use emca -c to configure the Database Control for Oracle RAC, check TNS_ADMIN on all cluster nodes. If different TNS_ADMIN are set for each node, the listener for the target cannot be configured correctly. If so, set the same TNS_ADMIN on all cluster nodes before executing the emca -c command.

Specifying the Ports Used by EMCA

When you initially install Oracle Databse 11g or configure the Database Control with EMCA, the Database Control uses a set of default system ports. For example, by default, you access Database Control using port 1158 in 11g Release 1, as in:

http://host.domain:1158/em

This is the default port assigned to Database Control by the Internet Assigned Numbers Authority (IANA). Likewise, the default Database Control Agent port, as assigned by the IANA, is 3938.

To use ports other than the default ports, use the following EMCA command-line arguments when you initially configure the Database Control with EMCA. Alternatively, you can explicitly assign ports after configuring Database Control using the following command:

emca -reconfig ports [-cluster]

Note:

You can also use the following EMCA command-line arguments to configure Database Control after you have installed and configured Oracle Database 11g.

The following list summarizes the EMCA command-line arguments that control the standard Database Control port assignments:

  • -DBCONTROL_HTTP_PORT <port_number>

    This port number is used in the Database Control Console URL. For example, if you set this port to 5570, you can then display the Database Control Console using the following URL:

    http://host.domain:5570/em
    
  • -RMI_PORT <port_number>

    This port number is used by the Remote Method Invocation (RMI) system, which is part of the J2EE software required by Database Control. The default port can be changed if the user wants to configure a specific port for Database Console. When a port other than the default port (1521) is used, use the -RMI_PORT or -JMS_PORT options along with the emca reconfig command.

  • -JMS_PORT <port_number>

    This port is used by the OC4J Java Message Service (JMS), which is part of the J2EE software required by Database Control. The default port can be changed if the user wants to configure a specific port for Database Console. When a port other than the default port (1521) is used, use the -RMI_PORT or -JMS_PORT options along with the emca reconfig command.

  • -AGENT_PORT <port_number>

    This port is used by the Database Control Management Agent, which is monitoring and administering the database for the Database Control.

EMCA Troubleshooting Tips

The following section describes some troubleshooting tips to consider when using EMCA to configure the Database Control:

Using EMCA After Changing the Database Listener Port

If you change the listener port of the database after you have configured Database Control, the database status will appear as down. To reconfigure Database Control so it uses the new listener port, run the EMCA command using the -config dbcontrol db [-cluster] command-line arguments.

Upgrading Database or ASM Instances With 11g Release 1 Grid Control Agents

When upgrading a 10g Release 2 database and/or ASM instance that was configured for Oracle Enterprise Manager (either Database Control or a Grid Control central agent) to 11g Release 1, all Enterprise Manager targets on the relevant host(s) referring to the upgraded instance(s) will be updated automatically. This is because the upgrade involves altering the instance's Oracle Home, port, or other target-associated properties. However, some of these targets on the host(s) will not be updated successfully during the upgrade if they are managed by an 11g Release 1 Grid Control Agent. To update these targets, in the Home page for the upgraded database (or ASM) target, click the "Monitoring Configuration" link. On this page, you can update the required properties such as Oracle Home, listener port and so on to the correct values.

Using EMCA When Database Host Name or IP Address Changes

When the database host name (including the domain name) or the IP address changes, deconfigure and then reconfigure the Database Console with the repository create command. Run the following command:

emca -deconfig dbcontrol db -repos drop
emca -config dbcontrol db -repos create

or

emca -deconfig dbcontrol db
emca -config dbcontrol db -repos recreate

Using EMCA When the TNS Configuration Is Changed

When the TNS configuration is changed, set the environment variable and then run the following command:

emca -config dbcontrol db