Using Enterprise Manager from the Command Line

Using the Oracle Enterprise Manager from the Command Line

The Oracle Enterprise Manager (OEM) is a powerful tool. But especially managing many targets can become a tedious task when one has to walk its menus. Luckily, there are command-line tools to ease these: the agents' emctl on the target machines, and OEMs emcli on the management machine.

Setting up

To make them easier available, you'll want to include them with your PATH environment variable, or create suitable aliases. Note that especially with emctl, you'll prefer dedicated aliases, as this binary might exist in multiple locations (e.g. on the OEM machine, there's one emctl for the agent and another one for the OMS).

Locations are $ORACLE_BASE/mw/bin for OMS, and $AGENT_HOME/bin for the agent. So aliases could look like:

alias emcli=$ORACLE_BASE/mw/bin/emcli               # OMS emcli
alias omctl=$ORACLE_BASE/mw/bin/emctl               # OMS emctl
alias amctl=$ORACLE_BASE/agent/agent_inst/bin/emctl # Agent emctl

Before you can use emcli conveniently, you will have to tell it what OMS server to connect to (by default, this is done on install – but when below login fails and you see a HTTP exception in the logs, it might have been skipped):

emcli setup -url="https://localhost:7799/em" -username=sysman

This example assumes the OMS server you want to manage runs on the same host you're using emcli on – which usually is the case. You might need to adjust the port (the same one you use to login to the OEM console with your browser). The command will prompt you for the sysman password and then, provided all worked well, will confirm your setup.

In the future, at the begin of each session (as well as after the timeout), you will have to login from the command line:

emcli login -username=sysman

After that, you're ready to use it – and when done, emcli logout again (or wait for the timeout).

Listing targets

emcli get_targets                               # list ALL targets the OMS knows of
emcli get_targets -targets="oracle_database"    # list specific targets of the OMS
emctl config agent listtargets                  # using agent's emctl, list what the agent knows

These listings are not just useful if you want to manipulate targets and see their correct names first – but also if you want to quickly examine (all) your targets' status. Here's some example output:

$ emcli get_targets -targets="oracle_database"
Status  Status           Target Type           Target Name
 ID
1       Up               oracle_database       ORCL1
1       Up               oracle_database       SALESDB
1       Up               oracle_database       WAREHOUS

The Target Name of this output is what you need to manipulate the target with.

Adding targets

Should the agent fail to detect it even when explicitly triggered for a discovery (well, that happens more often than expected), this can still be done via the OEM WebUI strangely. So it should be possible via emcli as well:

emcli add_target -name="name" -type="type" [-host="hostname"]
        [-properties="pname1:pval1;pname2:pval2;..."]...
        [-credentials="userpropname:username;pwdpropname:password;..."]
        [-monitoring_creds="HostCredsPriv;host;HostCreds;HostUserName;foo;..."]

-type: host, oracle_database, oracle_apache, oracle_listener, oracle_emd
-host: where the collecting agent runs
-properties: name-value pairs of properties for the target
-credentials: the monitoring credentials

Some examples, to make this easier to follow:

# adding an $ORACLE_HOME:
emcli add_target -name="OraDb11g_home1_1_myhost.example.com" -type="oracle_home" -host="myhost.example.com" \
 -properties="HOME_TYPE:O;INSTALL_LOCATION:/u01/app/oracle/product/11.2.0/dbhome_1;INVENTORY:/u01/app/oraInventory"
# adding a database:
emcli add_target -name="database" -type="oracle_database" -host="myhost.example.com" \
 -credentials="UserName:dbsnmp;password:dbsnmp;Role:Normal" \
 -properties="SID:semcli;Port:15091;OracleHome:/oracle;MachineName:smpamp-sun1.example.com"
# adding a listener (ListenerOraDir is where the listener.ora resides):
emcli add_target -name="mylist" -type="oracle_listener" -host="myhost.example.com" \
 -properties="LsnrName:LISTENER;ListenerOraDir:/oracle/lsnr" \
 -properties="Port:15091;OracleHome:/oracle;Machine:smpamp-sun1.example.com"

This is just a simplified version – for more options, please call emcli help add_target.

Deleting targets

Sometimes you have to remove targets from your OEM – e.g. when a database or an entire server has been decomissioned. In the latter case this might affect multiple targets at once, so you'll be glad not having to jog through all those menus in the OEM console multiple times:

# delete listener from OMS:
emcli delete_target -name="<LISTENER NAME>" -type="oracle_listener"
# delete DB from OMS:
emcli delete_target -name="<DB NAME>" -type="oracle_database"
# delete an entire agent including all its targets:
emcli delete_target -name="<Agent HOSTNAME>.<DOMAINNAME>:3872" -type="oracle_emd" \
 -delete_monitored_targets -async

# delete listener from Agent (using the agent's emctl):
emctl config agent deletetarget oracle_listener <LISTENER NAME>
# delete an (expired) ORACLE_HOME from Agent (again, using the agent's emctl):
emctl config agent deletetarget oracle_home <ORACLE_HOME NAME>

Modifying target properties

This comes in handy e.g. if you use „Golden Images“ for offsite patching – after which your databases end up in a different $ORACLE_HOME. Instead of jogging through the WebUI menus to modify each target, there's again a nice emcli command for that:

# you've moved a database to a new $ORACLE_HOME (e.g. after deploying a „Golden Image“):
emcli modify_target -type='oracle_database' -name='<DB NAME>' -properties='OracleHome:<NEW $ORACLE_HOME PATH>'

User Management

You can create a new user, assign her/him roles and privileges, all with a single call:

emcli create_user -name="<username>" [-password="password"] [-desc="user_description"] \
  [-expired=true] [-roles="role1;role2;..."] [-privilege="name[;secure-resource-details]]"]

There are several more options to this (see emcli help create_user), but these are the ones you will need most often. The first three are self-explaining, the forth is to force the user to change the password at first login. Which roles are available depends on what you've set up. For a list of available privileges, you can execute emcli get_supported_privileges. Here comes a simple example:

emcli create_user -name="john" -password="secret"] [-desc="John Doe Test-User"] \
  -expired=true -roles="public;test_role" \
  -privilege="view_target;TARGET_NAME=host1.us.example.com:TARGET_TYPE=host"

