27.9 EMCTL Commands for Management Agent

Table 27-3 lists the EMCTL commands for Management Agents.

Table 27-3 EMCTL Commands for Management Agent

EMCTL Command Description

emctl start agent

Starts the Management Agent.

On IBM AIX environment with a large memory configuration where the Management Agent is monitoring a large number of targets, the Agent may not start. To prevent this issue, prior to starting the Management Agent, add the following parameters to the common environment file:


The LDR_CNTRL variable sets the data segment size and disables loading of run time libraries in kernel space. The AIXTHREAD_SCOPE parameter changes AIX Threadscope context from the default Processwide 'P' to Systemwide 'S'. This causes less mutex contention.

emctl stop agent

Stops the Management Agent.

emctl status agent

Lists the status of Management Agent.

If the Management Agent is running, this command displays status information about the Management Agent, including the Agent Home, the process ID, and the time and date of the last successful upload to the Management Repository ().

Note: On a Windows system change the directory to the AGENT_INSTANCE_HOME directory before executing the command.

emctl status agent -secure

Lists the secure status of the Mangement Agent and the secure mode port on which the Management Agent is running. It also lists the OMS security status and the port.

emctl status agent scheduler

Lists all the running, ready, and scheduled collection threads.

emctl status agent jobs

Lists the status of the jobs that are running at present on the Management Agent.

emctl status agent target <target name>,<target type>,<metric>

Lists the detailed status of the specified targets such as target name, target type, and so on. You can also provide a particular metric name in the emctl status agent command to get the status of a particular metric of a target.

emctl status agent mcache <target name>,<target type>,<metric>

Lists the names of the metrics whose values are present in the metric cache.

emctl upload

Uploads the .xml files that are pending to the OMS under the upload directory.

emctl upload (agent)

Use this command to force an immediate upload of the current management data from the managed host to the Management Service. Use this command instead of waiting until the next scheduled upload of the data.

emctl reload (agent)

This command can be used to apply the changes after you have manually modified the emd.properties file. For example, to change the upload interval, emd.properties can be modified, and emctl reload can then be run.

Note: Oracle does not support manual editing of the targets.xml files unless the procedure is explicitly documented or you are instructed to do so by Oracle Support.

emctl reload agent dynamicproperties [<Target_name>:<Target_Type>]...

Recomputes the dynamic properties of a target and displays them.

emctl pingOMS [agent]

Pings the OMS to check if the Management Agent is able to connect to the OMS. Management Agent will wait for the reverse ping from the OMS so that Management Agent can confirm that the pingOMS is successful.

emctl config agent getTZ

Configures the current time zone as set in the environment.

emctl config agent getSupportedTZ

Displays the supported time zone based on the setting in the environment.

emctl config console <fileloc> [<EM loc>]

Configures the console based on the configuration entries mentioned in the file <fileloc>.

The <EM loc> parameter is optional and can be used to operate on a different Oracle home.

emctl config agent listtargets [<EM loc>]

Lists all the target names and types monitored by the Management Agent, that are present in targets.xml file.

The <EM loc> parameter is optional and can be used to operate on a different Oracle home.

emctl control agent runCollection <target_name>:<target_type> <metric_name>

Allows you to manually run the collections for a particular metric of a target.

For example, emctl control agent runCollection myOracleHomeTargetName:oracle_home oracle_home_config.

emctl control agent runCollection <targetName>:<targetType> <colletionItemName>

Performs an immediate reevaluation of a metric collection

Executing this command causes the reevaluated value of the metric to be uploaded into the Management Repository, and possibly trigger alerts if the metric crosses its threshold.

To identify the metric name and the collection item name associated with the metric, see Reevaluating Metric Collections Using EMCTL Commands.

emctl resetTZ agent

Resets the time zone of the Management Agent. To change the current time zone to a different time zone, stop the Management Agent and then run this command. You can then start the Management Agent.


Before you change the Management Agent time zone, first check to see if there are any blackouts that are currently running or scheduled to run on any targets managed by that Management Agent. Refer to Viewing Blackouts/Notification Blackouts to know how to check for blackouts.

