EMCA REFERENCE : ORACLE ONLINE DOCUMENTS 11.2G
http://docs.oracle.com/cd/E11882_01/server.112/e25494/dbcontrol.htm#ADMIN13418
Table 10-1 EMCA Command-Line Operations
Command Description
emca -h | --h | -help | --help
Use this option to display help messages for the
EMCA utility. The options described in Table 10-1, Table 10-2, and
Table 10-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 re-creating) the 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 Oracle 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 on which 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 Oracle 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 -addNode (db | asm) [-silent] [parameters]
Configures Enterprise Manager for a new cluster
instance of a database or ASM storage. For more information, see
"Using EMCA With Oracle RAC". This option applies only to Release
11g.
emca -deleteNode (db | asm) [-silent] [parameters]
Deconfigures Enterprise Manager for a node being
deleted. For more information, see "Using EMCA With Oracle RAC".
This option applies only to Oracle Database Release 11g.
emca -addInst (db | asm) [-silent] [parameters]
Configures Enterprise Manager for a newly added
cluster instance of an administrator-managed database or Oracle ASM
storage. This parameter takes a SID for the instance being added.
For more information, see "Using EMCA With Oracle RAC".
emca -deleteInst (db | asm) [-silent] [parameters]
Deconfigures Enterprise Manager for a newly
deleted cluster instance of an administrator-managed database or
Oracle ASM storage. This parameter takes a SID for the instance
being deleted. This is discussed further below, in "Using EMCA With
Oracle RAC".
emca -reconfig ports [-cluster] [parameters]
Explicitly reassigns Database Control ports.
Options include performing this operation on a cluster environment.
For more information, see "Specifying the Ports Used by Database
Control".
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, see "Using EMCA With Oracle
RAC".
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, see "Using EMCA With Oracle RAC".
emca -upgrade (db | asm | db_asm) [-cluster] [-silent]
[parameters]
Upgrades the configuration of an earlier release
of Enterprise Manager to the current release. This operation can be
performed for Oracle Database, Oracle ASM, or Oracle Database and
Oracle ASM instances together simultaneously. This does not upgrade
the actual database or Oracle 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 or Oracle ASM target, or both, on the host,
across all Oracle homes (because it is likely that certain target
properties, such as the 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
this operation).
emca -migrate -from dbcontrol -to centralAgent [-repos drop]
[-cluster] [-silent] [parameters]
Migrates the Enterprise Manager configuration
from Database Control to Central Agent.
Table 10-2 EMCA Command-Line Flags
Flag Description
db
Performs the operation for a database (including
cluster databases). Use this option for databases that use Oracle
ASM to store the data files. If a database is using Oracle 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 Oracle ASM instances.
asm
Performs the operation for an Oracle ASM-only
instance (including cluster Oracle ASM instances).
db_asm
This flag can only be used in -upgrade and
-restore mode. Performs the upgrade or restore operation for an
Oracle Database and an Oracle ASM instance together. Database and
Oracle ASM instances may be upgraded or restored separately (that
is, upgrading an Oracle ASM instance does not require upgrading the
database instances it services). Therefore, the Enterprise Manager
configuration can be upgraded or restored separately for a database
and its respective Oracle 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 re-creates a new one.
-cluster
Performs the operation for a cluster database or
Oracle 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_destinitialization 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 10-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, see "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 database hostname.
-LISTENER_OH
Oracle home from which 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 system user name (for automatic
backup).
-HOST_USER_PWD
Host system 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
Oracle ASM Oracle home.
-ASM_SID
System identifier for Oracle ASM instance.
-ASM_PORT
Port number for the listener servicing the Oracle
ASM instance.
-ASM_USER_ROLE
User role for connecting to the Oracle ASM
instance.
-ASM_USER_NAME
User name for connecting to the Oracle ASM
instance.
-ASM_USER_PWD
Password for connecting to the Oracle ASM
instance.
-DBSNMP_PWD
Password for the DBSNMP user.
-SYSMAN_PWD
Password for the SYSMAN user.
-SYS_PWD
Password for the SYS user.
-SRC_OH
Oracle home of the database with Enterprise
Manager configuration to be upgraded or 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, see "Specifying the Ports Used by Database
Control".
-AGENT_PORT
Use this parameter to specify the Management
Agent port for Database Control. For more information, see
"Specifying the Ports Used by Database Control".
-RMI_PORT
Use this parameter to specify the RMI port for
Database Control. For more information, see"Specifying the Ports
Used by Database Control".
-JMS_PORT
Use this parameter to specify the JMS port for
Database Control. For more information, see"Specifying the Ports
Used by Database Control".
-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, see "Using EMCA
With Oracle RAC".
-EM_NODE_LIST
Comma-delimited list of NODEs for agent-only
configurations, uploading data to -EM_NODE. For more information,
see "Using EMCA With Oracle RAC".
-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.
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:
$ ./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 10-1 and enter the following command at the operating system prompt:
$ ./emca -config dbcontrol db -repos create -backup -respFile
input_file_path
Example 10-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
Specifying the Ports Used by Database Control
When you initially install Oracle Database or configure Database
Control with EMCA, Database Control uses a set of default system
ports. For example, by default, you access Database Control using
port 1158, as shown in the following example:
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.
The following list summarizes the EMCA command-line arguments that
control the standard Database Control port assignments:
-DBCONTROL_HTTP_PORT port_number
This port is used in the Database Control Console URL. For example, if you set this port to 5570, you can then use the following URL to display the Database Control Console:
-RMI_PORT port_number
This port 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 you want to configure a specific port for Database Control. 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 , 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 Control. 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.
Using EMCA With Oracle RAC
Each EMCA command can be used in Oracle RAC environments, and
certain commands are only applicable in cluster setups. To perform
cluster commands using EMCA, use the cluster flag that 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 several 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 situation, the Database Control is started only 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 which you can monitor and manage all the targets in the cluster. The following subdirectory is created on each instance of the Oracle RAC database where nodename is the name of a node in the cluster, and dbuniquename is the database instance name of the database for release 11g and later:
$ORACLE_HOME/nodename_dbuniquename
For Oracle Database release 10g, nodename is the name of the node in the cluster and sid is the database instance name:
$ORACLE_HOME/nodename_sid
However, note that if you upgrade an existing Oracle RAC database configured with Database Control to the current release, then the existing Database Control configuration is retained. The existing Database Control has a Database Control running on each cluster node. The console will still be started on each individual node.
To modify the existing configuration in a release 11g and later database, use the following command where nodename is the public name of the node and node_list is a comma-delimited list of nodes where the database is configured:
$ emca -reconfig dbcontrol –cluster –EM_NODE nodename -EM_NODE_LIST
node_list
To modify the existing configuration in a release 10g database, use the following command where nodename is the public name of the node and SID_list is a comma-delimited list of database system identifiers:
$ emca -reconfig dbcontrol –cluster –EM_NODE nodename -EM_SID_LIST
SID_list
Note:
SCAN listener configuration is mandatory when configuring
Database Control in an Oracle RAC environment.
This command reconfigures the current Database Control setup and
performs the following actions in sequence:
Note:
Unless otherwise specified, all command options in the following
actions represent release 11g and later databases. Release 10g
database differences are called out in the sequence.
Starts a Database Control Console on nodename, if one has not been
started yet.
Redirects the agents monitoring the database instances in node_list (SID_list in release 10g of the database) 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 enter the command options -EM_NODE or -EM_NODE_LIST (-EM_SID_LIST for release 10g of the database) at the command line, you will be prompted to enter them.
-EM_NODE defaults to the local node if it is not specified when prompted. If not specified, -EM_NODE_LIST (-EM_SID_LIST for release 10g of the database) defaults to all nodes where the database is configured.
You can use this command to start the console on multiple nodes. For instance, on an 8-node cluster with nodes node1, node2, node3, node4, node5, node6, node7, and node8, you can run the following commands in succession:
$ emca -reconfig dbcontrol –cluster –EM_NODE node1 -EM_NODE_LIST
node2,node3,node4
$ emca -reconfig dbcontrol –cluster –EM_NODE node5 -EM_NODE_LIST
node6,node7,node8
For release 10g databases, run the following commands in succession:
$ emca -reconfig dbcontrol –cluster –EM_NODE node1 -EM_SID_LIST
sid2,sid3,sid4
$ emca -reconfig dbcontrol –cluster –EM_NODE node5 -EM_SID_LIST
sid6,sid7,sid8
In this scenario, there are 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 about the current cluster configuration, run the following command:
$ emca -displayConfig dbcontrol –cluster
The preceding 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.
To configure Enterprise Manager for a newly added node of a cluster, enter the following command:
$ emca -addNode db
To configure Enterprise Manager for a new cluster instance of an administrator-managed database or Oracle ASM storage, enter the following command:
$ emca -addInst db
For Oracle Database release 11g, on cluster policy managed databases another common operation is the addition and deletion of cluster nodes. After you add a new node, you can run EMCA to configure Database Control or central agent management for that node using the command emca -addNode db. Running EMCA only configures Enterprise Manager so that you can manage the instance in a way consistent with the rest of the cluster database instances.
For Oracle Database releases 10g and 11, on cluster databases you can create and delete 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.
On release 11g and later, when configuring Enterprise Manager for a new node, run the EMCA command only after you have added the node. Also, run the command from a node in the cluster that already has Enterprise Manager configured for it, because the Enterprise Manager configuration settings on the existing node are propagated to the new node when you run the command. Because the -addNode option can be used only in an Oracle RAC environment, you do not need to use the -cluster option on the command line.
After running the command emca -addNode db, enter the node name and database unique name for the node and database. For example:
Node name: node2
Database Unique Name: EM102
Similarly in releases 10g and 11g of the database, 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
For release 11g and later, to deconfigure Enterprise Manager for a
specific node you are deleting from the cluster, log in to a
different node from the one you plan to delete, then use the
commandemca -deleteNode db. Running this command removes the
Enterprise Manager configuration so that you will no longer be able
to manage the instance with Enterprise Manager on that node. Ensure
that you run the EMCA command before you delete the actual cluster
node. Because this option can be used only in an Oracle RAC
environment, you do not need to use the -cluster option on the
command line.
For Oracle Database release 10g, 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 10-1 which describes EMCA command line operations.
Note:
If you use the command emca -cluster to configure Database Control for Oracle RAC, then check the TNS_ADMIN environment variable on all cluster nodes. If you have a different TNS_ADMIN set for each node, then the listener for the target cannot be configured correctly. In this case, set the value of TNS_ADMIN the same on all cluster nodes before running the emca -cluster command.
