Oracle Enterprise Manager 12c Command-Line Interface

By Kellyn Pot'Vin, Seth Miller and Ray Smith

Oracle Enterprise Manager 12c Command-Line Interface shows how to use Enterprise Manager’s powerful scripting language to automate your database administration work and save time by scripting routine tasks, and then executing those scripts across collections of databases and instances in your environment. This book is chock full of ready-made scripting examples contributed by the authors and leading members of the community. For example, you'll find scripts and examples of commands to:

• Remove an Enterprise Manager agent and its related targets
• Quickly create administrator accounts that are fully-configured with pre-expired passwords and all needed roles
• Invoke batch files to execute sequences of related commands with consistency against multiple targets
• Batch create large groups of user logins with a single command
• and more!

The Enterprise Manager Command Line Interface (EM CLI) is the administrator's key to unlocking the power of Enterprise Manager 12c (EM12c) with scalability, repeatability, and confidence. In previous versions, most administrators ventured into the command-line interface only with the assistance of Oracle Support. But now there are many features in EM12c that are accessible only from the command-line. This is far from a disadvantage! Enterprise Manager is now a powerful tool for automation in the hands of a skilled database administrator.

Enterprise Manager scripting offers potential for all administrators who manage Oracle’s enterprise-level products in their environment. You can automate from the smallest, single-instance configuration all the way up to a broadly distributed enterprise-level rollout having database instances strewn across broad geographical distributions. The power of the EM CLI returns the administrator to the golden age, where the entire environment, from database to application to infrastructure, can often be managed from this powerful command line tool secured by the robust Enterprise Manager framework.

• Brings a golden-age of automation to Oracle Database administrators
• Provides ready-made scripts contributed by leading members of the community
• Covers advanced techniques involving Jython and Python

• Language: English
• Publisher: Apress
• Release date: Nov 3, 2014
• ISBN: 9781484202388

Book preview

© Kellyn Pot'Vin 2014

Kellyn Pot'Vin, Seth Miller and Ray SmithOracle Enterprise Manager 12c Command-Line Interface10.1007/978-1-4842-0238-8_1

1. Architecture

Kellyn Pot'Vin¹ , Seth Miller¹  and Ray Smith¹ 

(1)

CO, US

Oracle Enterprise Manager 12c provides a scalable and reliable central repository, a console, and services for managing your all of your Oracle products. Users typically interact with OEM through the OEM console, which has a rich intuitive graphical interface.

The Enterprise Manager Command-Line Interface (EM CLI) provides access to OEM system functionality outside of the console. Interactive EM CLI tasks can replace lengthy click-streams in defining EM administrator accounts and roles, as one example of its usefulness. EM CLI interactive commands can be used in shell scripts or can be CLI invoked through CLI’s own scripting mode in Jython.

This book explores different ways you can apply these techniques to simplify and automate tasks in your Oracle environment.

Enterprise Manager Framework

The Oracle Enterprise Manager application runs as a JEE application in a WebLogic Server J2EE domain on a WebLogic server. This combination is known as the Oracle Management Server, or OMS.

Java processes running on the OMS gather and process XML file uploads that come from EM agents on your remote hosts. That information is posted to a repository database, where it is stored in the SYSMAN schema.

When you view a page on your OEM console, the data is assembled from the repository database for presentation. In the same way, commands that you issue from the console are processed through the OMS to update repository information (metric collection or notifications, for instance) or manipulate managed targets either through a call to the EM agent or through an authenticated connection to a remote database or host.

Each command issued by the console executes a Java program. The console solicits and assembles data as well as the input commands required for those routines to execute. Much of the manipulative and query code base can be accessed through EM CLI.

The EM CLI program is itself a lightweight Java program that performs the same activities as the console pages but runs an immediate execution of OMS modules using values passed as command-line inputs; it is often employed in shell scripts or Jython programs.

EM CLI Verbs

Interface commands are referred to as verbs. Each verb performs a single task and either succeeds with reasonable feedback or comes back with a quick and obvious failure message.

Many verbs require input values on the command line. As with a PL/SQL package, your input must be passed to the OMS using very specific syntax. The values are always preceded by a filter keyword, and most input requires your strings to be wrapped in double-quotes.

Note

The authors’ experiences using quotation marks have been mixed. They are recommended, but often aren’t required. We’ll use them for clarity in our examples. You may find that you don’t always need them, or that you prefer not to use them.

Use the get_targets verb to display or capture a list of the targets in your environment, as follows:

emcli get_targets

To find only Oracle database targets you’d filter your request with the targets keyword:

emcli get_targets -targets=oracle_database

Numerous examples throughout this book demonstrate how verbs and input values are applied. A catalog of EM CLI verbs and their syntax is available in Oracle Support document E17786-x. Be aware that some verbs are tied to management packs that require licensing fees. You can also find online help at the command-line that lists all of the verbs available and their intended use. For example:

emcli help

Summary of commands:

argfile    -- Execute emcli verbs from a file

help       -- Get help for emcli verbs (Usage: emcli help [verb_name])

