EM CLI is ideally suited for shell scripts, but it also simplifies tasks that are ordinarily performed in the console. For instance, removing an EM agent and its related targets through the console can be quite trying. With EM CLI, you issue a one-line command and the same tasks execute quickly and completely from the command line.

This chapter will introduce you to some of the basics of EM CLI at the command line and then illustrate several ways you can apply EM CLI to administering your environment more quickly—without all the mouse clicks required to perform the same tasks in the console.

We often associate the term “command line” with Unix, and that’s applicable here too, but do remember that since EM CLI is a Java application it can be run on any platform.  EM CLI runs the same whether you’re logged into a server or executing the commands from your desktop.

Start an EM CLI Session

Although each CLI command is run on a separate line, when logging into EM CLI a single session is established for all subsequent statements. The login verb establishes a connection to the OMS server and validates the user before any work starts. You may either enter your password on the command line (not recommended for interactive sessions) or wait to be prompted for the password during the login process.

The sync command ensures that your run-time execution uses the current verb definitions available in the management server’s software library. This is particularly important after you’ve patched or upgraded your OMS.

emcli login -username="SYSMAN"

emcli sync

CLI References

Oracle document #E17786.12 contains a catalog of the EM CLI verbs available with the release of OEM 12.1.0.4. Check with Oracle at http://docs.oracle.com/cd/E24628_01/em.121/e17786.pdf to make sure you have the latest version.

Help is also available online through EM CLI itself. The current listing of verbs known to your OMS software library is available at the command line.

emcli help

> emcli help

Summary of commands:   argfile    -- Execute emcli verbs from a file
    help       -- Get help for emcli verbs (Usage: emcli help [verb_name])
    login      -- Login to the EM Management Server (OMS)
    logout     -- Logout from the EM Management Server
    setup      -- Setup emcli to work with an EM Management Server
    status     -- List emcli configuration details
    sync       -- Synchronize with the EM Management Server
    version    -- List emcli verb versions or the emcli client version

  Add Host Verbs
    continue_add_host             -- Continue a failed Add Host session
    get_add_host_status           -- Displays the latest status of an Add Host session.
    list_add_host_platforms       -- Lists the platforms on which the Add Host operation can be performed.
    list_add_host_sessions        -- Lists all the Add Host sessions.
    retry_add_host                -- Retry a failed Add Host session
    submit_add_host               -- Submits an Add Host session.

  Agent Administration Verbs
    get_agent_properties     -- Displays details of all properties of an agent
    get_agent_property       -- Displays the value of specific property of an agent
    resecure_agent           -- Resecure an agent
    restart_agent            -- Restart an agent
    secure_agent             -- Secure an agent
    set_agent_property       -- Modify specific property of an agent
    start_agent              -- Start an agent
    stop_agent               -- Shut down an agent
    unsecure_agent           -- Unsecure an agent
...

Add the name of a verb to the help command for specific guidance on that verb. The example below shows the help result for the sync verb.

> emcli help sync
  emcli sync

  Description:
Synchronize the emcli client with the OMS.

    After synchronization, all verbs and associated online help
    available to that OMS become available at the emcli client.
    Synchronization automatically happens during a call to a setup.
  Options:
    -url
        The URL of the EM (OMS).
        Both http and https protocols are supported
        (https is recommended for security reasons).
    -username
        The EM username to be used by all subsequent emcli commands
        when contacting the OMS.
    -password
        The EM user's password.
        If this option is not specified, the user is prompted
        for the password interactively.
        Providing a password on the command line is insecure and
        should be avoided.
    -trustall
        Automatically accept any server certificate from the OMS,
        which results in lower security.
        Also indicates that the setup directory is local and trusted.

The get_targets Verb

EM CLI verbs fall into three broad categories: EM queries, OEM administrative actions, and target manipulations. Verbs use a very specific syntax, so the names of targets being passed to EM CLI must match the object’s name in OEM’s dictionary.

The get_targets verb can be used to verify the target name prior to its use in any administrative or maintenance task. For instance, let’s say you want to create a blackout for database orcl1 on host myhostx and that you promote discovered database and listener targets through the automated process. The database target in OEM may have been added as sidc_myhostx, by its RAC instance name, or perhaps by its global name. Sometimes it may even appear as its service name or SID. This variability can occur when you use target promotion through Auto Discovery Results. You should set target names manually when you add targets, using the guided discovery process to ensure consistency across your enterprise.

Output Formats

EM CLI has three preconfigured output formats for query results. User-defined formats are also supported.

