This chapter discusses the following Enterprise Manager Command Line Interface (EM CLI) topics:
EM CLI provides two installable kits:
This kit supports the Standard mode only.
This kit supports all three modes, but only Interactive and Scripting modes enable you to provide Jython-based scripts.
EM CLI consists of two components used to access the Enterprise Manager framework functionality:
The EM CLI client is a command-line program (Sun Java JRE-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 Cloud Control console. You can download the EM CLI client on any system within your managed network.
EM CLI Oracle Management Services (OMS)
The EM CLI OMS is automatically installed with the OMS and serves as the communication conduit between the EM CLI client and the OMS.
You can download the EM CLI client on any system within your managed network. The EM CLI client is a command-line program (Sun Java JRE-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 Cloud Control console. The EM CLI OMS is automatically installed with the OMS and serves as the communication conduit between the EM CLI client and the OMS.
For instructions about setting up and running EM CLI, see Chapter 2, "Downloading and Deploying EM CLI".
Note:
EM CLI does not support JRockit JVM.The EM CLI OMS is automatically installed with the OMS, but you must download and set up the EM CLI client portion. The following instructions cover download procedures for the EM CLI client. The EM CLI client kits are available for public access, so do not require authentication.
As mentioned in Chapter 1, the EM CLI client features two kits: EM CLI Standard and EM CLI with the Script option. The EM CLI Script option includes the Jython Interpreter for Jython script support (described in Chapter 3), as well as all of the features present in the EM CLI Standard kit.
The following sections explain how to download and deploy these two kits.
Before downloading the EM CLI client, ensure that the following system requirements have been met:
Enterprise Manager 12c Cloud Control framework
Sun Java JRE version 1.6.0_43 or greater
Workstation running Solaris, Linux, HPUX, Tru64, AIX, or Windows with NTFS
Note:
EM CLI does not support JRockit JVM.To download the EM CLI client for standard EM CLI only:
Obtain the standard EM CLI client kit emclikit.jar using one of the following methods:
Download this kit from any 12.1.0.3 or later Cloud Control installation at the following location:
https://<your_em_host:port>/em/public_lib_download/emcli/kit/emclikit.jar
For example:
wget --no-check-certificate https://<your_em_host:port>/em/public_lib_download/emcli/kit/emclikit.jar
Download this kit from the Cloud Control console:
From the Setup menu, select Command Line Interface.
In the EM CLI Standard section, click the Download the EM CLI Standard Kit to your workstation link.
Set your JAVA_HOME environment variable and ensure that it is part of your PATH. You must be running Sun Java JRE 1.6.0_43 or greater. For example:
Linux platform:
setenv JAVA_HOME /usr/local/packages/j2sdk1.6.0_43
Windows platform:
C:\Users>set JAVA_HOME=C:\Program Files\Java\jdk1.6.0_43
Install EM CLI Standard kit into any directory using emclikit.jar. The directory in which EM CLI is installed is called "EM CLI Home" (or "EM CLI Client Directory").
For Enterprise Manager Cloud Control version 12.1.0.4.0 and later —
On a Linux platform, enter:
$JAVA_HOME/bin/java -jar emclikit.jar -install_dir=<em_cli_home_dir>
On a Windows platform, enter:
%JAVA_HOME%\bin\java -jar emclikit.jar -install_dir=<em_cli_home_dir>
For Enterprise Manager Cloud Control versions prior to 12.1.0.4.0 —
On a Linux platform, enter:
$JAVA_HOME/bin/java -jar emclikit.jar client -install_dir=<em_cli_home_dir>
On a Windows platform, enter:
%JAVA_HOME%\bin\java -jar emclikit.jar client -install_dir=<em_cli_home_dir>
Change directories to the <em_cli_home_dir> directory where EM CLI is installed, then execute emcli help setup for instructions on how to use the setup verb to configure the EM CLI client for a particular OMS.
For information on configuring for shared directories environments, see Section 2.2.4, "Using EM CLI With Shared Directories".
Note:
Before proceeding, click here to see a video tutorial on how to download and get started with EM CLI in Interactive Mode, and click here to see a video tutorial on how to download and get started with EM CLI in Script Mode.Read the readme.txt file shipped with the EM CLI kit with Scripting mode.
The default behavior for EM CLI with Scripting or Interactive mode is to create its own session, which is not persistent and does not store any user session information on disk. If you have set up EM CLI with Scripting or Interactive mode, the values passed to its options such as -autologin or -trustall would be used by the new session. If you have not set up EM CLI or these options were not passed in the setup verb, you would need to set EM CLI client properties before script execution or launching EM CLI Interactive mode.
If EM CLI is set up with the -autologin option, the script executes as the auto logged-in user. In the script, you can directly call the verb as a function without having to use login() in it.
If EM CLI is set up without the -autologin option, the login() function has to be used. If the password is not passed as an argument in the script, you are prompted for the password during script execution.
If EM CLI is set up with the -trustall option, EMCLI_TRUSTALL or EMCLI_CERT_LOC is not required.
To download the EM CLI client for standard EM CLI as well as Interactive and Script EM CLI:
Obtain the EM CLI client kit emcliadvancedkit.jar using one of the following methods:
Download this kit from any 12.1.0.3 or later Cloud Control installation at the following location:
https://<your_em_host:port>/em/ public_lib_download/emcli/kit/emcliadvancedkit.jar
For example:
wget --no-check-certificate https://<your_em_host:port>/em/ public_lib_download/emcli/kit/emcliadvancedkit.jar
Download this kit from the Cloud Control console:
From the Setup menu, select Command Line Interface.
In the EM CLI with Script Option section, click the Download the EM CLI with Script option kit to your workstation link.
Set your JAVA_HOME environment variable and ensure that it is part of your PATH. You must be running Sun Java JRE 1.6.0_43 or greater. For example:
Linux platform:
setenv JAVA_HOME /usr/local/packages/j2sdk1.6.0_43
Windows platform:
C:\Users>set JAVA_HOME=C:\Program Files\Java\jdk1.6.0_43
Install EM CLI with Scripting mode into any directory using emcliadvancedkit.jar. The directory in which EM CLI is installed is called "EM CLI Home" (or "EM CLI Client Directory").
For Enterprise Manager Cloud Control version 12.1.0.4.0 and later —
On a Linux platform, enter:
$JAVA_HOME/bin/java -jar emcliadvancedkit.jar -install_dir=<em_cli_home_dir>
On a Windows platform, enter:
%JAVA_HOME%\bin\java -jar emcliadvancedkit.jar -install_dir=<em_cli_home_dir>
For Enterprise Manager Cloud Control versions prior to 12.1.0.4.0 —
On a Linux platform, enter:
$JAVA_HOME/bin/java -jar emcliadvancedkit.jar client -install_dir=<em_cli_home_dir>
On a Windows platform, enter:
%JAVA_HOME%\bin\java -jar emcliadvancedkit.jar client -install_dir=<em_cli_home_dir>
Change directories to the <em_cli_home_dir> directory where EM CLI is installed, then execute emcli help sync for instructions on how to use the sync verb to configure the EM CLI client for a particular OMS.
Note:
By default, EM CLI with Scripting mode does not store any user session information on disk. It is tailored to build production-grade Jython modules for Enterprise Manager.Read the readme.txt file shipped with the EM CLI kit with Scripting mode.
To avoid contention issues when different Enterprise Manager users are accessing the same EM CLI directories, the following configuration is suggested:
Set the EMCLI_OPTS environment variable as shown in the following example, using the export Linux operating system command:
export EMCLI_OPTS="-Duser.home=/home/user/cli -Demcli.state.dir=/home/user/cli"
Since this is an environment variable, you can set this permanently in your session, depending on your operating system.
Invoke the setup command, noting the following recommendations:
Use a different EM CLI state directory per user by defining the directory location with the -dir option.
Use a different verb jars directory per user by defining the directory location with the -verb_jars_dir option.
For example:
$EMCLI_INSTALL_HOME/emcli setup
-url=https://omsmachine.example.com:em_port/em
-username="admin"
-dir="/home/user/cli"
-verb_jars_dir="/home/user/cli"
After the EM CLI client is downloaded and 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 available:
argfile — Execute an EM CLI verb where the verb and any options 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.
(See Section 2.3.2, "Connecting the EM CLI Client to OMS" for important information about this verb.
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.
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 invoke a verb in standard mode, precede the verb with the emcli command. For example, to invoke the help for an overview of all available verbs, enter one of the following commands:
Linux platform:
./emcli help
Windows platform:
>.\emcli help
Alternatively, enter the same command followed by the verb name to view a detailed verb description, the verb parameters and options, and usage examples, as in:
Linux platform:
./emcli help login
Windows platform:
>.\emcli help login
Note:
You can execute EM CLI without using ./ for Linux or .\ for Windows if you set the PATH environment variable to the directory where EM CLI is installed.To access command-line verbs in interactive mode, you must first invoke the EM CLI command prompt:
$>./emcli
To invoke a verb, call the verb name followed by parentheses. For example, enter the following command to invoke the help:
emcli> help()
To find help for a specific verb, call the help command with the verb within the parentheses surrounded by a single quote:
emcli>help('login')
Note:
The setup and sync commands are not available inside Script and Interactive modes.Tip:
Read the readme.txt file shipped with the advanced kit for more specific examples on how to call the verbs in the EM CLI Client in Script and Interactive modes.To call a script, you must first invoke the EM CLI command prompt:
$>./emcli
To run a script, enter emcli and provide the script location as shown in the following example, where my_script.py is the full path of a valid Python script:
%emcli @my_script.py
Note:
The setup and sync commands are not available inside Script and Interactive modes.Tip:
Read the readme.txt file shipped with the advanced kit for more specific examples on how to call the verbs in the EM CLI Client in Script and Interactive modes.You must run the setup verb to connect the EM CLI client to the OMS running the EM CLI Management Services. Running setup installs all available verb-associated command-line help from the EM CLI Management Service. If you have installed EMCLI with the Script option, you can use the sync command instead of the setup command.
Note:
If you have followed the instructions in Section 2.2, the set up is already done for you.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 the EM CLI client directory for the particular OMS.
To connect the EM CLI client to OMS:
Understand the syntax of the setup and sync verbs and their options by entering the following commands or referring to the respective verbs in Chapter 5, "Verb Reference":
Enter the setup verb with at least the minimally required parameters as shown in This examples:
Command-line EM CLI:
./emcli setup -url=http://omsmachine.example.com:em_port/em -username=em_user
Script and Interactive EM CLI:
./emcli sync -url=http://omsmachine.example.com:em_port/em -username=em_user -trustall
If you have already downloaded certificates, you can specify them using the environment variable EMCLI_CERT_LOC. In this case, the -trustall option is not needed.
Note:
Specify the URL you are using to log in to Enterprise 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 the default noautologin mode, if no EM CLI command executes within the 45-minute default session time-out 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 and noautologin 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.
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. This examples illustrate setting the EMCLI_OPTS environment variable for both Windows and UNIX operating systems.
EM CLI creates log files to record informational and error messages generated during operation. Not all of the logs in This 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 help you to troubleshoot any run-time errors.
Note:
By default, .emcli.log is only created when an exception or error occurs, or when debugging is enabled. Otherwise, the file does not exist.This 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.
This example show possible log file locations:
Example 2-3 No Configuration Directory Specified with 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 2-4 Local Configuration Directory Specified with 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).
You can specify the log file directory and the log level, if desired, using the following variables, which you can set as environment variables:
EMCLI_LOG_LOC — Sets the log file directory to any desired location.
EMCLI_LOG_LEVEL — Presets the log level. Allowed values in descending order are:
SEVERE (highest level)
WARNING
INFO
CONFIG
FINE
FINER
FINEST (lowest level)
Additionally, you can use the level OFF to turn off logging, and the level ALL to enable logging of all messages.
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 2-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 4. Copyright (c) 1996, 2014 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.example.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 4. Copyright (c) 1996, 2014 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.4.0 Sun Java JRE Home : /private/MWHome/jdk16/jdk Sun Java JRE Version : 1.6.0_43 Log file : /private/emcli/setup/.emcli/.emcli.log EM URL : https://myomshost.us.example.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 sub-directory).
JRE_HOME in a Sun Java JRE installation is typically JAVA_HOME/jre.
The Sun Java JRE keytool command can manage the key stores. For more information about this tool, see the security documentation for your Sun Java JRE 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 EM CLI 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 EM CLI 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 EM CLI 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 insecure 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 needs to execute. However, if you explicitly logged out by running emcli logout, you need to explicitly log in again using emcli login.
Note:
The following information regarding the -script option is not to be confused with the Script mode.For easy parsing of verb output by scripts, a –script option is available for all verbs that generate output data. If you use the -script option, 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 option in place of -script.
[-script|-format="name:<format type>;column_separator:<separator_text>;row_separator:<separator_text>"]
Supported -format options are shown in Table 2-1.
Table 2-1 Supported "-format" Options
| Option | 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 |
|
|
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 This example: