1 Command Line Interface

The Enterprise Manager Command Line Interface (EM CLI) allows you to access Enterprise Manager Grid Control functionality from text-based consoles (shells and command windows) of a variety of operating systems. This capability provides administrators with the ability to call Enterprise Manager functionality using custom scripts such as SQL*Plus, OS shell, Perl, or Tcl, thus permitting easy integration of Enterprise Manager functionality with a company's business process.

Using EM CLI, you can perform Enterprise Manager Grid Control console-based operations like monitoring/managing targets, jobs, groups, blackouts, notifications and alerts. EM CLI is intended for use by enterprise or system administrators writing scripts such as shell/batch files, Perl, Tcl or PHP that provide workflow in the customer's business process. EM CLI commands can also be used interactively from an operating system console.

EM CLI is fully integrated with Enterprise Manager's security and user administration functions, thus allowing administrators to carry out operations using EM CLI with the same security and confidentiality as the Enterprise Manager Grid Control console. For example, the EM CLI user will only be able to see and operate on targets for which they are authorized.

Example Uses

Enterprise Manager Integration with third party or custom software via scripting. Actions (such as add/delete target, submit/delete jobs, create/delete user) that are part of a customer's business model can be performed via scripting.
Every day, send an e-mail list of backup jobs that were still running after 6 AM.
Every week, write pertinent information about failed Enterprise Manager jobs to a file and then purge the Enterprise Manager job history.

Open Issues

EM CLI setup Verb will not work if you have executed a UNIX "su" or "msu" command to operate as another user in the current window. To run the "setup" Verb as another user, open a new terminal window and run the "setup" Verb as the new user in that window.
EM CLI does not allow OS Script jobs to be run against database targets. The Enterprise Manager Grid Control console, however, does allow this.
EM CLI has only been certified for submitting OS Script and SQL Script jobs.
The current version of EM CLI (10.2.0.0) will not work with Oracle Management Services (OMS) with single sign-on (SSO) enabled.

EM CLI QuickStart

Setting up and running EM CLI is simple. EM CLI consists of two components used to access the Enterprise Manager framework functionality:

EM CLI Client
EM CLI Oracle Management Service Extension

The EM CLI Client can be installed on any machine within your managed network and is a command line program (Java-based) that sends EM CLI Verbs to a specific Oracle Management Service (OMS). In some respects, the EM CLI Client functions as a command line equivalent of an Enterprise Manager Grid Control console. The EM CLI Oracle Management Service Extension is automatically installed with the OMS and serves as the communication conduit between the EM CLI Client and the OMS.

Requirements

Before installing EM CLI, you will need the following:

Enterprise Manager 10g 10.2.0.0 Grid Control framework
Java version 1.4.1 or greater
Workstation running Solaris, Linux, HPUX, Tru64, AIX, or Windows with NTFS.

Installation and Setup

As mentioned earlier, the EM CLI OMS Extension is automatically installed with the OMS. You must install and setup the client portion. The following instructions cover installation and setup procedures for the EM CLI Client.

Installing the EM CLI Client

Obtain the EM CLI Client kit (emclikit.jar).

The EM CLI client kit is downloadable from any 10.2 Grid Control installation at the following location:

HTTP(S)://host:port/em/console/emcli/download

The emclikit.jar file is physically located in the $ORACLE_HOME/sysman/jlib directory of the 10.2 Grid Control OMS home.
Set your JAVA_HOME environment variable and ensure that it is part of your PATH. You must be running Java 1.4.1 or greater. For example

setenv JAVA_HOME /usr/local/packages/j2sdk1.4.1_02setenv PATH $JAVA_HOME/bin:$PATH
Install the EM CLI Client. You can install the client in any directory either on the same machine as the EM CLI Management Services or on any machine in your network (download the emclikit.jar to that machine). Run the following command:

java -jar emclikit.jar client -install_dir=<emcli client dir>

After you have installed the EM CLI Client, you are ready to begin client setup.

Setting Up the EM CLI Client

Once the EM CLI Client is installed, you are ready to begin using EM CLI. At this point you can run the EM CLI Client out of the "install_dir" location, or alternatively, you can add it to your PATH.

Immediately after installation, only basic operational Verbs are installed:

argfile: Executes an EM CLI Verb where the Verb and any arguments are contained in a file.
help: Access command line help for EM CLI Verbs.
setup: Configure EM CLI to work with a specific Enterprise Manager Management Service (OMS)
sync: Synchronize the EM CLI Client with an OMS.
add_mp_to_mpa: Add a Management Plug-in to a Management Plug-in Archive. The Management Plug-in Verb is used for adding new target types to Enterprise Manager.

You must run "setup" to connect the EM CLI Client to the OMS running the EM CLI Management Services. For information on how to use the setup Verb, see the command line help by entering the following:

> emcli help setup

Example 1-1 Setting Up the EM CLI Client