• Pretty format aligns the column headings with the result-set data.
• Script format separates the values in the heading and results columns with a space. This format works very well with the awk programming language.
• Csv format, as the name suggest, separates the values with a comma for parsing in a spreadsheet or with the shell’s cut command.

Let’s say you want to set the OEM credentials for the eamz database using this command:

emcli set_credential -target_type=oracle_database -target_name="eamz" 
                     -credential_set=DBCredsNormal 
                     -columns="username:dbsnmp;password:Super_S3cret;role:Normal"

Your command would fail because OEM can’t find a matching target name. Figure 4-1 illustrates the different styles.

emcli get_targets -targets="oracle_database" -format="name:csv" | grep -i eamz

We’ll explore several examples of applying this verb later in this chapter as well as in the next.

Agent Administration

The ability to install the EM CLI client on your desktop allows you to execute an EM CLI command without opening a browser—no need to use the console or log into the management server host. This flexibility allows you to quickly control the OEM agents using one of the many EM CLI verbs related to them.

As we saw earlier, you can use the get_targets verb to find the specific name of any agent by filtering the get_targets results for target type oracle_emd. This is particularly important for agents, since the agent name contains the host name and port number.

> emcli  get_targets –targets="oracle_emd"  –name="name:csv"
Status ID,Status,Target Type,Target Name
1,Up,oracle_emd,acme_dev:2480
1,Up,oracle_emd,acme_qa:3872
1,Up,oracle_emd,acme_prod:3872

The targets variable also accepts paired values that include the target name and target type, like this:  –targets=“acme_qa:oracle_database”

All of the agent-management tasks available through the OEM console are also available as EM CLI verbs. Notice in these examples that the password is required for the OEM agent binary owner/host user in every case.

emcli stop_agent  -agent=acme_qa:3872 -host_username=oracle
Host User password:
The Shut Down operation is in progress for the Agent: acme_qa:3872
The Agent "acme_qa:3872" has been stopped successfully.

emcli start_agent  -agent=acme_qa:3872 -host_username=oracle
Host User password:
The Start Up operation is in progress for the Agent: acme_qa:3872
The Agent "acme_qa:3872" has been started successfully.

emcli restart_agent  -agent=acme_qa:3872 -host_username=oracle
Host User password:
The Restart operation is in progress for the Agent: acme_qa:3872
The Agent "acme_qa:3872" has been restarted successfully.

Agents sometimes fall out of sync with the OMS after patching or as a result of an outage and thus require an update to their registration information or even an agent synchronization in order to permit uploads. The easiest way to achieve this is to resecure the agent to straighten out the connection. If your environment does not require secured agents, you can remove the secure relationship by executing the unsecure_agent verb with identical syntax to the secure_agent verb.

Notice that the password for the owner of the agent executable and the OMS registration password are both required.

emcli secure_agent  -agent=acme_qa:3872 -host_username=oracle
Host User password:
Registration Password:
The Secure operation is in progress for the Agent: acme_qa:3872
The Agent "acme_qa:3872" has been secured successfully.

emcli resecure_agent  -agent=acme_qa:3872 -host_username=oracle
Host User password:
Registration Password:
The Resecure operation is in progress for the Agent: acme_qa:3872
The Agent "acme_qa:3872" has been resecured successfully.

The agent_resync verb kicks off a job in the repository database to update the status of a blocked agent. An agent is placed in blocked status when the repository contains conflicting data from the agent upload. This typically happens after unscheduled issues affect the agent connection to the OMS. As a result, standard output isn’t informative at the command line. While you can click through to the job in the console to track the progress, there is no matching option in EM CLI.

emcli resyncAgent -agent=acme_qa:3872
Resync job RESYNC_20140422135854 successfully submitted

EM CLI can also be used to provide detailed information about an agent, either listing all of its properties or drilling down to a specific property, as shown below.

emcli get_agent_properties -agent_name=acme_qa:3872
Name                        Value
agentVersion                12.1.0.3.0
agentTZRegion               America/Los_Angeles
emdRoot                     /opt/oracle/agent12c/core/12.1.0.3.0
agentStateDir               /opt/oracle/agent12c/agent_inst
perlBin                     /opt/oracle/agent12c/core/12.1.0.3.0/perl/bin
scriptsDir                  /opt/oracle/agent12c/core/12.1.0.3.0/sysman/admin/ scripts
EMD_URL                     https://acme_qa:3872/emd/main/
REPOSITORY_URL              https://myoms.com:4903/empbs/upload
EMAGENT_PERL_TRACE_LEVEL    INFO
UploadInterval              15
Total Properties :          10