If any blackouts exist, then from the Cloud Control Console, stop all the scheduled and all the currently running blackouts on all targets monitored by that Management Agent. You can then change the Management Agent's time zone and later create new blackouts on the targets as needed.

emctl getversion agent

Prints the version of the Management Agent.

emctl dumpstate agent <component> . . .

Generates the dumps for the Management Agent. This command allows you to analyze the memory/CPU issues of the Management Agent.

emctl gensudoprops

Generates the sudo properties of the Management Agent.

emctl clearsudoprops

Clears the sudo properties.

emctl clearstate

Clears the state directory contents. The files that are located in the $ORACLE_HOME/sysman/emd/state will be deleted if this command is run. The state files are the files which are waiting for the Management Agent to convert them into corresponding .xml files.

emctl getemhome

Prints the Management Agent home directory.

emctl start blackout <Blackoutname> [-nodeLevel] [<Target_name>[:<Target_Type>]].... [-d <Duration>]

Starts blackout on a target.

If the parameter <Target_name:Target_type> is not entered, then the local node target is taken as the default.If -nodeLevel parameter is specified after <Blackoutname>,the blackout will be applied to all targets and any target list that follows will be ignored.The <Duration> should be specified in [days] hh:mm format.

emctl stop blackout <Blackoutname>

Stops the blackout that was started on a particular target. Only those blackouts that are started by the emctl tool can be stopped using emctl. This command cannot stop the blackouts that are started using the console or em cli utility.

emctl status blackout [<Target_name>[:<Target_Type>]]....

Provides the status of the target blackout. The status includes the type of blackout and whether it is a one-time action, or repeating, or a scheduled blackout. This command also specifies whether the blackout has started or stopped.

emctl secure agent [registration password] -emdWalletSrcUrl <url> -protocol <ssl|tls>

Secures the Management Agent with an OMS. The registration password is essential, as you will be prompted for it if you do not provide it along with the command.

The -emdWalletSrcUrl parameter indicates the URL of the OMS with which the agent has to be secured.

The -protocol parameter indicates the protocol to be used to secure the Management Agent. The allowed values are ssl and tls.

emctl unsecure agent

Un-secures the Management Agent. This command changes the Management Agent's port to a HTTP port. After executing this command the Management Agent will be able to upload to the OMS on HTTP by connecting to OMS's HTTP upload port instead of the HTTPS upload port.

emctl verifykey

Verifies the communication between the OMS and Management Agent by sending pingOMS.

emctl deploy agent [-s <install-password>] [-o <omshostname:consoleSrvPort>] [-S] <deploy-dir> <deploy-hostname>:<port> <source-hostname>

Creates and deploys only the Management Agent.

The parameters are explained below:

  • [-s <password>]: Indicates the install password for securing the Management Agent.

  • [-S ]: Indicates that the password will be provided in STDIN.

  • [-o <omshostname:consoleSrvPort>]: Indicates the OMS host name and the console servlet port. Choose the un-secured port.

  • <deploy-dir>: Indicates the directory to create the shared (state-only) installation port.

  • <deploy-hostname:port>: Indicates the host name and the port of the shared (state-only) installation. Choose an unused port.

  • <source-hostname>: Indicates the host name of the source install. Typically, it is the machine where the EM is installed. The host name is searched for and replaced in the targets.xml file with the host name provided in the argument <deploy-hostname:port>.

  • <sid>: Indicates the instance of the remote database. It is only specified when deploying the dbconsole.

emctl setproperty agent

Configures the specified property name and value in the Management Agent configuration file. The flag, allow_new is an optional flag that inserts a new property in the Management Agent configuration file, if it does not exist.

emctl getproperty agent

Gets the specified properties or a category of properties from the Management Agent configuration files. Currently, this command does not support spaces in the name. The flag, -name provides a list of property names separated by spaces.

emctl clear_property agent

Clears the value of the specified property in the Management Agent configuration file.

emctl status agent verify

Verifies that the Management Agent is live.