login      -- Login to the EM Management Server (OMS)

logout     -- Logout from the EM Management Server

setup      -- Setup emcli to work with an EM Management Server

status     -- List emcli configuration details

sync       -- Synchronize with the EM Management Server

version    -- List emcli verb versions or the emcli client version

Add Host Verbs

continue_add_host             -- Continue a failed Add Host session

get_add_host_status           -- Displays the latest status of an Add Host session.

list_add_host_platforms       -- Lists the platforms on which the Add Host operation can be performed.

list_add_host_sessions        -- Lists all the Add Host sessions.

retry_add_host                -- Retry a failed Add Host session

submit_add_host               -- Submits an Add Host session.

...

The help verb can be filtered with specific verbs to display detailed usage instructions:

emcli help get_targets

emcli get_targets

[-targets=[name1:]type1;[name2:]type2;...]

[-alerts]

[-noheader]

[-script | -format=

[name:];

[column_separator:column_sep_string];

[row_separator:row_sep_string];

]

[-config_search=Configuration Search UI Name]

[-unmanaged]

Description:

Obtain status and alert information for targets.

Options:

-targets=name:type

Name or type can be either a full value or a pattern match

using %. Also, name is optional, so the type may be

specified alone.

-config_search=Configuration Search UI Name

Search UI Name should be the display name of the configuration search.

-alerts

Shows the count of critical and warning alerts for each target.

-noheader

Display tabular output without column headers.

-script

This option is equivalent to -format=name:script.

-format

Format specification (default is -format=name:pretty).

-format=name:pretty prints the output table

in a readable format but is not intended to be parsed by scripts.

-format=name:script sets the default column separator

to a tab and the default row separator to a newline.

The column and row separator strings may be specified

to change these defaults.

-format=name:csv sets the column separator to a comma

and the row separator to a newline.

-unmanaged

Get unmanaged targets (no status or alert information)

Output columns:

Status ID  Status  Target Type  Target Name  Critical  Warning

Examples:

emcli get_targets

Shows all targets. Critical and Warning columns are not shown.

emcli get_targets

-alerts

Shows all targets. Critical and Warning columns are shown.

emcli get_targets

-targets=oracle_database

Shows all oracle_database targets.

emcli get_targets

-targets=%oracle%

Shows all targets whose type contains the string oracle.

emcli get_targets

-targets=database%:%oracle%

Shows all targets whose name starts with database and type

contains oracle.

emcli get_targets

-targets=database3:oracle_database

-alerts

Shows status and alert information on the Oracle database named

database3.

emcli get_targets

-config_search=Search File Systems on Hosts

-targets=oracle%:host

-alerts

Shows status and alert information of the resulting targets from

configuration search named Search File Systems on Hosts and targets

whose name starts with oracle and of type host.

emcli get_targets

-targets=host

-unmanaged

Shows name and type information for unmanaged host targets.

EM CLI Client Software

The basic OEM installation on a management server preconfigures an EM CLI client as part of OMS Oracle Home. In Chapter 2 we’ll show you how to upgrade that client to the EM CLI Advanced Kit.

Part of EM CLI’s strength comes from its flexibility. In addition to the client installation on the OMS server, you can install the EM CLI client on a non-OMS host or even on your desktop.

Installing the EM CLI client consists of downloading and extracting an installation jar file in order to install the binaries, and then configuring the client with connection information for your OMS server. The jar file and installation for its use are available through the OEM console under Setup > Command-Line Interface. Follow the instructions on that web page to install the EM CLI to your workstation.

EM CLI and EMCTL

Several EM CLI functions can be performed through the Agent Control utility EMCTL. Your choice of technique depends on a combination of factors.

EM CLI client must be manually installed and maintained on the remote host when called by shell scripts on the remote host. The console displays a listing of remote CLI client installations, but you still have to manually update the client software.

EM CLI configuration on a remote host requires connection information for interaction with the OMS server. When this information changes, you must visit each EM CLI installation.

EMCTL commands are specific to the targets known to a specific agent, so the commands passed on the command line are typically much simpler.

You must be logged in on the remote host to execute an EMCTL command. EM CLI allows you to perform many EMCTL-equivalent commands remotely in order to avoid a trip to the server. This can be particularly helpful when managing a number of servers in one session.

We recommend using EMCTL when you’re just getting started or if your installation is small. Commands in EMCTL tend to be simpler, and the setup ahead of time is also simpler. The investment in time to get set up using EM CLI however, becomes worthwhile at scale. Those with large infrastructures to support will find themselves tending toward using EM CLI.

Agent Start and Stop

EM agents can be started and stopped from inside the OEM console, through EM CLI, and of course by EMCTL. Since EMCTL commands are performed for a single agent, the commands tend to be quite simple:

emctl start agent

emctl stop agent

Similar functionality can be performed from the management server, your desktop, or any host with the EM CLI client installed. Portability comes with complexity since you have to identify not only the agent to be controlled, but also the credentials to be used.