emcli get_agent_property -agent_name=acme_qa:3872 -name=agentTZRegion
Property Name: agentTZRegion
Property Value: America/Los_Angeles

Deleting EM Targets with EM CLI

The delete_targets verb can be used to remove individual targets or a group of related targets. It may seem simpler to select targets individually from the console and press the Delete Target button. That’s usually true, but we’ve found that under some conditions it’s possible to end up with orphaned targets, like an oracle_dbsys target type left behind when all its fellow members were deleted. Besides, if you have an EM CLI client installed on your desktop you can remove the target without logging into the console!

Let’s first look at an example of removing an individual target. Let’s say that database bertha was finally retired, and so was the related listener  LSNRBERTHA. Both of them belong to an oracle_dbsys target type.¹

Find Exact Target Names

The console derives target names and target types from session information, so target deletion within the console is sure to use the exact name and target type for both of these targets. To find those values, we’ll use the get_targets verb and a simple grep to distinguish the targets we’re interested in.

> emcli get_targets | grep -i bertha
1       Up               oracle_database    bertha
1       Up               oracle_dbsys         bertha_sys
1       Up               oracle_listener       LSNRBERTHA_oemdemo.com

Delete the Target

The database and listener both belong to the database system bertha_sys, so all three can be deleted with one command:

> emcli delete_target –type = "oracle_db_sys" –name="bertha_sys" –delete_members
  Target "bertha_sys:oracle_dbsys" deleted successfully

You can also delete individual members, like this:

> emcli delete_target –type = "oracle_listener" –name="LSNRBERTHA"
  Target "LSNRBERTHA:oracle_listener" deleted successfully

How to Remove an Enterprise Manager Agent with One Command

Removing an EM agent from Enterprise Manager requires removal of all the targets managed by that agent and all of their metrics. In the console, this requires multiple deletion actions in roughly reverse order of their discovery. For instance, when you first deploy an agent to a host, the agent and host become the first and second targets known. Then you discover and promote other targets residing on the host.

Monitored targets are removed in the reverse order of discovery so that referential data can be removed properly from the repository database. Target removal must start with the discovered/promoted targets, then the host, and finally the agent.

The delete_targets verb removes the agent and its monitored targets in just one command if you use the delete_monitored_targets flag.

> emcli delete_target -name="<Agent Name>"
  -type="oracle_emd"
  -delete_monitored_targets
  -async;

The process for deleting the agent target type is very similar to that for removing other target types. Since agent names consist of the host name and agent port number, we’ll run get_targets first.

> emcli get_targets | grep -i demohost01
1       Up               host                     demohost01
1       Up               oracle_emd          demohost01:3872

> emcli delete_target -name="demohost01:3872" -type="oracle_emd" -delete_monitored_targets -async;
Target "LSNRBERTHA:oracle_listener" deleted successfully

Complete removal of the agent involves activities on the management server (OMS) as well as work on the remote host. See Table 4-1.

Transferring Targets to Another EM Agent

Changes happen. Perhaps you’ve decided to move a database to a different host or you want to change the directory containing your EM agent binaries. You could drop and rediscover the targets, but you’d lose their metric history.

You can retain that history and reassign metric collection and blackout responsibility for specific targets to another EM agent using the relocate_targets verb.

How It Works

Each EM agent has its own targets.xml file located in $AGENT_BASE/agent_inst/sysman/emd. The relocate_targets verb updates those XML files on the source and destination hosts and also updates the relationships in the repository.

The agent and the targets it monitors must reside on the same host. That means that you can’t use relocate_targets to monitor databases through an agent on a different host. This technique is limited to moving targets to an EM agent on the same host or to performing a migration task to another server. Let’s look at an example.

To move goldfish database and its listener from the alice server to buster:

emcli relocate_targets
  -src_agent="alice:3872"
  -dest_agent="buster:3872"
  -target_name="goldfish"
  -target_type="oracle_database"
  -copy_from_src

emcli relocate_targets
  -src_agent="alice:3872"
  -dest_agent="buster:3872"
  -target_name="lsnrgoldfish"
  -target_type="oracle_listener"

For the transfer you’d use these values:

• src_agent= alice:3872        (current agent name)
• dest_agent= buster:3872  (destination agent name)
• target_name= goldfish      (name of the target to move)
• target_type= EM types for that target

Database targets also include the copy_from_src flag in order to retain their history. You can only relocate one target per EM CLI command.

OMS-Mediated Targets

Do not use the relocate targets verb with RAC databases or Oracle clusters of any type. Your management server knows about the relationships between clustered objects that use Oracle software and will mediate agent responsibilities automatically across the clustered hosts. If you manually relocate a clustered target to another agent in another cluster you run the risk of corrupting OEM’s associations between the cluster members.