emcli setup -url=http://myworkstation.us.oracle.com:em_port/em -username=em_user

When the EM CLI Client connects with the EM CLI Management Services, you will be prompted at the command line to enter the user password. Running the "setup" Verb installs all available Verb-associated command line help from the EM CLI Management Service. Setup must be run each time you wish to connect to a different OMS.

After running the "setup" Verb, you are ready to begin using EM CLI.

EM CLI Log Files

EM CLI creates log files to record informational and error messages generated during operation. Not all of the logs in the following examples will necessarily be present. Logs are created as needed and are append-based—they are preserved between invocations of EM CLI. Log files may be safely deleted at any time without affecting EM CLI operation.

The logs contain stack traces, which may not be useful for the casual user, but may be of benefit to users with a high level of system knowledge. The following examples show possible log file locations:

CONFIG_DIR/.emcli.log
CONFIG_DIR/.emcli.log.1

CONFIG_DIR refers to the directory specified by the "-dir" option in the latest running of the "setup" Verb (with a ".emcli" subdirectory appended). The current "CONFIG_DIR" directory can be identified by executing the "setup" verb with no options to display the setup summary. Log files are limited to a maximum of 0.5 MB. EM CLI alternates between the two log files: As each file hits the 0.5 MB limit, EM CLI begins writing to the other file, overwriting the oldest log file once emcli.log.1 has been filled for the first time.

The following examples show possible log file locations:

Example 1-2 No configuration directory is specified with the setup Verb (Default location)

user.home/.emcli/.emcli.log
user.home/.emcli/.emcli.log.1

If no configuration directory is specified when the "setup" Verb is run ("-dir" option is omitted), EM CLI assumes the .emcli configuration directory is located within the user's local home directory. The log files are placed at the root level of the .emcli directory. The .emcli directory must be local (not mounted remotely).

