1 Command Line Interface Concepts and Installation

Overview

The Enterprise Manager Command Line Interface (EM CLI) enables you to access Enterprise Manager Grid Control functionality from text-based consoles (shells and command windows) for a variety of operating systems. You can call Enterprise Manager functionality using custom scripts, such as SQL*Plus, OS shell, Perl, or Tcl, thus easily integrating Enterprise Manager functionality with a company's business process.

Using EM CLI, you can perform Enterprise Manager Grid Control console-based operations, such as monitoring and 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. You can also use EM CLI commands interactively from an operating system console.

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

Examples of EM CLI usage are as follows:

• Enterprise Manager Integration with third-party or custom software through scripting. Actions (such as adding/deleting targets, submitting/deleting jobs, creating/deleting users) that are part of a customer's business model can be performed through scripting.

• Every day, send an e-mail list of backup jobs that were still running after 6 a.m.

• Every week, write pertinent information about failed Enterprise Manager jobs to a file and then purge the Enterprise Manager job history.

How the EM CLI Works

The EM CLI Client is a Java application that accepts a command as input. The EM CLI Client 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 included 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 Oracle Management Services (OMS) Console via HTTP/HTTPS and sends the command line through 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 logs on to the OMS and establishes a session automatically, as necessary, to access the OMS-Side Controller. The remote Verb impersonates the Enterprise Manager user that invoked the command from the Client. The Enterprise Manager user credentials are established locally to the EM CLI Client during a one-time, interactive exchange when the Enterprise Manager administrator uses the EM CLI setup Verb. Figure 1–1 shows the high-level architecture of EM CLI.

Figure 1-1 EM CLI Architecture

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

Preliminary Advisory Information

• 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.

• To avoid an uncommon occurrence in which multiple emcli sessions are created on the OMS, Oracle recommends that you enter the login command before running a script containing EMCLI commands.

EM CLI Quick Start

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

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

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

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

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

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

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

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.

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

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

Script Availability for Output Data Verbs

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, all output columns become tab-separated (with non-null values), and all rows become newline-separated. You can override the default column and row separators 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 Table 1–1.

• -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 can 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. For example, the tab character is represented by \u0009 and the newline character is represented by \u000A.

• The pretty format type has no attributes.

• In script mode, any Verb output cells that contain the separator strings are substituted with the unicode values for these strings so that the output does not break any scripts required to parse the output.

• script is the only format type for which separators can be specified.

• Separators need not be single characters, and can be specified using both regular characters interspersed with unicode sequences as shown in the following example:

  Example 1-6 Complex Separator

  Separator Specification: xxx\u0009xxx\u0009

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