You can query the repository database to determine which targets are OMS mediated as follows:

SELECT   entity_type,
         entity_name,
         host_name
FROM     sysman.em_manageable_entities
WHERE    manage_status =2-- Managed
AND      promote_status =3-- Promoted
AND      monitoring_mode =1-- OMS mediated
ORDERBY  entity_type,entity_name, host_name;

ENTITY_TYPE                ENTITY_NAME                            HOST_NAME
-------------------------  -------------------------------------  --------------------
cluster                    clust01                                cluster01b.com
cluster                    clust01                                cluster01b.com
rac_database               apple                                  cluster01b.com
rac_database               betty                                  cluster01a.com
rac_database               jack                                   cluster01b.com
weblogic_domain            /EMGC_GCDomain/GCDom                   myoms.com
weblogic_domain            /Farm01_IDMDomain/ID                   myoms.com
weblogic_domain            /Farm02_IDMDomain/ID                   myoms.com

Managing OEM Administrators

The console provides a clear, convenient method for managing OEM administrator accounts, but its flexibility makes it tremendously inconvenient for creating multiple accounts as you click through all the screens. EM CLI combines the flexibility inherent in the OEM codebase with the simplicity of the command-line interface.

All of the options defined in the console can be granted as options in EM CLI using the flags shown below. To create an administrator you only need to give the account a name and password.

emcli create_user -name="SuzyQueue" -password="oracle"

You wouldn’t be reading a book from Apress if you were one to ignore user security, so you’ll want to expire the user’s new password with the -expired="true" flag, like this:

emcli create_user -name="SuzyQueue" -password="oracle" -expired="true"

Other optional parameters allow you to perform most of the user grants available in the OEM console but without the click-stream. Both EM CLI and the OMS server use the same codebase, so this should come as no surprise.

Role Management

Enterprise Manager administrators and users are stored as database user accounts in the repository database. Resist the temptation to grant role privileges through SQL*Plus, since there may be other actions being performed by OEM’s internal security management.

You can add role grants while creating the user by adding the -roles parameter:

emcli create_user -name="SuzyQueue" -password="oracle" 
                                    -roles="em_all_administrator"

You can also modify the user through the grant_roles or revoke_roles verbs:

emcli grant_roles -name="SuzyQueue" -roles="em_all_viewer"

emcli revoke_roles -name="SuzyQueue" -roles="em_all_operator"

We’ll discover how to build out a set of administrators using shell scripts in the next chapter.

Tracking Management Server Login

Occasionally you may want to know who is logged in to your management servers. The list_active_sessions verb provides that information with details if you pass the –details flag, like this:

emcli list_active_sessions -details

OMS Name: myoms.com:4889_Management_Service
Administrator: SYSMAN
Logged in from: [email protected]
Session: F7CA6D7DE88B0917E04312E7510A9E54
Login Time: 2014-04-24 06:46:53.876687

OMS Name: myoms.com:4889_Management_Service
Administrator: BOBBY
Logged in from: [email protected]
Session: F7CD5C7EE0A961C7E04312E7510A8A71
Login Time: 2014-04-24 11:05:24.199258

OMS Name: myoms.com:4889_Management_Service
Administrator: PHIL
Logged in from: [email protected]
Session: F7CECDD6335543E3E04312E7510AA25C
Login Time: 2014-04-24 11:13:20.567234

OMS Name: myoms.com:4889_Management_Service
Administrator: SYSMAN
Logged in from: [email protected]
Session: F7CF52CA3BE1692FE04312E7510A7494
Login Time: 2014-04-24 11:50:31.152683

OMS Name: myoms.com:4889_Management_Service
Administrator: SYSMAN
Logged in from: [email protected]
Session: F7CF52CA3BE3692FE04312E7510A7494
Login Time: 2014-04-24 11:55:52.482938

OMS Name: myoms.com:4889_Management_Service
Administrator: SYSMAN
Logged in from: [email protected]
Session: F7CF52CA3BE5692FE04312E7510A7494
Login Time: 2014-04-24 12:07:52.335728

Summary

EM CLI allows you to perform many administrative tasks from the command line and even on your desktop. The simple techniques described in this chapter lend themselves handily to shell scripting and further automation, as described in the following chapter.

_____________________

¹There are several target types in your environment. During its installation, the EM agent discovers the targets on the host and associates them with specific target types. A new Oracle Home is created and the appropriate plug-in is installed for each target type identified. The labels of each target type are fixed, and each target is associated with one and only one target type.