You can specify a host user, a named credential, or a credential set. When you pass the username you also have to provide a password. In a purely interactive mode you can be prompted for the password, but using this technique in a shell script may expose the password to other operating system users. Using OEM named credentials avoids this issue:

emcli start_agent –agent_name=dbservera:3872 –host_username=oracle –host_pwd=Souper_53cre3t

emcli start_agent –agent_name=dbservera:3872 –credential_name=oraprod

emcli start_agent –agent_name=dbservera:3872 –credential_setname=HostCreds

The stop commands require the same conditional values; for instance:

emcli stop_agent –agent_name=dbservera:3872 –host_username=oracle

We’ll explore some of these options in greater depth in Chapter 4.

Centralization

Perhaps you’ve decided to shut down some of your EM agents during a physical server move or perhaps during operating system patching. You can quickly build a list of the affected agents with EM CLI get_targets for oracle_emd types and turn that list into two CLI argfiles—one to stop the agents and another to start them.

Note

Argfiles are used to process batches of CLI commands. They are discussed in more detail in Chapter 5.

Following is an example putting argfiles to use:

touch argfile_stop.lst

touch argfile_start.lst

emcli get_targets | grep oracle_emd > workfile.lst

for thisAGENT in `cat workfile.lst`; do

echo start_agent –agent_name=${thisAGENT} –credential_name=oraprod > argfile_start.lst

echo stop_agent –agent_name=${thisAGENT} –credential_name=oraprod > argfile_stop.lst

done

emcli login –user=SYSMAN

emcli sync

emcli argfile ./argfile_stop.lst

logout

Access

Larger Oracle environments may have a separation of duties between the OEM administrator and regular DBA staff, or perhaps your security rules make it difficult to visit servers for routine maintenance. In those cases, running the CLI commands or managing up/down through the console makes sense.

Safety Net

You are prompted for a confirmation any time you ask to perform a dangerous task in the OEM console. EM CLI doesn’t have the same functionality. When you give a command your task is executed exactly as you requested, so be mindful when deleting or modifying targets. Despite this, many people prefer the command line for its direct actions without excess feedback. Just be careful.

© Kellyn Pot'Vin 2014

Kellyn Pot'Vin, Seth Miller and Ray SmithOracle Enterprise Manager 12c Command-Line Interface10.1007/978-1-4842-0238-8_2

2. Installation and Security Framework and EM12c Release 4

Kellyn Pot'Vin¹ , Seth Miller¹  and Ray Smith¹ 

(1)

CO, US

Now that you understand the Enterprise Manager architecture, you may want to understand more-advanced installation methods for the Oracle Management Service (OMS) host or for a remote installation. You’ll also want to be up to date on the latest verbs that come into play with 12.1.0.4, also known as EM12c Release 4, which is all covered in this chapter.

EM CLI and WebLogic Installation

Enterprise Manager runs as a domain on a WebLogic server (WLS). The cloud life-cycle solution couldn’t exist without the middle-tier architecture provided by WebLogic. WLS handles the business logic along with communicating with web services and other remote processing to ensure front-end transactions are completed from beginning to end.

There was a time when the OMS required a separate installation of the WLS. Although it’s currently an automated step in the installation of EM12c, comprehending how to perform this manually is valuable to the administrator, especially going forward when administering and managing the environment.

The WebLogic server must be made available to and synchronized with the Enterprise Manager Command-Line Interface (EM CLI) in order to offer the latest plug-ins, management packs, and full access to the Enterprise Manager Cloud environment.

Requirements

In order to understand the requirements before the EM CLI installation on your OMS proceeds, ensure that the WebLogic Domain Provisioning Profile is created in such a way that the software library has the Middleware Home that belongs to the domain archived and stored as part of the WebLogic domain.

Creating the WebLogic Domain Provisioning Profile

There are three components that make up the provisioning profile:

a middleware home

the binaries used by the WebLogic server components

the domain configuration for the provisioning profile

If you simply have an administrator or super administrator log in to the EM12c environment, it will not be sufficient to complete the WLS domain provisioning profile. To complete this task, you must have the following:

Host credentials for the WLS and any other host involved in the provisioning setup. These credentials were required during the initial OEM installation.

All targets must have Java Required Files (JRF) enabled, which is discovered and monitored by Enterprise ManagerEnsure.

Log in to the Enterprise Manager Cloud Console as a super user and click on Enterprise, Provisioning and Patching, and then Software Library, as shown in Figure 2-1.

A978-1-4842-0238-8_2_Fig1_HTML.jpg

Figure 2-1.

Accessing the software library within the EM12c console

Once you enter the software library, you will need to create a folder in which to store the profile (Figure 2-2).

A978-1-4842-0238-8_2_Fig2_HTML.jpg

Figure 2-2.

Creating a new folder within the software library for provisioning, patching, or installations

The Software Library already has a pre-determined set of sub-directories available. For our example, we will create a new directory named Profile_Home, give a defined description, and save it to a newly defined Networks sub-directory (Figure 2-3).

A978-1-4842-0238-8_2_Fig3_HTML.jpg

Figure 2-3.

Creation