Example 1-3 Local configuration directory is specified with the setup Verb (-dir=<local directory>

local.dir/.emcli/.emcli.log
local.dir/.emcli/.emcli.log.1

In this example, the configuration directory is specified using the "-dir" option when the setup Verb is run. This allows you to specify a local configuration directory in the event the user home directory is mounted remotely (via NFS, for example).

Configuring an HTTP Proxy Environment

If you are planning to use EM CLI through an HTTP proxy server, you need to set an additional environment variable (EMCLI_OPTS) that supplies EM CLI with the requisite proxy host and port information. The following examples illustrate setting the EMCLI_OPTS environment variable for both Windows and UNIX operating systems.

Example 1-4 Setting EMCLI_OPTS in a Microsoft Windows Environment

>set EMCLI_OPTS=-Dhttp.proxyHost=<proxy host> -Dhttp.proxyPort=<proxy port>

Example 1-5 Setting EMCLI_OPTS in a UNIX Environment (TCSH)

>setenv EMCLI_OPTS "-Dhttp.proxyHost=<proxy host> -Dhttp.proxyPort=<proxy port>"

EM CLI Command Line Help

The EM CLI incorporates a comprehensive command line help system that provides various levels of assistance. Available from any EM CLI Client installation, the help system provides a listing of all available verbs, descriptive overviews for each Verb, syntax, as well as usage examples. The command line help is the definitive EM CLI information source.

To access command line help, type the following:

>emcli help

Provides an overview of all available verbs.

>emcli help <verb>

Provides a detailed description of the Verb, Verb arguments and options, and usage examples.

How the EM CLI Works

The EM CLI Client is a Java application that accepts a command as input. The EM CLI Client then uses the input command to identify a Verb to execute the command. A Verb is a Java plug-in extension to the EM CLI Client. A Verb services the command with its specific options and posts the results to the standard output stream. Any errors are posted to the error output stream. The Verb also returns an integer exit value that the EM CLI Client sets as the exit value of the command in the Client's calling environment (the operating system console).

A Verb can perform its operations locally, but most of the verbs that come with the EM CLI are covered by the remote Verb in the EM CLI Client. The remote Verb contacts the EM CLI OMS Extension in the Enterprise Manager OMS Console via HTTP/HTTPS and sends the command line via HTTP to the OMS for processing. The EM CLI OMS Extension is essentially a standard Enterprise Manager console page and is installed in the OMS just as any other standard console page. As with the EMCLI Client, the EM CLI OMS Extension uses the input command to identify a Verb to execute the command. The Verb can access the Management Repository or Management Agents via OMS services as necessary in processing the command.

The remote Verb will log on to the OMS and establish a session automatically, as necessary, to access the OMS-Side Controller. The remote Verb impersonates the Enterprise Manager user that instigated the command from the Client. The Enterprise Manager user credentials are established local to the EM CLI Client during a one-time, interactive exchange when the Enterprise Manager administrator uses the EM CLI setup Verb. Figure 1-1shows the high-level architecture of EM CLI.

Figure 1-1 EM CLI Architecture

Description of "Figure 1-1 EM CLI Architecture"

For more information about any of these functional areas, see the Enterprise Manager Concepts Guide.

Security and Authentication

Each operating system user must execute a one-time EM CLI initialization that locally defines the location of the Oracle Management Services and the Enterprise Manager credentials to be used whenever this user invokes EM CLI.

Example 1-6 CLI-Enterprise Manager Authentication

>emcli setup –url="http[s]://host:port/em/" –username="<username>"  [-trustall] [-novalidate]>please enter password:

Note:

You can find out the OMS connection information from any EM CLI Client by issuing the SETUP Verb without any options. For example:

>emcli setup

Oracle Enterprise Manager 10g Release 10.2.0..0

CONFIG DIRECTORY: /home/emcli_install_dir/.emcli

OMS : http://my_machine.my_co.com:port/em/

EM USER : username

TRUST ALL : false

HTTPS Trusted Certificate Management

For authenticating an OMS during the SSL server authentication phase of an HTTPS connection handshake, EM CLI looks for trusted certificates in the following key stores:

CONFIG_DIR/.emcli/.localkeystore
user.home/.emcli/.keystore
JRE_HOME/lib/security/cacerts

"CONFIG_DIR" is the directory specified by the "-dir" option in the latest running of the "setup" Verb (with a ".emcli" subdirectory appended). See "EM CLI Log Files" for more information about the "CONFIG_DIR" parameter.

"JRE_HOME" in a JDK installation is typically "JAVA_HOME/jre".

The key stores can be managed by the JDK "keytool" command. For more information about this tool, see the security documentation for your Java VM installation or (at the time of this writing):http://java.sun.com/j2se/1.4.2/docs/guide/security/SecurityToolsSummary.htmlNot all of the key stores in the list above will necessarily be present.

Secure Clients

You can provide credentials to EM CLI in one of two ways:

Provide credentials a the time of use.
Make credentials persistent on the host machine where the EM CLI client is running, as might be the case when executing EM CLI verbs from a shell script.

Caution:

Making credentials persistent on hosts should only done when the host is a secure client, since the only protection available for credentials is the file system security of the OS.

Oracle also recommends not using persistent credentials if the EM CLI user's home directory is mounted over NFS or any other insecure file system.

EM CLI General Behavior

For easy parsing of Verb output by scripts a "–script" argument is available for all verbs that generate output data. If the "-script" argument is used then all output columns will be tab separated (with non-null values) and all rows will be newline separated. The default column and row separators may be overridden by using the "-format" argument in place of "-script".

[ -script | -format="name:<format type>;column_separator:<separator_text>;row_separator:<separator_text>"]

Supported "-format" arguments are shown in the following table.

Table 1-1 Supported "-format" Arguments

Argument	Explanation
-format="name:pretty"	Pretty print the output. This is the default when both "-script" and "-format" are not specified.
-format="name:script"	This is identical to just specifying "–script". Columns will be tab separated and rows will be newline separated.
-format="name:script;column_separator:<column_sep_string>"	This causes the Verb output to be column separated by <column_sep_string>. Rows are separated by the newline character.
-format="name:script;row_separator:<row_sep_string>"	This causes the Verb output to be row separated by <row_sep_string>. Columns are separated by the tab character.
-format="name:script;column_separator:<column_sep_string>;row_separator:<row_sep_string>"	This causes the Verb output to be column separated by <column_sep_string> and row separated by <row_sep_string>.
-format="name:csv"	This produces a table with the columns separated by commas and the rows by newlines.

'-script' is equivalent to '–format="name:script;column_separator:\u0009;row_separator:\u000A"'
The values for column and row separator are given as one or more character strings. Any of the characters may be represented by the unicode sequence "\uXXXX" (where X is a hex value). NOTE: The ASCII character set is represented by "\u00XX" where XX can range from 00 to 7F. So, for example, the tab character is represented by "\u0009" and the newline character is represented by "\u000A".
Formats supported for the first release are "script", "pretty", and "csv".
The "pretty" format type has no attributes.
In "script" mode any Verb output cells which contain the separator strings will be substituted with the unicode values for those strings so that the output will not break any scripts required to parse the output.
Separators need not be single characters and may be specified using both regular characters interspersed with unicode sequences as shown in the following example.
"script" is the only format type for which separators may be specified.

Example 1-7 Complex Separator

Separator Specification: xxx\u0009xxx\u0009

This separator appears as "xxx" followed by a tab followed by "xxx" followed by another tab.

Using EM CLI

As mentioned previously, the EM CLI provides programmatic access to the functions of the Enterprise Manager Grid Control framework. A subset of framework functions accessed from the Enterprise Manager console can now be accessed via command line using the EM CLI Verbs. See Chapter 2, "Error Code/Verb Reference" for more information on available verbs.