Oracle® Enterprise Manager Command Line Interface 12c Release 1 (12.1.0.2) Part Number E17786-06 |
|
|
PDF · Mobi · ePub |
This chapter discusses the following Enterprise Manager Command Line Interface (EM CLI) topics:
Overview
How the EM CLI Works
EM CLI Quick Start
Security and Authentication
Script Availability for Output Data Verbs
The Enterprise Manager Command Line Interface (EM CLI) enables you to access Enterprise Manager Cloud 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 Cloud Control console-based operations, such as monitoring and managing targets, jobs, groups, and blackouts. 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 Cloud 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:
Integrate Enterprise Manager 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.
Create a new Enterprise Manager administrator account.
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 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 Service (OMS) Console through 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 through OMS 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. You need to use the login verb if session timeout occurs because you have not executed any EM CLI commands for x minutes, for example.
Figure 1–1 shows the high-level architecture of EM CLI.
For more information about any of these functional areas, see Oracle Enterprise Manager Concepts.
Setting up and running EM CLI is simple. EM CLI consists of two components used to access the Enterprise Manager framework functionality:
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 Cloud 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.
Before installing EM CLI, you will need the following items:
Enterprise Manager 12c Cloud Control framework
Java version 1.6.0_24 or greater
Workstation running Solaris, Linux, HPUX, Tru64, AIX, or Windows with NTFS (client installation)
As mentioned above, the EM CLI OMS Extension is automatically installed with the OMS. You must install and set up the client portion. The following instructions cover installation and setup procedures for the EM CLI Client.
Obtain the EM CLI Client kit (emclikit.jar).
You can download the EM CLI client kit from any 12c Cloud Control installation at the following location:
http(s)://oms_host:oms_port/em/console/emcli/download
The emclikit.jar
file is physically located in the $ORACLE_HOME/sysman/jlib directory
of the 12c Cloud Control OMS home.
Set your JAVA_HOME
environment variable and ensure that it is part of your PATH
. Make sure that this variable is set to the home of a JDK 1.6.0_24 or greater. For example:
setenv JAVA_HOME /usr/local/packages/j2sdk1.6.0_24 setenv PATH $JAVA_HOME/bin:$PATH
Enter the following command to ensure that you have the correct Java in your PATH:
which java
This should show the Java in $JAVA_HOME/bin.
Install the EM CLI Client. You can install the client portion of EM CLI in any directory either on the same system as the OMS or on any system in your network (download the emclikit.jar
file to that system).
Go to the directory where you have installed emclikit.jar:
cd $HOME/<your_emcli_installation_directory>
Enter the following command:
java -jar emclikit.jar client -install_dir=<emcli_client_dir>
The EM CLI client is installed in the <emcli_client_dir>.
After you have installed the EM CLI Client, you are ready to begin setting up the client.
After 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 installation directory location, or alternatively, you can add it to your PATH
.
Immediately after installation, only basic operational verbs are installed:
argfile — Execute an EM CLI verb where the verb and any arguments are contained in a file.
help — Access command-line help for EM CLI verbs.
login — Log in and establish a session with the OMS.
logout — Log out of EM CLI client from Enterprise Manager.
setup — Configure EM CLI to function with a specific OMS.
status — Show EM CLI setup details
sync — Synchronize the EM CLI Client with an OMS.
version — List EM CLI verb versions or the EM CLI client version.
You must run setup to connect the EM CLI Client to the OMS running the EM CLI Management Services. Running the setup
verb installs all available verb-associated command-line help from the EM CLI Management Service. You can use one EM CLI client installation to function with multiple OMSes. However, at any time, EM CLI can function with a particular OMS. For either scenario, you need to set up the EM CLI client once for each OMS. You also need to subsequently set the EMCLI_STATE_DIR environment variable to the directory that was specified as client directory for the particular OMS.
Understand the syntax of the setup verb and its options by entering the following command or referring to the setup verb in the verb reference chapter of this guide:
./emcli help setup
Enter the setup verb with at least the minimally required parameters as shown in the following example:
./emcli setup -url=http://myworkstation.example.com:em_port/em -username=em_user
Note:
Specify the URL you are using to log in to Entprise Manager through the browser.As you observed from step 1, the setup verb has several options, including the following important options:
autologin
noautologin
In autologin mode, if a session times out, EM CLI automatically logs you in. In default noautologin mode, if no EM CLI command executes within the 45-minute default sesion timeout period, you need to log in using the login verb to be able to execute the verbs.
Enter your user password for Enterprise Manager when prompted after the EM CLI client connects with the EM CLI Management Services.
After running the setup
verb, the message "Emcli Setup Successful" appears, and you are ready to begin using EM CLI.
Tip:
For complete information on the setup verb and its options, including autogin, noautologin, and custom_attrib_file referenced in step 2, see the setup verb.To configure the EM CLI Client to function with multiple Oracle Management Services by implementing multiple setups, see the Examples section for the Setup verb.
EM CLI creates log files to record informational and error messages generated during operation. Not all of the logs in the following examples are necessarily present. Logs are created as needed and are appended — they are preserved between invocations of EM CLI. You can safely delete log files any time without affecting the EM CLI operation. The logs contain stack traces, which may not be useful for the casual user, but may benefit you with a high level of system knowledge.
The following examples show possible log file locations:
<EM_CLI_Instance_Home>/.emcli.log <EM_CLI_Instance_Home>/.emcli.log.1
<EM_CLI_Instance_Home>
refers to the directory specified by the -dir
option in the latest running of the setup
verb (with an appended .emcli
sub-directory). The current <EM_CLI_Instance_Home>
directory can be identified by executing the status
verb 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 reaches the 0.5 MB limit, EM CLI begins writing to the other file, overwriting the oldest log file after emcli.log.1
has been filled for the first time.
The following examples show possible log file locations:
Example 1-1 No configuration directory is specified with the setup verb (Default location)
user.home/.emcli/.emcli.log user.home/.emcli/.emcli.log.1
If you do not specify a configuration directory when you run the setup
verb (-dir
option is omitted), EM CLI assumes the .emcli
configuration directory is located within your 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-2 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 if the user home directory is mounted remotely (through NFS, for example).
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.
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, enter the following command for an overview of all available verbs ...
./emcli help
... or enter the same command followed by the verb name for a detailed verb description, verb arguments and options, and usage examples, as in:
./emcli help setup
To enable EM CLI to function with a particular OMS, configure EM CLI by executing the setup verb. This is a one-time operation for this particular OMS.
Example 1-5 CLI-Enterprise Manager Authentication
>emcli setup –url="http[s]://host:port/em" –username="<username>" [-trustall] [-novalidate]>please enter password:
You can find out the OMS connection information from any EM CLI Client by invoking the setup
verb without any options. For example:
$ emcli setup Oracle Enterprise Manager Cloud Control 12c Release 2. Copyright (c) 1996, 2012 Oracle Corporation and/or its affiliates. All rights reserved. Instance Home : /private/emcli/setup/.emcli Verb Jars Home : /private/emcli/setup/.emcli EM URL : https://myomshost.us.oracle.com:5416/em EM user : user1 Trust all certificates : true Auto login : false
You can also invoke the status command, which provides more information than the setup command:
$ emcli status Oracle Enterprise Manager Cloud Control 12c Release 2. Copyright (c) 1996, 2012 Oracle Corporation and/or its affiliates. All rights reserved. Instance Home : /private/emcli/setup/.emcli Verb Jars Home : /private/emcli/setup/.emcli Status : Configured EMCLI Home : /private/MWHome/oms/bin EMCLI Version : 12.1.0.2.0 Java Home : /private/MWHome/jdk16/jdk Java Version : 1.6.0_24 Log file : /private/emcli/setup/.emcli/.emcli.log EM URL : https://myomshost.us.oracle.com:5416/em EM user : sysman Auto login : false Trust all certificates : true
For authenticating an OMS during the SSL server authentication phase of an HTTPS connection handshake, EM CLI searches 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 an appended .emcli
subdirectory). See Using EM CLI Log Files for more information about the CONFIG_DIR
parameter.
JRE_HOME
in a JDK installation is typically JAVA_HOME/jre
.
The JDK keytool
command can manage the key stores. 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.5.0/docs/tooldocs/solaris/keytool.html
Not all of the key stores in the list above will necessarily be present.
You can provide credentials to EM CLI in one of two ways:
Provide credentials at the time of use. See the login and logout verbs for information on credentials.
Make credentials persistent on the host system where the EM CLI client is running, as might be the case when executing EM CLI verbs from a shell script.
Caution:
You should only persist credentials on hosts 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.
The EM CLI client installs certain configuration files and a client-side implementation of verbs on the client system. The EM CLI client configuration files contain information such as the OMS URL, Enterprise Manager user names, and Enterprise Manager passwords.
By default, the EM CLI client is set up in secure mode. In this mode, EM CLI does not store any Enterprise Manager or SSO passwords on the client disk. The command emcli setup -noautologin ... sets up the EM CLI client in secure mode. By default, -noautologin is true. Therefore, you do not need to specify it if you want to set up the EM CLI client in secure mode. In secure mode, if the EM CLI session times out due to inactivity, explicit login (using the login verb) is required before invoking any verb.
If you want to set up EM CLI in the unsecure auto-login mode, you can use the emcli setup -autologin .... command. In this mode, if an EM CLI session times out due to inactivity, EM CLI automatically re-establishes the session when a verb has to be executed. However, if you explictly logged out by running emcli logout, you need to explicitly log in again using emcli login.
For information on the noautologin option, see the setup verb on page 2-398.
For information on logging in, see the login verb on page 2-291.
For information on logging out, see the logout verb on page 2-292.
For easy parsing of verb output by scripts, a –script
argument is available for all verbs that generate output data. If you use the -script
argument, 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.
Table 1-1 Supported "-format" Arguments
Argument | Explanation |
---|---|
|
Pretty-print the output. This is the default when both |
|
Identical to just specifying |
|
Causes the verb output to be column-separated by |
|
Causes the verb output to be row-separated by |
|
Causes the verb output to be column-separated by |
|
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 specified 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:
Prior to Enterprise Manager version 12.1.0.2, if you set up 'n' EM CLI instances with a particular OMS, the client side verb jars were present in each of these 'n' EM CLI instance directories.
Enterprise Manager version 12.1.0.2 and later enables multiple EM CLI instances to share the client-side verb jars. Set up each of these instances using the following command:
emcli setup -url=<> -verb_jars_dir=<>
The client-side verb jars are downloaded only the first time, and all instances do not download again, but use them anyway.