Architecture
Oracle Enterprise Manager 12c provides a scalable and reliable central repository, a console, and services for managing your all of your Oracle products. Users typically interact with OEM through the OEM console, which has a rich intuitive graphical interface.
The Enterprise Manager Command-Line Interface (EM CLI) provides access to OEM system functionality outside of the console. Interactive EM CLI tasks can replace lengthy click-streams in defining EM administrator accounts and roles, as one example of its usefulness. EM CLI interactive commands can be used in shell scripts or can be CLI invoked through CLI’s own scripting mode in Jython.
This book explores different ways you can apply these techniques to simplify and automate tasks in your Oracle environment.
Enterprise Manager Framework
The Oracle Enterprise Manager application runs as a JEE application in a WebLogic Server J2EE domain on a WebLogic server. This combination is known as the Oracle Management Server, or OMS.
Java processes running on the OMS gather and process XML file uploads that come from EM agents on your remote hosts. That information is posted to a repository database, where it is stored in the SYSMAN schema.
When you view a page on your OEM console, the data is assembled from the repository database for presentation. In the same way, commands that you issue from the console are processed through the OMS to update repository information (metric collection or notifications, for instance) or manipulate managed targets either through a call to the EM agent or through an authenticated connection to a remote database or host.
Each command issued by the console executes a Java program. The console solicits and assembles data as well as the input commands required for those routines to execute. Much of the manipulative and query code base can be accessed through EM CLI.
The EM CLI program is itself a lightweight Java program that performs the same activities as the console pages but runs an immediate execution of OMS modules using values passed as command-line inputs; it is often employed in shell scripts or Jython programs.
EM CLI Verbs
Interface commands are referred to as verbs. Each verb performs a single task and either succeeds with reasonable feedback or comes back with a quick and obvious failure message.
Many verbs require input values on the command line. As with a PL/SQL package, your input must be passed to the OMS using very specific syntax. The values are always preceded by a filter keyword, and most input requires your strings to be wrapped in double-quotes.
Note The authors’ experiences using quotation marks have been mixed. They are recommended, but often aren’t required. We’ll use them for clarity in our examples. You may find that you don’t always need them, or that you prefer not to use them.
Use the get_targets verb to display or capture a list of the targets in your environment, as follows:
emcli get_targets
To find only Oracle database targets you’d filter your request with the targets keyword:
emcli get_targets -targets="oracle_database"
Numerous examples throughout this book demonstrate how verbs and input values are applied. A catalog of EM CLI verbs and their syntax is available in Oracle Support document E17786-x. Be aware that some verbs are tied to management packs that require licensing fees. You can also find online help at the command-line that lists all of the verbs available and their intended use. For example:
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.
...
The help verb can be filtered with specific verbs to display detailed usage instructions:
emcli help get_targets
emcli get_targets
[-targets="[name1:]type1;[name2:]type2;..."]
[-alerts]
[-noheader]
[-script | -format=
[name:<pretty|script|csv>];
[column_separator:"column_sep_string"];
[row_separator:"row_sep_string"];
]
[-config_search="Configuration Search UI Name"]
[-unmanaged]
Description:
Obtain status and alert information for targets.
Options:
-targets=name:type
Name or type can be either a full value or a pattern match
using "%". Also, name is optional, so the type may be
specified alone.
-config_search="Configuration Search UI Name"
Search UI Name should be the display name of the configuration search.
-alerts
Shows the count of critical and warning alerts for each target.
-noheader
Display tabular output without column headers.
-script
This option is equivalent to -format="name:script".
-format
Format specification (default is -format="name:pretty").
-format="name:pretty" prints the output table
in a readable format but is not intended to be parsed by scripts.
-format="name:script" sets the default column separator
to a tab and the default row separator to a newline.
The column and row separator strings may be specified
to change these defaults.
-format="name:csv" sets the column separator to a comma
and the row separator to a newline.
-unmanaged
Get unmanaged targets (no status or alert information)
Output columns:
Status ID Status Target Type Target Name Critical Warning
Examples:
emcli get_targets
Shows all targets. Critical and Warning columns are not shown.
emcli get_targets
-alerts
Shows all targets. Critical and Warning columns are shown.
emcli get_targets
-targets="oracle_database"
Shows all "oracle_database" targets.
emcli get_targets
-targets="%oracle%"
Shows all targets whose type contains the string "oracle".
emcli get_targets
-targets="database%:%oracle%"
Shows all targets whose name starts with "database" and type
contains "oracle".
emcli get_targets
-targets="database3:oracle_database"
-alerts
Shows status and alert information on the Oracle database named
"database3".
emcli get_targets
-config_search="Search File Systems on Hosts"
-targets="oracle%:host"
-alerts
Shows status and alert information of the resulting targets from
configuration search named "Search File Systems on Hosts" and targets
whose name starts with "oracle" and of type "host".
emcli get_targets
-targets="host"
-unmanaged
Shows name and type information for unmanaged host targets.
EM CLI Client Software
The basic OEM installation on a management server preconfigures an EM CLI client as part of OMS Oracle Home. In Chapter 2 we’ll show you how to upgrade that client to the EM CLI Advanced Kit.
Part of EM CLI’s strength comes from its flexibility. In addition to the client installation on the OMS server, you can install the EM CLI client on a non-OMS host or even on your desktop.
Installing the EM CLI client consists of downloading and extracting an installation jar file in order to install the binaries, and then configuring the client with connection information for your OMS server. The jar file and installation for its use are available through the OEM console under Setup > Command-Line Interface. Follow the instructions on that web page to install the EM CLI to your workstation.
EM CLI and EMCTL
Several EM CLI functions can be performed through the Agent Control utility EMCTL. Your choice of technique depends on a combination of factors.
- EM CLI client must be manually installed and maintained on the remote host when called by shell scripts on the remote host. The console displays a listing of remote CLI client installations, but you still have to manually update the client software.
- EM CLI configuration on a remote host requires connection information for interaction with the OMS server. When this information changes, you must visit each EM CLI installation.
- EMCTL commands are specific to the targets known to a specific agent, so the commands passed on the command line are typically much simpler.
- You must be logged in on the remote host to execute an EMCTL command. EM CLI allows you to perform many EMCTL-equivalent commands remotely in order to avoid a trip to the server. This can be particularly helpful when managing a number of servers in one session.
We recommend using EMCTL when you’re just getting started or if your installation is small. Commands in EMCTL tend to be simpler, and the setup ahead of time is also simpler. The “investment” in time to get set up using EM CLI however, becomes worthwhile at scale. Those with large infrastructures to support will find themselves tending toward using EM CLI.
Agent Start and Stop
EM agents can be started and stopped from inside the OEM console, through EM CLI, and of course by EMCTL. Since EMCTL commands are performed for a single agent, the commands tend to be quite simple:
emctl start agent
emctl stop agent
Similar functionality can be performed from the management server, your desktop, or any host with the EM CLI client installed. Portability comes with complexity since you have to identify not only the agent to be controlled, but also the credentials to be used.
You can specify a host user, a named credential, or a credential set. When you pass the username you also have to provide a password. In a purely interactive mode you can be prompted for the password, but using this technique in a shell script may expose the password to other operating system users. Using OEM named credentials avoids this issue:
emcli start_agent –agent_name="dbservera:3872" –host_username="oracle" –host_pwd="Souper_53cre3t"
emcli start_agent –agent_name="dbservera:3872" –credential_name="oraprod"
emcli start_agent –agent_name="dbservera:3872" –credential_setname="HostCreds"
The stop commands require the same conditional values; for instance:
emcli stop_agent –agent_name="dbservera:3872" –host_username="oracle"
We’ll explore some of these options in greater depth in Chapter 4.
Centralization
Perhaps you’ve decided to shut down some of your EM agents during a physical server move or perhaps during operating system patching. You can quickly build a list of the affected agents with EM CLI get_targets for oracle_emd types and turn that list into two CLI argfiles—one to stop the agents and another to start them.
Note Argfiles are used to process batches of CLI commands. They are discussed in more detail in Chapter 5.
Following is an example putting argfiles to use:
touch argfile_stop.lst
touch argfile_start.lst
emcli get_targets | grep oracle_emd > workfile.lst
for thisAGENT in `cat workfile.lst`; do
echo "start_agent –agent_name=${thisAGENT} –credential_name=oraprod" > argfile_start.lst
echo "stop_agent –agent_name=${thisAGENT} –credential_name=oraprod" > argfile_stop.lst
done
emcli login –user="SYSMAN"
emcli sync
emcli argfile ./argfile_stop.lst
logout
Access
Larger Oracle environments may have a separation of duties between the OEM administrator and regular DBA staff, or perhaps your security rules make it difficult to visit servers for routine maintenance. In those cases, running the CLI commands or managing up/down through the console makes sense.
Safety Net
You are prompted for a confirmation any time you ask to perform a dangerous task in the OEM console. EM CLI doesn’t have the same functionality. When you give a command your task is executed exactly as you requested, so be mindful when deleting or modifying targets. Despite this, many people prefer the command line for its direct actions without excess feedback. Just be careful.