Downloading and Deploying EM CLI

2 Downloading and Deploying EM CLI

This section discusses the following Enterprise Manager Command Line Interface (EM CLI) topics:

EM CLI Installation

EM CLI provides two installable kits:

EM CLI Standard

This kit supports the Standard mode only.
EM CLI with Scripting mode

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:

EM CLI client

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 Downloading and Deploying EM CLI.

Note:

EM CLI only supports Oracle Java. EM CLI does not support JRockit JVM, OpenJDK, or other versions of JDK.

Downloading and Deploying the EM CLI Client

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 EM CLI Overview and Concepts, 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 Using EM CLI), 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.

Requirements

Before downloading the EM CLI client, ensure that the following system requirements have been met:

Enterprise Manager 13c Cloud Control framework
Sun Java JRE version 1.7.0_111 or greater
Workstation running Solaris, Linux, HPUX, Tru64, AIX, or Windows with NTFS

Note:

EM CLI does not support JRockit JVM.

Note:

If you are using an MD5-based signature algorithm, you need to overwrite the java.security file to switch from the OMS JDK to your client JDK location

Downloading and Deploying the EMC CLI Client for Standard EM CLI

To download the EM CLI client for standard EM CLI:

Obtain the standard EM CLI client kit emclikit.jar using one of the following methods:
- Download this kit from any 13.1.0.0 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.7.0_111 or greater. For example:

Linux platform:
```
setenv JAVA_HOME /usr/local/packages/j2sdk1.7.0_111
```
Windows platform:
```
C:\Users>set JAVA_HOME=C:\Program Files\Java\jdk1.7.0_111
```
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 13.1.0.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 13.1.0.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 Using EM CLI With Shared Directories.

Downloading and Deploying the EM CLI Client with the Script Option

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.

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.

For more information, see Secure Mode for the EM CLI Setup.

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 13.1.0.0 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.7.0_111 or greater. For example:

Linux platform:
```
setenv JAVA_HOME /usr/local/packages/j2sdk1.7.0_111
```
Windows platform:
```
C:\Users>set JAVA_HOME=C:\Program Files\Java\jdk1.7.0_111
```
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 13.1.0.0.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 13.1.0.0.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.

Using EM CLI With Shared Directories

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"
```

Troubleshooting After Installation

If you receive the following error when you try to execute your first EM CLI verb, EM CLI tried and failed to acquire a lock for a file:

Error: Some required configuration is missing, corrupt, inaccessible, or insecure (access permissions are too liberal). Resolve the problem and run setup.

To see how this issue occurs, run the sample java program provided in My Oracle Support Knowledge Document 1480978.1, "EMCLI fails with Some required configuration is missing.. error or Java.io.IOException: No Locks Available ":

https://support.oracle.com/rs?type=doc&id1=480978.1

The program tries to acquire a lock for a file and fails. This error is caused by an NFS problem in your environment. To work around this issue:

Specify -Duser.home="<non nfs path>" to force EM CLI to create the files under this directory.

Set the EMCLI_OPTS variable as follows:

export EMCLI_OPTS ="-Duser.home=/tmp"

For example:

export EMCLI_OPTS=-Duser.home=/tmp/emclitemp/prod

Run the emcli setup command as follows:

emcli setup 
url="https://omsmachine.example.com:em_port/em"
     -username="admin"
     -password="password1234" 
     -trustall 
     -dir=/tmp/emclitemp/prod

Getting Started with EM 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.

Using Basic Operational Verbs

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

Using Commands in Standard Mode

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.

Using Commands in Interactive Mode

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.

Calling a Script

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.

Connecting the EM CLI Client to OMS

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 Downloading and Deploying the EM CLI Client, 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 Connecting the EM CLI Client to OMS:
- Command-line EM CLI:
```
./emcli help setup
```
- Script and Interactive EM CLI:
```
./emcli help sync
```
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 sign 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.

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. This examples illustrate setting the EMCLI_OPTS environment variable for both Windows and UNIX operating systems.

Example 2-1 Setting EMCLI_OPTS in a Microsoft Windows Environment

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

Example 2-2 Setting EMCLI_OPTS in a UNIX Environment (TCSH)

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

Configuring Log File Settings for EM CLI

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.

Log File Locations

This example show possible log file locations:

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

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

Example 2-3 No Configuration Directory Specified with Setup Verb (default location)

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

Example 2-4 Local Configuration Directory Specified with Setup Verb (-dir=<local directory>

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

Log File Location and Log Level

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.

Security and Authentication

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.

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 13c Release 2.
Copyright (c) 1996, 2016 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 13c Release 1.
Copyright (c) 1996, 2016 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          : 13.2.0.0.0
Sun Java JRE Home      : /private/MWHome/jdk17/jdk
Sun Java JRE Version   : 1.7.0_111
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

Example 2-5 CLI-Enterprise Manager Authentication

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

>please enter password:

HTTPS Trusted Certificate Management

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.

Secure EM CLI Clients

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.

Secure Mode for the EM CLI Setup

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.

For information on the -noautologin option, see the setup verb.
For information on logging in, see the login verb.
For information on logging out, see the logout verb.

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
`-format="name:pretty"`	Pretty-print the output. This is the default when both `-script` and `-format` are not specified.
`-format="name:script"`	Identical to just specifying `–script`. Columns are tab-separated, and rows are newline-separated.
`-format="name:script;column_separator:<column_sep_string>"`	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>"`	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>"`	Causes the verb output to be column-separated by `<column_sep_string>` and row- separated by `<row_sep_string>`.
`-format="name:csv"`	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:

Example 2-6 Complex Separator

Separator Specification: xxx\u0009xxx\u0009

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