Skip Headers
Oracle® Enterprise Manager Command Line Interface
12c Release 1 (12.1.0.4)

E17786-13
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

2 Downloading and Deploying EM CLI

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

2.1 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 client portion. The following instructions cover download procedures for the EM CLI client. The 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.

2.1.1 Requirements

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

  • Enterprise Manager 12c Cloud Control framework

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

2.1.2 Downloading and Deploying the Client for Standard EM CLI

To download the client for standard EM CLI only:

  1. Obtain the standard EM CLI client kit emclikit.jar using one of the following methods:

    • Download this kit from any 12c Cloud Control installation at the following location:

      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.

  2. Set your JAVA_HOME environment variable and ensure that it is part of your PATH. You must be running Java 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
    
  3. 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>
      
  4. 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 client for a particular OMS.

2.1.3 Downloading and Deploying the 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.

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 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 client for standard EM CLI as well as Interactive and Script EM CLI:

  1. Obtain the EM CLI client kit emcliadvancedkit.jar using one of the following methods:

    • Download this kit from any 12c Cloud Control installation at the following location:

      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.

  2. Set your JAVA_HOME environment variable and ensure that it is part of your PATH. You must be running Java 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
    
  3. 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>
      
  4. 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 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.

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

2.2.1 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 Section 2.2.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.

2.2.1.1 Using Commands in Standard Mode

To access command-line help, for instance, in standard mode, enter the following command for an overview of all available verbs:

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.

2.2.1.2 Calling Commands in Script and Interactive Modes

To access command-line help for Interactive mode, for instance, you must first invoke the EM CLI command prompt:

$>./emcli

To access help for all verbs, call the verb name followed by parentheses:

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.

2.2.2 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 Section 2.1, 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 client directory for the particular OMS.

To connect the EM CLI client to OMS:

  1. 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 4, "Verb Reference":

    • Command-line EM CLI:

      ./emcli help setup
      
    • Script and Interactive EM CLI:

      ./emcli help sync
      
  2. 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.

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

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

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

2.2.4.1 Log File Locations

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

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

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

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

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

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

2.3.3 Secure Mode for the EM CLI Setup

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

2.4 Format Option Availability for Output Data Verbs

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.