The -privilege option can be used multiple times in the same run, e.g. to grant access to different targets. More examples are shown at the end of the output from emcli help create_user.

If lateron the user/role shall get (rid of) additional privileges, that can be done using emcli as well:

emcli grant_privileges -name="<username>" -privilege="name[;secure-resource-details]]"
emcli grant_roles -name="<username>" -roles="role1;role2;..."
emcli revoke_privs -name="username|rolename" [-privilege="name[;secure-resource-details]]"
emcli revoke_roles -name="username/rolename" -roles="role1;role2;..."

Roles are created like users:

emcli create_role -name="role_name" [-description="description"] \
        [-roles="role1;role2;..."] [-users="user1;user2;..."] \
        [-privilege="name[;secure_resource_details]]"

With the -users option you can directly assign it to the specified users upon creation.

To modify existing users/roles, you can use the modify_user resp. modify_role verbs – which accept the same commands as their create_ counterparts. Only options you specify are changed, all others are kept. You don't want to use this to add/remove privileges or roles from a user or role, as then you'd have to specify those you want to keep as well; for this, better use the grant_/revoke_ verbs.

Wanna get rid of them again?

emcli delete_role -name="role_name"
emcli delete_user -name="user_name"

Blackouts

For maintenance reasons, you might want to create/stop blackouts easily. Again, a simplified variant here, and see emcli help <verb> for advanced options:

emcli create_blackout -name="name" -add_targets="name1:type1;name2:type2;..."... \
      -reason="reason" [-description="description"] \
      [-notification_only] [-propagate_targets] [-dep_services_all]
emcli stop_blackout -name="name"
emcli get_blackouts [-target=<name1:type1> | -hostnames=<host1;host2;...>]

-notification_only: keep monitoring, but don't send out alerts. Blackout duration is excluded from Availability(%) calculations.
-propagate_targets: with this, you just need to specify the host in -add_targets – and all dependent services (e.g. databases running on that host) are blacked-out as well.
-dep_services_all: black out all targets depending on the blacked-out target (so in our host example, even if they run on another host)

Clear error status

Sometimes OEM shows errors which do not (or no longer) exist – like a database instance being down despite it isn't, and OEM even successfully connects to it when checking the monitoring configuration. These status can be cleared by the local agent (i.e. the agent running on the database host, not the one on the management server), using the emctl clearstate agent command (optionally with the agent down):

emctl stop agent                                # optional
emctl clearstate agent                          # clear all status
emctl clearstate agent mydb,oracle_database     # for a specific target only; multiple:
emctl clearstate agent mydb,oracle_database listener_example.com,oracle_listener
emctl clearstate agent mydb,oracle_database,Response    # special case ¹
emctl start agent                               # when initially stopped
emctl upload agent                              # force it to sync with OMS

Similarly, incidents can be cleared from the command line if the WebIF refuses doing so. To generate the corresponding commands, one can run the following SQL as sysman on the EM database:

select t.target_name, i.severity, i.incident_num, i.creation_date, i.summary_msg
       , 'emcli delete_incident_record -incident_number_list="'||i.incident_num||'" -force' as clear_cmd
  from sysman.mgmt$target t, sysman.mgmt$incidents i
 where i.resolution_state != 'Closed'
   and i.addr_related != 1
   and i.target_guid = t.target_guid
   and i.creation_date < to_date(sysdate -30)
 order by 4 asc;

You can replace -force by -preview if you want to check first.

¹ This is a specific case documented in MOS note 1535613.1 („How to Troubleshoot Incorrect Database Instance Status (Up, Down) in Enterprise Manager Cloud Control“). Note that from the code box above, you usually need only one of the emctl clearstate agent commands, not all of them in a row – they are just multiple examples.

More commands

As this is a scratchpad, it just scratched at the surface – there are many more commands available. You can find them, grouped by „categories“ and also alphabetically by verb („command name“), for example in this verb reference (for OEM 13.3) – or here (12.1).

For more help on troubleshooting OEM, also see MOS note 1535613.1 („How to Troubleshoot Incorrect Database Instance Status (Up, Down) in Enterprise Manager Cloud Control“).

2022-07-26

IzzySoft