ibmtivoli zenterprise monitoringagent version 6.2€¦ · ibmtivoli zenterprise monitoringagent...

IBM Tivoli zEnterprise Monitoring AgentVersion 6.2.3

Installation and Configuration Guide

SC14-7358-00

��

NoteBefore using this information and the product it supports, read the information in “Notices” on page 265.

This edition applies to version 6, release 2, modification 3, fix pack 1 of IBM Tivoli Monitoring (product number5724-C04 ) and to all subsequent releases and modifications until otherwise indicated in new editions.

© Copyright IBM Corporation .US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Figures . . . . . . . . . . . . . . vii

Tables . . . . . . . . . . . . . . . ix

Chapter 1. Tivoli zEnterprise monitoringagent overview. . . . . . . . . . . . 1Agent components . . . . . . . . . . . . 1

Enterprise Common Collector . . . . . . . 2Tivoli zEnterprise monitoring agent. . . . . . 4Tivoli Common Reporting . . . . . . . . . 5

Prerequisites, corequisites, and integratedapplications. . . . . . . . . . . . . . . 5

Monitoring agent requirements . . . . . . . 7Cognos and Tivoli Common Reportingprerequisites . . . . . . . . . . . . . 8Running the Prerequisite Scanner . . . . . . 8

Installation flow . . . . . . . . . . . . . 9

Chapter 2. zEnterprise monitoringsecurity . . . . . . . . . . . . . . 11Security between the collector and the HMC . . . 11Security between the collector and its clients . . . 13

Chapter 3. Setting up the System zHardware Management Console for usewith the Enterprise Common Collector . 21Defining a user . . . . . . . . . . . . . 21Enabling the Web Services API . . . . . . . . 22Deploying the Guest Platform ManagementProvider . . . . . . . . . . . . . . . 22Acquiring the Hardware Management Consolecertificate . . . . . . . . . . . . . . . 22Firewall considerations . . . . . . . . . . 23

Chapter 4. Installing the EnterpriseCommon Collector . . . . . . . . . 25Installing the Enterprise Common Collector byusing the installation wizard. . . . . . . . . 25

Using the Advanced path to set ports . . . . 36Installing the Enterprise Common Collector fromthe console . . . . . . . . . . . . . . 41Installing the Enterprise Common Collector byusing the silent installation method . . . . . . 46Verifying that the Enterprise Common Collectorinstalled correctly . . . . . . . . . . . . 51Manually registering the Enterprise CommonCollector as a service . . . . . . . . . . . 52Starting, stopping, removing, installing, andquerying the status of the Enterprise CommonCollector . . . . . . . . . . . . . . . 53Resetting the Enterprise Common Collector invalidlogin count for the user ID admin . . . . . . . 58

Restoring the Enterprise Common Collector defaultconfiguration . . . . . . . . . . . . . . 59Uninstalling the Enterprise Common Collector usingthe installation wizard . . . . . . . . . . . 59Uninstalling the Enterprise Common Collector fromthe console . . . . . . . . . . . . . . 62

Chapter 5. Customizing the EnterpriseCommon Collector . . . . . . . . . 65Understanding the command-line interface . . . . 66Logging on to the Enterprise Common Collector byusing the command-line interface . . . . . . . 70Changing the default administrator password . . . 71Defining whether the Enterprise Common Collectoruses base authentication or LDAP by using thecommand-line . . . . . . . . . . . . . 72Managing certificates by using the command-line . 73Creating, listing, updating, and deleting clients byusing the command-line . . . . . . . . . . 75Setting up the collection profile by using thecommand-line . . . . . . . . . . . . . 78Setting up HMC data sources by using thecommand-line . . . . . . . . . . . . . 83Setting collector logging levels by using thecommand-line . . . . . . . . . . . . . 86Summary of administrator commands . . . . . 90Summary of utility commands . . . . . . . . 92Managing the Enterprise Common Collector webcontainer . . . . . . . . . . . . . . . 93

Chapter 6. Installing the monitoringagent, application support files, andoptional language support . . . . . . 97Installing if you have enabled the self-describingagent feature . . . . . . . . . . . . . . 97Installing components by using the agent depot . . 99

Installing the monitoring agent and applicationsupport by using remote deployment. . . . . 99

Installing the monitoring agent . . . . . . . 104Installing the monitoring agent by using theinstallation wizard. . . . . . . . . . . 105Installing the monitoring agent on Windowssystems by using the silent install script . . . 113Installing the monitoring agent on Linux orUNIX by using the console install andconfiguration scripts . . . . . . . . . . 118

Installing application support . . . . . . . . 124Installing application support on TivoliEnterprise Monitoring Server . . . . . . . 125Installing application support on the TivoliEnterprise Portal Server . . . . . . . . . 126Installing application support for the TivoliEnterprise Portal desktop and browser clients . 126

Language pack installation . . . . . . . . . 126Installing language packs on Windows systems 126

© Copyright IBM Corp. iii

Installing language packs on UNIX or Linuxsystems . . . . . . . . . . . . . . 127Silent installation of language packs for agents 128

Uninstalling the monitoring agent or applicationsupport or both . . . . . . . . . . . . 129

Chapter 7. Installing Tivoli CommonReporting and importing reports . . . 131Obtaining Tivoli Common Reporting . . . . . 131Installing Tivoli Common Reporting. . . . . . 132

Chapter 8. Verifying components afterconfiguration . . . . . . . . . . . 135Starting and verifying the core components of thezEnterprise monitoring agent environment . . . 135Verifying that historical collection is configuredcorrectly . . . . . . . . . . . . . . . 136Testing the Enterprise Common Collectorconnection to the HMCs. . . . . . . . . . 138Importing the generated Enterprise CommonCollector certificate into the monitoring agent'struststore . . . . . . . . . . . . . . . 139

Chapter 9. Troubleshooting theEnterprise Common Collector . . . . 143Problems and workarounds . . . . . . . . 148

No zEnterprise data or incorrect data is foundin Tivoli Enterprise Portal . . . . . . . . 148Enterprise Common Collector fails to initialize 154Known problems and workarounds . . . . . 161

Enterprise Common Collector components . . . 162Message ranges. . . . . . . . . . . . . 164Enterprise Common Collector general messages 165Enterprise Common Collector command lineinterface messages. . . . . . . . . . . . 184

Chapter 10. Migrating and backing upthe Enterprise Common Collector byusing the Migration Manager. . . . . 187Manual backup. . . . . . . . . . . . . 187Automatic backup . . . . . . . . . . . . 188

Appendix A. Customizing theEnterprise Common Collector byusing the ReST APIs . . . . . . . . 191Background on the web services interface . . . . 191Starting and ending an API session . . . . . . 192Defining whether the Enterprise CommonCollector uses base authentication or LDAP usingthe ReST APIs . . . . . . . . . . . . . 193Setting up collection profiles by using the ReSTAPI. . . . . . . . . . . . . . . . . 193Setting up HMC data sources by using the ReSTAPI. . . . . . . . . . . . . . . . . 194Managing certificates by using the ReST API . . . 195Creating, listing, and updating clients by using theReST API . . . . . . . . . . . . . . . 196

Setting collector logging levels by using the ReSTAPI. . . . . . . . . . . . . . . . . 196Managing backups by using the ReST API . . . 197Enterprise Common Collector configuration APIsoverview . . . . . . . . . . . . . . . 198

DELETE /eccapi/admin/clients/{client-name} 200DELETE /eccapi/admin/collection-profiles/{name} . . . . . . . . . . . . . . . 201DELETE /eccapi/admin/config/certificates/{alias} . . . . . . . . . . . . . . . 201DELETE /eccapi/admin/config/loggers/{logger-name} . . . . . . . . . . . . . . . 202DELETE /eccapi/admin/data-sources/{name} 203DELETE /eccapi/sessions/this-session . . . . 204GET /eccapi/admin/backup . . . . . . . 205GET /eccapi/admin/clients . . . . . . . 206GET /eccapi/admin/clients/{client-name} . . . 209GET /eccapi/admin/collection-profiles . . . . 211GET /eccapi/admin/collection-profiles/{name} 213GET /eccapi/admin/config/authentication . . 216GET /eccapi/admin/config/certificates/ . . . 217GET /eccapi/admin/config/certificates/{alias} 219GET /eccapi/admin/config/certificates/trust-all 221GET /eccapi/admin/config/loggers. . . . . 221GET /eccapi/admin/config/loggers/{logger-name} . . . . . . . . . . . . . . . 223GET /eccapi/admin/data-sources . . . . . 225GET /eccapi/admin/data-sources/{name} . . . 227POST /eccapi/admin/backup . . . . . . . 229POST /eccapi/admin/clients/. . . . . . . 230POST /eccapi/admin/collection-profiles . . . 232POST /eccapi/admin/config/loggers . . . . 234POST /eccapi/admin/data-sources . . . . . 236POST /eccapi/sessions/. . . . . . . . . 238PUT /eccapi/admin/clients/{client-name} . . . 240PUT /eccapi/admin/clients/{client-name}/resume . . . . . . . . . . . . . . 242PUT /eccapi/admin/collection-profiles/{name} 242PUT /eccapi/admin/config/authentication . . 244PUT /eccapi/admin/config/certificates/{alias} 247PUT /eccapi/admin/config/certificates/trust-all 249PUT /eccapi/admin/config/loggers/{logger-name} . . . . . . . . . . . . . . . 250PUT /eccapi/admin/data-sources/{name} . . . 252

Appendix B. Event IntegrationSupport . . . . . . . . . . . . . . 255

Documentation library . . . . . . . 257IBM Tivoli Monitoring library . . . . . . . . 257

Documentation for the base agents . . . . . 258Related publications . . . . . . . . . . . 259Other sources of documentation . . . . . . . 259

Support information . . . . . . . . 261

Notices . . . . . . . . . . . . . . 265Trademarks . . . . . . . . . . . . . . 267

iv IBM Tivoli zEnterprise Monitoring Agent: Installation and Configuration Guide

zEnterprise Monitoring AgentGlossary . . . . . . . . . . . . . 269

Index . . . . . . . . . . . . . . . 277

Contents v

vi IBM Tivoli zEnterprise Monitoring Agent: Installation and Configuration Guide

Figures

1. Tivoli zEnterprise monitoring agent architectureoverview . . . . . . . . . . . . . . 2

2. Tivoli Enterprise Monitoring Agent:Configuration of the Enterprise CommonCollector screen . . . . . . . . . . . 15

3. Tivoli Enterprise Monitoring Agent: SecureSockets Layer Communication screen . . . . 17

4. Tivoli Enterprise Monitoring Agent: AllCertificates Will Be Accepted screen . . . . 18

5. Tivoli Enterprise Monitoring Agent: SecureSockets Layer, Trust All Certificates No . . . 19

6. Tivoli Enterprise Monitoring Agent: TruststoreCredentials screen . . . . . . . . . . 20

7. Enterprise Common Collector welcome screen 278. Enterprise Common Collector Introduction

screen . . . . . . . . . . . . . . 289. Enterprise Common Collector Software License

Agreement screen . . . . . . . . . . 2910. Enterprise Common Collector Install Type

screen . . . . . . . . . . . . . . 3011. Enterprise Common Collector Choose Install

Folder screen . . . . . . . . . . . . 3112. Enterprise Common Collector Pre-Install

Summary screen . . . . . . . . . . . 3213. Enterprise Common Collector Installing

Enterprise Common Collector screen . . . . 3314. Enterprise Common Collector Key Pair

Generation screen . . . . . . . . . . 3415. Enterprise Common Collector Incomplete

Information popup . . . . . . . . . . 3416. Enterprise Common Collector Alias Already

Exists popup . . . . . . . . . . . . 3517. Enterprise Common Collector Key Pair

Generation Results screen . . . . . . . . 35

18. Enterprise Common Collector successfulinstallation screen . . . . . . . . . . 36

19. Enterprise Common Collector Install Typescreen with Advanced selected . . . . . . 37

20. Enterprise Common Collector Install Typescreen with Port Settings selected . . . . . 38

21. Enterprise Common Collector Install Typescreen with Current Port Settings selected . . 41

22. Uninstall Enterprise Common CollectorUninstall Introduction screen. . . . . . . 61

23. Uninstall Enterprise Common CollectorUninstall Complete screen . . . . . . . 62

24. Tivoli zEnterprise Monitoring Agent SelectFeatures screen . . . . . . . . . . . 106

25. Tivoli Enterprise Monitoring Agent:Configuration of the Enterprise CommonCollector screen . . . . . . . . . . . 107

26. Tivoli Enterprise Monitoring Agent: Log TraceLevel Parameters screen . . . . . . . . 109

27. Tivoli Enterprise Monitoring Agent: SecureSockets Layer Communication screen . . . 110

28. Tivoli Enterprise Monitoring Agent: AllCertificates Will Be Accepted screen . . . . 111

29. Tivoli Enterprise Monitoring Agent: TruststoreCredentials screen . . . . . . . . . . 112

30. Tivoli zEnterprise Monitoring Agent -InstallShield Wizard Complete screen . . . 113

31. Manage Tivoli Enterprise Monitoring Servicesscreen . . . . . . . . . . . . . . 152

32. Monitoring Agent for Tivoli EnterpriseMonitoring Agent: Configuration of theEnterprise Common Collector screen. . . . 153

33. Flow of automated backup processing 189

© Copyright IBM Corp. vii

viii IBM Tivoli zEnterprise Monitoring Agent: Installation and Configuration Guide

Tables

1. Versions of the Enterprise Common Collectorinstallation program by platform . . . . . . 4

2. Platforms on which the Tivoli zEnterprisemonitoring agent or the Enterprise CommonCollector can be installed . . . . . . . . 6

3. Tasks roles that determine tasks permitted forthe managed resources . . . . . . . . . 22

4. Platforms and versions of the EnterpriseCommon Collector installation wizard . . . 25

5. Platforms and versions of the EnterpriseCommon Collector installation wizard . . . 26

6. Default port assignments for the installationprogram . . . . . . . . . . . . . 38

7. Platforms and versions of the EnterpriseCommon Collector installation . . . . . . 42

8. Default port assignments . . . . . . . . 479. Parameters for key pair generation. . . . . 48

10. Platforms and versions of the EnterpriseCommon Collector installation . . . . . . 49

11. Summary of administrator commands . . . 9012. Summary of utility commands . . . . . . 9213. Passport Advantage IDs for Tivoli Common

Reporting components . . . . . . . . 13114. Commands for launching the Tivoli Common

Reporting installation program by platform . 13215. Location of KZE messages . . . . . . . 14116. Location of KZE messages . . . . . . . 15017. Common Java exceptions . . . . . . . 15518. Enterprise Common Collector known

problems . . . . . . . . . . . . . 16119. Enterprise Common Collector components

and message ranges . . . . . . . . . 16420. Message log locations for ECC command line

interface messages . . . . . . . . . . 18421. Enterprise Common Collector APIs . . . . 19822. LDAP authentication mode setting . . . . 246

© Copyright IBM Corp. ix

x IBM Tivoli zEnterprise Monitoring Agent: Installation and Configuration Guide

Chapter 1. Tivoli zEnterprise monitoring agent overview

The IBM® zEnterprise® System is a workload-optimized, multiplatform technology offering that consistsof the IBM zEnterprise central processor complex, the IBM zEnterprise Unified Resource Manager(zManager) and built-in support for the IBM zEnterprise BladeCenter® Extension (zBX) units.

The IBM Tivoli® zEnterprise Monitoring Agent is a monitoring application for the zEnterprise platform,built specifically to monitor the components of the zEnterprise platform, including the physical, virtual,and logical layers, workload resource groups, and other related artifacts.

The key enabler for this agent is a new component called the Enterprise Common Collector (collector). Thiscomponent is the central collection point for zEnterprise data gathered from one or more System z®

Hardware Management Consoles (HMCs). This component polls the HMCs for zEnterprise configurationand monitoring data from physical, virtual, and logical resources. The collector keeps the data cached, sothat it can be provided to requesting applications, such as the Tivoli zEnterprise monitoring agent.

The agent collects performance, availability, and configuration information from the hardware level up tothe virtual server level. This agent is based on the IBM Tivoli Monitoring technology and as such, isintegrated seamlessly into the monitoring infrastructure that is in place for other monitors, such as theMonitoring Agent for AIX®.

The data collected by the Tivoli zEnterprise monitoring agent helps you to monitor the health,performance, and availability of the workloads for a zEnterprise ensemble. This ensemble is a collection ofone or more System z nodes (including any attached zBladeCenter Extension, or zBX) that are managedas a single logical virtualized system by the zManager, through the use of a Hardware ManagementConsole. Specifically, this agent monitors the following information:v The configuration of zEnterprise ensembles and the nodes in those ensemblesv The physical layer of the environment (such as resources as central processing complexes (CPCs),

chassis, and blades)v The virtual layer of the environment (such as virtual servers and virtualization hosts)v The performance characteristics of the environment (such as workloads, performance policies, service

classes, performance indexes, and workload service level indexes)

To help you understand the underlying causes of potential problems, the zEnterprise monitoring agentprovides views that relate zEnterprise workloads to the underlying physical and virtual infrastructure,including networking devices and storage resources. From high-level views, you can drill down to moredetailed views that answer specific questions about both physical and virtual resources, such as whatplatform a virtual server is running on and what other virtual servers are running on the samehypervisor.

This detailed information about workload resource groups helps you understand service classes, thevirtual servers associated with a particular service class, and whether these servers are meeting theirservice class goals. All of this easy-to-access and easy-to-understand information helps you deliver the24-7 availability that your zEnterprise users expect.

Agent componentsEach component of the Tivoli zEnterprise monitoring agent environment is discussed in detail in thefollowing sections.

Use Figure 1 on page 2 as a reference in the discussion.

© Copyright IBM Corp. 1

Enterprise Common CollectorThe Enterprise Common Collector (collector) is the common data repository that extracts and stores datafrom the zEnterprise System z Hardware Management Console (HMC) for use by a number of differentcomponents, including the Tivoli zEnterprise monitoring agent.

The collector is the central collection point for zEnterprise data gathered from one or more System zHMCs. This component polls the HMCs for zEnterprise configuration and monitoring data from physical,virtual, and logical resources. The collector caches the data for use by requesting applications, such as theTivoli zEnterprise monitoring agent.

When the collector is started, its database is populated with resources described in the HMC. After thisinitial operation to populate the database, the collector monitors and reports the property changes, statuschanges, workload resource group states, and performance and availability metrics of all managed objects

Figure 1. Tivoli zEnterprise monitoring agent architecture overview

2 IBM Tivoli zEnterprise Monitoring Agent: Installation and Configuration Guide

(physical, logical, and virtual) for the enterprise. The collector maintains the discovered data in its mostcurrent state by listening to notifications emitted by the HMCs and periodically rediscovers and updatesthe data.

The collector has the following capabilities:v Manages individual connections to zEnterprise System z Hardware Management Consoles (HMCs)v Collects data in parallel from multiple zEnterprise HMCsv Processes monitoring requests and background data collection activities concurrentlyv Reflects inventory, status, and property changes in data requested from the collector API

The collector provides these additional benefits to programs that use the collector services:v Reduces the processing load on the HMC by providing an alternative source of performance and

inventory data.v Enables greater sharing of information currently available only to the limited set of users with access to

the HMC and also decreases the amount of traffic to and from the console.v Relieves client programs of the burden of message handling normally required to keep data current.v Is available over an IP-network to allow the collector and consuming products to be installed on

different physical or virtual servers.v The collector API allows exploiters to retrieve configuration information as well as metric information

for interval and ad-hoc reporting.v Adds value to HMC performance information by deriving deltas and generating new metrics based on

the sampled data.

Installation considerations

Install and maintain a single version of the Enterprise Common Collector in your enterprise. You mightinstall multiple copies on different hosts for short-term testing prior to migrating a version intoproduction, but only one instance of this component should be in use in your enterprise.

The collector requires that all its components (server as well as administrative console) operate with thesame locale settings. When using the Enterprise Common Collector administrative console, make sure torun it in the same locale as the Enterprise Common Collector service.

On UNIX and Linux, the Enterprise Common Collector service is run under the root account. Thecollector uses account's locale settings at system startup.

On Windows, the Enterprise Common Collector service is run under the Local System account. Theinstalling user's locale settings are used to determine the locale in which the Enterprise CommonCollector service runs. Service creation typically takes place when the Enterprise Common Collector isinstalled.

You have a choice of the following three ways to install the Enterprise Common Collector:v Using the graphical user interface (installation wizard). See “Installing the Enterprise Common

Collector by using the installation wizard” on page 25.v Using the console command-line interface. See “Installing the Enterprise Common Collector from the

console” on page 41.v Using the silent installation method. See “Installing the Enterprise Common Collector by using the

silent installation method” on page 46.

See Table 1 for a choice of six installation programs you can use based on your operating system. Theseinstallation programs are found on the IBM Tivoli Enterprise Common Collector V1.1.0.0 DVD.

Chapter 1. Tivoli zEnterprise monitoring agent overview 3

Table 1. Versions of the Enterprise Common Collector installation program by platform

Installation program Target platform for installing the collector

setup_ecc_v110_aix_ppc64.bin AIX POWER®, 64-bit

setup_ecc_v110_linux_s390x.bin Linux on System z, 64-bit

setup_ecc_v110_linux_x86_32.bin Linux on System x®, 32-bit ( Intel 32-bit )

setup_ecc_v110_linux_x86_64.bin Linux on System x, 64-bit ( includes EM64T (Xeon) and AMD64(Opteron) )

setup_ecc_v110_windows_x86_32.exe Windows Datacenter, Enterprise, and Standard editions, 32-bit


The collector runs as a Windows service (eccsrv with the display name "IBM Enterprise CommonCollector Service") or as a Linux or UNIX daemon (eccSvc). After installation, when you start, stop,remove, or query the status of the Enterprise Common Collector, you are actually addressing thesecommands to the Windows service or Linux or UNIX daemon. The Enterprise Common Collector serviceor daemon is configured to start when the operating system is started and runs in the background whilethe operating system is running. The service can also be started and stopped manually when required.

If you install the Enterprise Common Collector from a user ID with administrator (on Windows systems)or root (on Linux or UNIX systems) authority, the collector can be started automatically when theoperating system starts because the component runs as a service on Windows systems or as a daemon onLinux of UNIX systems.

Any of the three installation methods (installation wizard, console installation, or silent installation)should be run by a user with administrator (Windows) or root (Linux or UNIX) authority to have theEnterprise Common Collector service start automatically when the operating system is started. If you didnot perform the installation of the Enterprise Common Collector from a user ID with the correctauthority, you must set up the Enterprise Common Collector service manually. See “Manually registeringthe Enterprise Common Collector as a service” on page 52.

Tivoli zEnterprise monitoring agentThe Tivoli zEnterprise monitoring agent is an IBM Tivoli Monitoring agent. Like other such agents, thisagent uses Tivoli Enterprise Portal as its primary interface.

View the full set of attribute groups and attributes defined at the zEnterprise monitoring agent by usingthe Tivoli Enterprise Portal (portal) interface. This interface supports the traditional workspaces,situations, and queries familiar to any user of IBM Tivoli Monitoring agents. All IBM Tivoli Monitoringagents support historical data collection, summarization and pruning using the Tivoli Warehouse Proxy,and a Summary and Pruning agent for managing warehouse data. Events are supported by user-definedor default situations that can be forwarded to IBM Tivoli OMNIbus/Netcool for resolution. This set ofcapabilities enables users to maximize their investment in IBM Tivoli Monitoring by adding zEnterpriseresources to the long list of monitored elements.

The Tivoli Enterprise Portal displays performance data from monitoring agents located on the managedsystems. The portal stores this data in system elements called attributes. An attribute table containsattributes that define characteristics of monitored resources. You can use these attributes to monitorsystem performance, build custom workspaces, and build situations to alert you of pending problems.Each of the workspaces contains one or more related attribute tables for a specific monitored resource orresource type.

A comprehensive set of workspaces on the portal is provided for the daily monitoring tasks, at differinglevels of detail showing both physical and virtual resources. Links enable users to navigate back andforth within and between these hierarchies. The workspaces provide detailed information about


zEnterprise BladeCenter Extensions (zBX), blades (System p®, System x, ISAOPT, and DataPower® XI50z),virtual servers and their hosts, virtual networks, and detailed workload resource groups.

For more information about using Tivoli Enterprise Portal interfaces, see the IBM Tivoli zEnterpriseMonitoring Agent: User's Guide.


Run this install process on any system where you want to access IBM Tivoli Monitoring and the TivolizEnterprise monitoring agent.

If you install from the IBM Tivoli zEnterprise Monitoring Agent v6.2.3.0 and Agent Reports DVD, choosefrom the following three ways to install the Tivoli zEnterprise monitoring agent:v Using the graphical interface (Windows only). See “Installing the monitoring agent by using the

installation wizard” on page 105.v Using the console interface (UNIX and Linux platforms). See “Installing the monitoring agent on UNIX

or Linux systems from the console” on page 122v Using the silent install (Windows and UNIX platform). See “Installing the monitoring agent on Linux

or UNIX by using the console install and configuration scripts” on page 118 or “Installing themonitoring agent on Windows systems by using the silent install script” on page 113.

Tivoli Common ReportingThe Tivoli Common Reporting feature is available and separately installable by Tivoli software users. Thefeature can be used to provide consistent approach to generating and customizing reports. Productsprovide reports that are designed for use with Tivoli Common Reporting and have a consistent look andfeel.

Tivoli Common Reporting runs on the Tivoli Integrated Portal interface. If you have installed anotherTivoli product that uses the Tivoli Integrated Portal interface or have installed Tivoli Common Reportingwith IBM Tivoli Monitoring version 6.2.3, do not install this environment again.

The Tivoli zEnterprise monitoring agent provides reports for use with Tivoli Common Reporting.v For information about installing Tivoli Common Reporting, see http://publib.boulder.ibm.com/

infocenter/tivihelp/v3r1/topic/com.ibm.tivoli.tcr.doc_21/ic-home.html.v For information about setting up Tivoli Common Reporting to work with the IBM Tivoli Monitoring

environment, see the IBM Tivoli Monitoring: Administrator's Guide and Chapter 7, “Installing TivoliCommon Reporting and importing reports,” on page 131.

v For information about using reports for the Tivoli zEnterprise monitoring agent, see IBM TivolizEnterprise Monitoring Agent: User's Guide.


Tivoli Common Reporting is installed and configured as part of IBM Tivoli Monitoring. It runs underTivoli Integrated Portal. See Chapter 7, “Installing Tivoli Common Reporting and importing reports,” onpage 131 for Tivoli Common Reporting information sources.

Prerequisites, corequisites, and integrated applicationsThe following prerequisite and corequisite products and versions are required.

Prerequisite software

Ensure that the following products are installed and configured before you begin installation of the TivolizEnterprise monitoring agent components:


http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.tivoli.tcr.doc_21/ic-home.html


v IBM Tivoli Monitoring version 6.2.3 Fix Pack 1 or later installation: Includes the Tivoli Enterprise Portalbrowser and desktop client interfaces for viewing the user interface component and Tivoli DataWarehouse running on one of the supported database platforms for storing historical data.

v The Enterprise Common Collector, version 1.1.0 or laterv System z Hardware Management Console Hardware Management Console (HMC) version 2.11.1,

Maintenance Bundle 30 or greater.v IBM Tivoli Netcool/OMNIbus: Enables situation event forwarding from IBM Tivoli Monitoring and use

of the Tivoli Event Integration Facility (EIF) interface to forward enterprise situation events to TivoliNetcool/OMNIbus (optional).

v Tivoli Common Reporting, version 2.1.1, provided with IBM Tivoli Monitoring (optional).

Supported platforms for installing the agent and collector

The Tivoli zEnterprise monitoring agent or the Enterprise Common Collector can be installed on one ofthe following platforms:

Table 2. Platforms on which the Tivoli zEnterprise monitoring agent or the Enterprise Common Collector can beinstalled

Operating system One of these supported versions

Linux on System z v Red Hat Enterprise Linux (RHEL) 5 or higherv Novell SUSE Enterprise Server (SLES) 10 or higher

AIX v AIX version 5.3 (Technology Level 12) or laterv AIX version 6.1 (Technology Level 5) or laterv AIX version 7.1 or later

Linux on System x

(x86 and x86_64)

v Red Hat Enterprise Linux (RHEL) 5.5 or higherv Novell SUSE Enterprise Server (SLES) 10 SP4 or higherv Novell SUSE Enterprise Server (SLES) 11 SP1 or higher

Windows

Datacenter, Enterprise, andStandard editions

v Windows Server 2008 SP2 or higherv Windows Server 2008 R2 or higher

These operating systems can be running locally or in any of these supported environments:v Linux on System z running in a logical partition (LPAR) on the PR/SM™ hypervisorv Linux on System z guest operating systems running inside a virtual machine on the z/VM® hypervisorv AIX guest operating systems running inside a virtual machine on the PowerVM® hypervisor (PHYP)v Linux guest operating systems running inside a virtual machine on the KVM hypervisor (XHYP)v All Windows editions listed in the previous table on both 32-bit and 64-bit supported platformsv Windows guest operating systems running inside a virtual machine on the KVM hypervisor (XHYP)v VMware ESX and ESXi Server, versions 4.1 and 5.0 or later

Some issues have been noted with running monitoring agents. For more information about issuesrunning the monitoring agent on the Security Enhanced Linux (SELinux) operating system, see thistechnote: http://www-01.ibm.com/support/docview.wss?uid=swg21430478

Required disk space for the Enterprise Common Collector

The Enterprise Common Collector requires maximum total space of 900 MB, divided as follows:v Installed files

The Enterprise Common Collector requires about 400 MB of disk space for installed files. This includesthe executable files of the collector itself and the associated components.


http://www-01.ibm.com/support/docview.wss?uid=swg21430478

v Log filesThe Enterprise Common Collector's log files can grow up to a maximum of 250 MB.

v DatabaseThe Enterprise Common Collector uses a database to store its configuration data and the datadiscovered from the HMC inventory gathering operation. This data is persistent on disk, so that it ispreserved over restarts of the collector. The required disk space of this database depends on theconfiguration of your HMCs. That is, the more objects (for example, virtual servers) that are discoveredon your HMCs, the more disk space is required by the Enterprise Common Collector's database. Youshould reserve at least 250 MB for this database, which should be enough for most HMCconfigurations.If your HMC environment is very large (for example, it includes thousands virtual servers andworkload resources groups), the amount of disk space required should be increased.

Required hardware

For the Enterprise Common Collector or the IBM Tivoli Monitoring components, including TivoliEnterprise Portal, see http://www-01.ibm.com/software/sysmgmt/products/support/Tivoli_Supported_Platforms.html.

Supported IP versions

The Tivoli zEnterprise monitoring agent and the Enterprise Common Collector support networkaddresses in both IPv4 and IPv6.

Monitoring agent requirementsIn addition to the requirements described in the IBM Tivoli Monitoring Installation and Setup Guide, agentstypically have agent-specific requirements.

During installation and configuration, if you are running this monitoring agent on the Linux operatingsystem, SELinux must not be enabled. See http://www-01.ibm.com/support/docview.wss?uid=swg21377580 for more information.

For a list of the platforms on which this monitoring agent can run, see Table 2 on page 6.

Note: For the most current information about the operating systems that are supported, see the Tivoliplatform and database support matrix (http://www-306.ibm.com/software/sysmgmt/products/support/Tivoli_Supported_Platforms.html).

You can also find information about operating systems through the Software product compatibilityreports (http://publib.boulder.ibm.com/infocenter/prodguid/v1r0/clarity/index.html).

Tivoli zEnterprise monitoring agent has the following agent-specific requirements:v A single computer that hosts the hub monitoring server, portal server, and a monitoring agent requires

approximately 300 MB of space. A computer that hosts only the monitoring agent requiresapproximately 30 MB of space, including the specific enablement code for the monitoring agent. Morespace is required for each additional monitoring agent that you deploy on the monitoring computer.

v Linux versions require some compatibility libraries to be installed for the agent to work correctly. Thelatest versions of the libstdc++, libgcc, and compat-libstdc++ libraries are required for the agent to runcorrectly. Linux RedHat 4 and 5, and SuSE 9 and 10 also require the C++ Runtime 6.0 library(libstdc++.so.6). See http://www-01.ibm.com/support/docview.wss?uid=swg21377580 for moreinformation.

v The monitoring agent must be connected to the following software:– IBM Tivoli Monitoring V6.2.3 Fix Pack 1 or greater


http://www-01.ibm.com/software/sysmgmt/products/support/Tivoli_Supported_Platforms.html






http://publib.boulder.ibm.com/infocenter/prodguid/v1r0/clarity/index.html

http://publib.boulder.ibm.com/infocenter/prodguid/v1r0/clarity/index.html


Cognos and Tivoli Common Reporting prerequisitesPrerequisites for Cognos® and Tivoli Common reporting are found in Tivoli Common Reportingdocumentation for version 2.1.1.

See the http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.tivoli.tcr.doc_21/ic-home.html for this information.

See the Cognos-based report packages chapter in the IBM Tivoli zEnterprise Monitoring Agent: User's Guidefor instructions to install, configure, and set up these reports. The reports do not run with earlier versionsof IBM Tivoli Monitoring.

Running the Prerequisite ScannerYou can perform prerequisite checking for the Tivoli zEnterprise monitoring agent before carrying out aninstallation.

About this task

This tool ensures that the prerequisite requirements for installing the monitoring agent have been met.This tool does not check prerequisites for the Enterprise Common Collector.

For additional information about running the Prerequisite Scanner, including definitions of all theparameters that can be specified when you run the command and how to run it remotely, see the IBMTivoli Monitoring: Installation and Setup Guide.

Do the following to run this command for the IBM Tivoli zEnterprise monitoring agent.

Note: A recent version of the bash shell is recommended.

Procedure1. Make sure you have a directory on your computer with read and write access to receive the output of

the prerequisite scanner.2. Open a command window. Change directories on the IBM Tivoli zEnterprise Monitoring Agent v6.2.3.0

and Agent Reports DVD to this location:

Platform Command

Linux or UNIX itm/itm_agents/unix/prereqcheckerNote: A recent version of the bash shell is recommended.

Windows itm\itm_agents\WINDOWS\prereqchecker

3. Run one of these commands, where my_directory is the directory on your computer that you created inStep 1.

Platform Command

Linux or UNIX ./prereq_checker.sh KZE detail outputDir="/my_directory"

Windows prereq_checker.bat KZE detail outputDir="C:\my_directory"

4. The output of this command is found in the results.txt file. Open this file and check to ensure thatthis information is found on the last line:Prereq Scanner Overall Result: PASS




Installation flowFollow this general installation roadmap to complete required and optional steps:1. Locate the IBM Tivoli Monitoring components:

Identify the computer systems in your environment where the Tivoli Monitoring components(monitoring servers, portal servers, and desktop clients) are located. You install application supportfor the agent on these systems.

2. Install or upgrade IBM Tivoli Monitoring:v If you do not already have IBM Tivoli Monitoring installed in your environment, perform that

product installation following the documented procedures in the IBM Tivoli Monitoringpublications library. Version 6.2.3 Fix Pack 1 is the minimum supported version.

v If you already have IBM Tivoli Monitoring installed in your environment, you might need toupgrade it to a minimum supported level for the Tivoli zEnterprise monitoring agent. Obtain anynecessary upgrades or fix packs and apply them to your environment, following the documentedprocedures with those upgrades.

3. Determine where you plan to install the monitor agent and its componentsSee “Prerequisites, corequisites, and integrated applications” on page 5 for supported environments.Three installation processes are required in this order:v Enterprise Common Collectorv Tivoli zEnterprise monitoring agent, its application support files, and language supportv Tivoli Common Reporting (optional)

4. Set up the System z Hardware Management Console for use with the Enterprise Common Collector:Before you can use the Web Services API published for the System z Hardware ManagementConsole (HMC), you must complete the following tasks:a. Define a user with the appropriate management scope and task roles to access objects and

perform actions at the HMC.b. Enable the Web Services API.c. Deploy and enable the Guest Platform Management Provider (GPMP) on the virtual servers for

which operating system-specific information such as OSname and hostname are required fordynamic workspace linking on the monitoring agent.

See Chapter 3, “Setting up the System z Hardware Management Console for use with the EnterpriseCommon Collector,” on page 21 for information about performing these tasks.

5. Install and configure the Enterprise Common Collector:This component is the interface between the System z Hardware Management Console and the TivolizEnterprise monitoring agent. This component must be installed first because the Tivoli zEnterprisemonitoring agent needs it to install and function correctly. See:v Chapter 4, “Installing the Enterprise Common Collector,” on page 25v Chapter 5, “Customizing the Enterprise Common Collector,” on page 65

6. Install Tivoli zEnterprise monitoring agent, application support, and optional language support:Use the installation and configuration procedures described in Chapter 6, “Installing the monitoringagent, application support files, and optional language support,” on page 97, along with the generalagent installation information found in the IBM Tivoli Monitoring library, to install the monitoringagent and the application support required for the monitoring agent. If you are running themonitoring agent in a language other than English, you must install language support.In a typical distributed environment, you might have the Tivoli Enterprise Monitoring Server on onesystem, the Tivoli Enterprise Portal Server on another system, and monitoring agents installed onadditional application server systems where services traffic is to be monitored. In a smallerenvironment you might be monitoring services on the same systems where IBM Tivoli Monitoringcomponents are installed, or you might have everything operating on a single system.


See Chapter 6, “Installing the monitoring agent, application support files, and optional languagesupport,” on page 97 for procedures on installing the monitoring agent, application support files forthe IBM Tivoli zEnterprise monitoring agent on distributed IBM Tivoli Monitoring components, andlanguage support.Perform additional configuration and administrative tasks:After installing the monitoring application support and enabling your runtime environment for datacollection, you can perform additional configuration and administrative tasks to complete yourinstallation.v Verifying the installation and configurationv Configuring for historical data collectionv Configuring for Remote Deploymentv Configuring IBM Tivoli Monitoring to forward events

7. Install Tivoli Common Reporting. See Chapter 7, “Installing Tivoli Common Reporting and importingreports,” on page 131 for information about performing these tasks.

8. Import this agent's reports into Tivoli Common Reporting:The Tivoli zEnterprise monitoring agent provides sample reports that you can import into the TivoliCommon Reporting component of IBM Tivoli Monitoring for retrieving and analyzing historical datacollected by the monitoring agent. See the reporting chapter of the IBM Tivoli zEnterprise MonitoringAgent: User's Guide for more information about importing, configuring, and running these reports.

9. A self-signed certificate was provided with the Enterprise Common Collector. You might want toimport additional certificates or create new certificates. Also, by default, the collector was set up touse its native base authentication, but you can configure the Enterprise Common Collector to useLDAP authenticate, as discussed under “Defining whether the Enterprise Common Collector usesbase authentication or LDAP by using the command-line” on page 72. To understand and potentiallyupdate the default security settings, see Chapter 2, “zEnterprise monitoring security,” on page 11.

10. After completing these tasks to install and configure the Tivoli zEnterprise monitoring agent in yourenvironment, verify that the products you have installed and configured can be launched and areable to communicate with each other. See Chapter 8, “Verifying components after configuration,” onpage 135.

11. When you have verified your environment, open the IBM Tivoli zEnterprise Monitoring Agent User'sGuide as well as the online product help system along with the rest of the documentation libraryprovided with this product to help you monitor your zEnterprise environment.


Chapter 2. zEnterprise monitoring security

The zEnterprise monitoring environment consists of many components that are typically distributedacross multiple systems.

It is important that interactions between these components are performed in a secure manner, to ensurethe integrity of the complete monitoring environment. Ensure that you review the following three aspectsof security when you install and configure this agent:v Authentication: verifying the identity of a data requesterv Authorization: ensuring a requester sees only data to which it is entitledv Secure communications: encrypting the transmission of data between the requester and provider to

prevent unauthorized interception.

zEnterprise monitoring relies entirely on the facilities of the IBM Tivoli Monitoring infrastructure toprovide security between the Tivoli Monitoring components. This infrastructure includes Tivoli EnterprisePortal users, the Tivoli Enterprise Portal Server, the Tivoli Enterprise Monitoring Server and TivoliEnterprise Monitoring Agents, such as the zEnterprise Monitoring Agent.

But the zEnterprise Monitoring solution includes an additional component, the Enterprise CommonCollector, that is not part of the Tivoli Monitoring infrastructure. This collector acts as an intermediarybetween System z Hardware Management Consoles (HMCs) that provide the zEnterprise monitoring dataand the client applications that use that data.

The remainder of this section discusses the three aspects of security as they relate to the EnterpriseCommon Collector:v How the collector communicates with HMCs to gather zEnterprise datav How client applications communicate with the collector to access the zEnterprise datav Configuring the collector

Security between the collector and the HMCThe security of the System z Hardware Management Console (HMC) is a topic of very great concern toSystem z administrators.

Typically, few users in an enterprise are actually allowed to log into the HMC. But the informationgathered by this console is critical to a number of users, including capacity planners, performanceanalysts, business managers and operators. None of these users should have access to an interface assensitive as the HMC, which is why the Enterprise Common Collector was developed.

The collector gathers information about zEnterprise resources and relationships (inventory data) and theperformance data (metrics) associated with those resources from one or more HMCs. In this context, thecollector is a client of each of the HMCs from which it gathers the information. The HMC implements aRepresentational State Transfer (ReST) application programming interface to enable applications like thecollector to retrieve this data. But because of the sensitive nature of this HMC data, the HMC implementssecurity mechanisms on this ReST API to ensure that the data is only available to authorized applications.To be viewed as an authorized application, the collector must adhere to these security requirements.

Authentication

The HMC requires each client to provide credentials for authentication, in the form of a user ID andpassword. These credentials are sent to the HMC by client applications when a session is initiated. When


the HMC has successfully authenticated the credentials, a session is established. All access to the HMCdata and administration functions are performed in the context of this authenticated session.

The HMC can be configured to authenticate the client’s credentials by using its own list of authorizedusers or by using an LDAP server. Client applications that use the HMC Web Services API must providecredentials that are valid for whichever authentication mechanism is configured for the HMC. SeeChapter 3, “Setting up the System z Hardware Management Console for use with the Enterprise CommonCollector,” on page 21 for information about setting up the HMC Web Services API.

The Enterprise Common Collector maintains one or more data source definitions that describe how tocommunicate with HMCs. Each data source definition includes the TCP/IP host name of the target HMC,the credentials (user ID and password, encrypted in the database) used for the HMC, and various otherattributes. These data source definitions for the collector are managed by using either the command lineinterface or the ReST application programming interface of the Enterprise Common Collector. See“Setting up HMC data sources by using the command-line” on page 83 for more details aboutmaintaining data source definitions.

During startup processing (or when a new data source definition is created), the collector uses theinformation in each data source to establish a session with the target HMC. This session creation processinvolves sending the credentials for the data source to the HMC, and the HMC authenticates thecredentials using its list of authorized users. If the authentication is successful, the session is established.All accesses to HMC inventory and metric data by the collector are performed in the context of thisauthenticated session.

Authorization

The HMC maintains a profile for each of its authorized users. This profile describes the zEnterpriseresources that the user is allowed to see and what actions the user is allowed to perform on thoseresources. Users attempting to access resources to which they are not authorized receive a “forbidden”error response. In this way, the HMC provides very fine-grained access control to the zEnterpriseresources it manages.

To the HMC, the Enterprise Common Collector is just another user of its Web Services APIs. Theinformation returned to the collector will be in accordance with the HMC profile of the user ID providedby the collector when its HMC session is established. The goal of the collector is to allow users andapplications to view the zEnterprise resource, relationship and metric information that it gathers fromHMCs. Therefore, it is important to configure each of the data source definitions in the collector with anHMC user ID that is authorized to see all of the zEnterprise resources that the collector is expected toprovide.

See “Defining a user” on page 21 for information about how to define authorized HMC users.

Secure communication

The HMC allows only authenticated and authorized users to access information about the zEnterpriseresources it manages. But even requests made by authorized users would not be completely secure if thecommunication between the requestor and the HMC is not encrypted. The in-transit data can beintercepted by someone who is unauthorized. This is why the HMC only supports HyperText TransferProtocol Secure (HTTPS) connections from the HMC users. Information transmitted over HTTPSconnections is encrypted to prevent unauthorized interception, which guarantees that only the twocommunicating partners for a connection (the HMC and its client) can interpret the data.

HTTPS connections are established by using digital certificates. These certificates not only provide thesecurity keys that enable data encryption and decryption, the certificates can also be used to identify and


authenticate the communicating partner. When an application initiates and HTTPS session, it canauthenticate the identity of its partner using the certificate provided by the target system during sessionnegotiation.

The HMC uses digital certificates only for session encryption, not for client authentication. (Instead, theHMC performs authentication by requiring the requestor to send user credentials over the encryptedsession, as described previously.) The HMC provides a digital certificate to requesting applications, toenable those clients to perform server authentication. By default, the HMC uses a self-signed certificategenerated when the HMC is initially set up and configured. But zEnterprise customers might choose toobtain a certificate signed by a trusted Certificate Authority and install that certificate in the HMC’skeystore in place of the self-signed certificate.

The collector initiates the HTTPS session with the HMC. During session negotiation, the HMC’scertificate is sent to the collector. The collector can be configured to process the HMC’s certificate in oneof two ways:v Trust all certificates

In this configuration, the collector does not perform any authentication of the HMC’s certificate at all,but data transmitted across the HTTPS session is still encrypted. This method is the simplestconfiguration, but it is also the least secure. Because the collector has not validated the identity of theHMC, accepting the session and continuing can result in the collector’s HMC credentials (user ID andpassword) being sent to an unknown and possibly untrusted entity, instead of the intended HMC. Thisconfiguration is not recommended.

v Certificate validation

In this configuration, the collector does perform authentication of the HMC’s certificate. In thisconfiguration, the collector must have a truststore that contains either the HMC’s public certificate orthe public certificate of the Certificate Authority that signed the HMC’s certificate. In this way, thecollector can validate the identity of the HMC before accepting the session and passing credentials tothe HMC.

See “Managing certificates by using the command-line” on page 73 for more information about how toconfigure the HTTPS settings for the collector data source definitions and import the required certificatesinto the collector’s truststore.

Security between the collector and its clientsThe Enterprise Common Collector gathers zEnterprise resource, relationship, and metric information fromone or more System z Hardware Management Consoles (HMCs).

The HMC provides security mechanisms (described under “Security between the collector and the HMC”on page 11) to protect access to this information, due to its sensitive nature. So, likewise, the collectormust also ensure that only authorized applications can access the data it has gathered from HMCs.

In this context, the collector is a server and the authorized applications are clients that are eitherretrieving the gathered HMC data or performing administration functions for the collector itself. Thecollector implements a Representational State Transfer (ReST) application programming interface toenable applications to perform these operations, and implements security mechanisms on this ReST APIto insure the operations are only performed by authorized applications. Two examples of authorizedapplications that communicate with the collector are the command-line interface of the collector and thezEnterprise monitoring agent. Each of these applications adheres to the collector’s security requirements,as described in the following sections.

Authentication

The Enterprise Common Collector requires each of its clients to provide credentials for authentication inthe form of a user ID and password. These credentials are sent to the collector by client applications

Chapter 2. zEnterprise monitoring security 13

when a session is initiated. When the collector has successfully authenticated the credentials, a session isestablished. All access to collector data and administration functions are performed in the context of thisauthenticated session.

The collector can be configured to authenticate the client’s credentials by using its own list of authorizedusers or by using an LDAP server. Client applications that use the collector ReST API must providecredentials that are valid for whichever authentication mechanism is configured for the collector. See“Defining whether the Enterprise Common Collector uses base authentication or LDAP by using thecommand-line” on page 72 for information about how to configure the collector to use local or LDAPauthentication. See “Creating, listing, updating, and deleting clients by using the command-line” on page75 for information about how to manage the list of authorized collector users when using localauthentication. Note that even if the Enterprise Common Collector is configured to use LDAP, the defaultadministrator ID "admin" will always be authenticated using the collector’s own authenticationmechanism. This is done to prevent the default administrator ID from being locked out of the collector incases when the LDAP server is offline, or if the LDAP configuration is not correct.

Collector clients can be locked if the password has expired or if too many unsuccessful attempts aremade to authenticate the client credentials. If a lockout occurs, the client must be unlocked before it canbe used again. See “Creating, listing, updating, and deleting clients by using the command-line” on page75 for information about the management of clients by using the collector administrator functions.

For the Enterprise Common Collector command-line interface application, users are required to specify auser ID and password at the time a command-line session is initiated. The command-line interfaceapplication uses this user ID and password to establish its session with the collector. See “Understandingthe command-line interface” on page 66 for information about using the command-line interface.

The zEnterprise Monitoring Agent must be configured to communicate with the collector, and the user IDand password of the collector is configured at the same time. This configuration is performed at the timethe zEnterprise Monitoring Agent is installed and can be modified by reconfiguring the agent using thenormal IBM Tivoli Monitoring agent configuration process. The following illustration shows how theagent is configured to communicate with the collector using the interactive graphical user interface.


See “Installing the monitoring agent” on page 104 for information about configuring the zEnterprisemonitoring agent.

Authorization

The Enterprise Common Collector assigns one or more roles to each authorized client. These roles definewhat collector information or functions are available to the client. Even if the collector is configured touse LDAP authentication, a client must be created on the collector (without a password) and associatedwith each authorized LDAP account, so that collector roles can be assigned to the LDAP account.

The roles defined by the collector are as follows:v Administrator: allowed to perform configuration and administration functions of the collector itself,

including the management of clients and roles and HMC data source definitionsv Explorer: allowed to retrieve zEnterprise resource and relationship information that the collector has

gathered from one or more HMCs.v Operator: allowed to retrieve zEnterprise monitoring and performance metric information and resource

and relationship information that the collector has gathered from one or more HMCs.

Multiple roles can be assigned to a client. For a client to have access to all aspects of the collector, allthree roles must be assigned to the client. Any attempt to access information or functions that are notauthorized to a client by its assigned roles results in a “forbidden" error response.

Figure 2. Tivoli Enterprise Monitoring Agent: Configuration of the Enterprise Common Collector screen


Users of the Enterprise Common Collector command-line interface must specify the credentials of acollector client that is assigned the Administrator role.

The credentials configured for the zEnterprise Monitoring Agent must be for a collector client that isassigned the Operator role. See “Creating, listing, updating, and deleting clients by using thecommand-line” on page 75 for information about managing the list of collector clients and their assignedroles.

Secure communication

The Enterprise Common Collector allows only authenticated and authorized users to access zEnterpriseinformation and collector administration functions. But even requests made by authorized users are notcompletely secure if the communication between the authorized client application and the collector is notencrypted. In-transit data could be intercepted by someone who is unauthorized. For this reason, thecollector supports only HyperText Transfer Protocol Secure (HTTPS) connections from client applications.Information transmitted over HTTPS connections is encrypted to prevent unauthorized interception,which guarantees that only the two communicating partners for a connection (the collector and its clientapplication) can interpret the data.

HTTPS connections are established by using digital certificates. These certificates not only provide thesecurity keys that enable data encryption and decryption, they can also be used to identify andauthenticate the communicating partner. When an application initiates and HTTPS session, it canauthenticate the identity of its partner by using the certificate provided by the target system duringsession negotiation.

The collector uses digital certificates for session encryption only, not for client authentication. (Instead, thecollector performs authentication by requiring the requestor to send user credentials over the encryptedsession, as described previously.) The collector provides a digital certificate to requesting applications, toenable those clients to perform server authentication. By default, the collector uses a self-signed certificatethat you generate when you install the Enterprise Common Collector. See “Installing the EnterpriseCommon Collector by using the installation wizard” on page 25 for information about generating thecustom key pair that enables a self-signed certificate to be created that ensures secure communicationbetween the collector and its clients.

You could also choose to generate a custom self-signed certificate or obtain a certificate signed by atrusted Certificate Authority and install that certificate in the collector’s keystore in place of the samplecertificate. See the WebSphere® Community Edition information center at http://publib.boulder.ibm.com/wasce/V3.0.0/en/administering-certificates.html for more information about adding certificates in thecollector’s keystore.

An authorized client application initiates the HTTPS session with the collector and, during sessionnegotiation, the collector’s certificate is sent to the client. The client may process the collector’s certificatein one of two ways:v Accept all certificates: In this configuration, the client does not perform any authentication of the

collector’s certificate at all, but data transmitted across the HTTPS session is still encrypted. This is thesimplest configuration, but it is also the least secure. Since the client has not validated the identity ofthe collector, accepting the session and continuing could result in the client’s collector credentials (userID and password, encrypted in the database) being sent to an unknown and possibly untrusted entity,instead of the intended collector. This configuration is not recommended.

v Certificate validation: In this configuration, the client does perform authentication of the collector’scertificate. In this configuration, the client must have a truststore that contains either the collector’spublic certificate or the public certificate of the Certificate Authority that signed the collector’scertificate. This enables the client to validate the identity of the collector before accepting the sessionand passing credentials to the collector.


The Enterprise Common Collector command-line interface does not perform any authentication of thecollector’s certificate. This is because the command-line interface can only be invoked on the systemwhere the collector is running.

The zEnterprise Monitoring Agent can be configured to accept all certificates or to perform certificatevalidation. This configuration is performed at the time the zEnterprise Monitoring Agent is installed andcan be modified by reconfiguring the agent by using the normal IBM Tivoli Monitoring agentconfiguration process. The following two illustrations show what the configuration panels look like whenall certificates are accepted.

Figure 3. Tivoli Enterprise Monitoring Agent: Secure Sockets Layer Communication screen


The next two illustrations show what the configuration panels look like when all certificates are notaccepted. Here the user must specify the location and password of a truststore that contains the certificateneeded to validate the collector’s certificate.

Figure 4. Tivoli Enterprise Monitoring Agent: All Certificates Will Be Accepted screen


Figure 5. Tivoli Enterprise Monitoring Agent: Secure Sockets Layer, Trust All Certificates No


See “Installing the monitoring agent” on page 104 for information about how to configure the HTTPSsettings for the zEnterprise Monitoring Agent.

See “Importing the generated Enterprise Common Collector certificate into the monitoring agent'struststore” on page 139 for information about importing the certificate generated during the monitoringagent installation process into the collector keystore.

See the WebSphere Community Edition information center at http://publib.boulder.ibm.com/wasce/V2.1.1/en/index.html for more information about adding other types of certificates in the collector’skeystore.

Figure 6. Tivoli Enterprise Monitoring Agent: Truststore Credentials screen


Chapter 3. Setting up the System z Hardware ManagementConsole for use with the Enterprise Common Collector

Before you can use the Web Services API published for the System z Hardware Management Console(HMC), perform the following setup steps:1. Define a user with the appropriate management scope and task roles to access objects and perform

actions at the HMC.2. Enable the Web Services API and enable the user defined in Step 1 to access this interface.3. Deploy and enable the Guest Platform Management Provider (GPMP) on the virtual servers for which

operating system-specific information such as OSname and hostname are required for dynamicworkspace linking on the monitoring agent.

These actions are described in detail in the sections that follow. For a comprehensive reference onmanagement scope and task roles as well as for information about console actions to administer the HMCenvironment, see the IBM System z Hardware Management Console Operations Guide Version 2.11.1 or later(SC28-6905) and the IBM zEnterprise System Hardware Management Console Operations Guide for Ensembles,Version 2.11.1 or later (SC27-2615).

Defining a userComplete the following procedure to define a new user.

Procedure1. Log in to the System z Hardware Management Console with the predefined user ACSADMIN or with

a user ID that has equivalent authorization.2. Select the User Profiles task.3. Add a new user:

a. Select the type of Authentication that you want to enable in the Enterprise Common Collector.v For Local Authentication, enter a password.v To use an LDAP Server as the means of authentication, define or select the server that manages

the LDAP directory that contains the user ID that must be authenticated.b. Select the Managed Resource Roles that determine what objects this user is permitted to access.

For systems management functions such as monitoring, discovery, and availability management,the user needs access to all resources in the scope of the ensemble managed by this HMC. Toenable this level of access, select the following predefined roles. If you want to limit access tocertain resources, define the corresponding roles manually.Managed Resource Roles:v BladeCenter Objectsv DPXI50z Blade Objectsv Defined zCPC Managed Objectsv Ensemble Object Groups created by SYSPROGv IBM Blade Objectsv IBM Blade Virtual Server Objectsv ISAOPT Blade Objectsv Storage Resource Objectsv Virtual Network Objectsv Workload Objectsv z/VM Virtual Machine Objects


c. Select the Task Roles that determine what tasks are permitted on the Managed Resources selectedin the previous step. Select the following predefined roles or equivalent roles that you have createdfor this HMC:

Table 3. Tasks roles that determine tasks permitted for the managed resources

Required task permissions Applicable predefined HMC task role

Workloads Report Task

Service Classes Report Task

(Monitor task group)

Performance Management Operator Tasks

Manage Storage Resources

(Configuration task group)

Storage Resource Administrator Tasks

Alternate Support Element

(Change Management task group)

System Programmer Tasks

d. Select other User Properties as needed. Ensure that you select Allow access to managementinterfaces so that the new user may access the Web Services API.

Enabling the Web Services APIDo the following to enable the Web Services API.

Procedure1. Log on to the System z Hardware Management Console (HMC) as the predefined user ACSADMIN

or a user that has the equivalent authorization (the authorization required to customize API settings).2. Select the Customize API Settings task.3. Select WEB Services and enable either ALL IP addresses or specific IP addresses that are allowed to

connect to this HMC.4. Ensure that the Enterprise Common Collector user name that logs on to the HMC is selected under

the User Access Control select. Note that users are selected automatically if the Allow access tomanagement interfaces user property is set for this user (see “Defining a user” on page 21).

Deploying the Guest Platform Management ProviderThe Guest Platform Management Provider (GPMP) is an optional component that must be deployed andenabled on the individual guest platforms if the Enterprise Common Collector requires information suchas the operating system name or the hostname to correlate a virtual server with similar informationobtained from another place.

Note: For z/OS® system, you need only configure and start the GPMP because this component is alreadypart of the z/OS v1.12 or later operating system.

The information required for this deployment is outside the scope of this document. See the IBMzEnterprise System Ensemble Performance Management Guide (GC27-2607), "Installing and configuring guestplatform management providers" for further details.

Acquiring the Hardware Management Console certificateCommunication over secure HTTP requires that all data is encrypted by using a secure key

For key exchange, the HMC sends its certificate to the client who can then validate it and when trusted,the keys can be exchanged.


To allow the Enterprise Common Collector to validate the certificate, its truststore must contain a copy ofthe public part of the server certificate or it must have a copy of the public part of the CertificateAuthority's (CA) certificate. If a server's certificate is not found in the truststore but the certificate of theCA that signed the server's certificate is, then the validation can still be performed.

The most secure way to set up certificates is to physically transport the certificate to the client. However,if you are setting up the collector in an environment where security is less important (for example, a testenvironment), you can use the method that follows. Your security administrator should be able to helpyou with this task.

For self-signed certificates, or for certificates that are signed by a CA that is not in the EnterpriseCommon Collector's truststore, you must first obtain a copy of the certificate (its public part). To get acopy of the certificate, type the web address of the HMC into the address field of your browser.

The first time you access the HMC in the current web browser session, you can receive a certificate error.In this case, follow the instructions provided by the browser to view and export the certificate. You mighthave to authenticate with an administrator user ID and password before the browser allows you toexport the certificate. Use the following sample procedure to access the HMC for the first time in theMozilla Firefox browser:1. Enter the hostname or the IP-address of the HMC into the browser URL input field.2. If the certificate cannot be validated, a warning pop-up window is displayed with the title “This

Connection is Untrusted.” Click “I Understand the Risks” and then click Add Exception. The “AddSecurity Exception” dialog is displayed.

3. Click Get Certificate. This action enables the browser to retrieve the certificate and causes the Viewbutton to be enabled.

4. Click View to open the Certificate Viewer dialog box.5. Verify that the information in the fields concerning who issued the certificate and to whom it was

issued is correct. If this information is correct, click the Details button and then the Export button tosave the certificate to your disk.

6. The certificate is stored in text format and can now be copied to the system where the EnterpriseCommon Collector is running and imported into collector's truststore. See “Managing certificates byusing the command-line” on page 73 for information about importing a certificate.

Firewall considerationsWhen the Web Services API is enabled, the System z Hardware Management Console (HMC) API HTTPserver listens for SSL-based socket connections on TCP port 6794.

The HMC is enabled for both the secure sockets layer (SSL) version 3 and transport layer security (TLS)version 1 protocols on this SSL port. It does not accept non-SSL connections.

As part of the Web Services API, the HMC also provides an integrated Java Message Server (JMS)message broker based on Apache ActiveMQ Version 5.2.0. This message broker is active on the HMCwhenever the Web Services API is enabled.

When active, the integrated broker listens for client connections by using the OpenWire protocol thatflows over SSL connections, listening port: 61617, which is supported by ActiveMQ.

The broker is enabled for the SSL version 3 and TLS version 1 protocols on these SSL ports.

The listening ports listed previously for the API and for the message broker are fixed port numbers andare not subject to customer reconfiguration.

Chapter 3. Setting up the System z Hardware Management Console for use with the Enterprise Common Collector 23

If you have firewalls between the Enterprise Common Collector and the HMC, contact your networkadministrator to set up firewall rules that enable communication over these ports across firewalls.


Chapter 4. Installing the Enterprise Common Collector

You must install and configure the Enterprise Common Collector before you install the components thatconnect to it.

Use one of the following three ways to install this component.v “Installing the Enterprise Common Collector by using the installation wizard”v “Installing the Enterprise Common Collector from the console” on page 41v “Installing the Enterprise Common Collector by using the silent installation method” on page 46

Six versions of the installation program that are listed in Table 4 can be found on the IBM Tivoli EnterpriseCommon Collector V1.1.0.0 DVD. In the procedures that follow, use the version applicable to your platformand operating system.

Table 4. Platforms and versions of the Enterprise Common Collector installation wizard

Installation wizard Target platform for installing the collector

setup_ecc_v110_aix_ppc64.bin AIX POWER, 64-bit


setup_ecc_v110_linux_x86_32.bin Linux on System x, 32-bit ( Intel 32-bit )

setup_ecc_v110_linux_x86_64.bin Linux on System x, 64-bit ( includes EM64T (Xeon) and AMD64 (Opteron))



There are also a number of configuration tasks that must be performed, either from the command lineinterface or programmatically using an application programming interface (API). When you complete thetasks in this chapter, proceed to Chapter 5, “Customizing the Enterprise Common Collector,” on page 65.

Install the Enterprise Common Collector from a user ID with administrator or rootauthority

The Enterprise Common Collector is designed to run as a Windows service or as a Linux or UNIXdaemon. When running as a system service or daemon, the Enterprise Common Collector can be startedautomatically when the operating system boots.

Installation as a service or daemon requires a user ID with administrative privileges (“Administrator” onWindows, “root” on UNIX or Linux).

If you do not perform the installation of the Enterprise Common Collector from a user ID with thecorrect authority, you must set up the service manually. See “Manually registering the EnterpriseCommon Collector as a service” on page 52.

Installing the Enterprise Common Collector by using the installationwizardUse this procedure to install the Enterprise Common Collector by using the installation wizard.


About this task

Quit all other programs before starting this installation. You can click Cancel during the installation toquit this installation until you reach the Pre-Install Summary screen. If you decide to cancel theinstallation process after this step, installed files will not be automatically removed. Instead, you willneed to follow the uninstall procedure explained in “Uninstalling the Enterprise Common Collector usingthe installation wizard” on page 59 to remove a partially installed Enterprise Common Collector image.

You can back up to a previous screen by clicking Previous. The default path is to click Next.

Errors generated by this installation process are recorded in one of these platform-specific log files:

Platform Log location

Linux or UNIX /tmp/ecc.log

Windows C:\tmp\ecc.log

Procedure1. Insert the IBM Tivoli Enterprise Common Collector V1.1.0.0 DVD in your DVD drive and start the

installation wizard by launching on the platform-appropriate setup file.

Table 5. Platforms and versions of the Enterprise Common Collector installation wizard








The Welcome screen is displayed:


2. Use the drop-down menu to select your language and click OK.3. The Introduction screen is displayed. Click Next to accept the defaults and proceed. Click Next.

Figure 7. Enterprise Common Collector welcome screen

Chapter 4. Installing the Enterprise Common Collector 27

4. The Software License Agreement screen is displayed. Read the license agreement. You can click Printto create a printed copy of the agreement. You must click the radio button adjacent to I accept theterms in the license agreement and click Next to continue.

Figure 8. Enterprise Common Collector Introduction screen


5. The Install Type screen is displayed. You can select a Typical or an Advanced install. The Typicalinstall is recommended for most users. If you have a special situation that requires you to changedefault port assignments, click the radio button adjacent to Advanced. Otherwise click the buttonadjacent to Typical and click Next to continue.

Figure 9. Enterprise Common Collector Software License Agreement screen


6. If you did not select Advanced on the previous screen, the Choose Install Folder screen isdisplayed. Unless you have a compelling reason to install in a different location, accept this default.The default installation location is as follows:

Platform Default directory

Linux or UNIX /opt/IBM/ecc

Windows C:\IBM\ECC

Figure 10. Enterprise Common Collector Install Type screen


Throughout this book, these directories will be referred to as <install_dir>.7. The Pre-Install Summary screen is displayed. The summary shows you the installation folder you

selected and displays the required amount of disk space and the available amount. If you agree withthis information, click Next to continue.

Figure 11. Enterprise Common Collector Choose Install Folder screen


Note: If you decide to cancel the installation process after this step, installed files will not beautomatically removed. Instead, you will need to follow the uninstall procedure explained in“Uninstalling the Enterprise Common Collector using the installation wizard” on page 59 to removea partially installed Enterprise Common Collector image.

8. The Installing Enterprise Common Collector screen is displayed and the installation starts whenyou press Install. The progress bar shows visually how far through the installation process you are.Messages are displayed reflecting what components are being installed (such as the Java runtimeenvironment and the application web application archive (WAR) file).

Figure 12. Enterprise Common Collector Pre-Install Summary screen


9. The Key Pair Generation screen is displayed. You are prompted to enter the information requiredfor the Enterprise Common Collector to generate the custom key pair that enables a self-signedcertificate to be created that ensures secure communication between the collector and its clients. Thedefault value "unknown" is displayed but you must change these values.

Figure 13. Enterprise Common Collector Installing Enterprise Common Collector screen


10. Provide the following information:v Fully qualified hostname of this computer system: The fully qualified host name (including

domain name) of the computer on which the Enterprise Common Collector is being installed.v Short name of the organization: A brief name identifying your organization in the self-signed

certificate that is generated for the key pair.v Key alias: The alias that is used when accessing this key pair in the Enterprise Common Collector

keystore.

If either of these fields is left blank or set to “Unknown,” this message is displayed:

11. Click OK to close the pop-up window, and correct the incorrect information. If you provide an aliasthat already exists in the keystore, this message is shown:

Figure 14. Enterprise Common Collector Key Pair Generation screen

Figure 15. Enterprise Common Collector Incomplete Information popup


12. Click OK to close the pop-up window, and correct the incorrect information. When all information iscorrect, click Next to continue.

13. Processing for this request takes place, and the screen status name Please Wait is displayed. Finallythe Key Pair Generation Results pop-up window confirms your key pair was generatedsuccessfully, and you are told the location to which the certificate has been exported.

14. When installation and configuration are complete, the Install Complete screen is displayed.Click Done to exit the installation wizard.

Figure 16. Enterprise Common Collector Alias Already Exists popup

Figure 17. Enterprise Common Collector Key Pair Generation Results screen


If your installation did not complete successfully, you see this message:The installation of Enterprise Common Collector is complete, but someerrors occurred during the install. Please see the installation logfor details. Press "ENTER" to quit the installer.

or this message:The installation of the Enterprise Common Collector is finished, butsome serious errors occurred during the install.Please see the installation log for details.

Open the installation log file that is found in this location:




Read the messages to determine why the collector did not install correctly, and retry the operation.

Using the Advanced path to set portsUse this procedure to change the default ports that the Enterprise Common Collector uses with theinstallation program.

About this task

The default port assignments in the Enterprise Common Collector are preselected to minimize the risk ofport conflicts that might exist in the environment. If you have a compelling reason to change the default

Figure 18. Enterprise Common Collector successful installation screen


ports, use this path in the installation program to make port changes.

Procedure1. Proceed with the install process as described in “Installing the Enterprise Common Collector by using

the installation wizard” on page 25.2. When you reach the place in the installation program where the Install Type screen is displayed,

select the Advanced install.

3. This action causes the Port Assignments screen to be displayed.

Figure 19. Enterprise Common Collector Install Type screen with Advanced selected


When you scroll this screen, you see these additional port assignment decisions. Use this table tounderstand port assignments:

Table 6. Default port assignments for the installation program

Port identifier Explanation Default value

ActiveMQPort The port used by WebSphere Application Server CommunityEdition to communicate with the ActiveMQ (active messagequeue) transport connector. In the WebSphere ApplicationServer Community Edition, enterprise messaging isimplemented by using the Apache ActiveMQ open sourceproject. In the initial server configuration, the ActiveMQbroker is configured with the following JMS networkconnectors: a TCP listener on port 61616 and a Streaming TextOrientated Messaging Protocol (STOMP) listener on port61613. See the project website at http://activemq.apache.org/for more information about the ActiveMQ message serviceand its interoperability with other message systems.

61616

Figure 20. Enterprise Common Collector Install Type screen with Port Settings selected


http://activemq.apache.org/

Table 6. Default port assignments for the installation program (continued)


AJPPort The port number where the WebSphere Application ServerCommunity Edition listens for AJP requests. When the serveris installed, the initial WebSphere Application ServerCommunity Edition configuration contains a connector thatreceives HTTP requests using Apache Jserv Protocol (AJP).Although WebSphere Application Server Community Editioncan receive HTTP requests directly from the network, thisconnector allows WebSphere Application Server CommunityEdition to receive requests from software in a lower tier. Forexample, WebSphere Application Server Community Editionmight receive requests from web servers (like the ApacheHTTP Server), proxy servers, and load balancing systems thatsupport the AJP protocols. AJPPort is the AJP port number forWebSphere Application Server Community Edition.

8009

COSNamingPort The CORBA naming service port number used by WebSphereApplication Server Community Edition. CORBA can be usedto control communication between a Java EE application clientand the server or to deploy a Java EE application client.

1050

DerbyPort The port used by WebSphere Application Server CommunityEdition to communicate with Apache Derby. Apache Derby isan open source relational database implemented entirely inJava and available under the Apache License, Version 2.0. Formore information, see http://db.apache.org/derby/.

1527

HTTPSPort The port number where the WebSphere Application ServerCommunity Edition listens for secure HTTP requests.

8443

JMXPort The port used by the Java Management eXtension (JMX) toconnect to a running WebSphere Application ServerCommunity Edition instance. JMX is a framework thatprovides a standard way of exposing Java resources, forexample, application servers, to a system managementinfrastructure. Using the JMX framework, a provider canimplement functions, such as listing the configuration settings,and editing the settings. This framework also includes anotification layer that management applications can use tomonitor events such as the startup of an application server.Note: This value was changed from the default IBMWebSphere Application Server Community Edition value toresolve a conflict with IBM Tivoli Monitoring.

8989

JMXSecurePort The secure port used by the Java Management eXtension(JMX) to connect to a running WebSphere Application ServerCommunity Edition instance. JMX is a framework thatprovides a standard way of exposing Java resources, forexample, application servers, to a system managementinfrastructure. Using the JMX framework, a provider canimplement functions, such as listing the configuration settings,and editing the settings. This framework also includes anotification layer that management applications can use tomonitor events such as the startup of an application server.For WASCE 2.1.0.1 and later, the --secure option can be usedto connect to JMX server using a secure channel with thedeploy and shutdown commands.

9998


http://db.apache.org/derby/

Table 6. Default port assignments for the installation program (continued)


NamingPort The Jconsole port for monitoring local server overallinformation, for example memories, threads, and VMsummaries. The default naming port for WebSphereApplication Server Community Edition is 1099.Note: This value was changed from the default IBMWebSphere Application Server Community Edition value toresolve a conflict with IBM Tivoli Monitoring.

2098

OpenEJBPort The port used by OpenEJB (Enterprise JavaBeans) forproviding EJB services.

4201

ORBPort The port used by the WebSphere Application ServerCommunity Edition OpenEJB ORB Adapter.

6882

ORBSSLPort The port used by the WASCE Object Request Broker (ORB)Secure Socket Layer (SSL).

2001

SMTPPort The port number where WebSphere Application ServerCommunity Edition listens for Simple Mail Transfer Protocol(SMTP) requests. .

25

To query current port usage for possible conflicts, you might use this method. The example uses theCOSNamingPort default value of 1050 as an example.a. Issue this command:

Platform Command

Linux or UNIX netstat -an | grep 1050

Windows netstat -an | find "1050"

b. Examine the output for a return of value 1050. If no value is returned, then it is likely that port1050 is not currently in use.

4. Change any port assignments that you must to resolve multiple use port conflicts. You see theCurrent Port Settings screen displayed for confirmation.


5. Click Next to return to the Path Selection screen. The steps that follow are the same as for the Typicalpath.

Installing the Enterprise Common Collector from the consoleTo install the Enterprise Common Collector from a console, complete the following procedure.

About this task

Errors generated by this install process are recorded in one of these platform-specific log files:




Quit all other programs before starting this installation. You can cancel the installation until you reach thePre-Install Summary prompt. If you decide to cancel the installation process after this step, installed fileswill not be automatically removed. Instead, you will need to follow the uninstall procedure explained in“Uninstalling the Enterprise Common Collector from the console” on page 62 to remove a partiallyinstalled Enterprise Common Collector image.

Procedure1. Insert the IBM Tivoli Enterprise Common Collector V1.1.0.0 DVD in your DVD drive and locate the

correct version for your platform:

Figure 21. Enterprise Common Collector Install Type screen with Current® Port Settings selected


Table 7. Platforms and versions of the Enterprise Common Collector installation








2. Install the product by issuing the console install command:<setup_file> -i console

where <setup_file> is one of the file names from the table in Step 1. A command window is displayedand you are prompted for input. The example that follows show directories for Windows systems,but the prompts for Linux or UNIX are the same (though the paths are different).

3. The command window prompts you for a locale:Choose Locale . . .--------------------

1- Deutsch->2- English

3- Espagñol4- Français5- Italiano6- Português (Brasil)

CHOOSE LOCALE BY NUMBER:_

Enter the number for your locale and press Enter.4. You see the Enterprise Common Collector installation start:

===============================================================================Introduction------------

InstallAnywhere will guide you through the installation of Enterprise CommonCollector v1.1.0

It is strongly recommended that you quit all programs before continuing withthis installation.

Respond to each prompt to proceed to the next step in the installation. If youwant to change something on a previous step, type ’back’.

You may cancel this installation at any time by typing ’quit’.

For information concerning Enterprise Common Collector installation andconfiguration, consult the "Enterprise Monitoring Agent Installation andConfiguration Guide" which can be found at this URL: http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/topic/com.ibm.itm.doc_6.2.3fp1/welcome.htm

Warning: This program is protected by copyright laws and internationaltreaties. Unauthorized reproduction or distribution of this program, or anyportion of it, may result in severe civil prosecution.


PRESS <ENTER> TO CONTINUE

5. The International License Agreement is displayed. Use these instructions to continue:Press Enter to continue viewing the license agreement,or enter "1" to acceptthe agreement, "2" to decline it, "3" to print it, or "99" to go back to previous screen.

6. When you accept the license agreement, you are shown the port assignments and given the choice toaccept these port assignments. Use the Typical path or make changes to these port assignments anduse the Advanced path.===============================================================================Install Type------------

Select "Typical" or "Advanced" setup type for your installation.

"Typical" will prompt for the minimum wizard setup panels that are needed.Enterprise Common Collector will be installed with the most common options.This choice is recommended for most users.

Enterprise Common Collector. The "Advanced" option will provide theopportunity to customize any of the port values as listed.

ActiveMQPort (ActiveMQ Transport Connector): 61626AJPPort (Tomcat Connector AJP): 8009COSNamingPort (CORBA Naming Service): 1050DerbyPort (Derby Connector): 1527HTTPSPort (Tomcat Connector HTTPS): 8443JMXPort (JMX Remoting Connector): 8989JMXSecurePort (JMX Secure Remoting Connector): 9998MulticastDiscoveryPort (Multi Cast Discovery): 6142MultipointPort (Multi Point Connector): 4212NamingPort (RMI Naming): 2098OpenEJBPort (OpenEJB Daemon): 4201ORBPort (OpenEJB ORB Adapter): 6882ORBSSLPort (OpenEJB ORB Adapter): 2001SMTPPort (Simple Mail Transfer Protocol): 25

->1- Typical2- Advanced

ENTER THE NUMBER FOR YOUR CHOICE, OR PRESS <ENTER> TO ACCEPT THE DEFAULT::

In this example, select Typical. For additional information about port assignments and selection see“Using the Advanced path to set ports” on page 36.

7. Your choice of the Typical install type is displayed, and you can press the Backspace key to changethat decision to Advance, or Enter to continue.===============================================================================Typical Install Type--------------------

You have selected the "Typical" install type.

Continue to complete the installation process or type "back" to re-select theInstall Type.

PRESS <ENTER> TO CONTINUE:

8. When you press Enter, you see the prompt for choosing the install folder:===============================================================================Choose Install Folder---------------------

Note: Destination Folder should not include any blanks or special characters.


Where would you like to install?

Default Install Folder: c:\IBM\ECC

ENTER AN ABSOLUTE PATH, OR PRESS <ENTER> TO ACCEPT THE DEFAULT:

Enter a path or press Enter to select accept the default.9. A Pre-Installation Summary similar to the one shows that follows is displayed.

===============================================================================Pre-Installation Summary------------------------

Please Review the Following Before Continuing:

Product Name:Enterprise Common Collector

Install Folder:C:\IBM\ECC

Disk Space Information (for Installation Target):Required: 411, 132,917 bytesAvailable: 35,232,690,176 bytes

PRESS <ENTER> TO CONTINUE:

Press Enter to continue.10. The Ready to Install prompt and summary is displayed:

===============================================================================Ready to Install----------------

InstallAnywhere is now ready to install Enterprise Common Collector onto yoursystem at the following location:

C:\IBM\ECC

Do not attempt the installation if there is not enough available space (seeprevious "Pre-Installation Summary").

If you need to make changes before beginning the install, type "back".

Type "quit" to end this install session.

PRESS <ENTER> TO INSTALL:

Press Enter to continue with the installation.

Note: If you decide to cancel the installation process after this step, installed files will not beautomatically removed. Instead, you will need to follow the uninstall procedure explained in“Uninstalling the Enterprise Common Collector from the console” on page 62 to remove a partiallyinstalled Enterprise Common Collector image.

11. The Installing. . . progress bar is displayed.12. During installation, you are prompted to enter the information required for the Enterprise Common

Collector to generate the custom key pair that enables a self-signed certificate to be created thatensures secure communication between the collector and its clients.===============================================================================

Key Pair Generation


----------------

The Enterprise Common Collector installer will now generatea custom key pair for secure communication betweenEnterprise Common Collector and its clients.

All input fields are mandatory.

Please provide the following information:

Fully qualified hostname of this computer system:The hostname including the domain name of the computer system onwhich the Enterprise Common Collector is being installed.

Short name of your organization:A brief name identifying your organization in the self-signedcertificate that will be generated for the key pair.

Key alias:The alias to be used when accessing the key pair in theEnterprise Common Collector keystore.

:

If any of these fields remain blank or are set to “Unknown,” or if you provide an alias that alreadyexists in the keystore or an invalid host name, a message is displayed and are prompted again forthe valid information. Provide the requested information, and press Enter to continue with theinstallation.

13. You receive confirmation that your key pair was generated successfully, and you are told the locationto which the certificate has been exported.===============================================================================Key Pair Generation Results---------------------------

Key generation completed successfully.

The certificate has been exported to the file C:\IBM\ECC\certificates\IBMalias.cert

PRESS <ENTER> TO ACCEPT THE FOLLOWING (OK):

Press Enter to continue with the installation.14. When the installation is complete, you see this message:

===============================================================================Installation Complete---------------------

Congratulations. Enterprise Common Collector has been successfully installedto:

C:\IBM\ECC

Note: application deployment is in progress and will still continue itsstartup for several minutes. Exiting this console install section will notaffect its processing.

PRESS <ENTER> TO EXIT THE INSTALLER:

Press Enter to exit the installer.


Installing the Enterprise Common Collector by using the silentinstallation methodYou can install the Enterprise Common Collector on all supported platforms using silent install byfollowing these steps.

Procedure1. Insert the IBM Tivoli Enterprise Common Collector V1.1.0.0 DVD in your DVD drive and locate the

Enterprise Common Collector response file setup_ecc_install.rsp.2. Copy the sample setup_ecc_install.rsp response file to a writeable location so you can edit it.3. Edit the setup_ecc_install.rsp file and provide values for the following installation variables:

a. Do not change this line if you plan to use the silent install:INSTALLER_UI=silent

b. Change the value of the LICENSE_ACCEPTED variable to true and uncomment this line (remove the#) if you accept the license agreement.LICENSE_ACCEPTED=false

where valid values are true or false.v If the LICENSE_ACCEPTED is anything other than true, the silent installation stops and no log

is produced. This lack of a log file is the only indicator you receive that the silent install failed.v By removing the number sign (#) and changing the value for LICENSE_ACCEPTED from false to

true, you are indicating that you accept IBM Tivoli Monitoring for zEnterprise licenseagreement. If you want to review this file, it is found on the license subdirectory on theproduct DVD.

c. Specify a valid directory into which the product should be installed. Uncomment one of thefollowing lines (remove the #) in the response file that corresponds to the platform where you areinstalling the Enterprise Common Collector.

Platform Command

Windows USER_INSTALL_DIR=C:\\IBM\\ecc

UNIX or Linux USER_INSTALL_DIR=/opt/IBM/ecc

d. Edit the Port Assignments section of the silent install program and make the appropriate updatesto the default port settings that follow as needed, or keep the default values.v Examine the current port usage of each port to expose port conflicts. Use the following

commands:

Platform Command

Windows netstat -an | find /i "port_number"

Where port_number is the port number you are querying.

UNIX or Linux netstat -an | grep port_number

Where port_number is the port number you are querying.

Examine the output of this command to determine if a default port assignment for theEnterprise Common Collector has been assigned a different use in your environment. If it is,assign a different port.

v Valid port number are a number of up to five digits in the range of 1-65535. If you assigninvalid port settings, the values are reset to their respective default value during installationprocessing.


v Unless there is a compelling reason to change port assignment, keep the defaults, whichsimplifies future updates.

Table 8. Default port assignments


ActiveMQPort The port used by WebSphere Application Server CommunityEdition to communicate with the ActiveMQ (active messagequeue) transport connector. In the WebSphere ApplicationServer Community Edition, enterprise messaging isimplemented by using the Apache ActiveMQ open sourceproject. In the initial server configuration, the ActiveMQbroker is configured with the following JMS networkconnectors: a TCP listener on port 61616 and a Streaming TextOrientated Messaging Protocol (STOMP) listener on port61613. See the project website at http://activemq.apache.org/for more information about the ActiveMQ message serviceand its interoperability with other message systems.

61616

AJPPort The port number where the WebSphere Application ServerCommunity Edition listens for AJP requests. When the serveris installed, the initial WebSphere Application ServerCommunity Edition configuration contains a connector thatreceives HTTP requests using Apache Jserv Protocol (AJP).Although WebSphere Application Server Community Editioncan receive HTTP requests directly from the network, thisconnector allows WebSphere Application Server CommunityEdition to receive requests from software in a lower tier. Forexample, WebSphere Application Server Community Editionmight receive requests from web servers (like the ApacheHTTP Server), proxy servers, and load balancing systems thatsupport the AJP protocols. AJPPort is the AJP port number forWebSphere Application Server Community Edition.

8009

COSNamingPort The CORBA naming service port number used by WebSphereApplication Server Community Edition. CORBA can be usedto control communication between a Java EE application clientand the server or to deploy a Java EE application client.

1050

DerbyPort The port used by WebSphere Application Server CommunityEdition to communicate with Apache Derby. Apache Derby isan open source relational database implemented entirely inJava and available under the Apache License, Version 2.0. Formore information, see http://db.apache.org/derby/.

1527

HTTPSPort The port number where the WebSphere Application ServerCommunity Edition listens for secure HTTP requests.

8443

JMXPort The port used by the Java Management eXtension (JMX) toconnect to a running WebSphere Application ServerCommunity Edition instance. JMX is a framework thatprovides a standard way of exposing Java resources, forexample, application servers, to a system managementinfrastructure. Using the JMX framework, a provider canimplement functions, such as listing the configuration settings,and editing the settings. This framework also includes anotification layer that management applications can use tomonitor events such as the startup of an application server.Note: This value was changed from the default IBMWebSphere Application Server Community Edition value toresolve a conflict with IBM Tivoli Monitoring.

8989


http://activemq.apache.org/

http://db.apache.org/derby/

Table 8. Default port assignments (continued)


JMXSecurePort The secure port used by the Java Management eXtension(JMX) to connect to a running WebSphere Application ServerCommunity Edition instance. JMX is a framework thatprovides a standard way of exposing Java resources, forexample, application servers, to a system managementinfrastructure. Using the JMX framework, a provider canimplement functions, such as listing the configuration settings,and editing the settings. This framework also includes anotification layer that management applications can use tomonitor events such as the startup of an application server.For WASCE 2.1.0.1 and later, the --secure option can be usedto connect to JMX server using a secure channel with thedeploy and shutdown commands.

9998

NamingPort The Jconsole port for monitoring local server overallinformation, for example memories, threads, and VMsummaries. The default naming port for WebSphereApplication Server Community Edition is 1099.Note: This value was changed from the default IBMWebSphere Application Server Community Edition value toresolve a conflict with IBM Tivoli Monitoring.

2098

OpenEJBPort The port used by OpenEJB (Enterprise JavaBeans) forproviding EJB services.

4201

ORBPort The port used by the WebSphere Application ServerCommunity Edition OpenEJB ORB Adapter.

6882

ORBSSLPort The port used by the WASCE Object Request Broker (ORB)Secure Socket Layer (SSL).

2001

SMTPPort The port number where WebSphere Application ServerCommunity Edition listens for Simple Mail Transfer Protocol(SMTP) requests. .

25

To query current port usage for possible conflicts, you might use this method. The example usesthe COSNamingPort default value of 1050 as an example.1) Issue this command:

Platform Command

Linux or UNIX netstat -an | grep 1050

Windows netstat -an | find "1050"

2) Examine the output for a return of value 1050. If no value is returned, then it is likely that port1050 is not currently in use.

e. Edit the section containing the parameters for generation of custom key pair for securecommunication with Enterprise Common Collector clients. Provide the following information:

Table 9. Parameters for key pair generation

Parameter Explanation Default value

ECC_CERT_O The short name of your organization(for example, IBM).

Unknown

You cannot advance without replacing"unknown" with a valid value.


Table 9. Parameters for key pair generation (continued)

Parameter Explanation Default value

ECC_CERT_ALIAS The alias under which the key pairshould be stored in the keystore.

Unknown

You cannot advance without replacing"unknown" with a valid value.

4. Save the updated setup_ecc_install.rsp file.5. Run the installer matching your operating system and architecture. The installer runs without further

prompts and with minimal screen output.

Platform Command

UNIX or Linux ./<setup_file> -f full_path/setup_ecc_install.rsp

Windows start /wait <setup_file> -f full_path\setup_ecc_install.rsp

The start /wait command stops the setup_ecc_windows.exe file from returningimmediate values. If the installation wizard starts instead, this means that the -f parameteris not valid. The -f parameter tells the installer where the response file is located and thename of the response file. Stop installing, check the path and the file name to ensure thatthey are correct, and reissue the command.

Where <setup_file> is one of the following:

Table 10. Platforms and versions of the Enterprise Common Collector installation

installation wizard Target platform for installing the collector







Example

Here is the text of the response file:## setup_ecc_install.rsp#### InstallAnywhere variables to configure for silent install of Enterprise Common Collector#### Windows supported platforms:#### Usage: start /wait setup_ecc_v110_windows.exe -f <full_path>\setup_ecc_install.rsp#### With windows, the "start /wait" command will prevent setup_ecc_v110_windows.exe## from immediately returning.#### If you will see GUI panel at the beginning it means that -f parameter## is not valid. Stop installing, check -f parameter and start again.###### Unix supported platforms:#### Usage (linux example): ./setup_ecc_v110_xlinux.bin -f <full_path>/setup_ecc_install.rsp####


## At a minimum, you MUST update and uncomment the following statements as noted## in the "Install Settings" section below:#### USER_INSTALL_DIR## LICENSE_ACCEPTED##################################################################################################

######################################## Install Settings ########################################

################################################################ Do not change the following line. This setting indicates# to use this file for a silent installation.###############################################################INSTALLER_UI=silent

################################################################################## Set Silent License Acceptance## Accept license agreement: remove the number sign (#),# for example, LICENSE_ACCEPTED=true## Silent Uninstall: do not define the LICENSE_ACCEPTED,# leave it commented out by having the number sign (#) in front of it.## If the LICENSE_ACCEPTED is anything other than "true",# the installation will exit, no log will be produced,# and no indication of failure provided.## By removing the number sign (#) and changing the value# for LICENSE_ACCEPTED from "false" to "true", you have signified# acceptance of the IBM Tivoli Monitoring for zEnterprise license agreement.##################################################################################LICENSE_ACCEPTED=false

####################################################################### IBM Tivoli zEnterprise Monitoring ECC Install Location## The install location of the product. Specify a valid directory# into which the product should be installed. For example, to# install the product to C:\Program Files\IBM\ECC, use# C:\\Program Files\\IBM\\ECC##---- Windows platform:#USER_INSTALL_DIR=C:\\IBM\\ECC

##---- UNIX platform:#USER_INSTALL_DIR=/opt/IBM/ecc

#####################################################################

#################################################################################### Port Assignments## Select Next to keep these default port values as listed above or specify other# values below. It is recommended to first examine your current port usage# (with netstat command) in order to determine if there will be port conflicts.## Valid range is 1-65535. Numeric characters only.


## Note: Port settings that are not valid will be reset to their respective# default value during installation processing.## For reference, these are the default values:## ActiveMQPort=61626 JMXPort=8989 OpenEJBPort=4201# AJPPort=8009 JMXSecurePort=9998 ORBSSLPort=2001# COSNamingPort=1050 MulticastDiscoveryPort=6142 ORBPort=6882# DerbyPort=1527 MultipointPort=4212 SMTPPort=25# HTTPSPort=8443 NamingPort=2098## Make the appropriate updates to the port setting below or keep the default values:#ActiveMQPort=61626AJPPort=8009COSNamingPort=1050DerbyPort=1527HTTPSPort=8443JMXPort=8989JMXSecurePort=9998MulticastDiscoveryPort=6142MultipointPort=4212NamingPort=2098OpenEJBPort=4201ORBPort=6882ORBSSLPort=2001SMTPPort=25

##################################################################################

#################################################################################### Parameters for generation of custom key pair for secure communication with# Enterprise Common Collector clients## Replace each of the values specified with a value appropriate for your# organization## ECC_CERT_O: Short name of your organization (e.g., IBM)ECC_CERT_O=Unknown# ECC_CERT_ALIAS: Alias under which the key pair should be stored in the keystore# (e.g., MyAlias)ECC_CERT_ALIAS=Unknown

Verifying that the Enterprise Common Collector installed correctlyFollow this procedure to start the Enterprise Common Collector and verify that you have installed thecomponent correctly.

About this task

Do not attempt to perform any actions involving the Enterprise Common Collector until you havecompleted the configuration found in Chapter 5, “Customizing the Enterprise Common Collector,” onpage 65.

Procedure1. If you installed the Enterprise Common Collector from a user ID with Administrator (Windows) or

root (Linux or UNIX) authority, then the collector should start automatically as a service or daemon. Ifyou did not install the collector in this way, you must register the service manually. See “Manuallyregistering the Enterprise Common Collector as a service” on page 52.


2. To confirm that the Enterprise Common Collector started successfully, look for this message in thecollector log file.a. Navigate to this location and open the Enterprise Common Collector message log:


Linux or UNIX /opt/IBM/ecc/wasce/var/log/EnterpriseCommonCollector.0.log

Windows C:\IBM\ECC\wasce\var\log\EnterpriseCommonCollector.0.log

b. Look for this message:CTGEZ0101I Enterprise Common Collector started successfully.

This message indicates that all components of the collector started successfully.3. To understand how to start and stop the Enterprise Common Collector service, see “Starting,

stopping, removing, installing, and querying the status of the Enterprise Common Collector” on page53.

What to do next

If you did not install the Enterprise Common Collector from a user ID with administrator (Windows) orroot (Linux or UNIX) authority, you must register the Enterprise Common Collector service manually. See“Manually registering the Enterprise Common Collector as a service.”

If you are ready to configure the Enterprise Common Collector, proceed to Chapter 5, “Customizing theEnterprise Common Collector,” on page 65.

Manually registering the Enterprise Common Collector as a serviceIf you did not install the Enterprise Common Collector from a user ID with administrator (Windows) orroot (Linux or UNIX) authority for the operating system, then you must install the Enterprise CommonCollector service manually.

About this task

This task must be performed from a user ID with administrator (Windows) or root (Linux or UNIX)authority for the operating system. This task requires that at least 100 KB of space be available in yourtmp directory. This space in the tmp directory is also needed at install time (that is, when the installercreates the service/daemon).

Procedure1. Navigate to the subdirectory where the ECC service startup scripts are found:

Platform Location of the startup script

UNIX or Linux <install_dir>/bin/

Windows <install_dir>\bin\

2. Issue the platform-specific command to launch the Enterprise Common Collector service.

Platform Command

Linux or UNIX ./eccService.sh install

Windows eccService install

A window is displayed briefly.


3. To confirm that the Enterprise Common Collector service or daemon started correctly, open acommand window and navigate to this location:

Platform Location



And issue this command:

Platform Command

Linux or UNIX ./eccService.sh status

Windows eccService status

If the eccService is running, you should see a message similar to the following message:

Platform Message

UNIX or Linux Status for Service eccSvc:Server on port 52098 is running.

Windows Status of Service ’eccsrv’:----------------------------------------------------ExitCode Name ProcessId StartMode State Status0 eccsrv 1168 Auto Running OK

4. To further confirm that the Enterprise Common Collector is running, go to the Enterprise CommonCollector log file found in this location:


UNIX or Linux <install_dir>/var/logs/

Where <install_dir> is the home directory for WebSphere Application Server CommunityEditions.

Windows <install_dir>\var\logs\

Where <install_dir> is the home directory for WebSphere Application Server CommunityEditions.

Look for this message:CTGEZ0101I Enterprise Common Collector started successfully.

This message indicates that all components of the collector started successfully.If you do not see this message, try starting the collector anyway and see if the failure was in thelogging operation. If the collector also fails to start, call IBM Software Support.

Starting, stopping, removing, installing, and querying the status of theEnterprise Common CollectorThe Enterprise Common Collector runs as a Windows service named eccsrv or as a Linux or UNIXdaemon named eccSvc.

About this task

After installation, when you start, stop, remove, or query the status of the Enterprise Common Collector,you are actually addressing these commands to the Windows service or Linux or UNIX daemon. The


Enterprise Common Collector service is configured to start when the operating system is booted and runsin the background as long as the operating is running. The service can also be started and stoppedmanually when required.

Once the ECC is installed as a service you can :v Stop the Enterprise Common Collector servicev Start the Enterprise Common Collector servicev Remove the Enterprise Common Collector servicev Install the Enterprise Common Collector service after it was removedv Query the status of the Enterprise Common Collector servicev List any Java processes associated with the Java Runtime Environment installed with the Enterprise

Common Collector.v Kill any Java processes that may still be running after a crash affecting the Enterprise Common

Collector.

If you issue the eccService command without parameters or with invalid parameters, a brief usagestatement is provided. The usage statement provides a list of valid parameters.

Procedure1. To stop the Enterprise Common Collector service, do the following:

a. Open a command window and navigate to the directory where the eccService utility script isinstalled.

Platform Location of the install script

Linux or UNIX <install_dir>/bin/


b. From a user ID with administrator (Windows) or root (Linux or UNIX) authority, issue thiscommand:


Linux or UNIX ./eccService.sh stop

Windows eccService stop

You see this message confirming that the Enterprise Common Collector service has been stopped.


Linux orUNIX

"Stopping Service eccSvc...Shutting down server on port 52098.Waiting for process ’<install_dir>/jre/jre/bin/java’ to terminate...No Enterprise Common Collector Java processes found."

Windows The service ’eccsrv’ has been stopped.No Enterprise Common Collector Java processes were found.

Now, if you want to use the Enterprise Common Collector, you must start the service or restart thecomputer (operating system) on which the Enterprise Common Collector is installed.

2. To start the Enterprise Common Collector service manually, do the following:a. Open a command window and navigate to the directory where the Enterprise Common Collector

service is running.







Linux or UNIX ./eccService.sh start

Windows eccService start

You see this message confirming that the Enterprise Common Collector service has been started.


Linux orUNIX

Starting Service eccSvc...Starting server on port 2098.

Windows Start command for Service ’eccsrv’ has been issued.

Status of Service ’eccsrv’:----------------------------------------------------ExitCode Name ProcessId StartMode State Status0 eccsrv 2164 Auto Running OK

If you did not install Enterprise Common Collector from a user ID with administrator (Windows)or root (Linux or UNIX) authority, you need to perform this step every time you start theEnterprise Common Collector. If you ran the registration script described in “Manually registeringthe Enterprise Common Collector as a service” on page 52, you do not need to start the serviceunless you stopped it manually since you last restarted your operating system.

c. Another way to start the Enterprise Common Collector service on Windows is to do the following:1) Access the Windows location for starting the the Enterprise Common Collector service: Start ->

Control Panel -> Administrative Tools -> Services.2) Scroll down to IBM Enterprise Common Collector Service - eccsrv.3) Right-click on it and select Start.

3. To remove the Enterprise Common Collector service, do the following:a. Ensure that the Enterprise Common Collector service is stopped.b. Open a command window and navigate to the directory where the eccService utility script is

installed.




c. From a user ID with administrator (Windows) or root (Linux or UNIX) authority, issue thiscommand:


Linux or UNIX ./eccService.sh remove

Windows eccService remove

You see this message confirming that the Enterprise Common Collector service has been removed.


Linux orUNIX

Removing Service eccSvc...

Windows Service ’eccsrv’ has been removed.

Note that this action removes the service from the set of programs that are autostated when the


operating system is booted. It does not uninstall the Enterprise Common Collector. To uninstall theEnterprise Common Collector, see “Uninstalling the Enterprise Common Collector using theinstallation wizard” on page 59 or “Uninstalling the Enterprise Common Collector from theconsole” on page 62.

4. If you have removed the Enterprise Common Collector service, you must install it again. To do this,do the following:a. Open a command window and navigate to the directory where the eccService utility script is

installed






Linux or UNIX ./eccService.sh install

Windows eccService install

You see a message similar to one of the following:


Linux orUNIX

Installing Service eccSvc...

Windows The service ’eccsrv’ has been installed.

5. To query the status of the Enterprise Common Collector service, do the following:a. Open a command window and navigate to the directory where the eccService utility script is

installed






Linux or UNIX ./eccService.sh status

Windows eccService status

You see a message similar to one of the following:


Linux orUNIX

Status for Service eccSvc:Server on port 2098 is running.



6. To list any Java processes associated with the WebSphere Application Server Community Editioninstance that is installed with the Enterprise Common Collector, do the following:a. Open a command window and navigate to the directory where the eccService utility script is

installed.






Linux or UNIX ./eccService.sh listproc

Windows eccService listproc

You see messages similar to the following:


Linux orUNIX

One of the following:

No Enterprise Common Collector Java processes found.

Or it will list the processes, such as:

PID PORT COMMAND19982 52098 <install_dir>/jre/jre/bin/java

Windows One of the following:

No Instance(s) Available.

Or it will list the processes, such as:

HandleCount Name Priority ProcessId ThreadCount WorkingSetSize653 java.exe 8 1332 21 136081408

7. To stop all of the Java processes associated with the WebSphere Application Server CommunityEdition instance that is installed with the Enterprise Common Collector, do the following:a. Open a command window and navigate to the directory where the eccService utility script is

installed.






Linux or UNIX ./eccService.sh kill

Windows eccService kill

Attention: Use the kill command only if the stop command fails to properly stop the ECCservice or daemon. Using the kill command can result in data loss.After issuing this command, you see a message similar to one of the following:



Linux orUNIX

If no processes are available to be killed:

No Enterprise Common Collector Java processes found.

If there is a process to shut down:

Terminating Enterprise Common Collector processes:Terminating Process 19982...

Windows The process ’<install_dir>\jre\jre\bin\java.exe’ has been shut down.

Resetting the Enterprise Common Collector invalid login count for theuser ID adminYou are permitted a maximum of three failed attempts to log on to any Enterprise Common Collectoruser ID, including the default admin user ID. More failed attempts cause a user ID to be locked ordisabled for logon.

This condition can arise if a rogue user is attempting to log on to admin and is incorrectly guessing itspassword. If you have another Enterprise Common Collector user ID defined in the Administrator role,you can use that user ID to reset the invalid logon count for the admin user ID. Therefore, creation of anadditional user ID in the role of Administrator during the installation process is suggested. See “Creating,listing, updating, and deleting clients by using the command-line” on page 75 for information aboutupdating a client ID to reset a password or the number of logon attempts. However, if admin is the onlyuser ID defined in the Administrator role, and it is disabled due to incorrect password attempts, it can bereset using the reseteccadmin utility script.

If the admin user ID is the only one with administrator authority, and it is locked, use this process toreset the invalid login count. Run this script from the system where the Enterprise Common Collector isinstalled.1. Stop the Enterprise Common Collector. (The script performs this shutdown automatically if the

Enterprise Common Collector is running.)2. Navigate to the subdirectory where the administrator scripts are found:




3. From a user ID with administrator (Windows) or root (Linux or UNIX) authority, issue this command:


Linux or UNIX ./reseteccadmin.sh

Windows reseteccadmin.bat

This script resets the invalid-login-attempts attribute to 0. This script does not alter the existingpassword for the admin user ID. If the password for the admin user ID has been lost, the EnterpriseCommon Collector database and backup database must be deleted and recreated, and configurationsettings reestablished. You will have to perform the following configuration steps again:a. Log in to the administrator console using the default user ID and password in interactive mode.

See “Logging on to the Enterprise Common Collector by using the command-line interface” onpage 70.

b. If you want to use LDAP authentication, see “Defining whether the Enterprise Common Collectoruses base authentication or LDAP by using the command-line” on page 72.


c. If you want to use a certificate other than the basic self-signed certificate or use a differenttruststore, see “Managing certificates by using the command-line” on page 73.

d. If you want to set up collection profiles other than the default profile, see “Setting up thecollection profile by using the command-line” on page 78.

e. You must redefine your data sources. See “Setting up HMC data sources by using thecommand-line” on page 83.

f. You must redefine your clients. See “Creating, listing, updating, and deleting clients by using thecommand-line” on page 75.

4. Restart the Enterprise Common Collector using the procedure described in “Starting, stopping,removing, installing, and querying the status of the Enterprise Common Collector” on page 53. Thereseteccadmin script automatically restarts the Enterprise Common Collector if it was found activewhen reseteccadmin was started.

Restoring the Enterprise Common Collector default configurationIf it becomes necessary to reset the Enterprise Common Collector to its default configuration, this can bedone with the following steps.

About this task

This might be necessary if, for example, the password for the admin user ID is missing and no other userID owning the Administrator role is available to change this password. Be aware that resetting theEnterprise Common Collector to its default configuration means that you lose all your configuration(such as data sources, user IDs, and configuration profiles). You will have to reconfigure the collector. SeeChapter 5, “Customizing the Enterprise Common Collector,” on page 65 for an overview of theseconfiguration tasks.

Procedure1. Stop the Enterprise Common Collector.2. Delete the following directories, including all the files and subdirectories contained in them:


UNIX or Linux <install_dir>/wasce/var/ecc/backup<install_dir>/wasce/var/ecc/database

Windows <install_dir>\wasce\var\ecc\backup<install_dir>\wasce\var\ecc\database

Note: If the collector is started with the database directory deleted, the collector attempts toreconfigure itself from the latest available backup bundle. If this attempt is unsuccessful, the collectorreconfigures itself with the default configuration. However, a reconfiguration from the latest backupbundle could mean that the situation the required restoration of the default configuration (a lostpassword for the admin user ID, for example) might still exist in the restored backup bundle.

3. Start the Enterprise Common Collector. During startup, the collector will recreate its defaultconfiguration (including the admin user ID with the default password).

4. Reconfigure the Enterprise Common Collector to match your needs again. See Chapter 5,“Customizing the Enterprise Common Collector,” on page 65.

Uninstalling the Enterprise Common Collector using the installationwizardDo the following to uninstall the Enterprise Common Collector (ECC) using the installation wizard.


About this task

The uninstallation process usually defaults to the mode that you chose for installation. If you installed inconsole mode, for example, the uninstaller defaults to console mode. Before an uninstall takes place, theEnterprise Common Collector backups and log files are automatically copied to this location:


Linux or UNIX <install_dir>/backups

Windows <install_dir>\backups

Note: In some instances, regardless of the type of uninstall operation you specified, Windows mayperform a silent uninstall. If the uninstall screens do not appear, check to see if an uninstall actuallyoccurred before you run this uninstall again.

Procedure1. Change directories to the highest-level ECC directory. The defaults are as follows:


Linux or UNIX opt/IBM/ecc/_uninst

Windows C:\IBM\ECC\_uninst

2. Issue the following platform-specific command.


Linux or UNIX <install_dir>/_uninst/ecc_uninstall

Windows <install_dir>\_uninst\ ecc_uninstall.exe

The Uninstall Enterprise Common Collector Uninstall Introduction screen is displayed:


Click Uninstall to continue or Cancel to quit.3. When the uninstall operation is complete, you see the Uninstall Enterprise Common Collector

Uninstall Complete screen.

Figure 22. Uninstall Enterprise Common Collector Uninstall Introduction screen


Click Done to exit. Uninstallation messages are found in this location:


Linux or UNIX /tmp/ecc_uninstall.log

Windows \tmp\ecc_uninstall.log

4. The uninstall process might not be able to completely remove the installation directory of theEnterprise Common Collector if additional files have been created underneath that directory after theinstallation has finished. You may have to remove residual files manually after the uninstall procedurehas been completed.

Uninstalling the Enterprise Common Collector from the consoleDo the following to uninstall the Enterprise Common Collector from the console. The uninstallationprocess defaults to the mode that you chose for installation. If you installed in console mode, forexample, the uninstaller defaults to console mode.

About this task

Before an uninstall takes place, the Enterprise Common backup directory is automatically copied to thislocation:


Linux or UNIX <install_dir>/backups

Windows <install_dir>\backups

Figure 23. Uninstall Enterprise Common Collector Uninstall Complete screen


Procedure1. Change directories to the highest-level Enterprise Common Collector directory and go to the _uninst

subdirectory. The defaults are as follows:


UNIX or Linux <install_dir>/_uninst

Windows <install_dir>\_uninst

2. Issue the following command:


UNIX or Linux ./ecc_uninstall.sh

Windows ecc_uninstall.exe

3. If you perform a silent uninstall, do not define the LICENSE_ACCEPTED. Leave this valuecommented out by retaining the number sign (#) in front of it. If you do not do this, you areprompted to accept the license.

4. The uninstallation process might not be able to completely remove the installation directory of theEnterprise Common Collector if additional files have been created underneath that directory after theinstallation has finished. You may have to remove residual files manually after the uninstall procedurehas been completed.


Chapter 5. Customizing the Enterprise Common Collector

Before you install the next component of the Tivoli zEnterprise monitoring agent solution, you mustperform some configuration on the Enterprise Common Collector.

There are two ways to configure the Enterprise Common Collector: using the command-line interface andusing the application programming interface (API).

In most instances, use the command-line interface to configure the Enterprise Common Collector.However, if you are setting up automation that uses the Enterprise Common Collector administratorfunctions, you might want to use the APIs.

This section describes how to complete configuration tasks using the command-line interface. Forinformation about performing these configuration tasks using the APIs, see Appendix A, “Customizingthe Enterprise Common Collector by using the ReST APIs,” on page 191.

Once you have installed the Enterprise Common Collector, follow this flow to configure the collector.After this initial setup, refer to the commands reference section for full details about individual sets ofcommands.1. Log in to the administrator console using the default user ID and password in interactive mode.

See “Logging on to the Enterprise Common Collector by using the command-line interface” on page70.

2. Change the default administrator password.See “Changing the default administrator password” on page 71.

3. By default, the collector uses its own base authentication. If you want to change this to LDAPauthentication, make that change now. If you want to continue using base authentication, skip thisstep.See “Defining whether the Enterprise Common Collector uses base authentication or LDAP by usingthe command-line” on page 72.

4. The Enterprise Common Collector includes a basic self-signed certificate. If you want to use adifferent certificate or a different truststore, make that change.See “Managing certificates by using the command-line” on page 73 to understand this task. Tounderstand the larger security issues around making the Enterprise Common Collector, the System zHardware Management Consoles that it communicates with, and the IBM Tivoli Monitoringenvironment that it passes data to secure, see Chapter 2, “zEnterprise monitoring security,” on page11.

5. Define your clients. These are the user IDs and passwords with their associated role or roles that youwill use to log on to the collector. Ensure that you create additional clients for which theAdministrator role is defined.See “Creating, listing, updating, and deleting clients by using the command-line” on page 75.

6. Instead of defining properties about how often to collect inventory and metrics in each data source,the Enterprise Common Collector uses collection profiles. Use collection profiles to define these valuesonce and then share these definitions with multiple data sources. A collection profile is an entity thatdefines parameters for metrics and inventory collection. The Enterprise Common Collector ships witha default collection profile named default. This collection profile includes the following information,including the corresponding configuration option shown in parentheses after each setting:v The name of the profile (-n default)v A description of this profile (-d Default Collection profile)v The short-term interval, the amount of time in seconds that passes before the discovery component

refreshes metric data from each System z Hardware Management Console (HMC) (-s 60)


v The long-term interval, the amount of time, in seconds, before the discovery component refresheshistorical metric data from each (-l 900)

v Whether long-term collection is enabled, which indicates whether historical metrics will becollected (-e false).

v Whether path-accessible-collection-enabled is enabled, which determines whether pathaccessibility status is collected for each virtualization host storage resource in the inventory. Whenvirtualization host storage resource information is retrieved from the HMC, no information aboutwhether the storage resource is currently accessible to the virtualization host via each path isretrieved. This is because path accessibility status can be time consuming to determine. After allinventory has been gathered, an optional post processing step gathers this status information if thisproperty is set to true, as it is in the default collection profile (-p true)

v The inventory resync interval, the amount of time that passes before this client resynchronizes withthe HMC (-r 28800)

If you want to change this profile or create alternate collection profiles for different data sources(HMCs), do this now. When you specify a data source in the next step, you must define theconfiguration profile used by each data source.See “Setting up the collection profile by using the command-line” on page 78.

7. The Enterprise Common Collector must know the location of the System z Hardware ManagementConsole (HMC) from which it gathers data. This location is called the data source, the system that youwill be collecting data from (in this case, an HMC) and the information about that system needed toconnect it. No default can be provided for this resource. You must define the HMC to the collector inthis configuration task for all instances of the HMC on systems from which you want to collectzEnterprise data.See “Setting up HMC data sources by using the command-line” on page 83.

8. The Enterprise Common Collector ships with a default logging level that should be sufficient for yourneeds. However, if you are debugging a problem, you might want to change the amount ofinformation captured in the collector log files. Or you might want to create multiple logger instancesto log activity on a per-component basis. The default logger is gez and the default logging level isFINE. Typically, change the logging level only if instructed to do so by IBM Software Support.See “Setting collector logging levels by using the command-line” on page 86.

Understanding the command-line interfaceThe Enterprise Common Collector (ECC) command-line interface is a Java-based framework that drivesthe administrative APIs as provided by the Enterprise Common Collector (ECC) from a systemcommand-line. This framework is based on the ECC ReST administrative API.

This section covers the following topics:v “Roles and syntax”v “Setting up a command file” on page 67v “Accessing help from the command-line interface” on page 69v “Finding messages issued by the command-line interface” on page 69v “Types of commands” on page 69

Roles and syntax

The command-line interface is implemented as a long-running shell that requires the user to logon as anadministrator and issue administrative commands, or specify a command file containing the commandsto be issued.

All Enterprise Common Collector administrative and utility commands are case-sensitive.


The supported commands are grouped into two categories: administrative commands issued againstresources such as data sources, clients, collection profiles, and configuration for logging andauthentication, and utility commands that enable a user to log on to and log off from the collector andexecute a command file. Administrative commands require that the user who is logged in and runningthe command has been assigned the Administrator role. Users with less authority (those with only theExplorer or Operator roles) can log into the command shell (the command window from whichcommands are entered and responses are received) but do not have authority to run a command file thatincludes any of the administrator commands.

All administrative commands follow the same general syntax:object operation parameters

where:

object Is one of the components on which a command can be focused: data-sources, collection-profiles,clients, loggers, or authentication.

operationIs the action performed on the objects. The possible operations are create, list, update, and deletefor administrative commands, and logon and logoff for the utility commands. The command-lineoperations correspond to the API verbs POST, GET, PUT and DELETE, respectively.

parametersIs the specific set of characteristics required to issue a particular command. For example, to issuea data-source create command, the following parameters are required:v The name of the data source you are creating: -n data_source_name

v The name of the HMC user with administrator authority creating the command and the user’spassword: -u hmc_user_name -p hmc_user_password

v The host on which the System z Hardware Management Console is running: -h hmc_host

v The name of the configuration profile you plan to assign to the data-source: -ccollection-profile-name

The collection profile name is a unique identifier generated when you define a collectionprofile. The default collection profile provided with the Enterprise Common Collector has aname of default.

You can also specify these optional parameters: -d data_source_description, -e enabled-value

See “Summary of administrator commands” on page 90 for a list of all required, optional, and defaultparameters for the administrator commands.

Utility commands do not have an object but have a set of parameters. Their syntax is:operation parameters

See “Summary of utility commands” on page 92 for a list of parameters required for utility commands.

Setting up a command file

One of the most useful utility commands is import, a file that enables a user to run a set ofadministrative commands listed in a command file. These commands can be run in either batch mode ormixed mode.

The command file is an ASCII file that you can create using any editor that does not insert rich textformatting (RTF) characters, such as Windows Notepad. Commands must be ended by a semicolon as inthe example that follows:data-sources list;clients create -n newclient -p pass -r "Operator";clients list;

Chapter 5. Customizing the Enterprise Common Collector 67

where this result is returned:name: HMCAcollection-profile-name: defaultenabled: truestatus: disconnectedhmc-user: hmcuser_1hmc-user-pwd: ********hmc-hostname: HMC510.mycompany.comdescription: HMCA datasource-----------------------------------------------------------------------------INFO: CTGEZ9810I Command clients completed.name: adminpassword: ********password-expiration-enabled: trueinvalid-login-attempts: 0roles: Administratorenabled: truedescription: default admin user-----------------------------------------------------------------------------name: newclientpassword: ********password-expiration-enabled: trueinvalid-login-attempts: 0roles: Operatorenabled: true-----------------------------------------------------------------------------name: user02password: ********password-expiration-enabled: trueinvalid-login-attempts: 0roles: Operatorenabled: truedescription: an operator-----------------------------------------------------------------------------

See the following sample command file that defines a data source and associates it with a user ID andpassword. After a successful logon, this command runs, notifies the user whether the command wassuccessful, and then exis the CLI shell.data-sources create -n mydatasource -u user0 -p pass0 -c default -h hostname;

The command returns the following message:INFO: CTGEZ9810I Command data-sources completed.

Because a command can span multiple lines in the command file, the semicolon command end mark isnecessary. The commands in the command file are read and executed sequentially. If one command fails,the command file stops executing at the bad command, and writes an error to the error log and continuesthrough the command file. If you have a command file with the separate commands where the first andthird commands are correct, they are executed. But the second incorrect command is not executed. Tocontinue running the commands in the command file after a failed command, use the pound sign (#) tocomment out commands that have already run and run the command file again.

Command files cannot be nested. That is, one command file cannot call another command file.

To avoid problems with an invalid state access for resources, the commands in the command file areexecuted synchronously. For example, in a scenario where an update request is issued against a resourcefollowed by a read request on that same resource, synchronization prevents invalid data from beingdisplayed.


Accessing help from the command-line interface

Help is available from the command-line interface. Type:help <object>

where object is one of the following: version (to display the version of the Enterprise Common Collector),data-sources, collection-profiles, clients, certificates, loggers, or authentication or one of the utilitycommands (import, logon, logoff, or exit). Helps displays the operations and parameters that a valid forthe specify object type, for example, enter this command:eccAdmin==>help data-sources

The following result is returned (the asterisk (*) means that the value is required; the double dash (--)indicates the long name of the parameter):data-sources +create +[-u|--hmc-user <value>]* [-p|--hmc-user-pwd <value>]* [-h|--hmc-hostname <value>]*[-c|--collection-profile-name <value]* [-n|- -name <value *] [-d|--description <value>][-e|--enabled <value>]

update +[-u|--hmc-user <value>] [-p|--hmc-user-pwd <value>] [-h|--hmc-hostname <value>][-c|--collection-profile-name <value>] [-n|--name <value>]* [-d|--description <value>][-e|--enabled <value>]

delete +[-n|--name <value>]*

list

Finding messages issued by the command-line interface

The command-line interface for the Enterprise Common Collector performs some validation of thecommands (such as command syntax, required parameters, and parameter syntax) before the commandsentered by the user are sent to the Enterprise Common Collector.

The command-line interface for the Enterprise Common Collector logs messages in this location:


UNIX or Linux <installdir>/logs/Ctgez_Cli.log

Windows <install_dir>\logs\Ctgez_Cli.log

Types of commands

The command-line interface is implemented as a long-running shell that requires that a user withadministrator authority logon and issue administrative commands (interactive mode) or specify acommand file containing the commands to be issued (batch mode).

The supported commands are grouped into two categories:v Administrator commands that allow you to perform one of four actions (create, read, update, or

delete) against one of the resource types (data-sources, clients, collection-profiles, loggers,authentication, and certificates) These commands correspond to the HTTP verbs POST, GET, PUT andDELETE, respectively.

v Utility commands that take care of logging into and out of the command shell, running command files(import), and exiting the command shell environment.


Logging on to the Enterprise Common Collector by using thecommand-line interfaceUse one of these two methods to launch the command-line interface and log on to the EnterpriseCommon Collector: interactive mode or batch mode.

About this task

Use one of these methods.

Procedure1. Use this information to log onto the command-line interface in interactive mode.

In interactive mode, the user is required to logon with a valid user ID and password. In this mode,once the logon is successful, the session ID is cached and used for all subsequent requests with theEnterprise Common Collector.a. Navigate to this location: <install_dir>/binb. If the command shell is not already started, start it by issuing one of these platform-specific

commands:


UNIX or Linux <install_dir>/bin/eccAdmin.sh

Windows <install_dir>\bin\eccAdmin.bat

c. Enter this command. Note that this command and all commands in the Enterprise CommonCollector customization are case-sensitive.logon -u <user> -p <password> -o <ecc_port>

Where:

user Is a user with Administrator authority on the Enterprise Common Collector. If you havejust installed the Enterprise Common Collector, you must use the default administratoruser ID: admin. This parameter is required.

passwordIs the password that corresponds to the user ID for usern. If you have just installed theEnterprise Common Collector, you must use the default administrator password: admin.Change this password immediately using the information found in “Changing the defaultadministrator password” on page 71. This parameter is required.

ecc_portIs the port that you use to connect the Enterprise Common Collector. The default value is8443 for secure communications. This parameter is optional.

d. The session ends when the user explicitly logs off or when the command shell exits.exit

This action returns you to the command shell.2. Use this information to log onto the command-line interface in batch mode. In batch mode, specify a

command file containing a set of supported commands that need to be executed. Only the commandscontained in the command file are executed. You must be logged in to use batch mode, so thecommand file cannot contain a logon, logoff, or exit command. In this example, the command file isnamed mycmd. Commands within the file are separated by semi-colons (;).a. Navigate to this location: <install_dir>/binb. If the command shell is not already started, start it by issuing one of these platform-specific

commands:



UNIX or Linux <install_dir>/bin/eccAdmin.sh


c. Enter this command. Note that this command and all commands in the Enterprise CommonCollector customization are case-sensitive.import -f mycmd -u user -p password -o <ecc_port>

Where:

mycmdIs the name of your ASCII file containing commands separated by semicolons.

user Is a user with Administrator authority on the Enterprise Common Collector. If you havejust installed the Enterprise Common Collector, you must use the default administratoruser ID: admin. This parameter is required if you have not logged on previously.

passwordIs the password that corresponds to the user ID for user. If you have just installed theEnterprise Common Collector, you must use the default administrator password: admin.Change this password immediately using the information found in “Changing the defaultadministrator password.” This parameter is required if you have not logged on previously.

ecc_portIs the port that you use to connect the Enterprise Common Collector. The default value is8443 for secure communications. This parameter is optional.

d. The session ends when the user explicitly logs off or when the command shell exits.exit

This action returns you to the command shell.

Changing the default administrator passwordThe first time you log on to the Enterprise Common Collector, you should change the administratorpassword provided to help you set up the collector.

About this task

The default user ID is admin. The default password is admin.

Procedure1. Navigate to this location: <install_dir>/bin2. If the command shell is not already started, start it by launching the eccAdmin command shell:

Platform Command file name

Linux or UNIX <install_dir>/bin/eccAdmin.sh


3. Enter this command. Note that this command and all commands in the Enterprise Common Collectorcustomization are case-sensitive.eccAdmin logon -u admin -p admin -o <ecc_port>

Where:


ecc_portIs the port that you use to connect the Enterprise Common Collector. The default value is8443 for secure communications. The parameter is optional.

4. Enter this command to reset the password for admin:clients update -n admin -p <new_client_password>

Where

new_client_passwordIs the new value you provide as the password for default administrative user admin.

and the command returns the following:INFO: CTGEZ9810I Command clients completed.

5. Complete the other configuration tasks in this section, and log off from the command shell.logoffexit

This action returns you to the command shell. For example:eccAdmin==>exitC:\IBM\ECC\bin>

Defining whether the Enterprise Common Collector uses baseauthentication or LDAP by using the command-lineUse the commands described in this section to define how the Enterprise Common Collectorauthenticates its clients: using the base mechanism or LDAP.

About this task

By default, the collector uses its own base authentication. If you want to change this to LDAPauthentication, make that change now. If you want to continue using base authentication, skip this step.

For information about performing these tasks using the APIs, see “Defining whether the EnterpriseCommon Collector uses base authentication or LDAP using the ReST APIs” on page 193.

Procedure1. Logon to the Enterprise Common Collector command shell. See “Logging on to the Enterprise

Common Collector by using the command-line interface” on page 70 for more information.2. To determine how the Enterprise Common Collector is configured to handle the authentication of its

clients, that is, whether it is using the basic mechanism or delegating password verification to LDAP,use the list commandauthentication list

This command returns something similar to the following:name: Authentication Optionsldap-authentication: falsepassword-expiration-interval: 90

For information about the API for performing this action, see “GET/eccapi/admin/config/authentication” on page 216.

3. To update the authentication mechanism that the Enterprise Common Collector uses to authenticateits clients, from the base authentication to LDAP server or from the LDAP server to the baseauthentication, use this API:authentication update -a <ldap_authentication_value> -p <ldap_user_provider>-f <ldap_user_filter> -s <ldap_use_ssl> -e <password_expiration_interval>

Where:


ldap_authentication_valueIs either true or false and specifies whether LDAP authentication is enabled. The default isfalse. By default, base authentication is provided. This parameter is optional.

ldap_user_providerIs the URL of the LDAP directory with a protocol prefix. This might optionally include thelocation in the LDAP directory tree where user entries are located. This parameter is optional.

ldap_user_filterIs the LDAP search filter used to find a user record for the specified user ID. This parameteris optional.

ldap_use_sslIs either true or false and specifies whether the connection to the LDAP directory should useSSL or not. The default is false. This parameter is optional.

password_expiration_intervalIs the number of days that pass before the password expires. This parameter is required.

This command returns output similar to the following:INFO: CTGEZ9810I Command authentication completed.

For information about the API for performing this action, see “PUT/eccapi/admin/config/authentication” on page 244.

4. If you no longer need the command shell, log off and exit. See “Logging on to the EnterpriseCommon Collector by using the command-line interface” on page 70.

Managing certificates by using the command-lineUse these commands to manage Enterprise Common Collector security certificates.

About this task

You can specify whether all certificates should be trusted. You can also list all the certificates in theEnterprise Common Collector truststore, import certificates from other sources, and delete certificates.You can perform these certificate operations even if the "trust-all" property is enabled.

Remember that the command-line interface manages certificates between the Enterprise CommonCollector and the System z Hardware Management Console only. The trust-all certificates used for securecommunication between the collector and the Tivoli zEnterprise monitoring agent are covered under“Importing the generated Enterprise Common Collector certificate into the monitoring agent's truststore”on page 139

More information about the APIs to perform these actions, see “Managing certificates by using the ReSTAPI” on page 195.


Common Collector by using the command-line interface” on page 70 for more information.2. To list all the certificates in the Enterprise Common Collector truststore, use this command:

certificates list

Immediately after installation there are not certificates to list, and the command returns only the stateof the trust-all-certificates parameter, which is false.trust-all-certificates: false

After you import certificates from the System z Hardware Management Console, this commandreturns information similar to this that describes the certificates:


eccAdmin==>certificates listalias: myaliassubject-dn: CN=myhost, OU=Tivoli, O=IBM, L=Unknown, ST=Unknown, C=Unknownissuer-dn: CN=myhost, OU=Tivoli, O=IBM, L=Unknown, ST=Unknown, C=Unknownfingerprint-md5: 77:61:8B:21:D8:D8:CF:A7:3B:47:65:75:4F:ED:55:E1fingerprint-sha1: C2:23:5C:AC:04:00:D0:7C:4E:93:74:45:8D:97:2A:2C:AE:4B:5E:29not-after: Tue Aug 07 10:28:24 CEST 2012not-before: Wed May 09 10:28:24 CEST 2012serial-number: 1336552104version: 3signature-algorithm-name: SHA1withDSApublic-key-algorithm-name: DSApublic-key-format: X.509-----------------------------------------------------------------------------trust-all-certificates: true-----------------------------------------------------------------------------

For information about performing this action using an API, see “GET/eccapi/admin/config/certificates/” on page 217. If you want to see the certificate associated with aparticular alias, you can use the “GET /eccapi/admin/config/certificates/{alias}” on page 219 API todiscover the alias or use the certificates list command to discover information about allcertificates. To show the current setting for the “trust all certificates” option, use the “GET/eccapi/admin/config/certificates/trust-all” on page 221 API. If trust-all is enabled, the EnterpriseCommon Collector does not validate the Hardware Management Console certificates whenestablishing an HTTPS connection. This parameter does not disable the "normal" HTTPS certificatemanagement between WebSphere Application Server Community Edition as a server and clients (suchas the Tivoli zEnterprise monitoring agent).

3. To import a new certificate into the Enterprise Common Collector truststore, use this command:certificates create -f <filename> -a <alias>

Where:

filenameIs the name of the file that contain the new certificate. Certificates that can be imported mustuse a printable encoding format (for example, those that the Internet RFC 1421 standard forPrivacy-Enhanced Mail (PEM) format). It is not possible to import a certificate in a binaryformat. Here is a sample:-----BEGIN CERTIFICATE-----MIIDBTCCAsOgAwIBAgIET6oqqDALBgcqhkjOOAQDBQAwZjEQMA4GA1UEBhMHVW5rbm93bjEQMA4GA1UECBMHVW5rbm93bjEQMA4GA1UEBxMHVW5rbm93bjEMMAoGA1UEChMDSUJNMQ8wDQYDVQQLEwZUaXZvbGkxDzANBgNVBAMTBm15aG9zdDAeFw0xMjA1MDkwODI4MjRaFw0xMjA4MDcwODI4MjRaMGYxEDAOBgNVBAYTB1Vua25vd24xEDAOBgNVBAgTB1Vua25vd24xEDAOBgNVBAcTB1Vua25vd24xDDAKBgNVBAoTA0lCTTEPMA0GA1UECxMGVGl2b2xpMQ8wDQYDVQQDEwZteWhvc3QwggG3MIIBLAYHKoZIzjgEATCCAR8CgYEA/X9TgR11EilS30qcLuzk5/YRt1I870QAwx4/gLZRJmlFXUAiUftZPY1Y+r/F9bow9subVWzXgTuAHTRv8mZgt2uZUKWkn5/oBHsQIsJPu6nX/rfGG/g7V+fGqKYVDwT7g/bTxR7DAjVUE1oWkTL2dfOuK2HXKu/yIgMZndFIAccCFQCXYFCPFSMLzLKSuYKi64QL8Fgc9QKBgQD34aCF1ps93su8q1w2uFe5eZSvu/o66oL5V0wLPQeCZ1FZV4661FlP5nEHEIGAtEkWcSPoTCgWE7fPCTKMyKbhPBZ6i1R8jSjgo64eK7OmdZFuo38L+iE1YvH7YnoBJDvMpPG+qFGQiaiD3+Fa5Z8GkotmXoB7VSVkAUw7/s9JKgOBhAACgYAk56z7H7WuGWmSudoFE2Nk2tiFsDTkEXnup7GYkGnayIQARZQtTEEiLZ48GC1SHJDvsoLp5oDkf4O2V1CLJy6X0S1okbTdN+SV+BuLZexiA1srUAARoG6nHHG0YZ3xYqM8wE/Y1YoCvsvIcKA+rX6n1FIpCnaU6+sjaWFr2ers7DALBgcqhkjOOAQDBQADLwAwLAIUZC6epGPyVx38CiUCQxTE6ClzjpcCFHvc954RrLad29I9xBm6EW5LY1d1-----END CERTIFICATE-----

alias Is the alias name that you assign to the certificate.

This command returns information similar to this:INFO: CTGEZ9810I Command certificates completed.

For information about performing this action using an API, see “PUT/eccapi/admin/config/certificates/{alias}” on page 247.


4. To update the configuration of the truststore to change the current setting for the “trust allcertificates” option in the Enterprise Common Collector, use this command:certificates update -t <trust-all-certificates>

Where:

trust-all-certificatesIs either true, meaning that the Enterprise Common Collector trusts all certificates, or false,meaning that it does not. This is a required parameter. The default configuration sets thisvalue to false.


For information about performing this action using an API, see “PUT/eccapi/admin/config/certificates/trust-all” on page 249.

5. To delete a certificate, you must first know its alias. Find the alias using the certificates listcommand. To then delete a certificate from the Enterprise Common Collector truststore, use thefollowing command:certificates delete -a <alias>

Where

alias Is the alias name that you assigned to this certificate when you imported it.


For information about performing this action using an API, see “DELETE/eccapi/admin/config/certificates/{alias}” on page 201.


Creating, listing, updating, and deleting clients by using thecommand-lineUse these commands to create, list, update, and delete clients who have access to the Enterprise CommonCollector.

About this task

You can add clients, lists the clients that are already defined, update clients, and delete clients.

To perform these tasks using the API, see“Creating, listing, and updating clients by using the ReST API”on page 196.


Common Collector by using the command-line interface” on page 70 for more information.2. To create the client specified with client-name from the Enterprise Common Collector database, use this

command:clients create -n <client-name> -p <client-password> -r <roles> -d <client-description>-e <enabled-value> -w <password-expiration-enabled>

Where:


client-nameIs the name of the client. This client name is the user ID that the client uses to log on to theEnterprise Common Collector. The parameter is required.

client-passwordIs the password that corresponds to the user ID assigned to this client. This parameter isrequired if authentication is not configured to use LDAP.

roles Is one or more of the three case-sensitive roles defined for all Enterprise Common Collectorclients:v Administrator role that can perform administrative tasks, such as creating data sources or

clientsv Explorer role that can perform discovery tasks, such as discovering all virtual serversv Operator role that can perform monitoring or discovery tasks, such at retrieving detailed

information about virtual servers and their performance metrics

Multiple roles can be defined for a client. For any one client to have access to all aspects ofthe collector, all three roles must be defined. The roles initial letter is capitalized (for example:roles: Administrator), and roles are listed on a single line and separated by commas. Thisparameter is required.

client-descriptionIs description of the client. This parameter is optional.

enabled-valueIndicates whether the client is enabled. If the client is not enabled, logon is not permitted. Thedefault is true. This parameter is optional.

password-expiration-enabledIndicates whether the client password expiration is enabled. If this value is not defined, thepassword does not expire. This parameter is optional. The default value is true. If thisparameter is enabled, the password expires in 90 days.

This sample command:eccAdmin==>clients create -n andy -p andypw -r Administrator,Operator -d "super user"-e true

returns the following:INFO: CTGEZ9810I Command clients completed.

For information about performing this action using the API, see “POST /eccapi/admin/clients/” onpage 230.

3. To list all clients configured in the Enterprise Common Collector, use this command:clients list

The command returns output similar to the following:name: adminpassword: ********password-expiration-enabled: trueinvalid-login-attempts: 0roles: Administratorenabled: truedescription: default admin user-----------------------------------------------------------------------------name: andypassword: ********password-expiration-enabled: trueinvalid-login-attempts: 0roles: Operator,Administratorenabled: truedescription: an operator-----------------------------------------------------------------------------


For information about performing this action using the API, see “GET /eccapi/admin/clients” onpage 206. To get information about a specific client defined in Enterprise Common Collector, use thisAPI: “GET /eccapi/admin/clients/{client-name}” on page 209.

4. To update the attributes of a specific client configured in the Enterprise Common Collector, use thiscommand:clients update -n <client-name> -d <client-description> -p <client-password>-e <enabled-value> -r <roles> -w <password-expiration-enabled> -m <resume>

Where:

client-nameIs the name of the client. This client name is the user ID that the client uses to log on to theEnterprise Common Collector. This parameter is required.

client-descriptionIs description of the client. This parameter is optional unless you want to change the currentvalue.

client-passwordIs the password that corresponds to the user ID assigned to this client. This parameter isoptional unless you want to change the current value.

enabled-valueIndicates whether the client is enabled. If the client is not enabled, logon is not permitted.This parameter is optional unless you want to change the current value.

roles Is one or more of the three case-sensitive roles defined for all Enterprise Common Collectorclients:v Administrator role that can perform administrative tasks, such as creating data sources or

clientsv Explorer role that can perform discovery tasks, such as discovering all virtual serversv Operator role that can perform monitoring or discovery tasks, such at retrieving detailed

information about virtual servers and their performance metrics

Multiple roles can be defined for a client. For any one client to have access to all aspects ofthe collector, all three roles must be defined. The roles initial letter is capitalized (for example:roles: Administrator), and roles are listed on a single line and separated by commas. Thisparameter is optional unless you want to change the current value.

password-expiration-enabledIndicates whether the client password expiration is enabled. If this value is not defined, thepassword does not expire. This parameter is optional unless you want to change the currentvalue. If this parameter is enabled, the password expires in 90 days.

resume Determines whether the client counter invalid-login-attempts counter should be set to 0. TheAdministrator uses this function to reset a locked password after a client exceeds themaximum number of login attempts (3).

This sample command:eccAdmin==>clients update -n andy -r Operator,Administrator


For information about performing this action using the API, see “PUT/eccapi/admin/clients/{client-name}” on page 240.

5. To reset the client counter invalid-login-attempts to 0 after a client exceeds the maximum number oflogin attempts (3), use this command:clients update -n <client-name> -m <resume>

Where:



resume Determines whether the client counter invalid-login-attempts counter should be set to 0. TheAdministrator uses this function to reset a locked password after a client exceeds themaximum number of login attempts (3). Valid values are true if you do not want resume andfalse if you do not.

This sample command:eccAdmin==>clients update -n andy -m true


For information about performing this action using the API, see “PUT/eccapi/admin/clients/{client-name}/resume” on page 242. See also “Resetting the EnterpriseCommon Collector invalid login count for the user ID admin” on page 58.

6. To delete client-name from the Enterprise Common Collector database, use this command:clients delete -n <client-name>

where:


The command:eccAdmin==>clients delete -n barney

returns output similar to the following:INFO: CTGEZ9810I Command clients completed.

And a subsequent clients list command no long shows client barney. Active Enterprise CommonCollector sessions for a deleted client are automatically destroyed. The count of destroyed sessions isreported in message “CTGEZ0712I” on page 167

For information about performing this action using the API, see “DELETE/eccapi/admin/clients/{client-name}” on page 200.


Setting up the collection profile by using the command-lineUse the commands described in this section to set up and administer collection profiles for the EnterpriseCommon Collector.

About this task

The Enterprise Common Collector ships with a default collection profile named default. This collectionprofile includes the following information:v The name of the profile (-n default)v A description of this profile (-d default collection profile)v The short-term interval, the amount of time in seconds that passes before the discovery component

refreshes metric data from each System z Hardware Management Console (HMC) (-s 60)v The long-term interval, the amount of time, in seconds, before the discovery component refreshes

historical metric data from each (-l 900)v Whether long-term collection is enabled, which indicates whether historical metrics are collected (-e

false).


v Whether path-accessible-collection-enabled is enabled, which indicates whether path accessibilitystatus is collected for each virtualization host storage resource (-p true)

v The inventory resynch interval, the amount of time that passes before this client resynchronizes withthe HMC (-r 28800)

If you want to change this profile or create alternate collection profiles for different data sources (HMCs),use the information that follows.

For information about performing these tasks using the API, see “Setting up collection profiles by usingthe ReST API” on page 193.


Common Collector by using the command-line interface” on page 70 for more information.2. To create a new collection profile for a user of the Enterprise Common Collector, use this command:

collection-profiles create -n <collection-profile-name> -s <short-term-interval>-r <inventory-resync-interval> -d <collection-profile-description>-l <long-term-interval> -e <long-term-collection-enabled>-p <path-accessible-collection-enabled>

Where:

collection-profile-nameIs a text string between 1 and 16 characters in length providing a name or label for thecollection profile. The parameter is required.

short-term-intervalIs an integer between 60 and 600 inclusive describing the amount of time, in seconds, betweenretrievals of the current set of metrics from the System z Hardware Management Console(HMC). The parameter is required.

inventory-resync-intervalIs an integer between 300 and 86400 inclusive describing the amount of time, in seconds, thatpasses before this client resynchronizes inventory with the System z Hardware ManagementConsole (HMC). A resync is the rediscovery of the inventory of all defined HMCs. Dependingon your configuration, this operation can take some time. A typical setting for this parameterwould be 7200 seconds (two hours) or more. This value can be an integer between 300 and86400 inclusive. The parameter is required.

collection-profile-descriptionIs a text string describing the collection profile. This parameter is optional unless you areusing this command to define it.

long-term-intervalAn integer between 300 and 1800 inclusive describing the amount of time, in seconds,between retrievals of the current set of historical metrics from the System z HardwareManagement Console (HMC). If long-term-collection-enabled is True, this value must begreater than the short-term-interval value, and it must be a multiple of the short-term-intervalvalue. The parameter is optional unless you are using this command to define it orlong-term-collection-enabled is true.

long-term-collection-enabledDefines whether long-term collection is enabled, meaning whether historical metrics data isretrieved from the System z Hardware Management Console (HMC). Valid values are true,meaning that long-term collection is enabled and false, meaning it is not. The parameter isoptional unless you are using this command to define it. The default is false.

path-accessible-collection-enabledDefines whether path accessibility status collection is enabled for this System z HardwareManagement Console (HMC). This value determines whether path accessibility status iscollected for each virtualization host storage resource in the inventory.


When virtualization host storage resource information is retrieved from the HMC, noinformation about whether the storage resource is currently accessible to the virtualizationhost via each path is retrieved. This is because path accessibility status can be time consumingto determine. After all inventory has been gathered, an optional post processing step gathersthis status information if this property is set to true.

This parameter is optional. Valid values are true, meaning that path accessible collection isenabled and false, meaning it is not. The default is true.

This sample command:eccAdmin==>collection-profiles create -n Raleigh -s 60 -r 600 -d "Raleighcollection interval" -e true -l 600

Returns the following:INFO: CTGEZ9810I Command collection-profiles completed.

And the list command showing this new collection profile looks like the following:eccAdmin==>collection-profiles listname: defaultdescription: default collection profileshort-term-interval: 60long-term-collection-enabled: falseinventory-resync-interval: 3600path-accessible-collection-enabled: false-----------------------------------------------------------------------------name: Raleighdescription: Raleigh collection intervalshort-term-interval: 60long-term-interval: 600long-term-collection-enabled: trueinventory-resync-interval: 600path-accessible-collection-enabled: true-----------------------------------------------------------------------------

For information about performing this action using an API, see “POST /eccapi/admin/data-sources”on page 236.

3. To list the properties of collection profiles defined for the Enterprise Common Collector, use thiscommand:collection-profiles list

The command returns output similar to the following:eccAdmin==>collection-profiles listname: defaultdescription: default collection profileshort-term-interval: 60long-term-collection-enabled: falseinventory-resync-interval: 3600path-accessible-collection-enabled: false-----------------------------------------------------------------------------name: Raleighdescription: Raleigh collection intervalshort-term-interval: 60long-term-interval: 600long-term-collection-enabled: trueinventory-resync-interval: 600path-accessible-collection-enabled: false-----------------------------------------------------------------------------name: Wilmingtondescription: Wilmington collection intervalshort-term-interval: 400long-term-interval: 1600long-term-collection-enabled: trueinventory-resync-interval: 800path-accessible-collection-enabled: false


-----------------------------------------------------------------------------name: Boonedescription: Boone collection intervalshort-term-interval: 600long-term-interval: 1800long-term-collection-enabled: trueinventory-resync-interval: 86400path-accessible-collection-enabled: false-----------------------------------------------------------------------------

For information about performing this action using the API, see “GET/eccapi/admin/collection-profiles” on page 211. To list the collection profile defined by thecollection-profile-name, use this API: “GET /eccapi/admin/collection-profiles/{name}” on page 213.

4. To update the description, inventory-resync-interval, long-term-collection-enabled, long-term-interval,path-accessible-collection-enabled, or short-term-interval values for a specified user of the EnterpriseCommon Collector, use this command:collection profiles update -n <collection-profile-name> -d <collection-profile-description>-s <short-term-interval> -l <long-term-interval> -e <long-term-collection-enabled>-r <inventory-resync-interval> -p <path-accessible-collection-enabled>

Where:

collection-profile-nameIs text string between 1 and 16 characters in length providing the name of the collectionprofile to update. The parameter is required.

collection-profile-descriptionIs a text string describing the collection profile. This parameter is optional unless you areusing this command to update it.

short-term-intervalIs an integer between 60 and 600 inclusive describing the amount of time, in seconds, betweenretrievals of the current set of metrics from the System z Hardware Management Console(HMC). The parameter is optional unless you are using this command to update it.

long-term-intervalIs an integer between 300 and 1800 inclusive describing the amount of time, in seconds,between retrievals of the current set of historical metrics from the System z HardwareManagement Console (HMC). If long-term-collection-enabled is true, this value must begreater than the short-term-interval value, and it must be a multiple of the short-term-intervalvalue. The parameter is optional unless you are using this command to update it.

long-term-collection-enabledDefines whether long-term collection is enabled, meaning whether historical metrics data isretrieved from the System z Hardware Management Console (HMC). Valid values are true,meaning that long-term collection is enabled and false, meaning it is not. The parameter isoptional unless you are using this command to define it.

inventory-resync-intervalIs an integer between 300 and 86400 inclusive describing the amount of time, in seconds, thatpasses before this client resynchronizes inventory with the System z Hardware ManagementConsole (HMC). A resync is the rediscovery of the inventory of all defined HMCs. Dependingon your configuration, this operation can take some time. A typical setting for this parameterwould be 7200 seconds (two hours) or more. This value can be an integer between 300 and86400 inclusive. The parameter is optional unless you are using this command to update it.

path-accessible-collection-enabledDefines whether path accessibility status collection is enabled for this System z HardwareManagement Console (HMC). This value determines whether path accessibility status iscollected for each virtualization host storage resource in the inventory.

When virtualization host storage resource information is retrieved from the HMC, noinformation about whether the storage resource is currently accessible to the virtualization


host via each path is retrieved. This is because path accessibility status can be time consumingto determine. After all inventory has been gathered, an optional post processing step gathersthis status information if this property is set to true.

This parameter is optional unless you are using this command to change it. Valid values aretrue, meaning that path accessible collection is enabled and false, meaning it is not.

This sample command:eccAdmin==>collection-profiles update -n Boone -r 1000

Returns the following:INFO: CTGEZ9810I Command collection-profiles completed.

And the list command showing this new collection profile looks like the following:eccAdmin==>collection-profiles listname: defaultdescription: default collection profileshort-term-interval: 60long-term-collection-enabled: falseinventory-resync-interval: 3600path-accessible-collection-enabled: false-----------------------------------------------------------------------------name: Raleighdescription: Raleigh collection intervalshort-term-interval: 60long-term-interval: 600long-term-collection-enabled: trueinventory-resync-interval: 600path-accessible-collection-enabled: false-----------------------------------------------------------------------------name: Wilmingtondescription: Wilmington collection intervalshort-term-interval: 400long-term-interval: 1600long-term-collection-enabled: trueinventory-resync-interval: 800path-accessible-collection-enabled: false-----------------------------------------------------------------------------name: Boonedescription: Boone collection intervalshort-term-interval: 600long-term-interval: 1800long-term-collection-enabled: trueinventory-resync-interval: 1000path-accessible-collection-enabled: false-----------------------------------------------------------------------------

For information about performing this action using the API, see “PUT/eccapi/admin/collection-profiles/{name}” on page 242.

5. To delete a collection profile for the user specified by collection-profile-name on the Enterprise CommonCollector, use this command. Note that a collection profile that is in use by one or more data sourcescannot be deleted.collection-profiles delete -n <collection-profile-name>

Where:

collection-profile-nameA text string between 1 and 16 characters in length providing the name of the collectionprofile to delete. This parameter is required.

This sample command:eccAdmin==>collection-profiles delete -n Boone

Returns the following:


INFO: CTGEZ9810I Command collection-profiles completed.

For information about performing this action using the API, see “DELETE/eccapi/admin/collection-profiles/{name}” on page 201


Setting up HMC data sources by using the command-lineUse the commands described in this section to set up data sources for the Enterprise Common Collector.

About this task

You must define a data source before you can start the Enterprise Common Collector and see data on theTivoli Enterprise Portal.

For information about performing these actions using APIs, see “Setting up HMC data sources by usingthe ReST API” on page 194.


Common Collector by using the command-line interface” on page 70 for more information.2. To create a System z Hardware Management Console as a new data source for the Enterprise

Common Collector, use this command:data-sources create -n <data-source-name> -u <hmc-user-name> -p <hmc-user-password>-h <hmc-host> -c <collection-profile-name> -d <data-source-description) -e <value>

Where:

data-source-nameIs a text string 1 to 16 in length identifying the data source. This parameter is required.

hmc-user-nameIs the user ID to use to logon to the HMC. This parameter is required.

hmc-user-passwordIs the password to use to logon to the HMC. This parameter is required.

hmc-hostIs the host name of the HMC. This value must must be 1 to 256 characters in length. Thisname cannot contain characters other than alphabetic characters (a-z, A-Z), digits (0-9), -(minus sign), _ (underscore), : (colon), % (percent sign), or . (period). This parameter isrequired.

collection-profile-nameIs the name of the collection profile to use. This parameter is required.

data-source-descriptionIs a text string describing the HMC. This parameter is optional.

enabled-valueIs true or false, depending on whether the collector establishes a session with the HMCimmediately and begin to gather data. The default is true. The parameter is optional unlessyou want to change the default.

This sample command:eccAdmin==>data-sources create -n HMCA -u hmcuser_1 -p passwd -h abc.mycompany.com-d "HMCA datasource" -e true -c default

returns this message:


INFO: CTGEZ9810I Command data-sources completed.

And if you then issue a data-sources list command, you see the new data source you just created:status: connectedenabled: truename: HMCAdescription: HMCA datasourcehmc-user: hmcuser_1hmc-user-pwd: ********hmc-hostname: abc.mycompany.comcollection-profile-name: default

The information in this response is explained in Step 2 except for the status parameter . When a datasource is created, the status is always disconnected initially. But if the data source is enabled, thestatus changes to connecting almost immediately. Status can be one of the following:v connected: The Enterprise Common Collector (collector) is connected to the data source using an

API session.v connecting: The collector is attempting to connect to the data source. The collector could be waiting

for a response from the data source or waiting a defined period of time before making anotherattempt after a previous connection attempt failed.

v disconnected: The collector is not currently connected to the data source and is not attempting toconnect to the data source.

v data-source-unreachable: The collector was unable to connect to the data source and is no longerattempting to connect to the data source. This status means that the collector tried to connect to theHMC and failed either because of a bad user ID or password, or because of 12 hours ofunsuccessful attempts.

v in-doubt: The collector has determined that its inventory data for this data source is outdated. Thecollector has started an unscheduled inventory discovery resynch its data with the HMC. When thediscovery process is complete, the status returns to connected.

For information about the API for performing this action, see “POST /eccapi/admin/data-sources” onpage 236.

3. To list the System z Hardware Management Consoles (HMCs) defined as data sources for theEnterprise Common Collector, use this command:data-sources list

The command returns output similar to the following:status: disconnectedenabled: truename: HMCAdescription: HMCA datasourcehmc-user: hmcuser_1hmc-user-pwd: ********hmc-hostname: abc.mycompany.comcollection-profile-name: default

For information about the API for performing this action, see “GET /eccapi/admin/data-sources” onpage 225. To see information about a named System z Hardware Management Console (HMCs) datasource by data-source-name, use this API: “GET /eccapi/admin/data-sources/{name}” on page 227.

4. To update the data source specified by data-source-name that is currently configured for the EnterpriseCommon Collector, use this command:data-sources update -n <data-source-name> -u <hmc-user-name> -p <hmc-user-password>-h <hmc-host> -c <collection-profile-name> -d <data-source-description) -e <enabled-value>

Where:

data-source-nameIs a text string 1 to 16 in length identifying the data source to update. This parameter isrequired.


hmc-user-nameIs the user ID to use to logon to the HMC. This parameter is optional unless you want toupdate this value.

hmc-user-passwordIs the password to use to logon to the HMC. This parameter is optional unless you want toupdate this value.

hmc-hostIs the host name of the HMC. This value must be supplied and must be 1 to 256 characters inlength. This name cannot contain characters other than alphabetic characters (a-z, A-Z), digits(0-9), - (minus sign), _ (underscore), : (colon), % (percent sign), or . (period). This parameter isoptional unless you want to update this value.

collection-profile-nameIs the name of the collection profile to use. This parameter is optional unless you want toupdate this value.

data-source-descriptionIs a text string describing the HMC. This parameter is optional unless you want to update thisvalue.

enabled-valueSpecifies whether the collector establishes a session with the HMC immediately and begin togather data. Valid values are true or false. The parameter is optional unless you want toupdate this value.

This sample command:eccAdmin==>data-sources update -n HMCA -d "HMCA in Raleigh"

Returns this message.INFO: CTGEZ9810I Command data-sources completed.

And if you then issue a data-source list command, you see the updated data-source:Update data-sources

eccAdmin==>data-sources update -n HMCA -d "HMCA in Raleigh"INFO: CTGEZ9810I Command data-sources completed.

eccAdmin==>data-sources liststatus: disconnectedenabled: truename: HMCAdescription: HMCA in Raleighhmc-user: hmcuser_1hmc-user-pwd: ********hmc-hostname: abc.mycompnay.comdcollection-profile-name: default

For information about the API for performing this action, see “PUT/eccapi/admin/data-sources/{name}” on page 252.

5. To delete a specified data source from the Enterprise Common Collector database, use this command:data-sources delete -n <data-source-name>

Where:

data-source-nameIs a string identifying the data source to delete. This parameter is required.

This sample command:eccAdmin==>data-sources delete -n HMCA

returns this message.


INFO: CTGEZ9810I Command data-sources completed.

If you try to delete a data source that is currently enabled, you see this message:CTGEZ1525E The data source cannot be removed because it is enabled.

For information about the API for performing this action, see “DELETE/eccapi/admin/data-sources/{name}” on page 203.


Setting collector logging levels by using the command-lineUse the commands in this section to manipulate logging levels in the Enterprise Common Collector andits components.

About this task

For information about performing these tasks using the API, see“Setting collector logging levels by usingthe ReST API” on page 196.


Common Collector by using the command-line interface” on page 70 for more information.2. To list the loggers configured for the Enterprise Common Collector, use this command

loggers list

The sample command:eccAdmin==>loggers list

Returns the name and logging level of the default logger:level: FINEname: gez

For information about the API for performing this action, see “GET /eccapi/admin/config/loggers”on page 221. If you want to retrieve information about a specific named logger, use this API: “GET/eccapi/admin/config/loggers/{logger-name}” on page 223

3. To create a new logger for one of the Enterprise Common Collector components, use this command:loggers create -n <logger-name> -l <logger-level> -e <enabled-value>

Where:

logger-nameIs the name that you assigned to this logger. This name is a text string beginning with gezthat specifies what Enterprise Common Collector component this logger applies to. If thename is not valid, the logger has no effect (no validation is done to ensure that it is a validlogger). This parameter is required.

If instructed to do so by IBM Software Support, capture a component-specific log. Thesecomponent log names are valid:

Logger name Component

gez.admin Admin Manager

gez.authorization Authorization Request Handler(s)

gez.cache Data Cache Manager

gez.data Data Provider

gez.gatherer.inventory Inventory Gatherer



gez.gatherer.metrics Metrics Gatherer

gez.migration Migration Manager

gez.nls National language message resource bundles

gez.notification Notification

gez.persistence Persistence Manager

gez.restapi Enterprise Common Collector ReST APIs

gez.servlet Servlet Initialization

gez.session Enterprise Common Collector Session Manager

gez.threads Thread Strategy

gez.utility Utilities (such as Logging, Security, and Constants)

gez.zhmc.restapi HMC ReST Client

gez.zhmc.session HMC Session Manager

logger-levelIs a text string indicating the logging level. The level must be one of the following levels.v OFF: No logging occurs.v SEVERE: Errors that cause premature termination and other unexpected errorsv WARNING: Undesirable or unexpected conditions that are not necessarily wrongv INFO: Interesting runtime eventsv CONFIG: Not supported. If set, shows the same level as INFO.v FINE: Important events and exceptionsv FINER: Detailed debug information, low-level logic, object dumps, and so onv FINEST: Method entry and exit tracingv ALL: Everything; essentially equivalent to FINEST

Note that each level includes all higher levels and applies not only to that package but to allsub-packages also (unless the sub-package has its own logger defined).

By default, only INFO and higher (INFO, WARNING, SEVERE) are logged.

This parameter is required.

enabled-valueIs true or false, indicating whether the Enterprise Common collector logger is enabled. Thedefault is true (the logger is enabled). This parameter is optional.

This sample command:eccAdmin==>loggers create -n gez.persistence -l SEVERE -e true

returns this message:INFO: CTGEZ9810I Command loggers completed.

If you then issue the loggers list command, you see all the defined loggers:level: FINEname: gez-----------------------------------------------------------------------------level: SEVEREenabled: truename: gez.persistence


-----------------------------------------------------------------------------level: INFOenabled: truename: gez.pilot.gez.zhmc.session

For information about the API for performing this action, see “POST /eccapi/admin/config/loggers”on page 234.

4. To update the level of a logger specified with logger-name that is currently configured for theEnterprise Common Collector to a new logging level, use this command:loggers update -n <logger-name> -l <logger-level> -e <enabled-value>

where:


If instructed to do so by IBM Software Support, capture a component-specific log. Thesecomponent log names are valid:



















logger-levelIs a text string indicating the logging level. The level must be one of the following levels.v OFF: No logging occurs.v SEVERE: Errors that cause premature termination and other unexpected errorsv WARNING: Undesirable or unexpected conditions that are not necessarily wrongv INFO: Interesting runtime eventsv CONFIG: Not supported. If set, shows the same level as INFO.v FINE: Important events and exceptionsv FINER: Detailed debug information, low -level logic, object dumps, and so on


v FINEST: Method entry and exit tracingv ALL: Everything; essentially equivalent to FINEST

Note that each level includes all higher levels and applies not only to that package but to allsub-packages also (unless the sub-package has its own logger defined).

By default, only INFO and higher (INFO, WARNING, SEVERE) are logged.

This parameter is optional.

enabled-valueIs true or false, indicating whether the Enterprise Common collector logger is enabled. Thisparameter is optional.

For information about the API for performing this action, see “PUT/eccapi/admin/config/loggers/{logger-name}” on page 250.

5. To delete the logger specified with logger-name that is currently configured for the Enterprise CommonCollector, use this API:loggers delete -n <logger-name>

Where:


This sample command:eccAdmin==>loggers delete -n gez.session

Returns this message:INFO: CTGEZ9810I Command loggers completed.

For information about the API for performing this action, see “DELETE/eccapi/admin/config/loggers/{logger-name}” on page 202.



Summary of administrator commandsThe commands summarized in the table the follows are issued by a user ID with administrator authorityagainst the resource types: data sources, clients, collection profiles, logging, and authentication.

Table 11. Summary of administrator commands

Object Action Description Required parametersOptionalparameters Defaults

data-sources create Creates a newdata source

v -e (enabled value)v -n (data source name)v -u (HMC user name)v -p (HMC user

password)v -h (HMC host name)v -c (collection profile

name)

v -d (data sourcedescription)

-e = true

list Displays all datasources

None None None

update Updates a datasource

v -n (data source name) v -u (HMC username)

v -p (HMC userpassword)

v -h (HMC hostname)

v -c (collectionprofile name)

v -d (description)v -e (enabled value)

None

delete Deletes a datasource

v -n (data source name) None None

collection-profiles create Creates acollection profile

v -n (name)v -s (short term interval)v -r (inventory resync

interval)v -l (long term interval)

Note: Long term interval(-l) is required only if longterm collection enabled(-e) is true.

v -d (description)v -e (long term

collectionenabled)

v -p(path-accessible-collection-enabled)

v -e=false

v -p=true

list Displays allcollectionprofiles

None None None

update Updates acollection profile

v -n (collection profilename)

v -d (description)v -s (short term

interval)v -l (long term

interval)v -e (long term

collectionenabled)

v -r (inventoryresync interval)

None

A defaultcollectionprofile nameddefault isprovided withthe collector.This defaultprofile cannotbe deleted.

delete Deletes acollection profile

v -n (collectionprofile-name)

None None


Table 11. Summary of administrator commands (continued)


clients create Creates a client v -n (name)v -p (password)v -r (roles)

v -d (description)v -e (enabled)v -w

(password-expiration-enabled)

v -e=false

v -w=true

list Displays allclients

None None None

update Updates a client v -n (name) v -d (description)v -p (password)v -e (enabled)v -r (roles)v -w

(password-expiration-enabled)

v -m (resume)

None

delete Deletes a client v -n (name) None None

loggers create Creates a logger v -n (name)v -l (level)

v -e (enabled) -e = true

list Displays allloggers

None None None

update Updates alogger

v -n (name) v -l (level)v -e (enabled)

delete Deletes a logger v -n (name) None None

authentication update Updates theauthenticationmethod

v -e (password-expiration-interval)

v -a(ldap-authentication)

v -p(ldap-user-provider)

v -f(ldap-user-filter)

v -s (ldap-use-ssl)

None

list Displays thecurrentauthenticationmethod

None None None


Table 11. Summary of administrator commands (continued)


certificates create Imports a newcertificate intothe collectortruststore

v -f (filename)v -a (alias)

None None

list Displays all thecertificates inthe collectortruststore

None None None

update Updates thecurrents settingfor the "trust allcertificates"option in thecollector

-t (trust-all-certificates) None None

delete Deletes acertificate fromthe collectortruststore

-a (alias) None None

Summary of utility commandsThe commands summarized in the table the follows are issued by as user ID with administrator authorityto access the Enterprise Common Collector command-line interface and run command files.

Table 12. Summary of utility commands

Command Description Required parameters Optional parameters Defaults

import Imports andrunscommandsfrom a file

v -f (filename)v -u (HMC user name)v -p (HMC user

password)

v -o (HMC port) v -o 8443

logon Logs on to theEnterpriseCommonCollector asanadministrator

v -u (HMC user name)v -p (HMC user

password)

v -o (HMC port) v -o 8443

logoff Logs off theEnterpriseCommonCollector asanadministrator

None None None


Table 12. Summary of utility commands (continued)

Command Description Required parameters Optional parameters Defaults

help Displays helpforcommand-lineinterfaceutility and thecommands orobjects

None v version [of theEnterprise CommonCollector]

v data-sourcesv collection-profilesv clientsv loggersv authenticationv certificatesv importv logonv logoffv exit

None

exit Exit thecommand-lineinterface shell

None None None

Managing the Enterprise Common Collector web containerThe Enterprise Common Collector is a web-based application that is deployed within an IBM WebSphereApplication Server Community Edition web container.

Normally, there is no need to manage the web container if the defaults defined in the installation packageare sufficient for your needs. However, local policies may require that installation options can be changedafter the initial installation of the Enterprise Common Collector has been completed.

See the description that follows to understand what optional steps are possible and what steps arenecessary to successfully manage the web container.

Optional Step 1: Changing web container administrator credentials

When you have installed the Enterprise Common Collector, the web container's administration consolecan be accessed using the default user credentials:v User Name: systemv Password: z1manager

Note: Change the user name and password after the installation has completed to prevent fromunauthorized modification of the web container's options.

To change the user name or password, enter the following URI in your browser's address field:https://hostname:8443

where hostname is either the TCP/IP hostname or the IP-address of the system where the EnterpriseCommon Collector is running. The installation default port for secure HTTP communication is port 8443.If you have changed this port during installation, specify the changed port number. If you receive aconnection error, ensure that the Enterprise Common Collector is active and use the information in“Starting, stopping, removing, installing, and querying the status of the Enterprise Common Collector”on page 53 to start it.

The browser opens the IBM WebSphere Application Server Community Edition web-based configurationapplication. Click on Administrative Console and enter the credentials to login as an administrator.


On the Administrative Console, select the Advanced Navigator and scroll down to the category Security.Click Users and Groups and follow the instructions on the panel to add or delete a user or to change thepassword of an existing user. Once you have changed administrator credentials, follow the instructionslisted under “Mandatory step: Reflect any preceding change in the Enterprise Common Collectorconfiguration file” to also reflect the credentials change in the Enterprise Common Collector configurationfile.

Note: Complete “Mandatory step: Reflect any preceding change in the Enterprise Common Collectorconfiguration file” to allow proper termination of the Enterprise Common Collector.

Optional step 2: Changing the RMI Naming port

The RMI Naming port cannot be changed on the IBM WebSphere Application Server Community Editionadministrative console. Instead you have to edit a configuration file. The steps to change the naming portare as follows:1. Stop the Enterprise Common Collector if it is not already stopped. See the information in “Starting,

stopping, removing, installing, and querying the status of the Enterprise Common Collector” on page53.

2. Open a command window and use an editor to edit the configuration file:


Linux or UNIX The configuration substitution properties file is located at:

<install_dir>/wasce/var/config/config-substitutions.properties

Windows The configuration substitution properties file is located at:

<install_dir>\wasce\var\config\config-substitutions.properties

These files must be opened or modified by the administrative user IDs provided by the operatingsystem.

3. Update the value for NamingPort. Change the port number to a number that meets your needs andsave the properties file.

Note: The Enterprise Common Collector default RMI Naming port has been set to 2098 in order toavoid conflicts with IBM Tivoli Monitoring, which uses 1099 as its naming port.

Mandatory step: Reflect any preceding change in the Enterprise CommonCollector configuration file

The Enterprise Common Collector service uses a hidden configuration file that contains the usercredentials of the web container administrator and the RMI Naming port to allow it to successfully stopthe Enterprise Common Collector.

To edit the configuration file with an editor, follow these steps:1. Open a command window and use an editor to edit the configuration substitution properties file:


Linux or UNIX The Enterprise Common Collector service configuration file is located at:

<install_dir>/config/.ecc.config

Windows The "Enterprise Common Collector service configuration file is located at:

<install_dir>\config\.ecc.config

2. Update the values for the following:v RMIPORTv ADMINID


v ADMINPWD3. Save the configuration file.4. Optionally, restart the Enterprise Common Collector to pick up the changes. See “Starting, stopping,

removing, installing, and querying the status of the Enterprise Common Collector” on page 53 forinformation about stopping and starting the Enterprise Common Collector.


Chapter 6. Installing the monitoring agent, application supportfiles, and optional language support

The monitoring agent, the application support files, and language support are installed in the same wayas any IBM Tivoli Monitoring agent using the IBM Tivoli zEnterprise Monitoring Agent v6.2.3.0 and AgentReports DVD.

In a typical installation scenario, perform these installations in the following manner:1. Install the IBM Tivoli Monitoring environment or upgrade all components of an existing environment

to Version 6.2.3 Fix Pack 1.2. Install the monitoring agent on the system where you want the agent to run.3. Install application support required by the monitoring agent on the system where the agent is running

and on the IBM Tivoli Monitoring components: Tivoli Enterprise Portal, Tivoli Enterprise PortalServer, and Tivoli Enterprise Monitoring Server.

4. If your language is not English, install language support.

For the Tivoli zEnterprise monitoring agent, if all components of IBM Tivoli Monitoring environment(monitoring agent, Tivoli Enterprise Portal Server, Tivoli Enterprise Monitoring Server, and the TivoliEnterprise Portal desktop client) are on the same physical machine, you can combine steps 2 and 3because the same installation wizard installs both the agent and the application support.

If the components of IBM Tivoli Monitoring environment (monitoring agent, Tivoli Enterprise PortalServer, Tivoli Enterprise Monitoring Server, and the Tivoli Enterprise Portal desktop client) are ofdifferent physical machines, you must perform both steps 2 and 3.

The information in this section assumes that you are performing the full manual installation describedpreviously(Steps 2, 3, and 4). There are two ways that you might deviate from this processv If you use the self-describing agent feature (see “Installing if you have enabled the self-describing

agent feature”)v If you use remote deployment and install this monitoring agent and its application support from the

agent depot (see “Installing components by using the agent depot” on page 99)

To perform the installation processes described in this section, you need the IBM Tivoli zEnterpriseMonitoring Agent v6.2.3.0 and Agent Reports DVD. This DVD has four subdirectories:v itm_app_data_files: Contains install image for the application support for the zEnterprise Monitoring

Agent, for installation into Tivoli Enterprise Monitoring Server, Tivoli Enterprise Portal Server, andTivoli Enterprise Portal.

v itm_agents: Contains install images for the Tivoli zEnterprise monitoring agent itself plus optionalapplication support.

v itm_language_pack: Contains install image for the Tivoli zEnterprise monitoring agent language pack.v reports: Contains install images for the sample Tivoli Common Reporting Cognos reports provided

with the Tivoli zEnterprise monitoring agent.

Installing if you have enabled the self-describing agent featureVersion 6.2.3 of IBM Tivoli Monitoring includes the self-describing agent.

The self-describing agent capability integrates the installation of an agent with the dispersal andinstallation of associated product support files throughout your IBM Tivoli Monitoring infrastructure.This feature makes it possible for new or updated IBM Tivoli Monitoring agents to become operational


after installation, without having to perform additional product support installation steps. Self-describingagents apply version updates to other components automatically without the need to recycle your hubTivoli Enterprise Monitoring Server, Tivoli Enterprise Portal Server, or remote Tivoli EnterpriseMonitoring Server.

Enable self-describing agents at the hub Tivoli Enterprise Monitoring Server first. For more information,see "Enabling self-describing agent capability at the hub monitoring server" in the IBM Tivoli Monitoring:Installation and Setup Guide.

To install this monitoring agent and its application support files using the self-describing agent, see the"Self-describing agent installation” topic in the IBM Tivoli Monitoring: Installation and Setup Guide.

Enable self-describing agents by checking the self-describing agent check box when you install themonitoring agent.

With the self-describing agent capability, new or updated IBM Tivoli Monitoring agents can becomeoperational after installation without having to perform additional product support installation steps. Totake advantage of this capability, see the IBM Tivoli Monitoring Installation and Setup Guide > "Enablingself-describing agent capability at the hub monitoring server." Also, see IBM Tivoli MonitoringAdministrator's Guide > "Maintaining Monitoring Agents" > "Self-Describing Monitoring Agents" foradditional information about using this capability.

If you have enabled the self-describing agent capability on the hub Tivoli Enterprise Monitoring Server,then do the following:v Install the monitoring agent on the system you want the agent to run.v Install application support for the Tivoli Enterprise Portal desktop client.v If your language is anything other than English, install language support.

Self-describing agent administration

Administration of self-describing agent control requires access to the tacmd command line interface froma distributed platform such as Windows, UNIX, or Linux.

If you do not want to install Tivoli Enterprise Portal Server or Tivoli Enterprise Monitoring Server on adistributed platform but you do intend to run with the self-describing agent feature enabled, install thetacmd command line interface on at least one distributed platform. It does not need to be installed on adistributed server, but the system that it is installed on requires access to your hub monitoring server thatuses a soap services connection.

To install the tacmd command line interface from the IBM Tivoli Monitoring version 6.2.3 (or higher)installation image, select the Tivoli Enterprise Services User Interface Extensions feature (KUE) whenrunning the installation wizard.

To install the tacmd command line interface on Windows, select the Tivoli Enterprise Services UserInterface Extensions feature which appears under the Tivoli Enterprise Monitoring Agents - TEMAfeature. When you select it, this action automatically pre-selects its prerequisite, Tivoli EnterpriseMonitoring Agent Framework.

To install the tacmd command line interface on a Linux or UNIX platform, select the Tivoli EnterpriseServices User Interface Extensions feature when you choose which IBM Tivoli Monitoring components toinstall.

You just configure the monitoring agent after deployment by the self-describing agent.


Troubleshooting the self-describing agent

If self-describing agent deployment is not working, ensure that you have done the following:v Did you edit the KBBENV environment variable file at the hub Tivoli Enterprise Monitoring Server, set

the KMS_SDA value to Y, and recycle the monitoring server?v Did you ensure that the monitoring agent instance is configured to use the hub monitoring server? Did

you wait a short time (10 minutes) for trying a self-describing agent operation?v Are you aware that the Tivoli Enterprise Portal desktop client is not supported. You must use browser

client or the Tivoli Enterprise Portal Webstart Client?

Use the following tacmd commands to troubleshoot self-describing agent problems:tacmd listappinstallrecs -t ZE -d

This tacmd command shows which applications are installed:tacmd listappinstallrecs

Installing components by using the agent depotMany IBM Tivoli Monitoring administrators use the agent depot to install and deploy components. Theagent depot is installation directory on the monitoring server from which you deploy agents andmaintenance packages in your environment.

You can use the agent depot to do the following:v Create and populate the agent depot with installable agent images.v View and change the contents of the agent depot.v Use one agent depot for all the monitoring servers in your monitoring environment.

To use the agent depot method of installation and deployment, follow the process described under the"Deploying non-OS agents" topic in the "Deploying monitoring agents across your environment" chapterof the IBM Tivoli Monitoring: Installation and Setup Guide Version 6.2.3 or later.

For information about remote deployment of this monitoring agent, see “Installing the monitoring agentand application support by using remote deployment.”

Installing the monitoring agent and application support by usingremote deploymentYou can install the monitoring agent remotely from the Tivoli Enterprise Portal or from the commandline.

About this task

When installing the agent remotely, you must provide the configuration values for the agent to operate.See “Configuration values” on page 102.

To install from the portal, see the IBM Tivoli Monitoring Installation and Setup Guide.

To remotely install or configure an agent through the Tivoli Enterprise Portal, you must install theapplication support for that agent (Tivoli Enterprise Monitoring Server, Tivoli Enterprise Portal Server,and Tivoli Enterprise Portal). You must also install the agent bundle into the Remote Deploy Depot.

For information about displaying the configuration options that are available to use with theconfigureSystem or addSystem commands see tacmd describeSystemType in the IBM Tivoli MonitoringCommand Reference.

Chapter 6. Installing the monitoring agent, application support files, and optional language support 99

For more information about deploying agents, see IBM Tivoli Monitoring: Installation and Setup Guide >"Installation and initial configuration of base components and agents" > "Deploying monitoring agentsacross your environment".

Be aware of these restrictions:v Tivoli Enterprise Monitoring Server should not be on the system where you are remotely deploying the

agent.v The Tivoli Enterprise Portal User Interface Extensions must be installed on the system where you are

installing the monitoring agent, regardless of which installation method you choose (remote, manual,or silent).

Procedure1. Set up the remote deployment depot and install this monitoring agent on the remote deployment

depot. For more information see IBM Tivoli Monitoring: Installation and Setup Guide > "Installation andinitial configuration of base components and agents" > "Deploying monitoring agents across yourenvironment".

2. Ensure that the OS agent that corresponds to your target platform is installed. If you are installingthe monitoring agent on a Windows system, for example, ensure that the Windows OS agent wasinstalled. If you are installing the monitoring agent on Linux, ensure that the Linux OS agent isinstalled.

3. Define DEPOTHOME to Tivoli Enterprise Monitoring Server.v On a Windows system, do the following:

a. Locate the KBBENV file and open it with a text editor:


Windows <install_dir>\cms

b. Add this line:DEPOTHOME=\\depot_name

Where depot_name is the name you gave the depot in Step 1 when you created it. It is the fullyqualified name of the depot.

c. Uncomment this line:KT1_TEMS_SECURE=YES

This statement is the environment variable to enable self-description. Uncomment this line andensure that the value is YES.

d. Save this file.v On a Linux or UNIX system, do the following:

a. Locate the env.config and the kbbenv.ini files.


Linux or UNIX <install_dir>/config/

b. Edit both of these files to add this line at the end:DEPOTHOME=\\depot_name

Where depot_name is the name you gave the depot in Step 1 when you created it. It is the fullyqualified name of the depot.

v Save these files.4. Stop and restart Tivoli Enterprise Monitoring Server and Tivoli Portal Server.


5. Open a command window and change directories to the bin directory. Before you can issue a tacmdcommand, you must be in the bin directory.


Linux or UNIX <install_dir>/bin

Windows <install_dir>\bin

For detailed information about the tacmd commands, issue the tacmd help command or see thetacmd chapter in the IBM Tivoli Monitoring Command Reference.

6. You must first logon to the take action command line interface and you must have administrator(Windows) or root (Linux or UNIX) authority to enter these commands.

Platform Command

Linux or UNIX ./tacmd login -s system_name -u root -p password

Windows tacmd login -s system_name -u administrator -p password

Where:

-s Is the fully qualified name of the system that you want log on to by using the tacmdcommand line interface.

-u Is a user ID with either administrator (Windows) or root (Linux or UNIX) authority.

-p Is the password for that user ID.7. Determine if you can view the Tivoli zEnterprise monitoring agent (ze) in the depot by issuing the

following command:

Platform Command

Linux or UNIX <install_dir>/bin/tacmd viewdepot -t ze

Windows <install_dir>\bin\tacmd viewdepot -t ze

And this command returns output similar to this, where Host Version is the supported platform:Product Code : zeVersion : 062300000Description : Monitoring Agent for Tivoli zEnterprise Monitoring AgentHost Type : ls3246Host Version : ls3246,ls3266Prerequisites: ci:062301000,la:010001000,gs:074027000,jr:060902000,ui:062301000,ax:062301000

Product Code : zeVersion : 062300000Description : Monitoring Agent for Tivoli zEnterprise Monitoring AgentHost Type : li6263Host Version : li6263Prerequisites: ci:062301000,la:010001000,gs:074027000,jr:060902000,ui:062301000,ax:062301000

Product Code : zeVersion : 062300000Description : Monitoring Agent for Tivoli zEnterprise Monitoring AgentHost Type : aix526Host Version : aix526,aix536Prerequisites: ci:062301000,la:010001000,gs:074027000,jr:060902000,ui:062301000,ax:062301000

Product Code : ZEVersion : 062300000Description : Monitoring Agent for Tivoli zEnterprise Monitoring AgentHost Type : WINNTHost Version : WINNTPrerequisites:

Product Code : ze


Version : 062300000Description : Monitoring Agent for Tivoli zEnterprise Monitoring AgentHost Type : lx8266Host Version : lx8266Prerequisites: ci:062301000,la:010001000,gs:074027000,jr:060902000,ui:062301000,ax:062301000

8. To discover the system name you need to use in the command to deploy the Tivoli zEnterprisemonitoring agent (which is called addSystem), issue the following command:

Platform Command

Linux or UNIX <install_dir>/bin/tacmd listSystems

Windows <install_dir>\bin\tacmd listSystems

And the command returns information similar to this:Managed System Name Product Code Version Statusteps_system_name:TEPS CQ 06.23.00.00 YOS_agent_system_name:NT NT 06.23.00.00 Ytems_system_name EM 06.23.00.00 Y

Where system_name is the name of the system where the component is running. If all components arerunning on the same system, these names would be the same.

9. To deploy the Tivoli zEnterprise Monitoring agent to system_name, issue the following command(notice that the node name -n comes from the listSystems command issued previously):

Platform Command

Linux <install_dir>/bin/tacmd addSystem -t ze -n Primary:OS_agent_system_name:LZ

UNIX <install_dir>/bin/tacmd addSystem -t ze -n Primary:OS_agent_system_name:UX

Windows <install_dir>\bin\tacmd addSystem -t ze -n Primary:OS_agent_system_name:NT

And information similar to this is returned:KUICAR010I: The agent type ZE is being deployed.

KUICAR028I: The operation has been successfully queued for deployment, the transaction idis 1326466219985000000000041, use the getDeployStatus CLI to view the status

If you are using the command line, the following command is an example of remote installation andconfiguration for Windows operating systems: After performing a remote configurationtacmd addSystem -t ZE -n Primary:sample.node.name:NT-p ENTERPRISE_COMMON_COLLECTOR.KZE_ECC_CONNECTION_TIMEOUT=valueENTERPRISE_COMMON_COLLECTOR.KZE_ECC_HOST=valueENTERPRISE_COMMON_COLLECTOR.KZE_ECC_PASSWORD=valueENTERPRISE_COMMON_COLLECTOR.KZE_ECC_PORT=valueENTERPRISE_COMMON_COLLECTOR.KZE_ECC_READ_TIMEOUT=valueENTERPRISE_COMMON_COLLECTOR.KZE_ECC_USER=valueKZE_CERT_ACPT_UNDEFINED.KZE_TEMA_TRUSTSTORE_UNDF=valueKZE_JAVA.JAVA_TRACE_LEVEL=valueKZE_SSL_NO.KZE_TEMA_TRUSTSTORE_NO=valueKZE_SSL_NO.KZE_TEMA_TRUSTSTORE_PASSWORD=valueKZE_SSL_YES.KZE_TEMA_TRUSTSTORE_YES=valueSSL.KZE_SSL_CERT_LIST=value

10. After some time has passed, observe that Managed Tivoli Enterprise Monitoring Services indicatesthat the environment has stopped. Start it again to see that the Tivoli zEnterprise monitoring agenthas been installed, but has not been configured. .

Configuration valuesFor both local and remote configuration, you provide the configuration values for the agent to operate.


When you are configuring an agent, a panel is displayed so you can enter each value. When a defaultvalue exists, this value is pre-entered into the field. If a field represents a password, two entry fields aredisplayed. You must enter the same value in each field. The values you type are not displayed to helpmaintain the security of these values.

The configuration for this agent is organized into the following groups:

Enterprise Common Collector (ENTERPRISE_COMMON_COLLECTOR)Configuration for the Enterprise Common Collector

The configuration elements defined in this group are always present in the agent's configuration.

This group defines information that applies to the entire agent.

Enterprise Common Collector Connection Timeout (KZE_ECC_CONNECTION_TIMEOUT)The number of milliseconds the zEnterprise Agent waits for the Enterprise CommonCollector to respond to a request to establish a connection at logon.

The type is numeric.

This value is required.

Default value: 60000

Enterprise Common Collector Hostname (KZE_ECC_HOST)The fully qualified hostname of the computer where the Enterprise Common Collector isrunning.

The type is string.


Default value: localhost

Enterprise Common Collector Password (KZE_ECC_PASSWORD)The password of the user logging onto the Enterprise Common Collector. There is nodefault value.

The type is password.


Default value: None

Enterprise Common Collector Port (KZE_ECC_PORT)The port of the computer where the Enterprise Common Collector is running.

The type is string.


Default value: 8443

Enterprise Common Collector Read Timeout (KZE_ECC_READ_TIMEOUT)The number of milliseconds the zEnterprise Agent waits for the Enterprise CommonCollector to respond to a read request.

The type is numeric.


Default value: 120000

Enterprise Common Collector User ID (KZE_ECC_USER)The user ID of the user logging onto the Enterprise Common Collector.

The type is string.



Default value: user02

Log Settings (KZE_JAVA)Log trace level parameters



Log trace level (JAVA_TRACE_LEVEL)This parameter allows you to specify the log trace level used by the Java providers

The type is one of the following values: "Off", "Error", "Warning", "Informational","Minimum Debug", "Medium Debug", "Maximum Debug", "All".


Default value: INFO

SSL (SSL)Secure Sockets Layer Communication



Accept All Certificates (KZE_SSL_CERT_LIST)Accept All Certificates from the Enterprise Common Collector

The type is one of the following values: "Yes", "No".


Default value: YES

SSL Truststore Credentials (KZE_SSL_NO)SSL Truststore Credentials

The configuration elements defined in this group are displayed only if the corresponding value isselected in a previous group.


Certificates Truststore (KZE_TEMA_TRUSTSTORE_NO)Truststore containing certificates for zEnterprise SSL communication with the EnterpriseCommon Collector

The type is string.


Default value: ze_agent_truststore

Certificates Truststore Password (KZE_TEMA_TRUSTSTORE_PASSWORD)Certificates truststore password

The type is password.


Default value: None

Installing the monitoring agentInstall the monitoring agent into an existing IBM Tivoli Monitoring Version 6.2.3 Fix Pack 1 environment.


The process outlined in the sections that follow assumes that you have already installed and configuredIBM Tivoli Monitoring at the level specified in “Prerequisites, corequisites, and integrated applications”on page 5. If you do not have IBM Tivoli Monitoring installed, install and configure IBM TivoliMonitoring first.

There are two methods by which you can install the monitoring agent:v “Installing the monitoring agent by using the installation wizard”v Using a silent or console install:

– “Installing the monitoring agent on Linux or UNIX by using the console install and configurationscripts” on page 118

– “Installing the monitoring agent on Windows systems by using the silent install script” on page 113

Installing the monitoring agent by using the installation wizardYou can install the Tivoli zEnterprise monitoring agent from the IBM Tivoli zEnterprise Monitoring Agentv6.2.3.0 and Agent Reports DVD by using the installation wizard.

About this task

To install this monitoring agent, follow the basic process for your operating system described under the"Installing monitoring agents" topic in the IBM Tivoli Monitoring: Installation and Setup Guide. Use thespecial screens in the example that follows to define values for the way in which the monitoring agentcommunicates with the Enterprise Common Collector

Procedure1. Insert the IBM Tivoli zEnterprise Monitoring Agent v6.2.3.0 and Agent Reports DVD in your DVD drive,

and change directories to the location where the Tivoli zEnterprise monitoring agent setup files arestored.


Windows cd \itm\itm_agent\setup.exe

2. Launch the install.sh or setup.exe file. A splash screen appears briefly and a pop-up window tellsyou that Setup is being prepared. Then the Welcome screen is displayed.

3. Follow the process described in IBM Tivoli Monitoring: Installation and Setup Guide version 6.2.3 FixPack 1 > "Installing IBM Tivoli Monitoring" > "Installing monitoring agents". Select the version ofthese instructions appropriate to your platform, either Windows or UNIX or Linux.

4. After the Welcome screen and the License screen, the Select Features screen is displayed.


Select the features that you want to the installation wizard to install.

Components to install Procedure

To install both the monitoring agent andapplication support

1. Click the plus sign by Tivoli Enterprise Monitoring Agents -TEMA and click the checkbox adjacent to the TivoliEnterprise Monitoring Agents - TEMA.

2. Click the check box by Tivoli Enterprise MonitoringFramework.

3. Click the check box by Tivoli Enterprise Services UserInterface Extensions.

4. Click the check box by Tivoli zEnterprise Monitoring Agent.

To install the monitoring agent only 1. Click the plus sign by Tivoli Enterprise Monitoring Agents -TEMA and click the checkbox adjacent to the TivoliEnterprise Monitoring Agents - TEMA.

2. Click the check box by Tivoli zEnterprise Monitoring Agent.

Figure 24. Tivoli zEnterprise Monitoring Agent Select Features screen


Components to install Procedure

To install application support for one of the IBMTivoli Monitoring components

1. Click the plus sign by Tivoli Enterprise Monitoring Agents -TEMA and click the checkbox adjacent to the TivoliEnterprise Monitoring Agents - TEMA.

2. Click the check box by Tivoli Enterprise MonitoringFramework.

3. Click the check box by Tivoli Enterprise Services UserInterface Extensions.

This screen also tells you how much disk space is required and how much is available. All agentsrequire that application support files contain agent-specific information be installed on the TivoliEnterprise Monitoring Server that the agents connect to, Tivoli Enterprise Portal Server, and TivoliEnterprise Portal desktop and browser clients. Install application support for installing the monitoringagent.Click the appropriate checkboxes and then click Next to continue.

5. Continue installing this monitoring agent using the process described in IBM Tivoli Monitoring:Installation and Setup Guide version 6.2.3 Fix Pack 1 > "Installing IBM Tivoli Monitoring" > "Installingmonitoring agents". Near the end of the installation process, a set of four screens is displayed thatenable you to provide the values required for this monitoring agent. The first of these screens,displayed by default, is the Configuration for the Enterprise Common Collector window.

Provide values for the following fields, where:

Figure 25. Tivoli Enterprise Monitoring Agent: Configuration of the Enterprise Common Collector screen


Enterprise Common Collector HostnameThe fully qualified hostname of the computer where the Enterprise Common Collector isrunning. The default is localhost.

If the Enterprise Common Collector and the zEnterprise agent are located on the same system,then the default localhost is sufficient and does not need to be changed. If the EnterpriseCommon Collector resides on different computer, then localhost needs to be replaced with afully qualified hostname, such as test1.somelab.raleigh.ibm.com.

Enterprise Common Collector PortThe port number of the secure port that the zEnterprise monitoring agent uses tocommunicate with the Enterprise Common Collector. The default is 8443.

Enterprise Common Collector Connection TimeoutThe time that the Tivoli zEnterprise monitoring agent waits for the Enterprise CommonCollector to respond to a request to establish a connection at logon before the user has toissue the request again. The default is 60000 milliseconds.

Enterprise Common Collector Read TimeoutThe time that the Tivoli zEnterprise monitoring agent waits for a response to requests fromthe Enterprise Common Collector before timing out. The default is 120000 milliseconds.

Enterprise Common Collector User IDThe user ID of the user logging onto the Enterprise Common Collector. In this field, specifythe user ID you defined on the Enterprise Common Collector as the Operator role ID that youwant operators to use on Tivoli Enterprise Portal.

Enterprise Common Collector PasswordThe password of the user logging onto the Enterprise Common Collector. In this field, specifythe password that corresponds to the user ID you defined for Enterprise Common CollectorUser ID.

Confirm Enterprise Common Collector PasswordThis field is provided to confirm your choice of the Enterprise Common Collector password.Enter the same value you typed into the previous field.

6. Click the Tivoli zEnterprise Monitoring Agent Log Settings tab and review the default log trace levelsetting (Informational).


These logging levels are supported by the monitoring agent:

Off Do not log any messages for the monitoring agent.

Error Log messages that indicate that an action cannot be completed because of a user or systemerror. These messages require user response.

WarningLog messages that call your attention to an exception condition. The condition might not bean error but can cause problems if not resolved.

InformationalLog messages that provide feedback about something that happened in the product or systemthat might be important. These messages can provide guidance when you are requesting aspecific action from the product. This is the default.

Minimum DebugStart writing trace records only when an error is detected.

Medium DebugStart writing trace records. Medium-detail debugging messages are captured. These messagesare used by IBM Software Support to diagnose software problems.

Maximum DebugAll trace data is captured. These messages are used by IBM Software Support to diagnosesoftware problems.

Figure 26. Tivoli Enterprise Monitoring Agent: Log Trace Level Parameters screen


All Set tracing to the maximum and display all log messages for the Enterprise CommonCollector.

7. Click the Monitoring Agent for Tivoli zEnterprise Monitoring Agent SSL tab.

Secure Sockets Layer (SSL) is a security protocol that provides communication privacy. With SSL,client-server applications can communicate in a way that is designed to prevent eavesdropping,tampering, and message forgery. Use this tab to configure SSL communication between the TivolizEnterprise monitoring agent and the Enterprise Common Collector. This parameter specifies whetheryou want this monitoring agent to accept all certificates sent from the collector. The default is Yes. Ifyou indicated Yes, then the final table reads All Certificates Will Be Accepted.

Figure 27. Tivoli Enterprise Monitoring Agent: Secure Sockets Layer Communication screen


8. If you selected No on the Monitoring Agent for Tivoli zEnterprise Monitoring Agent SSL tab, you seean additional screen titled SSL Truststore Credentials. A truststore is a key database that holds signercertificates for only the target servers that the user trusts. By choosing No, you indicated that youwant to define your own truststore for communication between this monitoring agent and theEnterprise Common Collector. This action causes a fourth tab to be displayed where you define SSLtruststore credentials.

Figure 28. Tivoli Enterprise Monitoring Agent: All Certificates Will Be Accepted screen


Use this information to select values for the following fields on the tab:

Certificates TruststoreThe name of the truststore is where you store the certificates of trusted parties. Specify thename and path for this truststore. A default, self-signed truststore certificate namedze_agent_truststore was shipped with this monitoring agent. You can select this truststorecertificate or provide a path and name to another truststore.

Certificates Truststore PasswordThe password required to access the truststore you specified in the previous field. If you areusing the default certificate (ze_agent_truststore), the default password is z1manager.

Confirm Certificates Truststore PasswordRe-enter the password you specified in the previous field.

When you are satisfied with these values, click OK to continue.9. More processing occurs. Tivoli Monitoring Services is stopped and restarted. The monitoring agent is

configured and started. When the processing is complete, the Tivoli zEnterprise Monitoring Agent -InstallShield Wizard Complete screen is displayed:

Figure 29. Tivoli Enterprise Monitoring Agent: Truststore Credentials screen


Installation is completed. Proceed with installing and configuring the next component.

Installing the monitoring agent on Windows systems by using thesilent install scriptTo install the monitoring agent on Windows, edit the system-type-specific Windows silent install script toprovide the values required for this monitoring agent, and run the script

Perform these tasks:v Editing the silent install file, as explained in “Editing the monitoring agent Windows silent installation

file”v Running the silent install, as explained in “Installing the monitoring agent by using the silent

installation” on page 118

Editing the monitoring agent Windows silent installation fileA sample Windows silent installation response file is provided on the IBM Tivoli zEnterprise MonitoringAgent v6.2.3.0 and Agent Reports DVD. Use the following steps to edit that response file as appropriate foryour environment:

About this task

This section provides information about installing the Tivoli zEnterprise monitoring agent using the silentinstallation method. This method of installation is useful for advanced users who are familiar with the

Figure 30. Tivoli zEnterprise Monitoring Agent - InstallShield Wizard Complete screen


decisions that you are prompted to make when you install using the installation wizard. Instructions forediting and running this file are found in Appendix B "Performing a silent installation of IBM TivoliMonitoring" in the IBM Tivoli Monitoring: Installation and Setup Guide. To better understand the values thatcan be configured in the response file, see “Configuration values” on page 102

Procedure1. Locate the WINDOWS\silent.txt file in the itm_agents subdirectory of the IBM Tivoli zEnterprise

Monitoring Agent v6.2.3.0 and Agent Reports DVD. .2. Copy this file to a temporary directory on your system.3. Open your copy of the silent.txt file in a text editor. The silent install file is the same for all

monitoring agents and for the IBM Tivoli Monitoring component. In the version of this file providedwith this monitoring agent, all entries are commented out. Each line in this file must be either acomment (containing a semicolon in column one for Windows ) or a meaningful statement. To editthis file to install the Tivoli zEnterprise monitoring agent, you, uncomment only the license agreementand the section about the KZE agent. If you uncommented every line in this file, you would reinstallIBM Tivoli Monitoring. Edit the following sections and lines:a. Locate this section, the license agreement.

;---------------------------------------------------------------------[INSTALLATION SECTION];---------------------------------------------------------------------;; Complete each step below.;;; Step 1: License Agreement.; The installation will copy license files to a directory called License in your; install directory. Uncomment the following statement to agree to the license.;;License Agreement=I agree to use the software only in accordance with the installed license.;; Note: You must agree with and uncomment the preceding statement to; proceed with the silent installation.

Uncomment the line that follows by removing the semi-colon at the beginning of the line.License Agreement=I agree to use the software only in accordance with the installed license.

b. Locate this section, the information for installing application support for the various IBM TivoliMonitoring components.;*********************************************************************;; TIVOLI ENTERPRISE MONITORING AGENT; TEMA INSTALLATION SECTION;; Any Feature selected that ends in CMA will cause the TEMA Framework and specific

Agent to be installed.;;*********************************************************************;;KZEWICMA=IBM Tivoli Monitoring for zEnterprise Agent ( Agent );;*********************************************************************;; TIVOLI ENTERPRISE MONITORING SERVER; TEMS INSTALLATION SECTION;; Any Feature selected that ends in CMS will cause the TEMS Framework to be installed.;;*********************************************************************;;KZEWICMS=IBM Tivoli Monitoring for zEnterprise Agent Support ( TEMS );


;*********************************************************************;; TIVOLI ENTERPRISE PORTAL SERVER; TEPS INSTALLATION SECTION;; Any Feature selected that ends in CNS will cause the TEPS Framework and browser to be installed.;;*********************************************************************;;KZEWICNS=IBM Tivoli Monitoring for zEnterprise Agent Support ( TEP Server );;;********************************************************************; Tivoli Enterprise Portal Desktop Client; TEP Desktop INSTALLATION SECTION;; Any Feature selected that ends in XEW will cause the TEP Desktop to be installed.;;********************************************************************;;KZEWIXEW=IBM Tivoli Monitoring for zEnterprise Agent Support ( TEP Workstation );;*********************************************************************

Uncomment this line to install application support for the monitoring agent:;KZEWICMA=IBM Tivoli Monitoring for zEnterprise Agent ( Agent )

Note that this section also contains the statements you would uncomment to install applicationsupport for the other IBM Tivoli Monitoring components. If you are running all IBM componentson the same system or using the self-describing agent support, you can also uncomment thefollowing lines, as appropriate. Otherwise, uncomment these lines only when you do a silentinstall of application support for the component.v To install application support on Tivoli Enterprise Monitoring Server, uncomment this line:

;KZEWICMS=IBM Tivoli Monitoring for zEnterprise Agent Support ( TEMS )

v To install application support on Tivoli Enterprise Portal Server, uncomment this line:;KZEWICNS=IBM Tivoli Monitoring for zEnterprise Agent Support ( TEP Server )

v To install application support on Tivoli Enterprise Portal desktop client, uncomment this line:;KZEWIXEW=IBM Tivoli Monitoring for zEnterprise Agent Support ( TEP Workstation )

c. Locate this section, the information about the Tivoli zEnterprise monitoring agent.[KZE_AGENT_CONFIG];;; Enterprise Common Collector Configuration for zEnterprise Agent;; This section configures the Enterprise Common Collecter; interface to the Tivoli Monitoring Agent for zEnterprise.;; Fully qualified hostname of Enterprise Common Collector.; If the Enterprise Common Collector and the zEnterprise agent; reside on the same system, then the default "localhost" is; sufficient and does not need to be changed. If the Enterprise; Common Collector resides on another system, then "localhost"; needs to be replaced with a fully qualified hostname, for; example: test1.somelab.raleigh.ibm.com;KZE_ECC_HOST=localhost;; Secure Enterprise Common Collector; This is the port number of the secure port that the zEnterprise; monitoring agent uses to communicate with the Enterprise Common; Collector. The default is 8443.;KZE_ECC_PORT=8443


;; The User ID of the user logging onto the Enterprise Common Collector.; In this field, specify the user ID you defined on the Enterprise Common; Collector as the Operator role ID that you want operators to use on; Tivoli Enterprise Portal.;KZE_ECC_USER=;; Password for Enterprise Common Collector userid that the; zEnterprise agent uses to logon to the Common Collector.;KZE_ECC_PASSWORD=;; Connection timeout. Amount of time before connection is requested again.; The default is 60000 milliseconds.;KZE_ECC_CONNECTION_TIMEOUT=60000;; Time Enterprise Common Collection waits for a response to requests before; timing out. The default is 120000 milliseconds.;KZE_ECC_READ_TIMEOUT=120000;; SSL Configuration for zEnterprise TEMA;; This section configures secure socket layer communication for; Tivoli Monitoring Agent for zEnterprise.;; This parameter specifies if you want to accept all certificates. The; default is yes. If you take the default then KZE_TEMA_TRUSTSTORE; and KZE_TEMA_TRUSTSTORE_PASSWORD do not need to be filled in. If you; do not want to take the default then change this to NO and; specify truststore and password for your enterprise.;KZE_SSL_ACPT_ALL_CERT_DESC=YES;; Truststore certificate. The default is ze_agent_truststore.; If KZE_SSL_ACPT_ALL_CERT_DESC=NO, then this parameter must be given a value.;KZE_TEMA_TRUSTSTORE=ze_agent_truststore;; Password for the truststore certificate. If KZE_SSL_ACPT_ALL_CERT_DESC=NO,; then this parameter must be given a value.;KZE_TEMA_TRUSTSTORE_PASSWORD=

d. Uncomment this line and accept the default value or provide your own value:KZE_ECC_HOST=localhost

This value should provide the fully qualified hostname of Enterprise Common Collector. Thedefault is localhost.If the Enterprise Common Collector and the zEnterprise agent reside on the same system, then thedefault localhost is sufficient and does not need to be changed. If the Enterprise Common Collectorresides on another system, then localhost needs to be replaced with a fully qualified hostname,such as test1.somelab.raleigh.ibm.com.

e. If the Tivoli Enterprise Monitoring Server and the zEnterprise agent do not reside on the samephysical system, remember to perform the tasks inside the CMA_CONFIG section of the silent installscript. For guidance performing these tasks, see "Performing a silent installation of IBM TivoliMonitoring" section of the IBM Tivoli Monitoring: Installation and Setup Guide.

f. Uncomment this line and accept the default value or provide your own value:KZE_ECC_PORT=8443

This value should provide the port number of the secure port that the zEnterprise monitoringagent uses to communicate with the Enterprise Common Collector. The default is 8443.

g. Uncomment this line and accept the default value or provide your own value:KZE_ECC_USER=


This value should provide the user ID of the user logging onto the Enterprise Common Collector.In this field, specify the user ID you defined on the Enterprise Common Collector as the Operatorrole ID that you want operators to use on Tivoli Enterprise Portal. There is no default.

h. Uncomment this line and accept the default value or provide your own value:KZE_ECC_PASSWORD=

This value should provide the password that corresponds to the Enterprise Common Collectoruser ID you provided in the previous step, the user ID that the zEnterprise agent uses to logon tothe Enterprise Common Collector. There is no default.

i. Uncomment this line and accept the default value or provide your own value:KZE_ECC_CONNECTION_TIMEOUT=60000

This value should provide amount of time that the agent will wait for a response to a requestbefore connection between the Enterprise Common Collector and the monitoring agent times outand must be requested again. The default is 60000 milliseconds (one minute).

j. Uncomment this line and accept the default value or provide your own value:KZE_ECC_READ_TIMEOUT=120000

This value should provide the amount of time that the Enterprise Common Collection waits for aresponse to requests before timing out. The default is 120000 milliseconds (two minutes).

k. Uncomment this line and accept the default value or provide your own value:KZE_SSL_ACPT_ALL_CERT_DESC=YES

The next set of values defines how you want to configure the Secure Sockets Layer (SSL)relationship beween the monitoring agent and the Enterprise Common Collector.SSL is a security protocol that provides communication privacy. With SSL, client-serverapplications can communicate in a way that is designed to prevent eavesdropping, tampering, andmessage forgery. This parameter specifies whether you want this monitoring agent to accept allcertificates. The default is Yes. If you respond yes, you indicate that you trust all certificateswithout any validation and will be using the default truststore ze_agent_truststore and the defaultpassword to set up this truststore.If you accept this default value, then KZE_TEMA_TRUSTSTORE ; andKZE_TEMA_TRUSTSTORE_PASSWORD do not need to be uncommented and completed and youcan skip to Step 4. If you do not want to take the default then change this default setting to Noand continue and specify a truststore and password for your enterprise.

l. If you changed the value for KZE_SSL_ACPT_ALL_CERT_DESC from yes to no, uncomment thisline and accept the default value or provide your own value:KZE_TEMA_TRUSTSTORE=ze_agent_truststore

By choosing No for the previous parameter, you indicated that you want to define your owntruststore for communication between this monitoring agent and the Enterprise Common Collector.The default is ze_agent_truststore. Provide your own trust store value along with path informationfor reaching this truststore on computer where the Enterprise Common Collector is running.

m. If you changed the value for KZE_SSL_ACPT_ALL_CERT_DESC from yes to no, uncomment thisline and accept the default value or provide your own value:KZE_TEMA_TRUSTSTORE_PASSWORD=

This value should provide the password accessing for the truststore certificate. IfKZE_SSL_ACPT_ALL_CERT_DESC=NO, then this parameter must be given a value. The defaultpassword is z1manager. The first time you log in, change this password.

4. Save the file and close the editor.


5. Run the silent installation file using the information found in “Installing the monitoring agent byusing the silent installation.”

Installing the monitoring agent by using the silent installationIf you are installing silently by using a response file, see the information about performing a silentinstallation in the IBM Tivoli Monitoring Installation and Setup Guide.

About this task

This procedure is explained in detail in Appendix B "Performing a silent installation of IBM TivoliMonitoring" in the IBM Tivoli Monitoring: Installation and Setup Guide. See "Creating and using a Windowsresponse file." This section also explains the following:v Automatically creating agent response filesv Running the silent installation from the IBM Tivoli Monitoring command line with parametersv Running the silent installation using SMS

Installing the monitoring agent on Linux or UNIX by using the consoleinstall and configuration scriptsTo install the monitoring agent on Linux or UNIX, edit the system-type-specific Linux or UNIX consoleinstall script and the system-type-specific console configuration script to provide the values required forthis monitoring agent and run these two scripts.

Perform these tasks:v Editing the console install file and the console configuration files, as explained in “Editing the

monitoring agent UNIX silent installation response file”v Running the silent install, as explained in “Installing the monitoring agent on UNIX or Linux systems

from the console” on page 122

Important: Some problems have been observed when using the silent installation method to install themonitoring agent on UNIX or Linux. See http://www-01.ibm.com/support/docview.wss?uid=swg21377580 for more information.

Editing the monitoring agent UNIX silent installation response fileA sample Linux or UNIX silent installation response file is provided on the product installation media.Use the following steps to edit the install and configuration response files as appropriate for yourenvironment.

About this task

This section provides information about installing the Tivoli zEnterprise monitoring agent on Linux orUNIX systems using the silent installation and configuration method. This method is useful for advancedusers who are familiar with the decisions that you are prompted to make when you install using theinstallation wizard. Instructions for editing and running this file are found in Appendix B "Performing asilent installation of IBM Tivoli Monitoring" in the IBM Tivoli Monitoring: Installation and Setup Guide. Tobetter understand the values that can be configured in the response file, see “Configuration values” onpage 102

Procedure1. Locate the silent_install.txt and the silent_config.txt files in the itm_agents subdirectory of the

IBM Tivoli zEnterprise Monitoring Agent v6.2.3.0 and Agent Reports DVD.2. Copy these files to a temporary directory on your system.3. Open your copy of the silent_install.txt file in a text editor. The silent install file is the same for

all monitoring agents and for the IBM Tivoli Monitoring component. In the version of this file




provided with this monitoring agent, all entries are commented out. Each line in this file must beeither a comment (containing a # in column one) or a meaningful statement. To edit this file to installthe Tivoli zEnterprise monitoring agent, you, uncomment only the license agreement and the sectionabout the KZE agent. If you uncommented every line in this file, you would reinstall IBM TivoliMonitoring. Edit the following sections and lines:a. Locate this instruction that defines what you are installing.

# The product codes of the products to be installed.# This parameter can be given once for each product to install or# specifying ’all’ will install all products for the given platform.# NOTE: Some products are not supported on some platforms. Use the# command line installer to determine what products are available# on the platform.# Install all products#INSTALL_PRODUCT=all

# Individual product codes of the products to be installed if you do not# choose the "all" option above.# Install Tivoli Enterprise Monitoring Server#INSTALL_PRODUCT=ms# Install Tivoli Enterprise Portal Server#INSTALL_PRODUCT=cq# Install Tivoli Enterprise Portal Desktop Client#INSTALL_PRODUCT=cj# Install Warehouse Proxy#INSTALL_PRODUCT=hd# Install Summarization and Pruning Agent#INSTALL_PRODUCT=sy# Install zEnterprise Monitoring Agent#INSTALL_PRODUCT=ze

If you want to install all the IBM Tivoli Monitoring components and the Tivoli zEnterprisemonitoring agent, uncomment #INSTALL_PRODUCT=all.

b. These instructions assume that the IBM Tivoli Monitoring environment is already installed at thev6.2.3 Fix Pack 1 or later level. Uncomment this line to install the Tivoli zEnterprise monitoringagent:INSTALL_PRODUCT=ze

4. Save this file.5. Open your copy of the silent_config.txt file in a text editor.

a. Locate this section, the information about the Tivoli zEnterprise monitoring agent.#################### ENTERPRISE COMMON COLLECTOR LOGON INFO ####################### This section configures the Enterprise Common Collecter# interface to the Tivoli Monitoring Agent for zEnterprise.

# Fully qualified hostname of Enterprise Common Collector.# If the Enterprise Common Collector and the zEnterprise agent# reside on the same system, then the default "localhost" is# sufficient and does not need to be changed. If the Enterprise# Common Collector resides on another system, then "localhost"# needs to be replaced with a fully qualified hostname, for# example: test1.somelab.raleigh.ibm.com#KZE_ECC_HOST=localhost

# Secure Enterprise Common Collector# This is the port number of the secure port that the zEnterprise# monitoring agent uses to communicate with the Enterprise Common# Collector. The default is 8443.#KZE_ECC_PORT=8443

# The User ID of the user logging onto the Enterprise Common Collector.# In this field, specify the user ID you defined on the Enterprise Common# Collector as the Operator role ID that you want operators to use on# Tivoli Enterprise Portal.


#KZE_ECC_USER=

# Password for Enterprise Common Collector userid that the# zEnterprise agent uses to logon to the Common Collector.#KZE_ECC_PASSWORD=

# Connection timeout. Amount of time before connection is requested again.# The default is 60000 milliseconds.#KZE_ECC_CONNECTION_TIMEOUT=60000

# Time Enterprise Common Collection waits for a response to requests before# timing out. The default is 120000 milliseconds.#KZE_ECC_READ_TIMEOUT=120000

#################### ENTERPRISE TEMA SSL CONFIGURATION #############################

#; This section configures secure socket layer communication for#; Tivoli Monitoring Agent for zEnterprise.

# This parameter specifies if you want to accept all certificates. The# default is yes. If you take the default then KZE_TEMA_TRUSTSTORE# and KZE_TEMA_TRUSTSTORE_PASSWORD do not need to be# filled in. If you do not want to take the default then change this to NO and# specify truststore and password for your enterprise.#KZE_SSL_ACPT_ALL_CERT_DESC=YES

# Truststore certificate. The default that is shipped is ze_agent_truststore.# If KZE_SSL_ACPT_ALL_CERT_DESC=NO, then this parameter# must be given a value.#KZE_TEMA_TRUSTSTORE=ze_agent_truststore

# Password for the truststore certificate. If you are using the default# ze_agent_truststore that is shipped with the Agent then the default# password is z1manager. If KZE_SSL_ACPT_ALL_CERT_DESC=NO,# then this parameter must be given a value.#KZE_TEMA_TRUSTSTORE_PASSWORD=

b. Uncomment this line and accept the default value or provide your own value:KZE_ECC_HOST=localhost

This value should provide the fully qualified hostname of Enterprise Common Collector. Thedefault is localhost.If the Enterprise Common Collector and the zEnterprise agent reside on the same system, then thedefault localhost is ; sufficient and does not need to be changed. If the Enterprise CommonCollector resides on another system, then localhost needs to be replaced with a fully qualifiedhostname, such as test1.somelab.raleigh.ibm.com.

c. If the Tivoli Enterprise Monitoring Server and the zEnterprise agent do not reside on the samephysical system, remember to perform the tasks inside the PRIMARY TEMS CONFIGURATION section ofthe silent install script. For guidance performing these tasks, see "Performing a silent installation ofIBM Tivoli Monitoring" section of the IBM Tivoli Monitoring: Installation and Setup Guide.

d. Uncomment this line and accept the default value or provide your own value:KZE_ECC_PORT=8443

This value should provide the port number of the secure port that the zEnterprise monitoringagent uses to communicate with the Enterprise Common Collector. The default is 8443.

e. Uncomment this line and accept the default value or provide your own value:KZE_ECC_USER=

This value should provide the user ID of the user logging onto the Enterprise Common Collector.In this field, specify the user ID you defined on the Enterprise Common Collector as the Operatorrole ID that you want operators to use on Tivoli Enterprise Portal. There is no default.


f. Uncomment this line and accept the default value or provide your own value:KZE_ECC_PASSWORD=

This value should provide the password that corresponds to the Enterprise Common Collector userID you provided in the previous step, the user ID that the zEnterprise agent uses to logon to theEnterprise Common Collector. There is no default.

g. Uncomment this line and accept the default value or provide your own value:KZE_ECC_CONNECTION_TIMEOUT=60000

This value should provide amount of time the agent will wait for a response to a request beforeconnection between the Enterprise Common Collector and the monitoring agent times out andmust be requested again. The default is 60000 milliseconds (one minute).

h. Uncomment this line and accept the default value or provide your own value:KZE_ECC_READ_TIMEOUT=120000

This value should provide the amount of time that the Enterprise Common Collection waits for aresponse to requests before timing out. The default is 120000 milliseconds (two minutes).

i. Uncomment this line and accept the default value or provide your own value:KZE_SSL_ACPT_ALL_CERT_DESC=YES

The next set of values defines how you want to configure the Secure Sockets Layer (SSL)relationship beween the monitoring agent and the Enterprise Common Collector.SSL is a security protocol that provides communication privacy. With SSL, client-server applicationscan communicate in a way that is designed to prevent eavesdropping, tampering, and messageforgery. This parameter specifies whether you want this monitoring agent to accept all certificatessent from the collector. The default is Yes If you respond yes, you indicate that you trust allcertificates without any validation and will be using the default truststore ze_agent_truststore andthe default password to set up this truststore.If you accept this default value, then KZE_TEMA_TRUSTSTORE andKZE_TEMA_TRUSTSTORE_PASSWORD do not need to be uncommented, and you can skip toStep 6. If you do not want to take the default, change this default setting to No and continue andspecify a truststore and password for your enterprise.

j. If you changed the value for KZE_SSL_ACPT_ALL_CERT_DESC from yes to no, uncomment thisline and accept the default value or provide your own value:KZE_TEMA_TRUSTSTORE=ze_agent_truststore

By choosing No for the previous parameter, you indicated that you want to define your owntruststore for communication between this monitoring agent and the Enterprise Common Collector.The default is ze_agent_truststore. Provide your own trust store value along with path informationfor reaching this truststore on computer where the Enterprise Common Collector is running.

k. If you changed the value for KZE_SSL_ACPT_ALL_CERT_DESC from yes to no, uncomment thisline and accept the default value or provide your own value:KZE_TEMA_TRUSTSTORE_PASSWORD=

This value should provide the password accessing for the truststore certificate. IfKZE_SSL_ACPT_ALL_CERT_DESC=NO, then this parameter must be given a value. The defaultpassword is z1manager. The first time you log in, change this password.

6. Save this file and close the text editor.7. Run the silent installation file first by using the information found in IBM Tivoli Monitoring: Installation

and Setup Guide > Appendix B: > "Performing a silent installation on a Linux or UNIX computer".Then run the silent configuration file by using information found in the same section.


Installing the monitoring agent on UNIX or Linux systems from the consoleTo install the Tivoli zEnterprise monitoring agent or application support or both on UNIX or Linuxsystems from a console, do the following.

Procedure1. Insert the IBM Tivoli zEnterprise Monitoring Agent v6.2.3.0 and Agent Reports DVD drive and change

directories on the DVD to the itm_agents subdirectory. Enter this command to launch the consoleinstallation shell:./install.sh

2. A message about the version of the shell you are running is displayed. Then you see the firstcommand prompt asking you to enter the name of the directory where you have already installedIBM Tivoli Monitoring v6.2.3 Fix Pack 1:IBM Tivoli Monitoring installationINSTALL

Enter the name of the IBM Tivoli Monitoring directory[ default = /opt/IBM/ITM]:

Type your directory name and press Enter, or accept the default by pressing Enter.3. Since IBM Tivoli Monitoring in already installed, the installation program asks you to confirm that

this installation location is acceptable.ITM home directory "/opt/IBM/ITM" already existsOK to use it [1-yes, 2-no; "1" is default]

To accept this default, press Enter.4. Your are prompted for the next installation step.

Select on of the following:

1) Install product to the local host.2) Install product to depot for remote deployment (requires TEMS).3) Install TEMS support for remote seeding4) Exit install.

Please enter a valid number:

To install the product on the local host, type 1 and press Enter.5. The installation program initializes and displays the license agreement.

Initializing ...International License Agreement for Early Release ofPrograms

Part 1 - General Terms

BY DOWNLOADING, INSTALLING, COPYING, ACCESSING, CLICKING ONAN "ACCEPT" BUTTON, OR OTHERWISE USING THE PROGRAM,LICENSEE AGREES TO THE TERMS OF THIS AGREEMENT. IF YOU AREACCEPTING THESE TERMS ON BEHALF OF LICENSEE, YOU REPRESENTAND WARRANT THAT YOU HAVE FULL AUTHORITY TO BIND LICENSEETO THE TERMS. IF YOU DO NOT AGREE TO THESE TERMS,

* DO NOT DOWNLOAD, INSTALL, COPY, ACCESS, CLICK ON AN"ACCEPT" BUTTON, OR USE THE PROGRAM; AND

Press Enter to continue viewing the license agreement, orenter "1" to accept the agreement, "2" to decline it, "3"to print it, "4" to read non-IBM terms, or "99" to go backto the previous screen.


If you agree to the terms, type 1 and press Enter.6. This information message is displayed, followed by a prompt to select the component you want to

install.All agents require that application support files that contain agent-specificinformation be installed on the Tivoli Enterprise Monitoring server that theagents will connect to, Tivoli Enterprise Portal Server and Tivoi EnterprisePortal desktop and browser client. Install application support before startingto install any Tivoli Enterprise Monitoring Agents.

Product packages are available for this operating systemand component support categories:

1) IBM Tivoli Monitoring components for this operating system2) Tivoli Enterprise Portal Browser Client support3) Tivoli Enterprise Portal Desktop Client support4) Tivoli Enterprise Portal Server support5) Tivoli Enterprise Monitoring Server support6) Other operating systems

Type the number or type "q" to quit selection[ number "1" or "IBM Tivoli Monitoring components for this operatingsystem" is the default]:

Since you are installing the Tivoli zEnterprise monitoring agent and its application support files, type1 and press Enter.

Note: If you were installing application support for another component (such as Tivoli EnterprisePortal browser or desktop client, Tivoli Enterprise Portal Server, or Tivoli Enterprise MonitoringServer), you would repeat the installation process and choose the appropriate component.

7. The installation program confirms your choice.You selected number "1" or "IBM Tivoli Monitoring components for thisoperating system"

Is the selection correct [ 1=Yes, 2=No ; default is "1"} ?

To accept the default, press Enter.8. You are prompted to choose what you want to install.

The following products are available for installation:

1) Tivoli Enterprise Services User Interface Extensions V06.23.01.002) Tivoli zEnterprise Monitoring Agent V06.23.00.003) all of the above

Type the numbers for the product you want to install, type "b" to changeoperating system or type "q" to quit selection.If you enter more than one number, separate the numbers by a comma or space.

Type your selections here:

Since you want to install this monitoring agent and its user interface extensions, type 3 and pressEnter.

9. You receive this message and are asked to confirm your choice.The following products will be installed:

Tivoli Enterprise Services User Interface Extensions V06.23.01.00Tivoli zEnterprise Monitoring Agent V06.23.00.00

Are your selections correct [ 1=Yes, 2=No ; default is "1"]?

Press Enter to continue


10. You see these messages as the installation takes place.... installing "Tivoli Enterprise Services User Interface ExtensionsV06.23.01.00 for your_operating_system"; please wait.

=> installed "Tivoli Enterprise Services User Interface ExtensionsV06.23.01.00 for your_operating_system"....Initializing component Tivoli Enterprise Services User InterfaceExtensions V06.23.01.00 for your_operating_system....Tivoli Enterprise Services User Interface Extensions V06.23.01.00for your_operating_system initialized.

... installing "Tivoli zEnterprise Monitoring Agent V06.23.00.00 foryour_operating_system"; please wait.

=> installed "Tivoli zEnterprise Monitoring Agent V06.23.00.00 foryour_operating_system".

Do you want to install additional products or product support packages[ 1=Yes, 2=No ; default is "2"]?

Press Enter to accept the default (do not install additional products).11. And finally, this.

...postprocessing; please wait.

...finished postprocessing.Installation step complete.

You may now configuration any locally installed IBM Tivoli Monitoring productvia the "/opt/IBM/ITM/bin/itmcmd config" command.

The install.sh command creates most of directories and files with world writepermissions. IBM Tivoli Monitoring provides the secureMain utility to helps youkeep the monitoring environment secured. You can secure this installation nowor manually execute the secureMain utility later. Fore more information, seeAppendix G. Securing your IBM Tivoli Monitoring installation on Linux or UNIXin the IBM Tivoli Monitoring Installation and Setup Guide.

Do you want to secure this IBM Tivoli Monitoring installation [1-yes, 2-no;"2" is default]?

If you want to secure this installation now, press Enter to accept the default. This step completes andthen returns you to the command prompt. Installation of the Tivoli zEnterprise monitoring agent andits application support files is complete.

What to do next

If you want to install application support for another component (such as Tivoli Enterprise Portalbrowser or desktop client, Tivoli Enterprise Portal Server, or Tivoli Enterprise Monitoring Server), repeatthe installation process on the machine running the chosen component.

Installing application supportIf you did not use the self-describing agent feature, before you can view data collected by the TivolizEnterprise monitoring agent, you must install and enable application support.

Application support files provide agent-specific information for workspaces, helps, situations, templates,and other data. Application support for a monitoring agent includes two types of files:v SQL files are required for adding product-provided situations, templates, and policies to the Enterprise

Information Base (EIB) tables maintained by the hub monitoring server. These SQL files are also calledseed data, and installing them on a monitoring server is also called seeding the monitoring server.


v Catalog and attribute (cat and atr) files are required for presenting workspaces, online help, and expertadvice for the agent in Tivoli Enterprise Portal.

All monitoring agents require that application support be configured on all instances of the followinginfrastructure components:v Tivoli Enterprise Monitoring Server (both hub and remote monitoring servers)v Tivoli Enterprise Portal Serverv Tivoli Enterprise Portal desktop client, if the desktop client was installed from the installation media.

You do not need to configure application support for desktop clients downloaded from the TivoliEnterprise Portal Server using IBM Web Start for Java.

Application support for monitoring agents is installed independently of where and when the monitoringagents themselves are installed:v Install application support for a particular type of monitoring agent on the monitoring servers, portal

server, and portal desktop clients. Install agents of that type on any managed system in theenvironment that is compatible with the agent.

v Install application support for a type of monitoring agent before or after any monitoring agents of thattype are installed.

After you install application support for a particular type of monitoring agent, you can add any numberof agents of that type to your environment without having to install application support again. Forexample, you can install application support for a Linux OS monitoring agent (the agent type) to aWindows monitoring server (using the IBM Tivoli Monitoring installation media for Windows). Later, youcan install any number of Linux OS monitoring agents to Linux computers in your environment (usingthe IBM Tivoli Monitoring installation media for Linux).

Configuring application support is a two-step process:1. Installing the application support files (from installation media).2. Enabling the application support (sometimes referred to as adding or activating the application

support).

On the portal server and portal desktop clients, application support is enabled when the component isconfigured. On monitoring servers, application support is enabled by seeding the database withagent-specific information.

The procedures for configuring application support differ by operating system. On Windows systems,both installation and enablement of application support are accomplished during the installation of themonitoring servers, portal server, and desktop clients. On Linux or UNIX systems, this two-step processis more visible, with the enablement step done separately from the installation.

Information about installation application support is found in the IBM Tivoli Monitoring: Installation andSetup Guide.

Installing application support on Tivoli Enterprise Monitoring ServerUse the following information to install application support for the Tivoli zEnterprise monitoring agenton monitoring servers (hub or remote) in your environment.

Locate the application support files for the monitoring server on the IBM Tivoli zEnterprise MonitoringAgent v6.2.3.0 and Agent Reports DVD. They should be located in the itm_app_data_files subdirectory.v To install application support on a monitoring server on Windows or UNIX or Linux, see the

"Installing application support on monitoring servers" topic in the "Installing IBM Tivoli Monitoring"chapter of the IBM Tivoli Monitoring: Installation and Setup Guide for the procedure for setting upapplication support on Tivoli Enterprise Monitoring Server.


v To install application support on a monitoring server running on z/OS, follow the instructions in"Adding application support to a monitoring server on z/OS" chapter of Configuring the TivoliEnterprise Monitoring Server on z/OS.

Installing application support on the Tivoli Enterprise Portal ServerUse the following procedures to install application support for the Tivoli Enterprise Portal Server in yourenvironment.

Locate the application support files for the portal server on the IBM Tivoli zEnterprise Monitoring Agentv6.2.3.0 and Agent Reports DVD. They should be located in the itm_app_data_files subdirectory.

To install application support on a monitoring server on Windows or UNIX or AIX, see the "Installingapplication support on the Tivoli Enterprise Portal Server" topic in the "Installing IBM Tivoli Monitoring"chapter of the IBM Tivoli Monitoring: Installation and Setup Guide for the procedure for setting upapplication support on Tivoli Enterprise Portal Server.

Installing application support for the Tivoli Enterprise Portal desktopand browser clientsUse the following procedures to install application support for the Tivoli Enterprise Portal desktop clientin your environment.

Locate the application support files for the Tivoli zEnterprise monitoring agent on the IBM TivolizEnterprise Monitoring Agent v6.2.3.0 and Agent Reports DVD. They should be located in theitm_app_data_files subdirectory.

See IBM Tivoli Monitoring: Installation and Setup Guide > "Installing IBM Tivoli Monitoring" > "Installingapplication support on the Tivoli Enterprise Portal desktop client" for the procedure for setting upapplication support on Tivoli Enterprise Portal desktop client on Windows or Linux.

Note: You must install application support on desktop clients that were installed from the installationmedia. You do not need to install application support on desktop clients that were obtained by using IBMWeb Start for Java to download the client from the Tivoli Enterprise Portal Server.

Language pack installationThe steps for installing language packs depend on which operating system and mode of installation youare using.

To install a language pack for the agent support files on the Tivoli Enterprise Monitoring Server, theTivoli zEnterprise monitoring agent, and the Tivoli Enterprise Portal Server, make sure that you installedthe product in the English language. Then use the steps for the operating system or mode of installationyou are using:v “Installing language packs on Windows systems”v “Installing language packs on UNIX or Linux systems” on page 127v “Silent installation of language packs for agents” on page 128

Installing language packs on Windows systemsYou can install the language packs on a Windows system.

Before you begin

First, make sure that you installed the product in the English language.


Procedure1. On the IBM Tivoli zEnterprise Monitoring Agent v6.2.3.0 and Agent Reports DVD, change to the

itm_language_pack directory.2. Double-click the lpinstaller.bat file to start the installation program.3. Select the language of the installer and click OK.4. In the Introduction panel, click Next

5. Click Add/Update and click Next.6. Select the folder where the National Language Support package (NLSPackage) files are located.

Typically, the NLSPackage files are located in the nlspackage folder where the installer executablefile is located.

7. Select the language support for the agent of your choice and click Next. To make multiple selections,press Ctrl and select the language that you want.

8. Select the languages that you want to install and click Next.9. Examine the installation summary page and click Next to begin installation.

10. After installation completes, click Finish to exit the installer.11. Restart the Tivoli Enterprise Portal, Tivoli Enterprise Portal Server, and Eclipse Help Server if any of

these components are installed.

Installing language packs on UNIX or Linux systemsYou can install the language packs on a UNIX or Linux system.

Before you begin


Procedure1. On the IBM Tivoli zEnterprise Monitoring Agent v6.2.3.0 and Agent Reports DVD, change to the

itm_language_pack subdirectory. Then, enter the following command to start the installationprogram:lpinstaller.sh -c itm_install_dir

where itm_install_dir is where you installed IBM Tivoli Monitoring. Typically, the directory name is/opt/IBM/ITM for AIX and Linux systems.

2. Select the language of the installer and click OK.3. In the Introduction panel, click Next.4. Click Add/Update and click Next.5. Select the folder where the National Language Support package (NLSPackage) files are located.

Typically, the NLSPackage files are located in the nlspackage folder where the installer executable fileis located.

6. Select the language support for the agent of your choice and click Next. To make multiple selections,press Ctrl and select the language that you want.

7. Select the languages that you want to install and click Next.8. Examine the installation summary page and click Next to begin installation.9. After installation completes, click Finish to exit the installer.

10. Restart the Tivoli Enterprise Portal, Tivoli Enterprise Portal Server, and Eclipse Help Server if any ofthese components are installed.


Silent installation of language packs for agentsYou can use the silent-mode installation method to install the language packs. In silent mode, theinstallation process obtains the installation settings from a predefined response file. It does not promptyou for any information.

Before you begin


Procedure1. Copy and paste the ITM_Agent_LP_silent.rsp response file template as shown in“Response file

example.”2. Change the following parameter settings:

NLS_PACKAGE_FOLDERFolder where the National Language Support package (NLSPackage) files are located.Typically, the NLSPackage files are located in the nlspackage folder, for example:NLS_PACKAGE_FOLDER = //tmp//LP//nlspackage.

PROD_SELECTION_PKGName of the language pack to install. Several product components can be included in onelanguage package. You might want to install only some of the available components in alanguage pack.

BASE_AGENT_FOUND_PKG_LISTAgent for which you are installing language support. This value is usually the same asPROD_SELECTION_PKG.

LANG_SELECTION_LISTLanguage you want to install.

3. Enter the command to install the language pack with a response file (silent installation):


Linux or UNIX lpinstaller.sh -c candle_home -i silent -f path_to_response_file

Where candle_home is the IBM Tivoli Monitoring base directory.

Windows lpinstaller.bat -i silent -f path_to_response_file

Response file example# IBM Tivoli Monitoring Agent Language Pack Silent Installation Operation## This is a sample response file for silent installation mode for the IBM Tivoli# Monitoring Common Language Pack Installer.# This file uses the IBM Tivoli Monitoring Common Agent Language Pack with the# install package as an example.# Note:# This response file is for the INSTALLATION of language packs only.# This file does not support UNINSTALLATION of language packs in silent mode.# -------------------------------------------------------------------------------# -------------------------------------------------------------------------------# To successfully complete a silent installation of the the example of Common Agent# localization pack, complete the following steps:## 1.Copy ITM_Agent_LP_silent.rsp to the directory where lpinstaller.bat or# lpinstaller.sh is located (IBM Tivoli Monitoring Agent Language Pack build# location).## 2.Modify the response file so that it is customized correctly and completely for


# your site.# Complete all steps listed below in the response file.## 3.After customizing the response file, invoke the silent installation using the# following command:# For Windows:# lpinstaller.bat -f <path_to_response_file># For UNIX and Linux:# lpinstaller.sh -c <candle_home> -f <path_to_response_file># Note:<candle_home> is the IBM Tivoli Monitoring base directory.# --------------------------------------------------------------------------------# --------------------------------------------------------------------------------# Force silent install mode.# --------------------------------------------------------------------------------INSTALLER_UI=silent# ---------------------------------------------------------------------------------# Run add and update actions.# ---------------------------------------------------------------------------------CHOSEN_INSTALL_SET=ADDUPD_SET# ---------------------------------------------------------------------------------# NLS Package Folder, where the NLS Packages exist.# For Windows:# Use the backslash-backslash(\\) as a file separator (for example,# C:\\ZMON_LP\\nlspackage).# For UNIX and Linux:# Use the slash-slash (//) as a file separator (for example,# //tmp//ZMON_LP//nlspackage).# ---------------------------------------------------------------------------------# NLS_PACKAGE_FOLDER=C:\\ZMON_LP\\nlspackageNLS_PACKAGE_FOLDER=//tmp//ZMON_LP//nlspackage# ---------------------------------------------------------------------------------# List the packages to process; both variables are required.# Each variable requires that full paths are specified.# Separate multiple entries with a semicolon (;).# For Windows:# Use the backslash-backslash(\\) as a file separator.# For Unix and Linux:# Use the slash-slash (//) as a file separator.# ---------------------------------------------------------------------------------# PROD_SELECTION_PKG=C:\\ZMON_LP\\nlspackage\\kze_NLS.nlspkg# BASE_AGENT_FOUND_PKG_LIST=C:\\ZMON_LP\\nlspackage\\kze_NLS.nlspkgPROD_SELECTION_PKG=//tmp//ZMON_LP//nlspackage//kze_NLS.nlspkgBASE_AGENT_FOUND_PKG_LIST=//tmp//ZMON_LP//nlspackage//kze_NLS.nlspkg# --------------------------------------------------------------------------------# List the languages to process.# Separate multiple entries with semicolons.# --------------------------------------------------------------------------------LANG_SELECTION_LIST=cs;de;es;fr;hu;it;ja;ko;pl;pt_BR;ru;th;zh_CN;zh_TW

Uninstalling the monitoring agent or application support or bothThe easiest way to uninstall the monitoring agent is the use the installation wizard.

About this task

To uninstall the monitoring agent or application support or both, follow the instructions provided in theIBM Tivoli Monitoring: Installation and Setup Guide for uninstalling the monitoring agent using theinstallation wizard. Launch and run the installation program. The installation panels show all optionsthat include the Tivoli zEnterprise monitoring agent as installed and therefore checked. To uninstall thesecomponents, remove the checks from the checkboxes adjacent to the Tivoli zEnterprise monitoring agentcomponents.


Chapter 7. Installing Tivoli Common Reporting and importingreports

The Tivoli Common Reporting tool (TCR) is a reporting feature available to users of Tivoli products. UseTivoli Common Reporting to gather, analyze, and report important trends in your managed environmentin a consistent and integrated manner.

Use the information in this section to understand how to obtain Tivoli Common Reporting version 2.1.1,install it, configure it to work with IBM Tivoli Monitoring version 6.2.3 Fix Pack 1, and import the TivolizEnterprise monitoring agent predefined reports.

The sample reports provided with this monitoring agent are found on the IBM Tivoli zEnterpriseMonitoring Agent v6.2.3.0 and Agent Reports DVD in the reports directory.

Obtaining Tivoli Common ReportingThe version of Tivoli Common Reporting shipped with IBM Tivoli Monitoring v6.2.3.1 is v2.1.1.

This version includes IBM Cognos Business Intelligence and Reporting Version 8.4 reports for the TivoliMonitoring OS Agents and other monitoring products. The Tivoli Common Reporting V2.1.1 Kit(LK4T-4913-00) that was provided with IBM Tivoli Monitoring version 6.2. Fix Pack 1 includes thefollowing platform-specific DVDs:v IBM Tivoli Common Reporting V2.1.1 - Windows 32/64 Bit Multilingual DVD (LCD7-5117-00)v IBM Tivoli Common Reporting V2.1.1 - Linux 32/64 Bit Multilingual DVD (LCD7-5118-00)v IBM Tivoli Common Reporting V2.1.1 - AIX 32/64 Bit Multilingual DVD (LCD7-5119-00)v IBM Tivoli Common Reporting V2.1.1 - HP-UX 32/64 Bit Multilingual DVD (LCD7-5120-00)v IBM Tivoli Common Reporting V2.1.1 - Solaris 32/64 Bit Multilingual DVD (LCD7-5121-00)v IBM Tivoli Common Reporting V2.1.1 - Linux on zSeries® 32/64 Bit Multilingual DVD (LCD7-5122-00)v IBM Tivoli Common Reporting V2.1.1 - Cognos Framework Manager Windows Multilingual DVD

(LCD7-5123-00)

This product is also available at no cost through the Passport Advantage® website as TCR eAssemblyCRH95ML for the distributed product (5724-C04) or through Shop zSeries for the mainframe product(5697-A79). The Passport Advantage IDs for TCR v2.1.1 are as follows:

Table 13. Passport Advantage IDs for Tivoli Common Reporting components

Platform Passport Advantage ID

Windows 32-bit CZZM7ML & CI01GML

Windows 64-bit CI01HML & CI01IML

Linux (Intel) 32-bit CZZM8ML

Linux (Intel) 64-bit CI01JML

AIX 32-bit CZZM9ML

AIX 64-bit CI01KML

HP-UX 32-bit CZZN0ML

HP-UX 64-bit CI01NML

Solaris 32-bit CZZN1ML

Solaris 64-bit CI01LML


Table 13. Passport Advantage IDs for Tivoli Common Reporting components (continued)

Platform Passport Advantage ID

Linux on zSeries 32-bit CZZN2ML

Linux on zSeries 64-bit CI01MML

Cognos Framework Manager CI01MML

Tivoli Common Reporting report packages were originally made available for many monitoring agents onthe on the IBM Integrated Service Management Library (OPAL). Report packages for other monitoringagents are included as .zip files on the Tivoli Monitoring Agent installation media. Reports for the TivolizEnterprise monitoring agent are located on the IBM Tivoli zEnterprise Monitoring Agent v6.2.3.0 and AgentReports DVD in the \reports directory. The current version of IBM Tivoli Monitoring includes a set ofpredefined reports on a separate eAssembly media package for monitoring individual, multiple, andenterprise resources.

Installing Tivoli Common ReportingTivoli Common Reporting might have been installed and configured when you installed IBM TivoliMonitoring version 6.2.3 or some other product that uses Tivoli Common Reporting.

If you have not installed Tivoli Common Reporting, do that before you attempt to import the TivolizEnterprise monitoring agent reports.

When that installation process is complete, import the Tivoli zEnterprise monitoring agent reports. Thisset of predefined reports, located in the reports subdirectory on the Tivoli zEnterprise monitoring agentare found on the IBM Tivoli zEnterprise Monitoring Agent v6.2.3.0 and Agent Reports DVD.

To start using reports, complete the following steps:1. Install Tivoli Common Reporting using the information found in the Tivoli Common Reporting

information center using one of the following platform-specific commands:

Table 14. Commands for launching the Tivoli Common Reporting installation program by platform

Platform Command

Linux setup_linux.bin

Windows setup_windows.exe

HP-UX setup_hpux.bin

AIX setup_aix.bin

Solaris setup_solaris.bin

See http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.tivoli.tcr.doc_21/ic-home.html for assistance performing this installation.

2. Install and configure the Tivoli Data Warehouse and warehouse agents: Warehouse Proxy Agent andSummarization and Pruning Agent. For more information, see the “Tivoli Data Warehouse solutions:common procedures,” chapter of the IBM Tivoli Monitoring: Installation and Setup Guide.

3. Configure historical collection. See the "Historical collection configuration" chapter in the IBM TivoliMonitoring: Tivoli Enterprise Portal User's Guide.

4. Prepare the database. See the "Creating shared dimensions tables and populating the time dimensionstable" topic and the "Creating and populating the resource dimensions table" in the IBM TivoliMonitoring: Administrator's Guide.

5. Import the Tivoli zEnterprise monitoring agent reports. See the "Importing reports using the reportinstaller" topic in the IBM Tivoli Monitoring: Administrator's Guide.




6. Review the reports. See the IBM Tivoli zEnterprise Monitoring Agent: User's Guide for report contentspecifics. Complete documentation for the Tivoli Common Reporting tool is located athttp://publib.boulder.ibm.com/ infocenter/tivihelp/v3r1/topic/com.ibm.tivoli.tcr_cog.doc/tcr_welcome.html.

Chapter 7. Installing Tivoli Common Reporting and importing reports 133

Chapter 8. Verifying components after configuration

With all the components that make up the zEnterprise monitoring agent environment installed singly andconfigured, the final step is to ensure that all the components in the environment can communicate witheach other and present a unified end-to-end monitoring solution.

Starting and verifying the core components of the zEnterprisemonitoring agent environmentStart the core components in the order described in the procedure that follows to verify that you havecreated a working end-to-end environment.

About this task

Ensure that the IBM Tivoli Monitoring version 6.2.3 Fix Pack 1 or later environment is configured andrunning.

Procedure1. Verify that the Enterprise Common Collector is started. Navigate to the indicated location and issue

one of these commands:

Platform Command

Linux or UNIX <install_dir>/bin/eccService.sh status

Windows <install_dir>\bin\eccService.bat status

If the Enterprise Common Collector service is running, you should see a message similar to this:


UNIX or Linux Status for Service eccSvc:Server on port 52098 is running.


Use the command line interface to list the data sources defined to the collector. See “Setting up HMCdata sources by using the command-line” on page 83 for more information. Verify that the status ofeach data source is connected. If the status of a data source is connecting or data-source-unreachable, the Enterprise Common Collector does not have an active session with that System zHardware Management Console (HMC). If all data sources are not connected, open the EnterpriseCommon Collector message log:


Linux or UNIX <install_dir>/wasce/var/log/enterpriseCommonCollector.0.log

Windows <install_dir>\wasce\var\log\enterpriseCommonCollector.0.log

Look for message IDs CTGEZ6001E, CTGEZ6002W, CTGEZ6003W or CTGEZ6004W to determine whythe Enterprise Common Collector cannot establish a session with the HMC. Correct the problem. Ifthe data source has been disabled (i.e. the enabled property of the data source is false) re-enable it;otherwise the Enterprise Common Collector should attempt to establish a session with the HMCwithin fifteen minutes.

2. Start the Tivoli zEnterprise monitoring agent.


Platform Procedure

Linux or UNIX Use the following commands to start and stop IBM Tivoli Monitoring components:

v itmcmd agent [start | stop]

v tacmd [startAgent | stopAgent]

See the IBM Tivoli Monitoring: Command Reference for the syntax of these commands.

You can also start and stop the IBM Tivoli Monitoring components from Manage TivoliEnterprise Monitoring Services. Use the following steps:

1. Right-click Tivoli zEnterprise Monitoring Agent.

2. Click Start.

3. If the Tivoli Enterprise Portal is not started, start it as well.

See the IBM Tivoli Monitoring: Installation and Setup Guide for information on how to startManage Tivoli Enterprise Monitoring Services.

Windows You can start and stop the IBM Tivoli Monitoring components from Manage Tivoli EnterpriseMonitoring Services. Use the following steps:

1. Right-click Tivoli zEnterprise Monitoring Agent.

2. Click Start.

3. If the Tivoli Enterprise Portal is not started, start it as well.

See the IBM Tivoli Monitoring: Installation and Setup Guide for information on how to startManage Tivoli Enterprise Monitoring Services.

You can also use the following command to start and stop IBM Tivoli Monitoring components:

tacmd [ startagent | stopagent ]

See the IBM Tivoli Monitoring: Command Reference for the syntax of this command.

3. Verify that the Tivoli zEnterprise monitoring agent is configured correctly to collect the data youwant:a. Open Tivoli Enterprise Portal and select the Physical view in the Navigator. Click down the

Navigator using this path: Enterprise > zEnterprise > zEnterprise Agent - [ System_Name ] >Ensembles Summary. This action loads the Ensemble Summary workspace.

b. Verify that you can see data in this workspace. If so, then the Tivoli Enterprise Portal, TivoliEnterprise Portal Server, Tivoli Enterprise Monitoring Server, and the Tivoli zEnterprise monitoringagent are communicating successfully.

c. Select the Workload Resource Groups node and confirm that this workspace also contains data.4. Verify that you are collecting historical data.

Note: Before you can perform this step, ensure that you have enabled data warehousing, using theinformation found in the "Setting up data warehousing" section of the IBM Tivoli Monitoring:Installation and Setup Guide. Then follow the procedure in “Verifying that historical collection isconfigured correctly.”

Verifying that historical collection is configured correctlyFollow this procedure to verify that historical collection is configured correctly.

Before you begin

This procedure walks you through configuring historical data collection for one attribute group only sothat you can do end-to-end verification. Repeat this procedure for each attribute group that you want tocollect historical data for.


To collect historical data, you must first create one or more collection settings. Each collection settingspecifies the attribute group to collect data from, where to store the historical data, and other informationsuch as the collection frequency and distribution. Create a historical collection setting for every attributegroup that you want to collect historical data for. You can then retrieve the historical data intoquery-based views.

Your user ID must have Configure History permission to open the History Collection Configurationwindow. If you do not have this permission, you cannot see the menu item or tool for historicalconfiguration.

About this task

Complete these steps for each attribute group that you want to collect historical data from on specifiedmanaged systems or managed system groups or on all the managed systems that connect to a TivoliEnterprise Monitoring Server. The following example creates a collection setting for the KZE EnsembleAttribute Group.

Procedure1. Once logged onto the Tivoli Enterprise Portal, click the History Configuration icon to open the

History Collection Configuration window.2. Click Create a new collection.3. Enter a Name of up to 256 bytes. A short name is also given to the collection and is shown in the

middle section of the status bar.4. Optional: Enter a Description for the collection, up to 64 bytes.5. Select zEnterprise Agent from the Monitored Application list.6. Select the KZE Ensemble Attribute Group from the list.7. Click OK to open the configuration tabs for the collection. The branch of the monitored applications

expands to show the new collection. At this point, it has not been distributed to the managedsystems.

8. Complete the fields in the Basic tab:a. Define a Collection Interval. A collection interval is the frequency of data transmission to the

short-term history file on the computer where the data is saved (Tivoli Enterprise MonitoringAgent or Tivoli Enterprise Monitoring Server). The options are every 1, 5, 15, or 30 minutes,every hour, or once per day. The default interval is 15 minutes. The shorter the interval, the fasterand larger the history file grows. This can overload the Tivoli Data Warehouse, warehouse proxy,and summarization and pruning agent. Such a short interval should be enabled for an attributegroup only if it is critical in your work.

b. Define a Collection Location. The collection location is where the short-term historical data fileresides: at the TEMA (Tivoli Enterprise Monitoring Agent) or the TEMS (Tivoli EnterpriseMonitoring Server). The default location is TEMA, which minimizes the performance impact onthe monitoring server from historical data management. For this verification exercise, selectTEMA.

9. Select the Distribution tab in the History Collection Editor.a. Select the *IBM_KZE managed system group.b. Drag this managed system group to the Start Collection On pane.

10. Click Apply to save the collection. The collection name appears in the monitored application branchof the tree with an icon. The icon for the collection group should be green. If instead it is disabled,edit the collection again and perform any steps you missed.

11. After waiting for one historical collection interval to complete, logon to Tivoli Enterprise Portal andnavigate to the Ensembles Summary Workspace by clicking zEnterprise Agent–>Ensembles in theNavigator pane.

12. Locate the Ensembles Summary table view in the middle of the workspace.

Chapter 8. Verifying components after configuration 137

13. Broaden the time range of the data being displayed beyond the current data samplings. You canhave the Tivoli Enterprise Portal log data samplings into history files or a database for display in atable or chart. These historical data enabled views have a tool for setting a range of previous datasamples to be reported. Follow this procedure to broaden the time range:a. Click Time Span in the view's toolbar.b. Select a time frame: Last _ Hours (or Days, Weeks, or Months, if the data is warehoused), or

Custom.c. Click OK. After this operation is complete, the Ensembles Summary view shows data from the

time span you specified. If the view is a table, a timestamp is displayed as the first column and isaccurate to the nearest minute; seconds are displayed as 00.

What to do next

Once you have enabled historical collection at Tivoli Enterprise Portal, verify that historical collection hasbeen enabled using the command line interface for the Enterprise Common Collector. On the systemwhere the collector is running, log into the eccAdmin facility (see “Logging on to the Enterprise CommonCollector by using the command-line interface” on page 70). If historical collection has been enabled, thevalue for the long-term-collection-enabled parameter under collection-profiles should be true. To see ifthis is true, enter the command that follows:collection-profiles list

The command returns output similar to the following, and the long-term-collection-enabled valueshould be true.eccAdmin==>collection-profiles listname: defaultshort-term-interval: 60inventory-resync-interval: 28800long-term-collection-enabled: truelong-term-interval: 900description: default collection profilepath-accessible-collection-enabled: true

For more information about the collection-profiles list command, see “Setting up the collectionprofile by using the command-line” on page 78.

Testing the Enterprise Common Collector connection to the HMCsFollow this procedure to verify the connection between the Enterprise Common Collector and the Systemz Hardware Management Console

Procedure1. Determine and record the fully qualified host names of systems where the System z Hardware

Management Console whose connections to the Enterprise Common Collector you want to test.2. Open a browser on the system where the Enterprise Common Collector is running. The web browser

must be able to display JSON content (for example, Mozilla Firefox and certain configurations ofMicrosoft Internet Explorer).

3. Enter this URL:https://hostname_HMC:6794/api/version

where hostname_HMC is the fully qualified host hame of the HMC you are testing. If this is the firsttime you have used this browser to connect this HMC, you will probably need accept (temporarily)this HMC's certificate.


Results

If the connection between the HMC and the collector is available, you should see a return similar to this:{"api-major-version": api_version, "hmc-version": hmc_version, "hmc-name": hmc_name,

"api-minor-version": api_minor_version}

Where:

api_versionIs the version of the HMC API code (for example, 1.2).

hmc_versionIs the version of the software that the HMC is running (for example, 2.11.1).

hmc_nameIs the name of the HMC.

api_minor_versionIs the release level of the API version of the HMC (for example, 2).

Here is sample output from this command:{"api-major-version":1,"hmc-version":"2.11.1","hmc-name":"HMC510","api-minor-version":2}

If you do not see this return, the connection is not working. See Chapter 3, “Setting up the System zHardware Management Console for use with the Enterprise Common Collector,” on page 21 forinformation about setting up the HMC.

Importing the generated Enterprise Common Collector certificate intothe monitoring agent's truststoreDuring installation of the Enterprise Common Collector, you were prompted to enter the informationrequired for the collector to generate the custom key pair that enables a self-signed certificate to becreated that ensures secure communication between the collector and its clients.

About this task

During this process, you were asked to provide the short name of your organization and the key alias tobe used when accessing the key pair in the Enterprise Common Collector keystore. If you provided thisinformation, you received confirmation that your key pair had been generated successfully, and you weretold the location to which the certificate has been exported.

Platform Location

Linux or UNIX <install_dir>/certificates/IBMalias.cert

Windows <install_dir>\certificates\IBMalias.cert

Import the certificate generated by this process into the monitoring agent keystore. Follow this procedureto accomplish this task.

Procedure1. On the system where the Tivoli zEnterprise monitoring agent was installed, follow these

platform-specific instructions to import the generated certificate.


Platform Procedure

Linux or UNIX 1. Change directories to the <itm_install_dir>/<arch>/ze/bin directory (/opt/IBM/itm is thedefault <itm_install_dir> directory on UNIX or Linux).

2. Copy the certificate generated by the Enterprise Common Collector from the virtual serverwhere the collector is installed to the current directory.

3. Issue the import command to import the certificate:

<itm_install_dir>/JRE/<arch>/bin/keytool -import -alias <agent_alias>-file <ecc_certificate_file>.cert -keystore ze_agent_truststore

where:

itm_install_dirIs the IBM Tivoli Monitoring installation directory. For example, /opt/IBM/itm is theUNIX or Linux default.

arch Is the architecture subdirectory for one of the architectures supported by IBM TivoliMonitoring.

agent_aliasIs the key alias that is used when accessing this key pair in the Tivoli zEnterprisemonitoring agent trusts. You can choose this alias name, but it is a best practice touse the hostname of the system on which the Enterprise Common Collector isrunning because this is the system for which you are importing the certificate.

ecc_certificate_fileIs the name of the file that contains the Enterprise Common Collector's certificate.See Step 12 on page 44 under “Installing the Enterprise Common Collector from theconsole” on page 41.

4. When prompted, enter the password for the Tivoli zEnterprise monitoring agent truststore.The default password is z1manager. If you have changed from the default shipped password,enter the password you selected.

Windows 1. Change directories to the <itm_install_dir>\TMAITM6 directory (C:\IBM\ITM is the default<itm_install_dir> directory for Windows).

2. . Copy the certificate generated by the Enterprise Common Collector from the virtual serverwhere the collector is installed to the current directory.

3. Issue this command:

<itm_install_dir>\java\java60\jre\bin\keytool -import-alias <agent_alias> -file<ecc_certificate_file>.cert -keystore ze_agent_truststore

where:

itm_install_dirIs the IBM Tivoli Monitoring installation directory. For example, C:\IBM\ITM is theWindows default.

agent_aliasIs the key alias that is used when accessing this key pair in the Tivoli zEnterprisemonitoring agent truststore.

ecc_certificate_fileIs the name of the file that contains the Enterprise Common Collector's certificate.See Step 9 on page 33 under “Installing the Enterprise Common Collector by usingthe installation wizard” on page 25.

4. When prompted, enter the password for the Tivoli zEnterprise monitoring agent truststore.The default password is z1manager. If you have changed from the default shipped password,enter the password you selected.

The commands return output similar this if responded "yes" when asked if you trusted this certificate:


Owner: CN=<fully_qualifed_hostname>, OU=Unknown, O=organization,L=Unknown, ST=Unknown, C=USIssuer: CN=fully_qualifed_hostname, OU=Unknown, O=organization,L=Unknown, ST=Unknown, C=USSerial number: serial_numberValid from: start_date_time until: end_date_timeCertificate fingerprints:

MD5: C4:4D:B6:12:31:F3:6F:79:95:C3:F2:C9:B0:32:10:62SHA1: E9:5A:15:16:E1:59:79:EB:5C:AD:B3:A2:3A:77:83:F3:B6:79:5A:9A

Trust this certificate? [no]: yesCertificate was added to keystore

2. When the certificate has been imported successfully, after a collection interval has passed, the TivolizEnterprise monitoring agent workspaces on Tivoli Enterprise Portal should display should displaydata. If no data is displayed, refer to the kze_trace.log, found in one of these locations:

Table 15. Location of KZE messages. Location of KZE messages

Platform Location

Linux or UNIX <install_dir>/logs/kze_trace.log

Windows <install_dir>\tmaitm6\logs\kze_trace.log


Chapter 9. Troubleshooting the Enterprise Common Collector

The Enterprise Common Collector generates log files that contain messages and trace information aboutthe events and processing being performed.

Product log files provide a complete record of system activity, not just of problems. The log files arecreated when you start the product components. These files are available to help you resolve problemsencountered while using the products.

IBM Software Support might request some or all of these files while investigating a problem you havereported. When you encounter a problem, first check the messages in the log files to determine if thesource is a problem in your environment or with the Tivoli zEnterprise monitoring agent. If youdetermine that the problem is caused by this monitoring agent, see the agent troubleshooting chapter inthe IBM Tivoli zEnterprise Monitoring Agent User’s Guide for information or “Support information” on page261 for how to contact IBM Software Support.

This section provides information about the following topics:v “Message format”v “Runtime logging locations” on page 144v “Log file format” on page 144v “Logging for the command line interface” on page 146v “Logging for the Enterprise Common Collector service” on page 145v “Collecting the logs that IBM Software Support needs to troubleshoot collector problems” on page 146

Message format

Enterprise Common Collector messages begin with the prefix CTGEZ and have the following format:

Message ID and textExplanationOperator or Programmer Response

The message ID has the following format:CTGEZ#####S

where:

CTGEZIs the prefix that indicates the Enterprise Common Collector.

##### Is the number of the message

S Is one of three letters indicating the severity of the message.

I Informational messages provide feedback about something that happened in the productor system that might be important. These messages can provide guidance when you arerequesting a specific action from the product.

W Warning messages call your attention to an exception condition. The condition might notbe an error but can cause problems if not resolved.

E Error messages indicate that an action cannot be completed because of a user or systemerror. These messages require user response.


The Text of the message provides a general statement regarding the problem or condition that occurred.The Explanation provides additional information about the message and what might have caused thecondition. The Operator or Programmer Response provides actions to take in response to the condition,particularly for error messages (messages with the "E" suffix).

Runtime logging locations

Runtime messages from the Enterprise Common Collector are collected in a log file, located here:


Linux or UNIX <install_dir>/wasce/var/log/EnterpriseCommonCollector.n.log

Where n is one of the log files, a number between 0 and 19.

Windows <install_dir>\wasce\var\log\enterpriseCommonCollector.n.log

Where n is one of the log files, a number between 0 and 19.

The most recent log file is named enterpriseCommonCollector.n.log in the var/log directory. The currentactive log has n value of 0.

When the current active log file reaches 10 MB in size, it is closed, rotated out, and a new file opened.Successively older files are named by incrementing the n value in the filename. A maximum of 20 filesare kept.

If instructed to do so by IBM Software Support, you could configure more detailed logging for one ormore specific components. These logger names correspond to major components of the ECC:



















Log file format

The Enterprise Common Collector log files are in XML format. See the following sample record:


<record><date>2011-12-12T10:14:55</date><millis>1323702895932</millis><sequence>118</sequence><logger>com.ibm.tivoli.gez.utility</logger><level>INFO</level><method>initializeMasterkeyFile</method><thread>7</thread><message>CTGEZ8301I No master key file detected. Created a new key file named C:\Program Files\IBM

\WebSphere\AppServerCommunityEdition\var\ecc\masterkey.bin</message></record>

Where:

date Is the date when the record was created in the format YYYY-MM-DDTHH:MM:SS.

millis Is the date when the record was created in milliseconds since January 1, 1970.

sequenceIs a unique sequence number.

logger Is the name of the Java logger that generated the record. This name is in the form of ahierarchical namespace and corresponds to the Java package of the Java class that was executingwhen the record was created. The name also corresponds to one of logger names in the previous"Logging location" topic except that it will have "com.ibm.tivoli." prepended to it and it may alsohave additional elements appended to the end. This information is important to IBM SoftwareSupport in debugging problems.

level Is a text string indicating the logging level defined for this component. The level must be one ofthe following levels.v OFF: No logging occurs.v SEVERE: Errors that cause premature termination and other unexpected errorsv WARNING: Undesirable or unexpected conditions that are not necessarily wrongv INFO: Interesting runtime eventsv CONFIG: Not supported. If set, shows the same level as INFO.v FINE: Important events and exceptionsv FINER: Detailed debug information, low-level logic, object dumps, and so onv FINEST: Method entry and exit tracingv ALL: Everything; essentially equivalent to FINEST

methodIs the code method that was executing when the record was created. This information isimportant to IBM Software Support in debugging problems.

thread Is the thread that was executing when the record was created. This information in important toIBM Software Support in debugging problems.

messageIs the explanation of this record in the format of a message output to the console. For a completelist of message explanations for the Enterprise Common Collector, see “Enterprise CommonCollector general messages” on page 165.

Logging for the Enterprise Common Collector service

The Enterprise Common Collector runs as a Windows service named eccsrv or as a Linux or UNIXdaemon named eccSvc. After installation, when you start, stop, remove, or query the status of theEnterprise Common Collector, you are actually addressing these commands to the Windows service orLinux or UNIX daemon. The Enterprise Common Collector service is configured to start when the

Chapter 9. Troubleshooting the Enterprise Common Collector 145

operating system is booted and runs in the background as long as the operating system is running. Theservice can also be started and stopped manually when required.

See the IBM Tivoli zEnterprise Monitoring Agent: Installation and Configuration Guide for more informationabout registering the Enterprise Common Collector service as part of the installation of the EnterpriseCommon Collector or about registering it manually after installation. Also see the installation guide forinformation about starting, stopping, or querying the status of the Enterprise Common Collector service,or about listing the Java processes associated with the Enterprise Common Collector or stoppingindividual Java processes.

On Windows , the eccService utility script produces three log files:v eccsrv.log that captures all transactions by the service wrapperv eccsrv.out that captures output that the Java code started by the service wrapper sends to the

standard output streamv eccsrv.err that captures output that the Java code started by the service wrapper sends to the

standard error stream

These logs capture primarily output from WebSphere Application Server Community Edition or ApacheGeronimo, but some output from the Enterprise Common Collector might also be found in these files.They are found in this location:


Linux or UNIX <install_dir>/wasce/var/log/<service_log_files>

Where <service_log_files> includes three files: eccsrv.log, eccsrv.out and eccsrv.err.

Windows <install_dir>\wasce\var\log\<service_log_files>

Where <service_log_files> includes three files: eccsrv.log, eccsrv.out and eccsrv.err.

Logging for the command line interface

The command line interface for the Enterprise Common Collector performs some validation of thecommands (such as command syntax, required parameters, and parameter syntax) before the commandsthat the user has entered are sent to the Enterprise Common Collector.

The command line interface for the Enterprise Common Collector logs messages in this location:


Linux or UNIX <install_dir>/logs/

Where <install_dir> is the directory where you installed the Enterprise Common Collector.

Windows <install_dir>\logs\

Where <install_dir> is the directory where you installed the Enterprise Common Collector.

The Ctgez_Cli.log is used for tracing and debugging errors. The command line interfaces messages arelogged here.

Collecting the logs that IBM Software Support needs to troubleshoot collectorproblems

If you experience a problem with the Enterprise Common Collector that you cannot solve, contact IBMSoftware Support. Before contacting support, run the ecc_collect tool to generate the logs required forservice personnel to diagnose your problem. The ecc_collect tool captures the following:


v Logsv Transaction service results (Results of this query are written to the ECC log)v Thread service results (Results of this query are written to the ECC log)v The collector persistent database (optional)

Note: The database is captured without the security masterkey file. This means that IBM SoftwareSupport is not able to decrypt the passwords that are stored in encrypted format in this database.

Perform the following steps:1. If you want to capture transaction service results, and thread service results, ensure that the

Enterprise Common Collector is started, if it can run. If you do not want to capture these data types,the collector can be offline.

2. Navigate to the collector bin subdirectory:




3. Open a command Window and enter the following an ecc_collect command, using the informationthat follows. To collect everything, enter this command: ecc_collect -a

ecc_collect [Options] [File]

where:

-a All. Collect all available data.

-n No database. Collect all data available excluding the Enterprise Common Collector persistentdatabase.

-o On Demand. Collect data in interactive mode, only on demand.

-h Help. Display help for this command.

-c <https://hostname.port>Custom. Specify an Enterprise Common Collector custom hostname (required for request todump thread- and transaction information into the log). If this parameter is not specified, thedefault value (https://localhost:8443) is used.

This parameter can be combined with the -o parameter.

-f <filename.zip>Is the name of the file used to store the collected information. If this parameter is notprovided, a default filename in the format ecc_collect_<current_timestamp>.zip is createdfor you. This parameter can be combined with the -o parameter.

If you use a custom filename, specify this with the -f (or --file) flag. See the current helpmessage for the ecc_collect tool: Usage: ecc_collect [Run mode] [Options]

4. Send the generated archive file to IBM.

Usage Notes:

v If the ecc collect command is issued without the -f option, , the generated archive file is namedecc_collect_<currrent_timestamp>.zip and is created in the current working directory.

v If the ecc collect command is issued from the bin directory of the Enterprise Common Collectorinstalled environment, the generated archive file is created in the bin subdirectory.

v If the ecc collect command is issued from another folder, the generated archive file is created in thisfolder.


v If the -f option is used used and the filename includes an absolute path, the generated archive files iscreated in the subdirectory specified by this path. For example, if you issued this command in a Linuxenvironment:ecc_collect.sh -f /tmp/collection_today.zip

The generated archive filed is named collection_today.zip and created in the /tmp/ subdirectory,independent of the current working directory.

Problems and workaroundsThe known problems and workarounds for the Enterprise Common Collector are organized into types ofproblems that might occur, such as configuration problems and connectivity problems.

Use the information in the sections that follow to understand problems with the Enterprise CommonCollector.

No zEnterprise data or incorrect data is found in Tivoli EnterprisePortalA number of configuration errors can result in zEnterprise data missing from Tivoli Enterprise Portalworkspaces.

Configuration between the Tivoli zEnterprise Monitoring agent and the Enterprise Common Collector is ahandshake process. That is, when you configure the monitoring agent, you are presented with panelswhere you define the logon and security characteristics of the system where the Enterprise CommonCollector is running.

The following scenarios are covered in this section:v “Data displayed in the zEnterprise workspaces is all zeros or character strings are displayed as

unknown.”v “Enterprise Common Collector user ID is unknown” on page 149v “Enterprise Common Collector user role attempting log in has insufficient authority” on page 150v “Incorrect hostname or port” on page 151v “Data source disabled unexpectedly” on page 153

Data displayed in the zEnterprise workspaces is all zeros or character strings aredisplayed as unknown.When you start Tivoli Enterprise Portal, the Tivoli zEnterprise monitoring agent shows data in theworkspaces, but all of the data is either zeros (for numerical data) or "unknown" (for character strings).

Explanation

When the Enterprise Common Collector starts collecting data from the System z Hardware ManagementConsole (HMC), a minimum of two sampling intervals must elapse for calculations to be performed.

Workaround

The HMC may need additional time to return inventory and monitoring data. The volume of the data isbased on the number of objects defined in the HMC (for example, the number of virtual servers). Allowmore time for data collection to complete.

If the problem persists after enough time has passed for data collection to complete, verify that a filterparameter specified in the predicate of a custom query has not eliminated all the rows from the result set.For more information about using the query editor, refer to the IBM Tivoli Monitoring: Administrator’sGuide.


Enterprise Common Collector user ID is unknownNo data is displayed in Tivoli Enterprise Portal because the user ID trying to log in to the EnterpriseCommon Collector in unknown.

Observations

There are a number of ways in which the Tivoli Enterprise Portal user can fail to be authenticated by theEnterprise Common Collector. In all cases, this HTTP error is returned:HTTP Status 403, Access to the specified resource () has been forbidden.

If you opened the Tivoli Enterprise Portal trace log, you would see this message:KZE0003E No data returned by the ECC. An authorization problem exists.

If you opened the ECC log, you would see one of the more specific messages explained in the sectionthat follows.

Explanation

The Enterprise Common Collector user ID configured for the monitoring agent (during both themonitoring agent configuration or the collector configuration) is incorrect, or the user ID has not beendefined to the collector.

A user ID for a user who will access Tivoli Enterprise Portal must be created by an IBM TivoliMonitoring administrator. That user ID must have authority to view information in Tivoli EnterprisePortal. That same user ID must be created and given the correct level of authority (Explorer authority ismost likely for an operator) using the Enterprise Common Collector clients create command lineinterface. The user ID (or client ID in the Enterprise Common Collector) and password in bothenvironments must be the same.

If you find the KZE0003E error message, open the ECC log because more granular information might befound there. Here are some examples:v If the Tivoli Enterprise Portal user ID attempting to log on has not been created in the Enterprise

Common Collector,CTGEZ0704E Authentication failed due to too many invalid logon attempts by user ID {0}.

v If the failure occurred because of too many invalid logon attempts, this message would be displayed:CTGEZ0704E Authentication failed due to too many invalid logon attempts

v If the failure occurred because the user ID was correct but the password was incorrect, expired, orreused, one of these messages would be displayed:CTGEZ0702E Authentication failed due to invalid password for user ID user_id.orCTGEZ0705E Authentication failed due expired password for user ID user_id.

Workaround

To correct this problem, verify the following:v If the problem is with the Enterprise Common Collector configuration:

– If the user ID specified in the message is not defined, configure a user ID in the monitoring agentconfiguration that is defined to the Enterprise Common Collector, or use the command line interfaceto define a new user. See “Creating, listing, updating, and deleting clients by using thecommand-line” on page 75 for more information.

– If the multiple attempts to logon using an invalid password have resulted in the user ID beinglocked, use the Enterprise Common Collector configuration API to resume this user ID. For example,if user ID andy is blocked, use this command:POST eccapi/admin/client/{andy}/resume


v If you confirm that the Enterprise Common Collector user ID and password is correct, the problemmight be with the Tivoli zEnterprise monitoring agent configuration. Right-click on the Agent on theManaged Tivoli Monitoring Services and select Reconfigure. Correct the problem with the User ID andpassword. For more details about reconfiguring a monitoring agent see “Incorrect hostname or port”on page 151 or the IBM Tivoli Monitoring: Installation and Setup Guide.

v If both of these components are configured correctly, confirm that you have defined the correct user IDand password for accessing the System z Hardware Management Console. See “Defining a user” onpage 21.

v If the password is expired for the user ID specified in the message use the command line interface tochange the password. See “Creating, listing, updating, and deleting clients by using the command-line”on page 75 for more information.

Enterprise Common Collector user role attempting log in has insufficient authorityNo data is displayed in Tivoli Enterprise Portal because the Enterprise Common Collector user ID used toaccess Tivoli Enterprise Portal has insufficient authority.

Observations

You might observe one or all of these situations:v If you opened the Enterprise Common Collector message log:


Linux or UNIX <install_dir>/wasce/var/log/enterpriseCommonCollector.n.log

Where n is a number between 0 and 19.



You would see this message:CTGEZ0301W The client <client_name> is not assigned to a role that is authorized to accessthe resource <resource_name>.

See “CTGEZ0301W” on page 166 for more information.v If you opened the monitoring agent trace message log:

Table 16. Location of KZE messages

Platform Location

Window <itm_install_dir>\tmaitm6\logs\kze_trace.log

Linux or UNIX <itm_install_dir>/logs/kze_trace.log

You would see this message:KZE0003E No data returned by the ECC. An authorization problem exists.

Explanation

A client ID is defined, but does not have the correct role setting to retrieve the desired data.

Every client that accesses the Enterprise Common Collector needs a user ID and pasword, and this userID must be associated with a specific role or roles. This role information tells the collector which URLsthis account can access. Three roles are defined. All Enterprise Common Collector clients must be amember of one or more of the these roles:v Administrator role that can perform administrative tasks, such as creating data sources or clientsv Explorer role that can perform discovery tasks, such as discovering all virtual servers


v Operator role that can perform monitoring and discovery tasks, such at retrieving detailed informationabout virtual servers and their performance metrics

The user ID used for communication between the Enterprise Common Collector and the TivolizEnterprise monitoring agent must be assigned to the Operator role.

Workaround

To correct this problem, use the monitoring agent reconfigure utility or the Enterprise Common Collectorcommand line interface to change the defined role of the user, or define a new user with the Explorer orOperator role. A user must be assigned the Operator role to retrieve metrics for the agent, or the Explorerrole to retrieve inventory data for discovery.v To correct the problem by changing the Enterprise Common Collector configuration, see “Creating,

listing, updating, and deleting clients by using the command-line” on page 75.v To correct the problem by updating the monitoring agent configuration, you can right-click on the

agent in the Managed Tivoli Monitoring Services window and select Reconfigure. See the “Incorrecthostname or port” scenario or the IBM Tivoli Monitoring: Installation and Setup Guide for moreinformation.

Incorrect hostname or portAfter a seemingly normal installation of the monitoring agent and the Enterprise Common Collection, nodata is displayed when the Tivoli Enterprise Portal is started.

Observations

If you go to the <itm_install_dir>\tmaitm6\logs directory on the computer where the monitoring agent isinstalled and open the log that begins _ze, you find messages similar to these, indicating that theattribute groups required to start the monitoring agent are not available:(4F042D98.0000-8:customproviderserver.cpp,666,"startProviderMonitoringThread")

The data provider process pid[15655] "ze_agent.sh" exited with return code 1(4F04475B.0000-1:cps_socket.cpp,2233,"sendStartReqInfo")

Requested attribute group ’Ensemble’ does not exist(4F04475B.0001-9:cps_socket.cpp,1389,"collectData")

Requested attribute group ’Ensemble’ does not exist(4F04475B.0002-1:cps_socket.cpp,2233,"sendStartReqInfo")

Requested attribute group ’Central_Processor_Complex’ does not exist(4F04475B.0003-9:cps_socket.cpp,2309,"sendStopReqInfo")

Requested attribute group ’Ensemble’ does not exist(4F04475B.0004-9:cps_socket.cpp,2309,"sendStopReqInfo")

Requested attribute group ’Ensemble’ does not exist(4F04475B.0005-9:cps_socket.cpp,1389,"collectData")



Requested attribute group ’Central_Processor_Complex’ does not exist(4F04475B.0008-1:cps_socket.cpp,2233,"sendStartReqInfo")

Requested attribute group ’BladeCenter_Extension’ does not exist(4F04475B.0009-9:cps_socket.cpp,1389,"collectData")

Requested attribute group ’BladeCenter_Extension’ does not exist(4F04475B.000A-9:cps_socket.cpp,2309,"sendStopReqInfo")

Requested attribute group ’BladeCenter_Extension’ does not exist(4F04475B.000B-9:cps_socket.cpp,2309,"sendStopReqInfo")

Requested attribute group ’BladeCenter_Extension’ does not exist(4F04475C.0000-9:cps_socket.cpp,1389,"collectData")

Requested attribute group ’Topology’ does not exist(4F044762.0000-A:cps_socket.cpp,2233,"sendStartReqInfo")

Requested attribute group ’Ensemble’ does not exist(4F044762.0001-1:cps_socket.cpp,2233,"sendStartReqInfo")

Requested attribute group ’Workload_Resource_Group’ does not exist(4F044762.0002-9:cps_socket.cpp,1389,"collectData")


Requested attribute group ’Ensemble’ does not exist(4F044762.0003-9:cps_socket.cpp,2309,"sendStopReqInfo")

Requested attribute group ’Ensemble’ does not exist(4F044762.0004-9:cps_socket.cpp,2309,"sendStopReqInfo")

Requested attribute group ’Ensemble’ does not exist(4F044762.0005-9:cps_socket.cpp,1389,"collectData")

Requested attribute group ’Workload_Resource_Group’ does not exist(4F044762.0006-9:cps_socket.cpp,2309,"sendStopReqInfo")


Requested attribute group ’Workload_Resource_Group’ does not exist(4F044763.0000-A:cps_socket.cpp,2233,"sendStartReqInfo")

Requested attribute group ’Workload_Resource_Group’ does not exist(4F044763.0001-9:cps_socket.cpp,1389,"collectData")



Requested attribute group ’Workload_Resource_Group’ does not exist

Explanation

A number of situations can cause this problem. One of the most common causes of this error is that thehostname and port of the computer where the Enterprise Common Collector is running are not correctlydefined to the monitoring agent.

This situation results from incorrect hostname or port information regardless of installation method(installation wizard, console, or silent).

Workaround

To correct this problem, you must reconfigure the Tivoli zEnterprise monitoring agent. Do the following:1. Right-click the agent in the Manage Tivoli Enterprise Monitoring Services and select Reconfigure.

2. Accept the values already shown in the installation wizard until you reach the Configuration for theEnterprise Common Collector window where you defined the hostname and port for the computerwhere the Enterprise Common Collector is running.

Figure 31. Manage Tivoli Enterprise Monitoring Services screen


Ensure that you provide valid values for the following fields:

Enterprise Common Collector HostnameThe fully qualified hostname of the computer where the Enterprise Common Collector isrunning. The default is localhost.

If the Enterprise Common Collector and the zEnterprise agent reside on the same system,then the default localhost is sufficient and does not need to be changed. If the EnterpriseCommon Collector resides on different computer, then localhost needs to be replaced with afully qualified hostname, such as test1.somelab.raleigh.ibm.com.

Enterprise Common Collector PortThe port number of the secure port that the zEnterprise monitoring agent uses tocommunicate with the Enterprise Common Collector. The default is 8443.

3. If you still do not see data, stop and restart Tivoli Enterprise Portal.

Data source disabled unexpectedlyThe Enterprise Common Collector no longer has a session with the data source, and inventory andmetrics data are no longer being collected.

Observations

The Interval End Time attribute in a number of Tivoli Enterprise Portal workspaces displays NOTCOLLECTED instead of the expected interval date and time information. The data source configuration

Figure 32. Monitoring Agent for Tivoli Enterprise Monitoring Agent: Configuration of the Enterprise Common Collectorscreen


indicates that the status is disconnected, and the enabled parameter is set to false, even though noadministrator set enabled to false.

Explanation

One of the components that performs some aspect of the data source monitoring encountered anunexpected error. In response to this situation, the collector stopped all components associated with themonitoring of this data source and ended the session with the data source.

If the unexpected error is related to a connection or session problem, or some other potentially temporaryproblem, a new session is automatically established and monitoring is resumed. But if collector does notrecognize the error and cannot recover automatically, the data source was disabled. This action keeps thecollector from generating the same error over and over each time a new session is established, thuspreventing thrashing.

Operator response

Review the Enterprise Common Collector logs to determine what error caused the data source to bedisabled.






Look for an INFO record associated with message “CTGEZ6012I” on page 176 (The data source named<data source> has been disabled). This message should be preceded closely (within a few seconds) byan INFO record with message “CTGEZ6006I” on page 176 (The API session with the data sourcenamed data source has been closed). Prior to these messsage, you should see one of the following,depending on which component encountered the error:v CTGEZ6022E: Inventory gatherer component has failed for the data source named

<data-source-name>

v CTGEZ6032E: Notification handling has failed for the data source named <data-source-name>

v CTGEZ6042E: Metrics gathering has failed for the data source named <data-source-name>

Before this message in your logs, you should find one or more exception records describing the problem.

Reenable the data source using the data-sources update command (see “Setting up HMC data sourcesby using the command-line” on page 83). If the problem occurs again, search IBM support for a atechnote regarding the problem. If nothing is available, contact IBM Software Support.

Enterprise Common Collector fails to initializeThe troubleshooting scenarios in this section concern issues that can cause the Enterprise CommonCollector to fail to initialize.

The following scenarios are covered in this section:v “Data source cannot be reached” on page 155v “Data source user authentication failed” on page 156v “Enterprise Common Collector does not start because web server container Apache Geronimo must be

running as Administrator on Windows 7” on page 157v “Enterprise Common Collector fails to initialize because of port conflict” on page 158v “HMC operation results in HTTP status code 403 and reason code 1” on page 159


v “Path accessibility information for a virtualization host could not be retrieved” on page 160

Data source cannot be reachedThe Enterprise Common Collector is unable to establish an API session with a specific data sourcebecause the data source failed to respond to a logon request.

Observations

If you open the Enterprise Common Collector log file:






The following message can be found multiple times (once for each attempt to connect):CTGEZ6002W An attempt to establish an API session with the data source named {0} failed.The data source cannot be reached.

See “CTGEZ6002W” on page 175 for more information.

Explanation

The most likely cause of this error is that no HTTPS connection was established with the data source. It ispossible the data source could not be reached.

To determine if this is the problem, look for exceptions that should appear in the collector log file justbefore the message cited earlier. Examine this exception to determine the nature of the problem. It isdifficult to anticipate every exception that might occur but here are a few of the most common:

Table 17. Common Java exceptions

Exception Meaning

java.net.ConnectException Indicates that the data source could not be reached at all.

Verify that the hmc-hostname is correct in the data sourceconfiguration and update it if necessary. See “Setting up HMCdata sources by using the command-line” on page 83 forinformation about how to do this.

Also verify that no network or firewall issues are preventing thecollector from connecting to the data source. Verify that the datasource is operational and accepting requests.


Table 17. Common Java exceptions (continued)

Exception Meaning

javax.net.ssl.SSLHandshakeException Indicates that the data source could be reached but the collectorand data source could not negotiate the desired level of security.

The most likely cause of this exception is that the data source'scertificate cannot be validated. Verify that the correct certificatehas been imported into the collector truststore and import thecertificate if necessary.

An alternative is to configure the Enterprise Common Collectorto trust all certificates. This setting is not recommended longterm but may be useful to assist in resolving the connectionproblem.

See “Managing certificates by using the command-line” on page73 for information about how to view and import certificatesand how to change the trust-all setting.

Note that the collector will attempt to connect to the HMC for about twelve hours. Once about twelvehours have elapsed the following message will appear in the collector log:CTGEZ6005E {n} attempts to establish an API session with the data source named {data-source_name}have failed. No more attempts will be made.

See “CTGEZ6005E” on page 176 for details.

The following message will then also be logged, indicating that the data source has been disabled:CTGEZ6012I The data source named <data-source-name> has been disabled.

See “CTGEZ6021I” on page 176 for details.

Workaround

Diagnose and correct the problem with the data source.

If the twelve hours have not yet elapsed, the collector will make another attempt to connect to the HMCwithin fifteen minutes. If the twelve hours have elapsed and the data source in the Enterprise CommonCollector has been disabled the data source must be re-enabled (using the data-sources update -n<data-source-name -e true) before any further attempts are made to connect to the data source. See“Setting up HMC data sources by using the command-line” on page 83 for more information.

Data source user authentication failedThe Enterprise Common Collector is unable to establish an API session with a specific data sourcebecause authentication failed.

Observations

If you open the Enterprise Common Connector message log:







You see these messages:CTGEZ6001E User authentication with the data source named <data_source_name> failed.

Later in the log you will also find this message indicating that the data source has been disabled.CTGEZ6012I The data source named <data_source_name> has been disabled.

Explanation

The user ID or password configured for this data source are incorrect. The data source has been disabled.

Workaround

Update the data source in the Enterprise Common Collector configuration to use the correct name andpassword at the Enterprise Common Collector and at the HMC.

After the problem has been found and addressed, the data source in the collector configuration must bere-enabled (using the data-sources update -n <data-source-name> -e true) before any further attemptsare made to connect to the data source. See “Setting up HMC data sources by using the command-line”on page 83 for more information.

It is possible that the problem is with the HMC configuration. The HMC user ID that the EnterpriseCommon Collector uses to communicate with the HMC must have, at a minimum, these ManagedResource Roles defined:v BladeCenter Objectsv DPXI50z Blade Objectsv Defined zCPC Managed Objectsv Ensemble Object Groups created by SYSPROGv IBM Blade Objectsv IBM Blade Virtual Server Objectsv ISAOPT Blade Objectsv Storage Resource Objectsv Virtual Network Objectsv Workload Objectsv z/VM Virtual Machine Objects

And these reporting roles:v Metrics Servicev Get Virtualization Host Storage Resource Detailsv Generate Workload Resource Groups Reportv Generate Service Classes Report

See also “Security between the collector and the HMC” on page 11.

Enterprise Common Collector does not start because web server containerApache Geronimo must be running as Administrator on Windows 7When the web server container that runs the Enterprise Common Collector is hosted on a Windows 7platform, the collector fails to start.


Observations

If you open the Enterprise Common Connector message log:






You see these errors:v Error reading configuration: <install_dir>\wasce\var\cache\org.eclipse.osgi\.manager\.file TableLock

(Access is denied.)v java.io.FileNotFoundException: <install_dir>\wasce\var\cache\org.eclipse.osgi\.manager\.file

TableLock (Access is denied.)

Explanation

The web server container Apache Geronimo must be running with Administrator authority on Windows7.

Workaround

When starting Geronimo, specify Run as Administrator. If starting Geronimo from the command prompt,start it as Administrator.

Enterprise Common Collector fails to initialize because of port conflictAfter installation, the Enterprise Common Collector fails to initialize.

Observations

If you check the directory where the product is installed, you find that it is indeed installed. If you checkthe installation log, you find a successful installation message.

Explanation

One of the most common causes of this failure is port conflict. One of the ports you specified when youinstalled the Enterprise Common Collector is already in use by another application.

Workaround

Do the following to address this problem.1. Open the Enterprise Common Collector server.log file:


Linux or UNIX <install_dir>/wasce/var/log/server.log

Windows <install_dir>\wasce\var\log\server.log

2. Search for the section of that log file that begins with ERROR.2012-01-09 10:51:49,564 ERROR [GBeanInstanceState] Error while starting;GBean is now in the FAILED state: abstractName="org.apache.geronimo.configs/j2ee-corba-yoko/3.0-w20110721/car?ServiceModule=org.apache.geronimo.configs


/j2ee-corba-yoko/3.0-w20110721/car,j2eeType=CORBANameService,name=NameServer"

org.apache.geronimo.corba.security.config.ConfigException:Error starting transient name service on port 1050

Search for the section that log file that begins ERROR.3. To correct this error, edit the config-substitutions.properties file found in one of these locations:

Platform File location

Linux or UNIX <install_dir>/wasce/var/config

Windows <install_dir>\wasce\var\config

Assign an unused port number to the port shown in the error message (in this instance,COSNamingPort).

4. Restart the IBM Enterprise Common Collector Service, using one of these commands:

Platform File location

Linux or UNIX cd <install_dir>/bin./eccService.sh start

Windows 1. Access the Windows location for starting the Enterprise Common Collector service: Start ->Control Panel -> Administrative Tools -> Services.

2. Scroll down to IBM Enterprise Common Collector Service - eccsrv.

3. Right-click on it and select Start.

HMC operation results in HTTP status code 403 and reason code 1A System z Hardware Management Console (HMC) operation invoked by the Enterprise CommonCollector fails validation and results in HTTP status code 403 and reason code 1.

Observations

If you open the Enterprise Common Collector message log:






The following exception can be found:com.ibm.tivoli.gez.zhmc.restapi.HmcRestClientException: HTTP status: 403;reason: 1; message: The API user does not have action/task permission tothe <action/task>

Where <action/task is the action or task that the HMC user does not have permission to execute.

Explanation

The HMC user under which the API request was authenticated does not have the required authority toperform the requested action.

Additional messages before or after this exception should indicate what actions were taken as result ofthis exception. These actions differ depending on the context in which this operation was invoked. It ispossible that the API session with the HMC has been closed and the data source disabled. Or, if the error


was not considered severe, a log message will indicate what information could not be retrieved from theHMC and processing will continue (although whatever inventory or monitoring would have beenretrieved through this operation will be missing from the Enterprise Common Collector).

Workaround

Update the access control configuration on the HMC for this user to include permission for the specifiedaction/task. See “Defining a user” on page 21 for information about defining HMC users with thenecessary permissions.

If the data source was disabled as a result of this error, you will find this message in the log:CTGEZ6012I The data source named <data-source-name> has been disabled.

See “CTGEZ6012I” on page 176 for more info.

Update the data source configuration in the Enterprise Common Collector to enable the data source. Seeinformation about the update command in the “Setting up HMC data sources by using thecommand-line” on page 83 topic. This action causes the collector to establish a new API session with theHMC.

Path accessibility information for a virtualization host could not be retrievedYou find message CTGEZ5502E: Path accessibility information for the virtualization host withobject-id <object_id> could not be retrieved from the data source with name <name>. The requestsent to the data source timed out. in the Enterprise Common Collector logs.

Observations

The collector logs are filled with log records similar to the example that follows, indicating that pathaccessibility for a virtualization host could not be retrieved and with exceptions related to thePathForVirtualizationHostStorageResourcesProcessing class. If you are connecting to a data source forthe first time, you find that it is taking an abnormally long time for metrics collection to begin.

Explanation

The Enterprise Common Collector gathers information about storage resources from the HardwareManagement Console (HMC), including whether the storage resource is accessible on certain paths ornot.

When the HMC attempts to verify path information for paths that are not accessible the response maytake considerably longer. After six minutes of waiting for a response from the HMC, the EnterpriseCommon Collector times out, resulting in log entries as described in Observations. If you are collectingthe inventory information from an HMC for the first time, metrics collection is not started until the initialcollection of inventory information is completed. If the collection profile specifies that path accessibilityinformation should be collected, this operation is performed as part of the collection of inventoryinformation. Metrics collection cannot begin until the collection of path accessibility information iscomplete.

Workaround

If you do not need to know which paths’ storage resources are accessible, collection of this informationcan be disabled in the collection profile by setting path-accessible-collection-enabled to false. See“Setting up the collection profile by using the command-line” on page 78 for more information aboutsetting the path-accessible-collection-enabled parameter.


Known problems and workaroundsSome problems are currently known but cannot be resolved at this time.

Table 18. Enterprise Common Collector known problems

Problem Solution or explanation

When you install the Enterprise Common Collector,the expected behavior is that the uninstallationprocess uses the same uninstallation type as theinstall process. For example, if you installed using asilent install, starting the uninstall program launchesthe silent version of the uninstall. In some instances,on Windows, even if you installed using theinstallation wizard, the uninstall will use the silentinstallation instead of the installation program.

The uninstall process still occurs, even if the method was notwhat you expected. No further action is required.

When running the Enterprise Common Collectorinstallation program in console mode or when usingthe Enterprise Common Collector administrativeclient in a non-English language environment onMicrosoft Windows, non-English characters mayappear corrupted.

To correct this problem, the Microsoft Windows commandwindow needs to be configured to use an appropriateTrueType font in place of the default raster font. Instructionsfor how to perform this configuration, as well as fontspecifications, can be found in Microsoft Knowledge BaseArticle KB247815 (see http://support.microsoft.com/kb/247815).

Perform the following steps to correct the problem:

1. Read Microsoft Knowledge Base Article KB247815 toobtain required information about TrueType fonts thatcan be used in a Windows command window. Eventhough this article was written for Windows 2000, it stillapplies to currently supported versions of MicrosoftWindows.

2. If a suitable TrueType font is not already installed onyour computer, obtain one that matches the criteriadescribed in Microsoft Knowledge Base Article KB247815.Install the font following the instructions provided withyour Windows operating system.

3. Follow the instructions in Microsoft Knowledge BaseArticle KB247815 to install and register the TrueType fontfor use in command windows.

4. Restart your computer.

5. Open a command window and select the Propertiesoption from the window's control menu.

6. Click on the Font tab of the Properties window and selectthe font you installed from the Font list.

7. In the Size list, select a suitable font size.

8. Click on OK to apply the changes.

If the Enterprise Common Collector is run in anon-English locale on Windows, a few EnterpriseCommon Collector messages with corruptedcharacters may be found in the eccsrv.err log file.

The same messages are correctly logged in theenterpriseCommonCollector.n.log file, where n is a numberbetween 1 and 20 for the product log. . . If you see corruptedcharacters in the eccsrv.err log, look for the same message ina correct format in the enterpriseCommonCollector.n.log file.Use the dates to correlate values between logs


Table 18. Enterprise Common Collector known problems (continued)

Problem Solution or explanation

Corrupted strings found in the Enterprise CommonCollector log.

Ensure that you operate all collector components with thesame locale settings

The collector requires that all its components (server as wellas administrative console) operate with the same localesettings. When using the Enterprise Common Collectoradministrative console, make sure to run it in the same localeas the Enterprise Common Collector service.

On UNIX and Linux, the Enterprise Common Collectorservice is run under the root account. The collector uses thataccount's locale settings at system startup.

On Windows, the Enterprise Common Collector service isrun under the Local System account. The collector uses thataccount's locale settings at the time the service is created;service creation typically takes place when the EnterpriseCommon Collector is installed.

Enterprise Common Collector componentsThe Enterprise Common Collector includes these components, all of which generate messages.

Messages reference these components, so a basic understanding of what the component is and whatfunction it performs might help you diagnose problems. Set message ranges are assigned on aper-component basis, another characteristic that might be useful during troubleshooting. These ranges aresummarized in “Message ranges” on page 164.v Notification Handler

The notification handler subscribes to the HMC to receive notification messages that indicate a changein configuration status.The Enterprise Common Collector processes the following three HMC notification types:– Status change notification: Sent if a change to the status property of a managed object has appeared.

The notification contains the old and new status of the managed object, and states whether the newstatus is an unacceptable status.

– Property change notification: Sent if changes to one or more properties of an object has appeared.The notification contains the name of the changed properties and their old and new values.

– Inventory Change Notification: Sent if a managed object was added or removed to or from thecurrent inventory.

Messages in the range of 6500 - 6799 are from the notification handler.v Inventory Gatherer

The inventory gatherer component queries the HMC for information about zEnterprise resources andreturns that information to the Enterprise Common Collector. This component is activated when thecollector is started or the resync interval has elapsed. The first inventory discovery process mightrequire some time to complete, since the initial inventory database must be built. Subsequentdiscoveries are typically infrequent (three times per day, for example). This inventory data is recordedwith the collector persistence manager component.The inventory gatherer is responsible for collecting all the inventory data from an HMC, transformingit into the Enterprise Common Collector internal data model, and storing it in the persistence managercomponent. The inventory gatherer is controlled by the HMC session manager, because an opened andactive HMC API Session is required for fetching the inventory data from an HMC.


The inventory gatherer is used to discover an HMC’s inventory data if none of this data is alreadyavailable in the persistence manager component or when the Enterprise Common Collector determinesthat the inventory data in the persistence manager from an HMC is outdated and a complete refresh isrequired.Messages in the range of 5200 - 5699 are from the inventory gatherer.

v Metrics Gatherer

The metrics gatherer component is activated when the monitoring sample interval has elapsed. Metricsare typically refreshed frequently (once per minute, for example). The context engine component limitsdata retrieval based on parameters configured by the administrator. Metrics are recorded by the datacache manager component.The metrics gatherer is responsible for collecting all the metrics data from an HMC, transforming thisdata into the Enterprise Common Collector internal objects and storing it using the data cachemanager.The metrics gatherer is controlled by the HMC session manager and requires an open and active ReSTAPI session so that it can retrieve the metrics data from the HMC. Two sessions are opened thatrepresent different collection intervals for metrics data: a short interval (usually 1 minute) and anoptional longer interval (usually 15 minutes).Messages in the range of 5000 - 5199 are from the inventory gatherer.

v Persistence Manager

The persistence manager component is responsible for storing data represented by the internal datamodel, managing and providing data that the collector needs to keep persistent across system andcollector restarts, and saving zEnterprise relationships. The persistence manager manages differenttypes of data:– Inventory data: This data is "discovered" from the HMC and kept persistent to avoid a complete

rediscovery of all this data after a restart.– Configuration data: This data includes configuration information about the collector itself, including

the connection data to the HMCs that the collector monitors.Messages in the range of 3000 - 3999 are from the persistence manager.

v Data Cache Manager

The data cache manager component is responsible for caching and providing metrics and report datathat is collected either a normal collection intervals or on-demand. The component caches differenttypes of data:– Metric group samples: This data is made up of samples of metrics that are collected from the HMC

at periodic intervals. Some metrics are captured as total values meaning that the collector calculatesthe deltas between two samples.

– Calculation of derived data: Derived metric values are calculated based on the samples and deltasbetween samples. Necessary data transformations also occur.

– Periodic reports: Reporting information is collected at a configured collection interval from theHMC. These reports do not use total values but instead provide delta values, and therefore, do notneed to be calculated.

Messages in the range of 4000 - 4999 are from the data cache manager.v Admin Manager

The admin manager handles requests for collector configuration changes, including modifying theconfiguration of authentication options, certificates, clients, collection profiles, data sources and loggers.Messages in the range of 1500 - 1799 are from the admin manager.

v HMC Session Manager

The HMC Session Manager establishes and manages the sessions with the configured data sources. Italso starts and manages the inventory gatherer, notification handler and metrics gatherer instances foreach data source.Messages in the range of 6000 - 6199 are from the HMC session manager.


v Client Session Manager

The client session manager component handles the authentication of collector clients (user) usingsession tokens. Before a client can use any of the collector’s APIs, the client must be successfullyauthenticated. If the authentication (based on a user ID and a password) is successful, the clientreceives a session token that is added as an HTTP header field to any request that uses one of thecollector APIs. This session token is valid until one of the following happens:– The client logs off– The client is disconnected due to a time out of the session token– Internal changes (such as administrator changes) take place cause an action such as deletion of the

client account owning the session.The Client Session Manager is responsible for managing the collector’s own session. Every time a clientof the collector (such as a monitoring agent) logs in, this component assigns this client a session-id andmanages these sessionsMessages in the range of 0300 - 0899 are from the Client Session Manager.

v Installation

Messages generated by the Enterprise Common Collector installation process are also found in this log.Messages in the range of 8400 - 8499 are from the Enterprise Common Collector installer.

v Migration, Backup, and Archive Manager

The Migration, Backup, and Archive Manager for the Enterprise Common Collector supports a methodfor manually creating and restoring a backup of the collector and for automatically creating backupsthat can be used to restore if the collector is started with an empty database (for example, afterupgrading to another version).Messages in the range of 8500 - 8699 are from the Enterprise Common Collector Migration, Backup,and Archive Manager.

Message rangesThe Enterprise Common Collector messages are categorized by component. Messages for a givencomponent are found within a defined number range.

The number of the message is therefore useful in troubleshooting because it indicates what componentgenerated the message.

Table 19. Enterprise Common Collector components and message ranges

Component Range

Housekeeping: Internal Utilities, Logging, Tracing 0000 - 0099

Servlet Maintenance 0100 - 0299

Client Session Manager 0300 - 0899

Client Authorization Manager 0900 - 0999

Client Data Provider 1000 - 1499

Client Admin Manager 1500 - 1799

Client RESTApi 1800 - 1899

Future Client-Side Use 1900 - 2999

Persistence Manager 3000 - 3999

Data Cache Manager 4000 - 4999

HMC Metrics Gatherer/Context Engine 5000 - 5199

HMC Inventory Gatherer 5200 - 5699

HMC Report Gatherer 5700 - 5999


Table 19. Enterprise Common Collector components and message ranges (continued)

Component Range

HMC Session Manager 6000 - 6199

HMC Notification Handler 6500 - 6799

HMC Inventory Update 6800 - 6999

HMC RESTApi 7000 - 7299

Future HMC Side Use 7300 - 7999

Threading 8000 - 8299

Internal Enterprise Common Collector Security and Encryption 8300 - 8399

Enterprise Common Collector Installer 8400 - 8499

Enterprise Common Collector Migration/ Backup Manager/ ArchiveManager

8500 - 8699

Unassigned 8700 - 9799

Command Line Interface (CLI) 9800 - 9900

Enterprise Common Collector general messagesEnterprise Common Collector general messages begin with the prefix CTGEZ.

Use the information in this section to understand the messages found in the Enterprise CommonCollector message log.

CTGEZ0000W Unable to create log file. Loggingwill be to console only.

Explanation: An attempt to configure logging to fileor to create the var/log directory failed.

Programmer response: Correct the loggingconfiguration and try the operation again.

CTGEZ0099W The ECC has encountered an errorand is unable to complete the currentrequest.

Explanation: This message is returned when theEnterprise Common Connector (ECC) encounters anerror or an exception from which it cannot recover.

System action: The request that was in process whenthe error or exception occurred is not complete.

User response: Confirm that the syntax of the requestis correct. Attempt to resubmit the request once. If thisproblem persists, contact IBM Software Support.

CTGEZ0100I Working directory set to {0}.

Explanation: The working directory is the location inthe file system that the Enterprise Common Collectoruses to store database files and other dynamic data.

User response: No action is required.

CTGEZ0101I Enterprise Common Collector startedsuccessfully.

Explanation: All components of the EnterpriseCommon Collector were started successfully.


CTGEZ0102E Enterprise Common Collector cannotstart successfully.

Explanation: The Enterprise Common Collector isunable to start all required components successfully.

System action: The Enterprise Common Collector maynot provide all services and may not run as expected.

User response: See the previous log messages fordetails about the error that occurred.

CTGEZ0103I Enterprise Common Collector stoppedsuccessfully.

Explanation: All components of the EnterpriseCommon Collector have been shut down successfully.


CTGEZ0300W Unknown role {0} for client {1}.

Explanation: The role assigned to the named client isnot known by the system. This situation occurs wheninvalid roles are found in the Enterprise Common

CTGEZ0000W • CTGEZ0300W


Collector database. The client is still defined, but therights granted by the denied role may not be available.

System action: The Enterprise Common Collectorignores the unknown role.

User response: Use the configuration API to updatethe client roles.

CTGEZ0301W The client {0} is not assigned to a rolethat is authorized to access the resource{1}.

Explanation: The client is attempting to access aresource that is not authorized for the assigned role.

System action: The request fails.

User response: If you want this client to be able toperform this request, use the CLI or API to add themissing role to this client.

CTGEZ0400W Login module for authentication isunknown; basic authentication is usedinstead.

Explanation: The configured login module, used toauthenticate users when a session is established, isunknown. The Enterprise Common Collector basicauthentication mechanism is used instead. Thismechanism uses the collector database for user accountvalidation and password hashes for passwordprotection.

System action: The Enterprise Common Collectorauthenticates clients using its own database instead ofusing LDAP.

User response: Ensure that the configuration forauthentication is valid.

Programmer response: Determine why an invalidconfiguration is saved in the Enterprise CommonCollector configuration database.

CTGEZ0401I Basic authentication enabled.

Explanation: Authentication of clients whileestablishing a session between the Enterprise CommonCollector and the Hardware Management Console isaccomplished using the collector basic authenticationmechanism. This mechanism uses the collector databasefor user account validation and password hashes forpassword protection.

System action: The Enterprise Common Collectorauthenticates clients using its own database.


CTGEZ0402I LDAP authentication enabled using theuser-provider {0} (with SSL enabled {1}),user-filter {2} and auth-identity {3}.

Explanation: Authentication of clients whileestablishing a session is accomplished with the LDAPserver specified during configuration.

System action: The Enterprise Common Collectorqueries an external LDAP server to authenticate clients.


CTGEZ0700I Successful logon by user {0}. Assignedsession-id: {1}.

Explanation: The user performed a successful logon.


CTGEZ0701E Authentication failed due to unknownuser ID {0}.

Explanation: An invalid user ID was provided atlogon.

User response: Check your user ID and try the logonagain.

CTGEZ0702E Authentication failed due to invalidpassword for user ID {0}.

Explanation: An invalid password was provided atlogon.

User response: Check your password and try thelogon again.

CTGEZ0703E Authentication failed due to disableduser ID {0}.

Explanation: The logon was rejected because thespecified user account is currently disabled.

User response: Contact your security administrator forassistance if this user account has been disabled inerror.

CTGEZ0704E Authentication failed due to too manyinvalid logon attempts by user ID {0}.

Explanation: The logon was rejected because the clientissued more than the allowed number of logonattempts using an invalid user ID.

User response: Enable the client again by doing theresume operation for this client.

CTGEZ0705E Authentication failed due expiredpassword for user ID {0}.

Explanation: The logon was rejected because the clientpassword has expired.

CTGEZ0301W • CTGEZ0705E


User response: Update the password as part of thenext logon request.

CTGEZ0706E Authentication failed due to missingcredentials.

Explanation: The logon was rejected because therequest was missing credentials, such as the user ID orthe password or both.

User response: Check your credentials and try thelogon again.

CTGEZ0707E Authentication failed due to internalproblem.

Explanation: The logon was rejected because aninternal problem occured during the handling of thelogon request.

System action: The Enterprise Common Collectorrejects the logon attempt.

User response: See the log file for more informationabout the cause of this problem.

CTGEZ0708I User {0} password is updated.

Explanation: The client user ID was updated, and theexpiration date for this client password was reset.


CTGEZ0709E New password is the same as the oldpassword.

Explanation: A new password was entered, but thenew password is the same as the old password.

System action: The Enterprise Common Collectorrejects updating the password with the previouspassword. The password and expiration date are notchanged.

User response: Submit another password updaterequest with a password that is different from the oldpassword.

CTGEZ0710E Authentication for user ID {0} failed.

Explanation: Details on why the authentication failedare not provided for security reasons. The cause maybe one or more of the following:

v An invalid user ID was provided at logon.

v An invalid password was provided at logon.

v The logon was rejected because the specified useraccount is currently disabled.

v The logon was rejected because the client issuedmore than the allowed number of logon attemptsusing an invalid user ID.

v The logon was rejected because the client passwordhas expired.

v The logon was rejected because the request wasmissing credentials, such as the user ID or thepassword or both.

v The logon was rejected because an internal problemoccurred during the handling of the logon request.

User response: Details on why the authenticationfailed are not provided for security reasons. Theresponse may be one or more of the followingdepending on the cause:

v Check your user ID and try the logon again.

v Check your password and try the logon again.

v Contact your security administrator for assistance ifthis user account has been disabled in error.

v Enable the client again by performing the resumeoperation for this client.

v Update the client password, or advise the client tosend a new password as part of the next logonrequest.

v Check your credentials and try the logon again.

v See the log file for more information about the causeof this problem.

CTGEZ0711I Successful logoff by user {0} usingsession-id {1}.

Explanation: The user performed a successful logoff.


CTGEZ0712I {0} active sessions for client with name{1} were destroyed because this clientwas deleted.

Explanation: The client was deleted by anadministrator, but the client had active sessions.

System action: The active sessions for the deletedclient were destroyed.


CTGEZ0713I {0} active sessions for client with name{1} were destroyed because this clientwas updated.

Explanation: The client was updated by anadministrator, but the client had active sessions.

System action: The active sessions for the updatedclient were destroyed.


CTGEZ0714I Sessions-id {0} of client with name {1}was destroyed because it stayed unusedfor too long.

Explanation: Session-ids that remain unused for toolong a period of time are destroyed automatically.

System action: The session was destroyed due to a

CTGEZ0706E • CTGEZ0714I


timeout and cannot be used any further.

User response: If the client of this session needs to usethe system again, the client must log in again and beassiged a new, valid session-id.

CTGEZ0800E No session ID was supplied with therequest. Retry the request with a validsession ID.

Explanation: A session ID was not supplied in therequest. This might occur if, for example, the requesttimed out or if the client is not logged in.

User response: Retry the request with a valid sessionID.

CTGEZ0801E Session ID {0} is invalid. Provide avalid session ID and retry the request.

Explanation: The session ID supplied in the request isnot valid.

User response: Retry the request with a valid sessionID.

CTGEZ1000E The uniform resource identifier (URI)is invalid without the requiredparameter {0}.

Explanation: The URI entered requires the specifiedparameter.

System action: No data is returned

User response: Retry the URI with the correctparameter.

CTGEZ1001E The uniform resource identifier (URI)contains invalid content.

Explanation: The URI entered contains characters thatare not valid.

System action: No data is returned

User response: Correct the URI and try the actionagain.

CTGEZ1002E An invalid value has been specifiedfor the parameter {0} in the uniformresource identifier (URI).

Explanation: The URI entered contains an incorrectvalue for one of the parameters entered.

System action: No data is returned.

User response: Specify a valid value for the parameterand try the URI again.

CTGEZ1003E An error occurred retrieving data fromthe persistent database for the object orelement named {0}.

Explanation: An operation attempted to retrieve datafor a managed object or element but failed. Inventorydata was retrieved but metric data might beincomplete.

System action: The managed object or element isreturned with inventory data and partial metric data.

User response: Determine why the inventory gatherercomponent is not functioning correctly for theHardware Management Console. Look for earliermessages in the log.

CTGEZ1004W An error occured retrieving the metricsample set {0} from the persistentdatabase.

Explanation: An operation attempted to retrievemetric data for a managed object or element but failed.The metric data is incomplete.

System action: The values obtained and calculatedfrom the metrics sample set are incorrect. Boolean datadisplays Unknown. String data displays an emptystring. Numeric data is set to zero.


CTGEZ1005W No data was found that satisfies thethe client request.

Explanation: A client attempted to retrieve data for amanaged object or element but no data met the criteriafor the request.

System action: No data is returned.

User response: Modify the parameters of the requestand submit the request again.

CTGEZ1006W A client attempted to retrieve data fora managed object or element but thelong-term monitoring interval is notconfigured.

Explanation: A client attempted to retrieve metric datafor a managed object or element but no metric data isbeing collected because no long-term monitoringinterval is defined.

System action: The values obtained and calculatedfrom the metric sample set are set to zero.

User response: Try the operation again with thelong-term-interval-enabled parameter in the collectionprofile configured for the specified HardwareManagement Console.

CTGEZ0800E • CTGEZ1006W


CTGEZ1007W An error occurred retrieving a metricsample set from the persistent databaseused in calculating data for the managedobject with object id {0}.

Explanation: An operation attempted to retrievemetric data for a managed object or element but failed.The metric data that was not retrieved is used tocalculate aggregate data for the specified object.

System action: The values were not obtained from themetrics sample set and were not used in aggregatecalculations for the specified object. Processingcontinues.


CTGEZ1008I No metric samples for the HardwareManagement Console (HMC) {0} areavailable yet for the {1}-interval.

Explanation: An operation attempted to retrievemetric data for a Hardware Management Console, butthis data is not available yet. The metric data should becollected within the specified interval and will beavailable then.

System action: Processing continues.


CTGEZ1009W Long-term monitoring interval is notenabled for the managed object {0} withobject-id {1}; therefore no metrics forthis object are available.

Explanation: A client attempted to retrieve metric datafor a managed object or element but no metric data isbeing collected because no long-term monitoringinterval is defined.

System action: All values in the long-term sample set,including calculated values, are set to zero.

User response: Use the command line interface or APIto set the value for the long-term-collection-enabledparameter to true in the collection profile configuredfor the specified Hardware Management Console.

CTGEZ1010W All required metrics of the metricgroup {0}, which are required for thecreation of the object {1} with object-id{2}, are not available.

Explanation: An operation attempted to retrievemetric data for a managed object or element but failed.The metric data that could not be retrieved would havebeen used to calculate aggregate data for the specifiedobject.

System action: The values obtained and calculated

from the metric sample set are set to zero.

User response: There can be numerous reasons whythere are no metric data is available. If no previousmessage was logged indicating that the EnterpriseCommon Collector had problems gathering the metricdata, it is likely that the Hardware ManagementConsole itself does not provide any data for this object.

CTGEZ1500E Attribute {0} is required and must be{1} to {2} characters in length.

Explanation: The request could not be processedbecause a required attribute was not provided in theAPI request or the attribute value did not meet thelength requirements.

User response: Resubmit the request with a validvalue for the indicated attribute.

CTGEZ1501E Attribute {0} is required and must be{1} or more characters in length.

Explanation: The request could not be processedbecause a required attribute was not provided in theAPI request or the attribute value did not meet thelength requirements.


CTGEZ1502E An internal error has occurred.Details: {0}.

Explanation: An internal error has occurred.

User response: Review the details in the log file andtry to determine the cause of the problem. If youcannot solve this problem, contact IBM Softwaresupport.

CTGEZ1503E Property {0} is required and must bebetween {1} and {2} (inclusive).

Explanation: The request could not be processedbecause a required property was not provided in therequest or the property value was out of range.

User response: Resubmit the request with a validvalue for the indicated property.

CTGEZ1504E Property {0}, if supplied, must be nolonger than {1} characters in length.

Explanation: The request could not be processedbecause an attribute value did not meet the lengthrequirements.


CTGEZ1007W • CTGEZ1504E


CTGEZ1505E Invalid character in the value forproperty {0} at position {1}. Thisproperty cannot contain the character {2}.

Explanation: The request could not be processedbecause an attribute value contained an invalidcharacter. The position number indicates what characteris invalid (where 1 is the first character, etc.).


CTGEZ1520I A data source named {0} has beendefined for host {1}.

Explanation: The data source referenced in themessage has been configured in the EnterpriseCommon Collector.


CTGEZ1521E The data source must be disabledbefore updating the hmc-hostname orhmc-user attributes.

Explanation: The attributes hmc-hostname andhmc-user cannot be updated for a data source that isenabled.

User response: Disable the data source, and try theoperation again.

CTGEZ1522E The hmc-hostname and hmc-userattributes cannot be updated while adata source connection is active.

Explanation: The connection between the data sourceand the Enterprise Common Collector was still activewhen you tried the update operation. When a requestto disable a data source is issued, some time is requiredfor the connection to end.

User response: Wait one minute and send the requestagain.

CTGEZ1523E {0} is not a valid data source propertyor cannot be updated.

Explanation: The data source could not be updatedbecause the specified property is not a property of adata source or because the property value cannot bechanged.

User response: Use the configuration API to updatethe data source.

CTGEZ1524E The data source named {0} does notexist.

Explanation: A data source could not be updated orremoved because it has not been created or has alreadybeen removed.

User response: Provide the name of an existing datasource in the update data source request uniformresource identifier (URI) and try the operation again.

CTGEZ1525E The data source cannot be removedbecause it is enabled.

Explanation: An enabled data source cannot beremoved.

User response: Issue an update data source request toset the enabled state to false and then send the removedata source request again.

CTGEZ1526E The data source cannot be removedbecause it is still active.

Explanation: The connection to the data source is stillactive, and a connected data source cannot be removed.Once the data source is disabled, it may take a fewseconds or longer for the connection to end.

User response: Wait one minute and resend therequest.

CTGEZ1527I The data source named {0} has beenremoved.

Explanation: The data source referenced in themessage has been removed.


CTGEZ1528E A data source with name {0} alreadyexists.

Explanation: A data source already exists in theEnterprise Common Collector with the specified name.A new data source with the same name cannot becreated.

User response: Resubmit the request with a uniquename value.

CTGEZ1540I A logger for name {0} has been createdwith level {1}.

Explanation: The logger referenced in the message hasbeen configured in the Enterprise Common Collector atthe level indicated.


CTGEZ1541E Attribute level is required and mustbe a valid Java standard logging level.

Explanation: The request could not be processedbecause a value for attribute level was not provided inthe API request or the level value was not valid. Validvalues are as follows:

v SEVERE (highest level, bugs or critical conditions)

v WARNING (undesireable or unexpected situations)

CTGEZ1505E • CTGEZ1541E


v INFO (high-level, heartbeat information)

v CONFIG (configuration parameters, equivalent toINFO)

v FINE (debugging, highest level)

v FINER (debugging, middle level)

v FINEST (debugging, lowest level)

v OFF (turns off all logging)

v ALL (enables logging of all messages, equivalent toFINEST)

User response: Use the configuration API to updatethe data source.

CTGEZ1542E {0} is not a valid logger property orcannot be updated.

Explanation: A logger could not be updated becausethe specified property is not a property of a logger orbecause the property value cannot be changed.

User response: Resubmit the update logger requestwith a valid property.

CTGEZ1543E Logger for name {0} does not exist.

Explanation: A logger could not be retrieved, updated,or removed because it has not been created or hasalready been removed.

User response: Ensure that the name in the updatelogger or remove logger request uniform resourceidentifier (URI) is correct.

CTGEZ1544I The logger for name {0} has beenremoved.

Explanation: The logger referenced in the message hasbeen removed from the Enterprise Common Collector.


CTGEZ1545E A logger for name {0} already exists.

Explanation: The logger referenced in the messagealready exists in the Enterprise Common Collector. Anew logger for the same name cannot be created.

User response: Use the configuration API to updatethe existing logger.

CTGEZ1546E The logger for name gez cannot bedeleted.

Explanation: The logger for name gez is the defaultlogger and cannot be deleted.


CTGEZ1547E Logger name must be in the form of ahierarchical namespace with gez as thefirst level in the hierarchy. For examplegez.gatherers.metrics or gez.admin.

Explanation: When the logger name is prependedwith com.ibm.tivoli. it should denote a Java packagewithin the Enterprise Common Collector code.Typically this name will be provided by IBM Softwaresupport.

User response: Submit the request again with a validlogger name.

CTGEZ1560E Configuration for authentication notapplicable.

Explanation: The specified configuration cannot beused for an update because it does not match therequired syntax.

System action: The Enterprise Common Collectorignores the configuration update request and keeps thecurrent configuration.

User response: Submit the request again with a validconfiguration.

CTGEZ1561E No LDAP authentication propertiesexpected.

Explanation: The specified configuration containsLDAP properties that were not expected because LDAPauthentication is disabled for the specifiedconfiguration.



CTGEZ1562E LDAP authentication propertiesexpected.

Explanation: The given configuration does not containthe expected LDAP properties, even though LDAPauthentication is enabled for the specifiedconfiguration.



CTGEZ1563E Password expiration interval invalid.

Explanation: The password expiration interval mustbe larger than 0.

System action: The Enterprise Common Collector



ignores the configuration update request and keeps thecurrent configuration.


CTGEZ1580E Configuration for certificates notapplicable.

Explanation: The specified configuration cannot beused for an update because it does not match therequired syntax.



CTGEZ1600I A client with name {0} has been created.

Explanation: The client referenced in the message hasbeen configured in the Enterprise Common Collector.


CTGEZ1601E At least one role must be specified,and all roles must be valid EnterpriseCommon Collector roles.

Explanation: The request could not be processedbecause no roles were provided in the API request orthe role that was provided was invalid. Valid roles areas follows:

v Explorer

v Operator

v Administrator

User response: Submit the request again with at leastone valid role value.

CTGEZ1602E {0} is not a valid client property orcannot be updated.

Explanation: A client could not be updated becausethe specified property is not a property of a client orbecause the property value is unchangeable.

User response: Submit the updated client requestagain without the invalid property.

CTGEZ1603E Client for name {0} does not exist.

Explanation: A client could not be retrieved, updated,or removed because it has not been created or hasalready been removed.

User response: Check the name in the UPDATECLIENT or REMOVE CLIENT request uniform resourceidentifier (URI) to ensure that it is correct.

CTGEZ1604I The client for name {0} has beenremoved.

Explanation: The client referenced in the message hasbeen removed from the Enterprise Common Collector.


CTGEZ1605E A client for name {0} already exists.

Explanation: The client referenced in the messagealready exists in the Enterprise Common Collector. Anew client with the same name cannot be created.

User response: Use the PUT operation to update theexisting client, or choose another name.

CTGEZ1606E The client for name admin cannot bedeleted.

Explanation: The client for name admin is the defaultadmin client and cannot be deleted.


CTGEZ1607E Only the enabled,password-expiration-enabled, andpassword properties can be changed forthe admin client.

Explanation: The client for name admin is the defaultadmin client. Only the enabled, password-expiration-enabled, and password properties can be changed forthe default admin client.

User response: Submit the change request again withan allowed property.

CTGEZ1620I A collection profile named {0} has beendefined.

Explanation: The collection profile referenced in themessage has been configured in the EnterpriseCommon Collector.


CTGEZ1621E The long-term-interval attribute valuemust be a multiple of theshort-term-interval attribute value.

Explanation: The collection profile could not beupdated because the short-term-interval andlong-term-interval values are not valid.long-term-interval must be a multiple ofshort-term-interval. For example, if short-term-intervalis 300, then long-term-interval must be 600, 900, 1200,or 1800.

User response: Try the operation again with correctvalues for short-term-interval and long-term-interval.



CTGEZ1623E {0} is not a valid collection profileproperty or cannot be updated.

Explanation: The collection profile could not beupdated because the specified property is not aproperty of a collection profile or because the propertyvalue cannot be changed.

User response: Try the operation again without thespecified attribute.

CTGEZ1624E Collection profile with name {0} doesnot exist.

Explanation: A collection profile could not beretrieved, updated, or removed because it has not beencreated or has already been removed.

User response: Provide a correct collection-profile-name in the request uniform resource identifier (URI)and try the operation again.

CTGEZ1625E The collection profile cannot bedeleted because it is being used by atleast one data source.

Explanation: A collection profile that is currently inuse by a data source cannot be removed.

User response: Issue a data-sources list command todetermine which data sources are using the collectionprofile that you want to delete. Issue an data-sourceupdate request to change the collection profile assignedto that data source to a different collection profile. Thentry to delete the collection profile again.

CTGEZ1626I The collection profile with name {0} hasbeen removed.

Explanation: The collection profile referenced in themessage has been removed from the EnterpriseCommon Collector.


CTGEZ1627E A collection profile with name {0}already exists.

Explanation: A collection profile already exists in theEnterprise Common Collector with the specified name.A new collection profile with the same name cannot becreated.

User response: Resubmit the request with a uniquename value.

CTGEZ1800E Unable to parse request body; it is notwell-formed.

Explanation: The request body must be well-formedJSON (that is, it must conform to the syntax injson.org).

User response: Correct the formatting error andresubmit the request.

CTGEZ1801E A data source with name {0} does notexist.

Explanation: A data source could not be updated orremoved because it does not exist.

User response: Ensure that the name in the datasource request uniform resource identifier (URI) iscorrect.

CTGEZ1802I Enterprise Common Collector URIRequest: {0} {1}

Explanation: This message contains the body of a URIrequest received by the Enterprise Common Collector.

User response: No response. This message is for auditreporting or problem diagnosis.

CTGEZ1803E The request is not well-formed or thevalue of a property in the request is inan invalid format.

Explanation: The request body must be well-formedJSON (that is, it must conform to the syntax in json.org)and all property values must be of the proper type andformat. Examine the request to determine why therequest is invalid.

User response: Correct the formatting error andsubmit the request again.

CTGEZ1804E Property {0} is unknown.

Explanation: The specified value is not valid in thiscontext.

User response: Determine if the property name ismisspelled or otherwise incorrect. Correct or removethe incorrect property and try the operation again.

CTGEZ3000I One or more active transactions aredetected during shutdown of theEnterprise Common Collector'sdatabase.

Explanation: The Enterprise Common Collector'sdatabase is about to shutdown, but active transactionsare still running.

System action: The Enterprise Common Collector willdelay the shutdown of the database for some momentsto give the transactions the chance to complete. Stillactive transactions will then be rolled back.




CTGEZ3001I No existing database was found. A newdatabase was created and initializedwith default configuration values.

Explanation: The Enterprise Common Collectordatabase is empty. This occurs when the EnterpriseCommon Collector is started for the first time or whenthe database was deleted manually.

System action: The Enterprise Common Collector willtry to find a backup bundle from which it can migratea configuration. If none can be found, a database iscreated with the system defaults.


CTGEZ3002I An existing database was found.

Explanation: The Enterprise Common Collectordatabase is populated, meaning that it contains therequired configuration and other data. This is thenormal condition if the collector was configuredpreviously or migrated and then restarted.

System action: The system started using an existingconfiguration from the database.


CTGEZ5000E Unable to process a value row fromthe metrics for the data source named{0}. The value row has been skipped.Interval name: {1}; Metrics group: {2};Object ID : {3}; Value row: {4}; Errordetails: {5}

Explanation: A value in the metrics from the specifieddata source could not be processed.

System action: The Enterprise Common Collectorignores this value row and continues with the rest ofthe metrics data.

User response: See the error details for moreinformation.

CTGEZ5001W The Enterprise Common Collector isalready collecting metrics for the datasource named {0}.

Explanation: It is not possible to collect metrics datafor the same data source using multiple processes inparallel.

System action: The Enterprise Common Collector willnot start a second collection operation for this datasource.


Programmer response: Verify that the EnterpriseCommon Collector is collecting metrics data only oncefor each data source.

CTGEZ5200W Inventory Error Document for URI {0}received from data source named {1}: {2}

Explanation: The Hardware Management Console(HMC) has sent an Inventory Error Document insteadof the expected resource or object. This happens whena resource or object is found on the HMC, but is notsuccessfully fully inventoried there.

System action: The Enterprise Common Collectorignores this resource or object and continues with theother resources.

User response: See the inventory error text and errorcode, reported within the Inventory Error Document,for more information.

CTGEZ5400W Network adapter with duplicateelement-id {0} gathered for virtual serverwith object-id {1}. The network adapterwith this already-used element-id isignored.

Explanation: A virtual server, whose inventoryinformation was gathered by the Enterprise CommonCollector, contains two (or more) network adapters thatuse an identical element-id and are therefore seen asduplicates by the collector. The element-id of thenetwork adapters must be unique in the scope of avirtual server. Therefore, only the first-gatherednetwork adapter with a given element-id is added tothe Enterprise Common Collector database. All othernetwork adapters with a duplicate element-id in thescope of this virtual server are ignored.

System action: The Enterprise Common Collectorignores this duplicate network adapter.

User response: Determine why this virtual server hasat least two network adapters using the sameelement-id and try to resolve this problem on theHardware Management Console.

CTGEZ5500W The Enterprise Common Collectoralready gathers the inventory data forHMC on host {0}.

Explanation: It is not possible to gather inventory datafor the same Hardware Management Console (HMC)using multiple processes in parallel.

System action: The Enterprise Common Collector willnot start a second gathering operation for this HMC.


Programmer response: Verify that the EnterpriseCommon Collector is gathering inventory data onlyonce for the same HMC.

CTGEZ3001I • CTGEZ5500W


CTGEZ5501E Path accessibility information couldnot be retrieved from the data sourcewith name {0} because the virtualizationhosts could not be retrieved from thepersistence manager.

Explanation: An unexpected exception occurred whenretrieving the virtualization hosts from the persistencemanager for the specified data source. Processingcontinues and control is returned to the inventorygatherer component.

System action: Inventory gatherer processingcontinues.

User response: Details on the exception can be foundin the log.

Programmer response: Details on the exception can befound in the log.

CTGEZ5502E Path accessibility information for thevirtualization host with object-id {0}could not be retrieved from the datasource with name {1}. The request sentto the data source timed out.

Explanation: If the request for virtualization hoststorage resource information does not respond with aspecified period of time, processing continues to thenext virtualization host.


Programmer response: If this problem occursregularly, it may indicate that the timeout value shouldbe increased.

CTGEZ5503E Path accessibility information for thevirtualization host with object-id {0}could not be retrieved from the datasource with name {1}.

Explanation: The response to a request forvirtualization host storage resource information wasinvalid or could not be processed. Processing continuesto the next virtualization host.


User response: Details on the exception can be foundin the log.

Programmer response: Details on the exception can befound in the log.

CTGEZ6000I An API session has been establishedwith the data source named {0}.

Explanation: A logon operation was sent to thespecified data source and successfully established anAPI session.


CTGEZ6001E User authentication with the datasource named {0} failed.

Explanation: The user ID or password or bothconfigured for this data source are incorrect.

User response: Use the configuration utility to correctthe user ID or password or both for the referenced datasource.

CTGEZ6002W An attempt to establish an APIsession with the data source named {0}failed. The data source cannot bereached.

Explanation: No response to a logon request wasreceived from the data source.

User response: It is possible that the problem withaccess to this data source is temporary. No action isnecessary unless this message occurs multiple times.

CTGEZ6003W An attempt to establish an APIsession with the data source named {0}failed. The data source returned HTTPstatus code: {1}; reason code: {2};message: {3}.

Explanation: The data source responded to a logonrequest with the HTTP status code, reason code andmessage referenced in the message. Seehttp://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for explanations of HTTP status codes. Seethe Hardware Management Console Web Services APImanual for explanations of the reason codes.

User response: It is possible that the problem withaccess to this data source is temporary. No action isnecessary unless this message occurs multiple times. Atthat time verify that the hostname is correct, and usethe configuration utility to update the hostname ifnecessary. The HTTP status code may provide moreinsight into the reason that the data source cannot bereached.

CTGEZ6004W An attempt to establish an APIsession with the data source named {0}failed. The data source sent an invalidresponse.

Explanation: An attempt to establish an API sessionwith the specified data source failed because the datasource sent an invalid response. This could be for anyone of the following reasons:

v The response was not in valid application/jsonformat.

v The response did not contain a JSON object.

v The JSON object did not contain a field namedapi-session or the value was empty.



v The JSON object did not contain a field namednotification-topic or the value was empty.

v The JSON object did not contain a field namedapi-major-version or the value was empty.

v The JSON object did not contain a field namedapi-minor-version or the value was empty.

User response: No action is necessary unless thismessage occurs multiple times.

Programmer response: Obtain trace logs to determinewhy the response was invalid.

CTGEZ6005E {0} attempts to establish an APIsession with the data source named {1}have failed. No more attempts will bemade.

Explanation: Multiple attempts to establish an APIsession with the specified data source have failed. Nomore attempts will be made.

User response: Verify that the hostname is correct,and use the configuration utility to update thehostname. Verify that the data source is operatingproperly.

CTGEZ6006I The API session with the data sourcenamed {0} has been closed.

Explanation: A logoff operation was sent to thespecified data source, and the API session is nowclosed.

User response: No action is required if this behavior isexpected.

CTGEZ6011I The data source named {0} has beenenabled.

Explanation: The Hardware Management Console(HMC) Session Manager detected that the specifieddata source has been enabled using the ConfigurationAPI.

System action: The HMC Session Manager attempts toestablish an API session with this data source.


CTGEZ6012I The data source named {0} has beendisabled.

Explanation: The Hardware Management Console(HMC) Session Manager detected that the specifieddata source has been disabled using the ConfigurationAPI.

System action: The HMC Session Manager hasstopped all inventory and metrics gathering, as well asnotification handling, for this data source and closedthe API session.


CTGEZ6013I The data source named {0} has beenremoved.

Explanation: The Hardware Management Console(HMC) Session Manager detected that the specifieddata source has been deleted using the ConfigurationAPI.


CTGEZ6020I Inventory gatherer component hasstarted for the data source named {0}.

Explanation: The inventory gatherer component hasstarted for the specified data source.


CTGEZ6021I Inventory gatherer component has beenintentionally stopped for the data sourcenamed {0}.

Explanation: The inventory gatherer component hasbeen stopped for the specified data source.


CTGEZ6022E Inventory gatherer component hasfailed for the data source named {0}.

Explanation: The inventory gatherer component hasfailed for the specified data source.

User response: Check the trace log for a previousadditional message about this shutdown.

CTGEZ6023I Inventory gatherer component hascompleted for the data source named {0}.

Explanation: The inventory gatherer component hascompleted for the specified data source.

System action: If metrics gathering and notificationhandling have not been started for the specified datasource, they will now be started.


CTGEZ6024E Unable to gather inventory for thedata source named {0}.

Explanation: An API session was established with thedata source, but an attempt to start the inventorygatherer component failed.

User response: Check the trace log for a previousadditional messages about this failure.

CTGEZ6030I Notification handling has started for thedata source named {0}.

Explanation: Notification handling has started for thespecified data source.




CTGEZ6031I Notification handling has been stoppedfor the data source named {0}.

Explanation: Notification handling has been stoppedfor the specified data source. Notification messages willnot be handled.

Programmer response: Check the trace log for aprevious message and try the operation again.

CTGEZ6032E Notification handling has failed forthe data source named {0}.

Explanation: Notification handling has failed for thespecified data source.

User response: Check the trace log for a previousmessage.

CTGEZ6033I Notification has detected that theinventory may not be synchronized withthe data source named {0}.

Explanation: Notification has detected that theinventory may be not be synchronized with thespecified data source.

System action: Inventory gathering is started for thespecified data source.


CTGEZ6034E Unable to accept notification messagesfor the data source named {0}.

Explanation: An API session was established with thedata source, but an attempt to start the notificationcomponent failed.


CTGEZ6040I Metrics gathering has started for thedata source named {0}.

Explanation: Metrics gathering has started for thespecified data source.


CTGEZ6041I Metrics gathering has been stopped forthe data source named {0}.

Explanation: Metrics gathering has been intentionallystopped for the specified data source.


CTGEZ6042E Metrics gathering has failed for thedata source named {0}.

Explanation: Metrics gathering has failed for thespecified data source.

System action: The Enterprise Common Collectordisconnects from the specified data source and status ofthis data source is set from enabled to disabled.

User response: Check the trace log for a previousmessage to determine why metrics gathering for thisdata source has failed. When the issue is resolved, usethe data-sources update -enabled command to changethe status of this resource from disabled to enabled.

CTGEZ6043E Unable to gather metrics for the datasource named {0}.

Explanation: An API session was established with thedata source, but an attempt to start the metrics gatherercomponent failed.


CTGEZ6500E Unable to connect to the HMC APIMessage Broker for the data sourcenamed {0}.

Explanation: An API session was established with thedata source, but an attempt to connect to the HMC APImessage broker failed.

User response: Verify that the HMC API messagebroker component is functioning and that the messagebroker URI (ssl://{hmc-hostname}:61617) is accessible.

CTGEZ6501E Unable to update property {0} ofobject or element with class {1} and id{2}; the property value was not of type{3} as expected

Explanation: A property change notification messagewas received from the data source but the new valuefor one of the properties was not of the expected type.

System action: The property is not updated.Processing continues to the next property or the nextmessage as appropriate.

User response: Ensure that the data source versionand Enterprise Common Collector version arecompatible.

Programmer response: Determine if a change isneeded to the collector data model.

CTGEZ8300I Existing master key file detected andused: {0}

Explanation: The master key file contains theinitialization vector and the key that are used for theencryption of the Hardware Management Console

CTGEZ6031I • CTGEZ8300I


passwords. This file was found and used for anauthentication operation.


CTGEZ8301I No master key file detected. Created anew key file named {0}

Explanation: The master key file is required for theencryption of the Hardware Management Console(HMC) passwords. It contains the initialization vector(IV) and the key. A new IV and the key are generatedby random. If no master key file is detected, a new oneis created by the system.

System action: A new key file was created.

User response: If an attacker gets access to the masterkey file, this person could in theory decrypt the HMCpasswords. Protect this file with all available optionssupported by the operating system.

CTGEZ8302E No master key file detected, but HMCconfiguration with encrypted passwordsexists.

Explanation: The master key file is required for theencryption of the Hardware Management Console(HMC) passwords. It contains the initialization vector(IV) and the key. This message means that HMCconfiguration information (including encryptedpasswords) was detected in the database, but themaster key file for decryption is missing.

System action: The Enterprise Common Collectorcontinued its startup and created a new master key file.But it will not be able to connect to the alreadyconfigured HMCs since it will not be able to decrypttheir passwords.

User response: If a backup for the master key file isavailable, replace the newly created master key filewith a valid one from a previous backup. Restart theEnterprise Common Collector to try to decrypt theHMC passwords, and logon again. If no backup isavailable, update the existing HMC configuration andreset the passwords to ensure that the passwords areencrypted with the new master key file.

CTGEZ8303E Cannot encrypt HMC password.

Explanation: Encryption of a Hardware ManagementConsole (HMC) password failed.

System action: The Enterprise Common Collectordoes not save an encrypted password for the HMC andtherefore is not able to connect to it.

Programmer response: Determine why the encryptionalgorithm that was used cannot encrypt the password.The most likely cause is that the wrong parameterswere configured for the algorithm. Other potentialproblems include the following:

v Bad key length (too long or too short)

v Bad block size

v Problems with padding the password to the specifiedblock size

CTGEZ8304E Cannot decrypt HMC password.

Explanation: Decryption of a Hardware ManagementConsole (HMC) password failed. This probablyoccurred because the master key file is corrupted orwas replaced with another one.

System action: The Enterprise Common Collector isnot able to connect to the HMC because the requiredpassword cannot be authenticated.

User response: Determine whether the master key fileseems to be corrupted or if it was missing and has beenreplaced with a new one (if you find messageCTGEZ8302E in the log).

Programmer response: If no problem is found withthe master key file, determine why the encryptionalgorithm used cannot decrypt the password. The mostlike cause is that the wrong parameters wereconfigured for the algorithm. Other potential problemsinclude the following:


v Bad block size


CTGEZ8305E Cryptographic algorithm {0} is notsupported.

Explanation: The cryptographic algorithm, requiredfor encryption and decryption of the HardwareManagement Console (HMC) passwords, is notsupported by the Java runtine environment (JRE) orJava development kit (JDK) used.

System action: The Enterprise Common Collector isnot able to connect to the HMCs because it cannotprocess the HMC passwords.

User response: Ensure that the JRE or JDK usedsupports the specified cryptographic algorithm.

Programmer response: If the JRE or JDK used cannotbe changed and does not support the currently selectedcryptographic algorithm, this algorithm must bechanged.

CTGEZ8306E Cannot access master key file.

Explanation: The master key file is required for theencryption of the Hardware Management Console(HMC) passwords. It contains the initialization vector(IV) and the key. The master key file cannot beaccessed due to insufficient access rights or because itdoes not exist or is corrupted.

System action: The Enterprise Common Collector isnot able to connect to the HMCs because it cannot

CTGEZ8301I • CTGEZ8306E


process the HMC passwords.

User response: Ensure that the master key file exists,is not corrupt, and can be accessed (that it has read andwrite access) by the system.

CTGEZ8307W JVM is configured to globally acceptall TLS/ SSL certificates. This is notrecommended.

Explanation: Transport Layer Security (TLS) andSecure Socket Layer (SSL) communication includescertification validation to verify the identity of theserver. Deactivation of this validation is possible butnot recommended due to possible security issues. Theconfiguration of this deactivation is global within theJava virtual machine (JVM) and therefore impacts otherapplications running within the same JVM.

System action: The Enterprise Common Collectordoes not validate the server certificates for TLS and SSLcommunication. This lack of validation could have animpact on with other applications running in the sameJVM.

User response: If possible, enable the certificationvalidation. Certification validation requires the use of atruststore containing the Certification Authority (CA)certificates to trust. The Enterprise Common Collectoris responsible for its truststore, but the CA certificatesmust be imported by the operator.

CTGEZ8308I Certificate validation for TLS/ SSLcommunication is enabled. This is therecommended mechanism.

Explanation: Transport Layer Security (TLS) andSecure Socket Layer (SSL) communication includescertification validation to verify the identity of theserver. Deactivation of this validation is possible butnot recommended due to possible security issues.

System action: The Enterprise Common Collectorvalidates the server certificates for TLS/ SSLcommunication.


CTGEZ8309E Hash algorithm {0} is not supported.

Explanation: The hash algorithm, required for hashingof Enterprise Common Collector users' passwords, isnot supported by the Java runtime environment (JRE)or Java development kit (JDK) used.

System action: The Enterprise Common Collector isunable to hash the password and therefore cannotcontinue progress on the task that requires thepassword hash.

User response: Ensure that the JRE or JDK usedsupports the specified hash algorithm.

Programmer response: If the used JRE or JDK cannot

be changed and does not support the currently selectedhash algorithm, this algorithm must be changed.

CTGEZ8310W Cannot store hash for new masterkey file.

Explanation: The hash for a newly generated masterkey file cannot be stored due to a problem with thedatabase.

System action: The Enterprise Common Collector isnot able to verify the integrity of the master key file.

User response: Determine why the hash cannot bestored in the database.

Programmer response: Determine why the hashcannot be stored in the database.

CTGEZ8311W Master key file is corrupt.

Explanation: Comparing the actual hash of the masterkey file and the saved hash in the database shows amismatch. This means that the master key file iscorrupt (due to such problems as disk error or manualmanipulation).

System action: The Enterprise Common Collector isunable to connect to the already configured HardwareManagement Consoles (HMCs) since it cannot decrypttheir passwords.

User response: If a backup of the master key file isavailable, restore from the backup and restart theEnterprise Common Collector. Retry the logon usingthe password defined in the restored master key file. Ifno backup for the master key file is available, updatethe existing HMC configuration and reset thesepasswords to ensure the passwords are encrypted againwith the actual master key file.

CTGEZ8312W No configuration for a truststorefound. JVM will use its defaulttruststore.

Explanation: Certification validation requires the useof a truststore containing the Certificate Authority (CA)certificates to trust. The JVM was designed to use itsown truststore, but the configuration for the location ofthis truststore cannot be found.

System action: The system Java virtual machine (JVM)uses its default truststore.

User response: If using the JVM default truststore wasnot the intended action, provide the truststore locationas part of the configuration for the web container.

CTGEZ8313I Truststore {0}, not found duringinitialization, is now created.

Explanation: Certification validation requires the useof a truststore containing the Certificate Authority (CA)certificates that are trusted.

CTGEZ8307W • CTGEZ8313I


System action: The Enterprise Common Collector hascreated a new and empty truststore at the specifiedlocation.

User response: The new truststore is empty. The CAcertificates must be imported to ensure the successfulvalidation of the Hardware Management Consoles(HMCs).

CTGEZ8314I Truststore {0} found.

Explanation: Certification validation requires the useof a truststore containing the Certificate Authority (CA)certificates that are trusted.

System action: The Enterprise Common Collectorfound an existing truststore at the specified location.


CTGEZ8315E Truststore {0} cannot be created.

Explanation: Certification validation requires theusage of a truststore containing Certificate Authority(CA) certificates that are trusted. The EnterpriseCommon Collector tried to create a new truststore, butwas not able to perform this task.

System action: The Enterprise Common Collector isunable to verify the identities of the HardwareManagement Consoles (HMCs) and cannotcommunicate with them using Transport Layer Security(TLS) and Secure Socket Layer (SSL) communication.

User response: Try to determine why the EnterpriseCommon Collector cannot create a new truststore. Onepotential problem might be insufficient rights for theEnterprise Common Collector to create a new truststorefile in the file system.

CTGEZ8316E Alias {0} already in use in truststore.Certificate cannot be imported.

Explanation: A certificate is identified by its aliaswithin a truststore. The alias of a certificate must beunique within this truststore.

System action: The Enterprise Common Collectorcannot import the certificate with this alias.

User response: Choose another alias for thiscertificate, and try importing it again.

CTGEZ8317I Certificate successfully imported intotruststore using alias {0}.

Explanation: A certificate is identified by its aliaswithin a truststore. The alias of a certificate must beunique within this truststore.

System action: The Enterprise Common Collector isable to communicate with the Hardware ManagementConsoles (HMCs) using Transport Layer Security (TLS)and Secure Socket Layer (SSL) communication and

identify which certificates can be verified by theimported certificate.


CTGEZ8318E Certificate cannot be imported intotruststore.

Explanation: The Enterprise Common Collector wasunable to import the given certificate into thetruststore.

System action: The Enterprise Common Collectortruststore does not contain the new certificate andcannot verify certificates from the HardwareManagement Consoles (HMCs) that were signed by thiscertificate.

User response: Verify that the certificate that was sentis not damaged and that the Enterprise CommonCollector has write access to the truststore.

CTGEZ8319E Certificate alias cannot be empty.

Explanation: The Enterprise Common Collector isunable to handle a certificate request using an alias thatis empty or null.

System action: The Enterprise Common Collectorcannot handle a certificate request with an invalid alias.

User response: Send the certificate request again usinga valid alias.

CTGEZ8320E No truststore configured as requested.

Explanation: No configuration information about thetruststore that the Enterprise Common Collector canuse is available. Therefore it is not possible for thecollector to read from the truststore or write to it.

System action: The collector cannot read from or writeto the truststore. Communication using Transport LayerSecurity (TLS) and Secure Socket Layer (SSL) may stillwork since the collector can use a Java virtual machine(JVM) default truststore.

User response: Configure the collector to use an itsown local truststore by adjusting the Web containerconfiguration to provide the Java system propertyjavax.net.ssl.trustStore.

CTGEZ8321E Certificate alias {0} unknown.

Explanation: No certificate with the specified alias canbe found.

System action: The Enterprise Common Collectorcannot return a certificate for the specified alias.

User response: Submit the request again with a validalias.



CTGEZ8322E Truststore file not found.

Explanation: The truststore file cannot be found in theconfigured location.

System action: The Enterprise Common Collectorcannot use the configured truststore and thereforecannot validate the Hardware Management Console(HMC) certificates, import certificates, or readcertificates.

User response: The Enterprise Common Collector triesto create a truststore on startup, if one is not found.Determine why the truststore cannot be created.

CTGEZ8323E Reading from or writing to truststorefailed.

Explanation: The Enterprise Common Collector cannotread from or write to its truststore.

System action: The Enterprise Common Collectorcannot perform the read or write operation on thetruststore that was requested.

User response: Examine the Enterprise CommonCollector exception log to determine the cause of theproblem.

CTGEZ8324I Certificate with alias {0} successfullydeleted.

Explanation: The certificate indicated by the specifiedalias was successfully removed from the truststore.


CTGEZ8325I Previous configuration change requiresa restart of the ECC.

Explanation: A configuration change has been madeto the Enterprise Common Collector (ECC) thatrequires a restart to complete the implementation.

User response: Restart the ECC.

CTGEZ8326E Cannot create required SSL contexts.

Explanation: A problem occurred while creating thesecure socket protocol implementation (SSL context)required by the Java Virtual Machine to communicateusing Transport Layer Security (TLS) and Secure SocketLayer (SSL).

System action: The system continues to run butcommunication with the monitored HardwareManagement Consoles using TLS or SSL may fail.

User response: Review the Enterprise CommonCollector log to determine the cause of the problem.

CTGEZ8327E Cannot update SSL contexts related toupdates to the truststore.

Explanation: A problem occurred while updating thesecure socket protocol implementation (SSL context)due to the changes to the truststore. This context isrequired by the Java Virtual Machine to communicateusing Transport Layer Security (TLS) and Secure SocketLayer (SSL). If a certificate is added or removed fromthe truststore, the SSL context must be updated to beaware of this changes.

System action: The system continues to run but maynot be aware of the changes to the truststore. A restartof the system may be necessary to be aware of thischanges.


CTGEZ8400I Enterprise Common Collector is alreadyinstalled.

Explanation: During the installation process, theinstallation wizard discovered that an instance of theEnterprise Common Collector had been previouslyinstalled.

System action: Installation processing stops.

User response: Click OK to close the message. Waitfor the installation wizard to quit the install.Afterwards, uninstall the existing version of theEnterprise Common Collector. When the uninstall hascompleted successfully, reinstall.

CTGEZ8500I The requested manual backup bundlecontaining the current EnterpriseCommon Collector configuration wassuccessfully created. Time of backup:{0}.

Explanation: A backup bundle of the currentEnterprise Common Collector configuration, includingthe masterkey-file and the truststore, is created due to amanual request.


CTGEZ8502I Enterprise Common Collectorconfiguration was manually restoredfrom a backup bundle of EnterpriseCommon Collector version {0}. Time ofrestored backup: {1}.

Explanation: The configuration data for the EnterpriseCommon Collector was sucessfully restored from abackup bundle due to a manual request.

System action: All restored data-sources are disabledafter restoring from a backup.

User response: If desired, enable the restoreddata-sources.



CTGEZ8503I Enterprise Common Collectorconfiguration was restored from adetected backup bundle of EnterpriseCommon Collector version {0}. Time ofrestored backup: {1}.

Explanation: The Enterprise Common Collector isstarted with an empty database. This might be due to anew installation of the Enterprise Common Collector orbecause the database for the existing installation wasdeleted. A migration backup bundle was detected andused to restore a previous configuration.

System action: All restored data-sources are disabledafter restoring from a backup.

User response: If desired, enable the restoreddata-sources.

CTGEZ8504E Enterprise Common Collectorconfiguration cannot be read.

Explanation: The configuration data for the EnterpriseCommon Collector, required for creating a backupbundle, cannot be read.

System action: The backup bundle creation operationstops.


CTGEZ8505E Enterprise Common Collector hasproblems accessing its truststore forhandling a backup bundle.

Explanation: The Enterprise Common Collectorencountered a problem accessing its truststore whilecreating or restoring a backup bundle.

System action: The backup bundle creation orrestoration operation stops.


CTGEZ8506E Enterprise Common Collector backupbundle cannot be encrypted ordecrypted.

Explanation: Encryption or decryption of a backupbundle for the Enterprise Common Collectorconfiguration failed.


User response: Examine the Enterprise CommonCollector log to determine the cause of the problem.

Programmer response: Determine why the algorithmthat was used cannot encrypt or decrypt the backupbundle. The most likely cause is that the wrongparameters were configured for the algorithm. Otherpotential problems include the following:


v Bad block size


CTGEZ8507E Enterprise Common Collector backupbundle cannot be created.

Explanation: Creation of a backup bundle for theEnterprise Common Collector configuration failed.



CTGEZ8508E Passphrase for encrypting ordecrypting a Enterprise CommonCollector backup bundle is notsufficient.

Explanation: The passphrase used to encrypt ordecrypt a backup bundle must meet the followingrequirements:

v Length between 8 and 50 characters

v At least one digit (0-9)

v At least one lowercase character (a-z)

v At least one uppercase character (A-Z)

v Special characters are optional

System action: The backup bundle creation orrestoration operation stops.

User response: Retry the backup bundle operationand provide a passphrase that matches the specifiedrequirements.

CTGEZ8509E Provided Enterprise CommonCollector backup bundle is incomplete.

Explanation: The Enterprise Common Collectorbackup bundle, from which the configuration should berestored, does not contain all required data. Thefollowing fields of the backup bundle are mandatory:

v version: containing the version of the EnterpriseCommon Collector that was used to create thebackup bundle

v backup: containing the encrypted backup data

System action: The backup bundle restorationoperation stops.

User response: Try the restore operation again using abackup bundle that matches the specified requirements.



CTGEZ8510E This Enterprise Common Collectorversion {0} cannot be restored from thebackup bundle that was created usingEnterprise Common Collector version{1}.

Explanation: Restoring the Enterprise CommonCollector configuration from a backup bundle failedbecause the backup bundle was created from anEnterprise Common Collector version that is notsupported by the current version.


User response: Try the restore operation again using abackup bundle from a supported version of theEnterprise Common Collector.

CTGEZ8511E Enterprise Common Collector backupbundle cannot be restored.

Explanation: Restoring the Enterprise CommonCollector configuration from a backup bundle failed.



CTGEZ8512E Enterprise Common Collector backupbundle cannot be restored because adata source is still active.

Explanation: When you restore an EnterpriseCommon Collector backup bundle, no connection toany data source is allowed to be active. Once the activedata sources are disabled, wait at least a minute for theconnection to end before retrying the operation.

User response: Disable all active data sources, waitone minute, and then try the restore operation again.

CTGEZ8600I Directory for automatic backup bundlesset to {0}.

Explanation: The Enterprise Common Collector storesthe automatic backup bundles in the named path in thefilesystem.


CTGEZ8601E Inaccurate configuration for ArchiveManager.

Explanation: The configuration for the ArchiveManager is not accurate. In general this means that oneof the configuration values is not set at all.

System action: Working with automatic backupbundle stops.

User response: Check the configuration for the

Archive Manager and verify that all backup-relatedconfiguration values are set accordingly.

CTGEZ8602W Cannot delete outdated backupbundle {0}.

Explanation: The Archive Manager cannot delete anout-ated backup bundle for some reason such asinsufficient access rights.

System action: The system create a new backupbundle, but cannot delete outdated bundles. The totalnumber of automatic backup bundles may increaselimitless.

User response: Verify that the Enterprise CommonCollector has the required access rights to delete thebackup bundles from the filesystem. To discover whatmight have caused the problem, look for earliermessages in the Enterprise Common Collector log.

CTGEZ8603I Automatically archived a backup bundleat {0} into file {1}.

Explanation: The Enterprise Common Collectordetected a change in the collector configuration and hasautomatically created a backup bundle and stored it inthe filesystem in the path indicated by the message.


CTGEZ8604I Enterprise Common Collector cannotfind a backup bundle, so a defaultconfiguration was created.

Explanation: The Enterprise Common Collector wasstarted with an empty database and could not find anybackup bundle. A default configuration was createdand was used to initialize the database.


CTGEZ8605I Enterprise Common Collector cannotlocate a backup bundle.

Explanation: The Enterprise Common Collector wasstarted with an empty database and is trying withoutsuccess to find a backup bundle. If one is found, thecollector will restore its configuration from the backupbundle. If more than one backup bundle is found, theconfiguration is restored from the latest one.


CTGEZ8606W Enterprise Common Collector cannotrestore from the backup bundle at {0};therefore a default configuration wascreated.

Explanation: The Enterprise Common Collector wasstarted with an empty database and was not able torestore from the latest backup bundle. A default



configuration was created and is used to initialize thedatabase.

System action: The system continues to run with thedefault configuration.


CTGEZ8607E Backup bundle created at time {0}already exists on disk.

Explanation: The Enterprise Common Collector triedto create a backup bundle for with a particulartimestamp, but that bundle already exists.

System action: The system continues to run withoutcreating a backup bundle.


Enterprise Common Collector command line interface messagesEnterprise Common Collector command line interface messages begin with the prefix CTGEZ.

Use the information in this section to understand the CLI messages found in the Enterprise CommonCollector message log.

Table 20. Message log locations for ECC command line interface messages

Platform Location

Linux or UNIX <install_dir>/logs/ctgez_cli.log

Windows <install_dir>\logs\ctgez_cli.log

CTGEZ9800E The administrator CLI cannot find thefile {0} specified.

Explanation: The file specified with the administratorcommand line interface (CLI) cannot be found.

System action: No action fails.

User response: Check the file name and try again.

CTGEZ9801W No ECC session exists.

Explanation: The Enterprise Common Collector (ECC)accepts requests only from a valid session. No activesession opened with Enterprise Common Collector.

System action: No action is taken.

User response: Start a session with EnterpriseCommon Collector by logging in.

CTGEZ9802W A session with the ECC is alreadyactive.

Explanation: The administrator command lineinterface allows only one active command line sessionwith the Enterprise Common Collector (ECC). There isalready an active session.

System action: The attempt to open a second sessionfails.

User response: Use this existing session, or log off theexisting session and start a new session.

CTGEZ9803I User {0} successfully logged on to theECC.

Explanation: The Enterprise Common Collectoraccepted the user credentials and started a session withthe user.


CTGEZ9805W Nested command files are notsupported. Command {0} not executed.

Explanation: The system does not allow nestedcommand files. Running a command file inside acommand file is not allowed.

System action: Any commands in the nestedcommand file are not executed.

User response: Run the commands in the nestedcommand file separately.

CTGEZ9806E The operation {0} is not valid.

Explanation: The operation specified in this commandis not supported by the administrator command lineinterface.

System action: The command is not executed.

User response: Type help <object> (where object isone of the following: data-sources, collection-profiles,clients, loggers, or authentication or one of the utilitycommands, logon or logoff) to see a list of validparameters. To continue running the commands in thecommand file, use # to comment out commands thathave already run and run the command file again.

CTGEZ9807E Required operation statement ismissing.



Explanation: No operation was provided in the theadministrator command line interface operationstatement.



CTGEZ9808E Required parameters are missing.

Explanation: All of the parameters required to run thefailing command were not provided.



CTGEZ9809E Command {0} is not valid.

Explanation: The command entered is not a validcommand.


User response: Construct a valid command and trythe command again.

CTGEZ9810I Command {0} completed.

Explanation: The specified command was successfullyimplemented by the Enterprise Common Collector.


CTGEZ9811E Authentication failed for user {0}.

Explanation: Authentication failed during logon to theEnterprise Common Collector (ECC) due to an invalidor expired password or a client that is currentlydisabled, does not exist, or whose access is locked dueto too many invalid logon attempts.

System action: The user is not logged on to the ECC.

User response: Check the user name and passwordand try again. A user with Administrator authorityneeds to delete the user name and add it again, or resetthe number of invalid attempts allowed.

CTGEZ9812E Parameter {0} is not valid.

Explanation: The parameter entered is not supportedby the administrator command line interface (CLI).

System action: The command is not executed


CTGEZ9813E No value specified for parameter {0}.

Explanation: The value for the specified parameterwas not provided.


User response: Specify values for all requiredparameters and try the command again.

CTGEZ9814E System error.

Explanation: The input caused an internal systemerror.


User response: Check the input to ensure that it meetsthe command line interface requirements and try thecommand again.

CTGEZ9815E The user {0} is not authorized to issueECC administrative commands.

Explanation: The administrator role is not defined forthe user ID attempting to issue commands using theEnterprise Common Collector (ECC) administratorcommand line interface.


User response: Logoff from the current session andstart a new session as an administrator.

CTGEZ9816E The logging level specified is not avalid Java logging level.

Explanation: The logging level should be one of thevalid Java logging levels: OFF, SEVERE, WARNING,INFO, CONFIG, FINE, FINER, FINEST, or ALL.


User response: Provide a valid Java logging level.



CTGEZ9817E The administrator command lineinterface (CLI) cannot connect to theEnterprise Common Collector.

Explanation: The administrator command lineinterface (CLI) cannot connect to the EnterpriseCommon Collector (ECC). Possible causes are using aport that is not secure, using an invalid port, or theECC server is down.

System action: No connection was made to the ECC.

User response: Ensure that the ECC server is up andrunning and that you specified the correct port.

CTGEZ9818I Executing command {0}.

Explanation: The administrator command lineinterface (CLI) is currently executing the specifiedcommand.

User response: No action is neccessary.

CTGEZ9819I Command return code {0}.

Explanation: The command line interface (CLI)command executed with the specified return code.

User response: To understand the return code, refer tothe installation guide explanation for the correspondingAPI.

CTGEZ9820E The command syntax is not valid.

Explanation: Something in the command syntax isincorrect.

User response: Check the command to ensure that itmeets the command line interface requirements. To seethe correct syntax, type help <object> (where object isone of the following: data-sources, collection-profiles,clients, loggers, or authentication or one of the utilitycommands, logon or logoff) to see a list of validparameters.



Chapter 10. Migrating and backing up the Enterprise CommonCollector by using the Migration Manager

The Enterprise Common Collector provides two related backup and migration features:v A method for manually creating and restoring a backup of the collectorv A second method for automatically creating backups that can be used to restore if the collector is

started with an empty database (for example, after upgrading to another version)

Both features are part of a component referred to as the Migration Manager.

Manual backups are created and restored using the Administrator ReST API. These backups areencrypted with a user-provided passphrase. Therefore, you may safely store these backups in anenvironment outside the control of the Enterprise Common Collector.

Automatic backups are stored in a directory controlled by the Enterprise Common Collector and arestored under the collector’s installation path.

Both types of backups contain the following data:v Configuration data from the Enterprise Common Collector database (such as the clients, data sources,

and collection profiles that you created during configuration)v Certificates from the collector’s truststore, the masterkey-file, the information required to encrypt and

decrypt the System z Hardware Management Console passwords in the database

These various types of backed-up data are referred to collectively as a backup bundle.

Inventory data and metrics are not included in the backup bundle because they can (and for the mostaccurate view of the enterprise, should) be gathered after a backup is restored.

Manual backupTo create or restore a manual backup bundle, use the following ReST APIs issued by a user whose ID hasbeen assigned the Administrator role.v “GET /eccapi/admin/backup” on page 205v “POST /eccapi/admin/backup” on page 229

Creating a backup bundle

This request to create a manual backup bundle requires a call to the “GET /eccapi/admin/backup” onpage 205 API and a passphrase that is used to encrypt the returned backup bundle, or else the backupwill fail. This passphrase in provided as HTTP Header Field X-API-Backup-Passphrase. The providedpassphrase must meet the conform to the following rules:v Be between 8 to 50 characters longv Contain at least one digitv Contain at least one lowercase character and at least one uppercase character

Therefore ibmIBMibm1 is a valid passphrase but ibmIBMibm is not valid because it does not contain a digit,and ibm1IBM is not valid because is contains only 7 characters and is too short.

When the backup bundle is created, in addition to the encrypted backup data, it includes metadata suchas the date and timestamp, the version number of the Enterprise Common Collector, self-describing


information (such as self, class, and name), and information about the cryptographic algorithms used tocreate the bundle (required for the collection to know how to decrypt the backup bundle during arestore).

See “GET /eccapi/admin/backup” on page 205 for details about this API and “Managing backups byusing the ReST API” on page 197 for procedural information about using this API.

Restoring a backup bundle

To restore from a backup bundle, the user sends a request to the “POST /eccapi/admin/backup” on page229 API. This request requires that the user provide the passphrase that was also used to encrypt thisbackup bundle as an HTTP Header Field X-API-Backup-Passphrase.

The POST request must provide the backup bundle as JSON content in the exact same format as it isreturned during the creation. Be aware that you cannot manipulate the backup bundle manually, only inthe prescribed manner through the APIs. The encryption-fields contain the information about how thisbackup is encrypted (used algorithms). This information might be required if restored to a newerEnterprise Common Collector version where the default algorithms may have changed. If not provided,such a collector may then have problems knowing how to decrypt the backup. The “backup” fieldcontains the backup data itself, which is the configuration data from the collector database (such asclients and data sources), the masterkey-file and all certificates from the collector truststore. The backupdata first is compressed to reduce the required disk space and then is encrypted. Therefore a manualcompression of such a backup bundle is likely not very effective. Even if parts of the backup bundle arereadable by humans, it should not be changed manually. Doing so will likely result in the collector notbeing able to restore from such a manipulated backup.

The following rules apply when you restore a backup:v Restoring is an exclusive operation, that means after restoring the collector, its database contains

exactly what is in the backup bundle. If, after you created the backup bundle, you imported a newcertificate, for example, this new certificate would be gone after the restore.

v Before you attempt to restore a backup, disable all configured data sources. If the data source isenabled when you start to restore a backup, the restore stops and fails.

v After a successful restore, all restored data sources are disabled and must be enabled manually ifdesired. This action is independent of the status that the data source had at the time when the backupwas created.

v The collector database can always be restored from a backup made from the same product version. Ifyou restore a backup from a back-level product version, the backup operation migrates the data in thebackup to the level of the new version.

v The converse is not true. You cannot restore a backup if the backup bundle is from a version of theproduct newer than the one currently running on the Enterprise Common Collector.

Do not make changes to the backup bundle, even to the files that can easily be read. Changing thebackup bundle outside of the prescribed APIs will make it unusable.

See “POST /eccapi/admin/backup” on page 229 for details about this API and “Managing backups byusing the ReST API” on page 197 for procedural information about using this API.

Automatic backupAutomated backup bundles are created automatically whenever the configuration information for theEnterprise Common Collector is change or whenever the collector is started on a new or otherwise emptydatabase.

Automated backups are triggered in one of these two ways.


Every successful change to the collector’s configuration using the command line interface or the APIsresults in the Migration Manager creating a backup bundle automatically and storing it to disk. Examplesof changes that trigger a new backup include the successful completion of the following types ofconfiguration operations:v Creating new objects or deleting or updating existing onesv Changes to configuration objects like clients, data sources, and collection profilesv Importing or removing certificatesv Updating the “invalid-login-attempt” counter for clients

If a configuration change is requested but fails, no new backup is created. When a backup fails, amessage is written to the log.

An automated backup bundle is not encrypted. Free access to this file from potential users (such as theoperating system) should be provided.

Location of automatic backup bundles

Automated backup bundles are written into a folder controlled by the collector in this location:


Linux or UNIX <install_dir>/wasce/var/ecc/backup/ecc_backup_<timestamp>.json

Where timestamp is the POSIX time of the time when this backup was created (for example,ecc_backup_1331903642085.json).

Windows <install_dir>\wasce\var\ecc\backup\ecc_backup_<timestamp>.json

Where timestamp is the POSIX time of the time when this backup was created (for example,ecc_backup_1331903642085.json).

Figure 33. Flow of automated backup processing

Chapter 10. Migrating and backing up the Enterprise Common Collector by using the Migration Manager 189

Up to five unique backup bundles are stored in this location. When five bundles already exist and a newbundle is created, the oldest bundle is deleted.


Appendix A. Customizing the Enterprise Common Collectorby using the ReST APIs

You can perform customization tasks for the Enterprise Common Collector using the ApplicationProgramming Interface (API) that are part of a Representational State Transfer (ReST) interface.

API requests are sent to the Enterprise Common Collector in JavaScript Object Notation (JSON), alightweight data interchange format based on the object-literal notation of JavaScript. JSON isprogramming-language neutral.

All of the APIs noted in this section require a tool to interact with them. A wide variety of tools isavailable through third parties. Any tool that can support HTTP GET, PUT, POST, and DELETE methodsand is able to display JSON format streams can be used.

The APIs describe functions that are used to develop system automation or other specialized tools. For adescription of the user-directed tool that implements these functions, see Chapter 5, “Customizing theEnterprise Common Collector,” on page 65. To understand more about how the Enterprise CommonCollector web services interface works and how the APIs and the command line implementation arerelated, see “Background on the web services interface.”

These APIs conform to all aspects of Enterprise Common Collector security, including requiring a logonand an established session before they can be executed.

Sets of APIs are available for performing the following tasks:v “Starting and ending an API session” on page 192v “Defining whether the Enterprise Common Collector uses base authentication or LDAP using the ReST

APIs” on page 193v “Setting up collection profiles by using the ReST API” on page 193v “Setting up HMC data sources by using the ReST API” on page 194v “Managing certificates by using the ReST API” on page 195v “Creating, listing, and updating clients by using the ReST API” on page 196v “Setting collector logging levels by using the ReST API” on page 196v “Managing backups by using the ReST API” on page 197

To view all the APIs summarized in a table, see “Enterprise Common Collector configuration APIsoverview” on page 198. This section includes links to descriptions of individual APIs.

Background on the web services interfaceThe Enterprise Common Collector uses a web services interface to implement its APIs.

The web services interface is a request-and-response oriented programming interface by which clientapplications obtain information about the system resources managed by the System z HardwareManagement Console.

As is the case for any web-oriented interface, client applications interact with this interface by means ofthe Hypertext Transfer Protocol (HTTP), an application protocol that flows over TCP/IP socketconnections. Client applications request operations by forming and sending text-oriented requestmessages as defined by HTTP, and the Web Services API responds with text-oriented HTTP responsemessages. The use of HTTP makes the API client-programming-language neutral, and thus accessible to a


wide variety of client applications. Client applications can be developed in programming languages suchas Java, or in scripting languages such as Perl or Python that include extensive support for performingHTTP operations.

The design of the API's mapping to HTTP has been influenced by the Representational State Transfer(ReST) style of interface design. The manageable resources of the system are associated with andidentified by durable URIs, and the basic get, update, create and delete operations on those manageableresources are mapped directly to the HTTP GET, PUT, POST and DELETE methods. Request andresponse data is provided using JavaScript Object Notation (JSON), a simple, open and portable transferrepresentation. Mapping the functions of the API to HTTP in this way simplifies client applicationdevelopment and allows access to the API without the need for extensive client side tooling or librariesas is often the case in other approaches to web services interface design.

Starting and ending an API sessionUse these APIs to establish and delete a session with between the Enterprise Common Collector.

About this task

Almost all operations of the Enterprise Common Collector API are requested and carried out in thecontext of an API session that is used for determining the client's authority to access managed resourcesand performing requested operations.

An API session is an Enteprise Common Collector concept that is independent of and layers on top ofnetwork-related considerations such as a TCP/IP socket connection. As a result, a single API session mayspan multiple TCP/IP socket connect/disconnect sequences from the same client. Sessions are createdupon request from a client by using a logon operation, and may be explicitly terminated by a client usinga logoff operation.

Sessions may also be terminated by the collector due to inactivity when no requests are made using thesession over a period of 6 hours. (This session timeout is not configurable.)

Sessions are identified by clients using a session-id, which is a string of 64 characters that is returned tothe client in the results from a successful logon operation (that is, successful execution of the POST/eccapi/sessions/ API command). This string is generated in a cryptographically-secure manner. Asession-id string is a form of authentication credentials for a user equivalent in power to a user's user IDand password. Because of this, a session-id should be transmitted only within SSL connections.

In order to indicate that subsequent requests are to be performed in the context of a designated session,the client supplies the appropriate session-id to the collector in each such subsequent request. This isdone by supplying the session-id as the value of the X-API-Session HTTP header which is anapplication-specific header defined by and recognized by the collector.

When you perform configuration actions for the Enterprise Common Collector using the command-line,this header information is also passed with each command, but this operation is transparent to you. Butwhen you perform configuration actions programmatically using the APIs, the session_ID is returned in aJSON document as the response to a successful logon procedure. You must use this session_ID as thecontent of the X-API-Session HTTTP header to send any other API commands.

The logon operation is the only operation in the collector API that can be performed without an APIsession, so requests for these operations do not need to provide the X-API-Session HTTP header. All otheroperations are valid only in the context of an API session and thus requests for all other operations mustsupply an X-API-Session header with a valid session-id in order to be successfully executed.


More information about this command-line operations to set up a session (log on) and end a session (logoff), see “Logging on to the Enterprise Common Collector by using the command-line interface” on page70.

Procedure1. To establish a session with the Enterprise Common Collector, a required task before you can use all

other APIs, use this API:POST /eccapi/sessions/

For more information about this API, see “POST /eccapi/sessions/” on page 238.2. To delete a session with the Enterprise Common Collector, use this API:

DELETE /eccapi/sessions/this-session

For more information about this API, see “DELETE /eccapi/sessions/this-session” on page 204.

Defining whether the Enterprise Common Collector uses baseauthentication or LDAP using the ReST APIsUse the APIs described in this section to define how the Enterprise Common Collector authenticates itsclients: using the base mechanism or LDAP.

Procedure1. To determine how the Enterprise Common Collector is configured to handle the authentication of its

clients, that is, whether it is using the basic mechanism or delegating password verification to LDAP,use the following API:GET /eccapi/admin/config/authentication

See “GET /eccapi/admin/config/authentication” on page 216 for more information about this API.2. To update the authentication mechanism that the Enterprise Common Collector uses to authenticate

its clients, from the base authentication to LDAP server or from the LDAP server to the baseauthentication, use this API:PUT /eccapi/admin/config/authentication

See “PUT /eccapi/admin/config/authentication” on page 244 for more information about this API.

What to do next

For information about performing these tasks using the command line, see “Defining whether theEnterprise Common Collector uses base authentication or LDAP by using the command-line” on page 72.

Setting up collection profiles by using the ReST APIUse the APIs described in this section to set up and administer collection profiles for the EnterpriseCommon Collector. To use these APIs, you must be logged onto the Enterprise Common Collector with auser ID that has Administrator access.

About this task

For information about performing these tasks using the command line, see “Setting up the collectionprofile by using the command-line” on page 78.

Appendix A. Customizing the Enterprise Common Collector by using the ReST APIs 193

Procedure1. To list the properties of current collection profiles defined for the Enterprise Common Collector, use

this API:GET /eccapi/admin/collection-profiles

For more information about this API, see “GET /eccapi/admin/collection-profiles” on page 211.2. To list the properties of a specific collection profile defined by name for the Enterprise Common

Collector, use this API:GET /eccapi/admin/collection-profiles/{name}

For more information about this API, see “GET /eccapi/admin/collection-profiles/{name}” on page213.

3. To create a new collection profile, use this API:POST/eccapi/admin/collection-profiles

For more information about this API, see “POST /eccapi/admin/collection-profiles” on page 232.4. To update the description, inventory-resync-interval, long-term-collection-enabled, long-term-interval,

path-accessible collection, or short-term-interval values for a specified Enterprise Common Collectorcollection profile, use this API:PUT /eccapi/admin/collection-profiles/{name}

For more information about this API, see “PUT /eccapi/admin/collection-profiles/{name}” on page242.

5. To delete the collection profile specified by name on the Enterprise Common Collector, use this API.Note that a collection profile that is in use by one or more data sources cannot be deleted.DELETE /eccapi/admin/collection-profiles/{name}

For more information about this API, see “DELETE /eccapi/admin/collection-profiles/{name}” onpage 201.

Setting up HMC data sources by using the ReST APIUse the APIs described in this section to set up data sources for the Enterprise Common Collector. To usethese APIs, you must be logged onto the Enterprise Common Collector with a user ID that hasAdministrator access.

About this task

For information about performing these tasks using the command line, see “Setting up HMC data sourcesby using the command-line” on page 83.

Procedure1. To list existing System z Hardware Management Consoles (HMCs) defined as data sources for the

Enterprise Common Collector, use this API:GET /eccapi/admin/data-sources

For more information about this API, see “GET /eccapi/admin/data-sources” on page 225.2. To list the properties of a named System z Hardware Management Consoles (HMCs) data source by

name for the Enterprise Common Collector, use this API:GET /eccapi/admin/data-sources/{name}

For more information about this API, see “GET /eccapi/admin/data-sources/{name}” on page 227.


3. To create a specified System z Hardware Management Console as a data source for the EnterpriseCommon Collector, use this API:POST /eccapi/admin/data-sources

For more information about this API, see “POST /eccapi/admin/data-sources” on page 236.4. To update the description, enabled state, name, hmc-hostname, hmc-user, and hmc-user-pwd values

for the Enterprise Common Collector, use this API:PUT /eccapi/admin/data-sources/{name}

For more information about this API, see “PUT /eccapi/admin/data-sources/{name}” on page 252.5. To delete a specified data source from the Enterprise Common Collector database, use this API:

DELETE /eccapi/admin/data-sources/name

For more information about this API, see “DELETE /eccapi/admin/data-sources/{name}” on page203.

Managing certificates by using the ReST APIUse these APIs to manage Enterprise Common Collector security certificates. To use these APIs, you mustbe logged onto the Enterprise Common Collector with a user ID that has Administrator access.

About this task

You can specify whether all certificates should be trusted. You can also list all the certificates in theEnterprise Common Collector truststore, import certificates from other sources, and delete certificates.You can perform these certificate operations even if the "trust-all" property is enabled.

More information about this command-line operations to perform these actions, see “Managingcertificates by using the command-line” on page 73.

Procedure1. To list all the certificates in the truststore of the Enterprise Common Collector, use this API:

GET /eccapi/admin/config/certificates/

For more information about this API, see “GET /eccapi/admin/config/certificates/” on page 217.2. To list the properties of a certificate for a specific alias in the Enterprise Common Collector, use this

API:GET /eccapi/admin/config/certificates/{alias}

For more information about this API, see “GET /eccapi/admin/config/certificates/{alias}” on page219.

3. To list the current setting for the “trust all certificates” option, use this API:GET /eccapi/admin/config/certificates/trust-all

For more information about this API, see “GET /eccapi/admin/config/certificates/trust-all” on page221.

4. To import a certificate into the Enterprise Common Collector and assign it the alias specified by{alias}, a value that you supply, use this API:PUT /eccapi/admin/config/certificates/{alias}

For more information about this API, see “PUT /eccapi/admin/config/certificates/{alias}” on page247.

5. To delete a certificate from the Enterprise Common Collector truststore, us the following API:


DELETE /eccapi/admin/config/certificates/{alias}

When you delete a certificate, you must specify the alias (the same alias that you used to store thecertificate in your database). For more information about this API, see “DELETE/eccapi/admin/config/certificates/{alias}” on page 201.

Creating, listing, and updating clients by using the ReST APIUse these APIs to create, read, and update clients who have access to the Enterprise Common Collector.To use these APIs, you must be logged onto the Enterprise Common Collector with a user ID that hasAdministrator access.

About this task

For information about performing these tasks using the command line, see “Creating, listing, updating,and deleting clients by using the command-line” on page 75.

Procedure1. To list the clients configured in the Enterprise Common Collector, use this API:

GET /eccapi/admin/clients

See “GET /eccapi/admin/clients” on page 206 for more information about this API.2. To list the attributes of a specific client defined in Enterprise Common Collector, use this API:

GET /eccapi/admin/clients/{client-name}

See “GET /eccapi/admin/clients/{client-name}” on page 209 for more information about this API.3. To update the attributes of a specific client configured in the Enterprise Common Collector, use this

API:PUT /eccapi/admin/clients/{client-name}

See “PUT /eccapi/admin/clients/{client-name}” on page 240 for more information about this API.4. To unlock a client that has been locked due to too many invalid login attempts to the Enterprise

Common Collector, use this API:PUT /eccapi/admin/clients/{client-name}/resume

See “PUT /eccapi/admin/clients/{client-name}/resume” on page 242 for more information about thisAPI.

5. To create a client for the Enterprise Common Collector, use this API:POST /eccapi/admin/clients

See “POST /eccapi/admin/clients/” on page 230 for more information about this API.6. To delete the client specified with client-name from the Enterprise Common Collector database, use

this API.DELETE /eccapi/admin/clients/{client-name}

See “DELETE /eccapi/admin/clients/{client-name}” on page 200 for more information about this API.

Setting collector logging levels by using the ReST APIUse these APIs to manipulate logging levels in the Enterprise Common Collector. To use these APIs, youmust be logged onto the Enterprise Common Collector with a user ID that has Administrator access.


About this task

For information about performing this task using the command line, see“Setting collector logging levelsby using the command-line” on page 86.

Procedure1. To list the loggers configured for the Enterprise Common Collector, use this API:

GET /eccapi/admin/config/loggers

See “GET /eccapi/admin/config/loggers” on page 221 for more information about the API.2. To list the level of the logger specified with logger-name that is currently configured for the Enterprise

Common Collector, use this API:GET /eccapi/admin/config/loggers/{logger-name}

See “GET /eccapi/admin/config/loggers/{logger-name}” on page 223 for more information about theAPI.

3. To create a logger for the Enterprise Common Collector, use this API:POST /eccapi/admin/config/loggers

See “POST /eccapi/admin/config/loggers” on page 234 for more information about the API.4. To update the level of a the logger specified with logger-name that is currently configured for the

Enterprise Common Collector, use this API:PUT /eccapi/admin/config/loggers/{logger-name}

See “PUT /eccapi/admin/config/loggers/{logger-name}” on page 250 for more information about theAPI.

5. To delete the logger specified with logger-name that is currently configured for the Enterprise CommonCollector, use this API:DELETE /eccapi/admin/config/loggers/{logger-name}

See “DELETE /eccapi/admin/config/loggers/{logger-name}” on page 202 for more information aboutthe API.

Managing backups by using the ReST APIUse the APIs described in this section to create and restore backups for the Enterprise Common Collector.

About this task

The Migration Manager saves its configuration within the CDMCCE-configuration-object in the database.For more information about migration and backup bundles, see Chapter 10, “Migrating and backing upthe Enterprise Common Collector by using the Migration Manager,” on page 187.

Procedure1. To create a backup bundle for the Enterprise Common Collector, use this API:

GET /eccapi/admin/backup

For more information about this API, see “GET /eccapi/admin/backup” on page 205.2. To restore a backup bundle created for the Enterprise Common Collector, use this API:

POST /eccapi/admin/backup

For more information about this API, see “POST /eccapi/admin/backup” on page 229


Enterprise Common Collector configuration APIs overviewThe ReST APIs for configuration handle Enterprise Common Collector (ECC) requests.

Overview

These APIs provide functionality that system administrators can use to set, query, and deleteconfiguration parameters and to automate configuration actions. They control the settings for allapplications using the HTTP Server API on the system.

These APIs conform to all aspects of Enterprise Common Collector security, including requiring a logonand an established session before they can be executed.

The following APIs are provided:

Table 21. Enterprise Common Collector APIs

API Function

“DELETE /eccapi/admin/clients/{client-name}” on page 200 Deletes the client specified with client-namefrom the Enterprise Common Collectordatabase.

“DELETE /eccapi/admin/collection-profiles/{name}” on page 201 Delete a collection profile for the userspecified by name on the EnterpriseCommon Collector.

“DELETE /eccapi/admin/config/certificates/{alias}” on page 201 Deletes a certificate with a specified aliasfrom the Enterprise Common Collectortruststore.

“DELETE /eccapi/admin/config/loggers/{logger-name}” on page 202 Deletes the logger specified withlogger-name that is currently configured forthe Enterprise Common Collector.

“DELETE /eccapi/admin/data-sources/{name}” on page 203 Deletes the data source specified with namefrom the Enterprise Common Collectordatabase.

“DELETE /eccapi/sessions/this-session” on page 204 Deletes a session with the EnterpriseCommon Collector.

“GET /eccapi/admin/backup” on page 205 Creates a backup bundle for the EnterpriseCommon Collector.

“GET /eccapi/admin/clients” on page 206 Lists the clients configured in theEnterprise Common Collector.

“GET /eccapi/admin/clients/{client-name}” on page 209 Lists the attributes of a specific clientdefined in Enterprise Common Collector.

“GET /eccapi/admin/collection-profiles” on page 211 Lists the properties of collection profilesdefined for the Enterprise CommonCollector.

“GET /eccapi/admin/collection-profiles/{name}” on page 213 Lists the properties of the collection profiledefined by name for the EnterpriseCommon Collector.

“GET /eccapi/admin/config/authentication” on page 216 Lists how the Enterprise Common Collectoris configured to handle the authenticationof its clients, that is, whether it is using thebasic mechanism or delegating passwordverification to LDAP.

“GET /eccapi/admin/config/certificates/” on page 217 Lists all the certificates in the truststore ofthe Enterprise Common Collector.


Table 21. Enterprise Common Collector APIs (continued)

API Function

“GET /eccapi/admin/config/certificates/{alias}” on page 219 Lists the properties of a certificate for aspecified alias in the Enterprise CommonCollector.

“GET /eccapi/admin/config/certificates/trust-all” on page 221 Lists the current setting for the “trust allcertificates” option.

“GET /eccapi/admin/config/loggers” on page 221 Lists the loggers configured for theEnterprise Common Collector.

“GET /eccapi/admin/config/loggers/{logger-name}” on page 223 Lists the level of a the logger specified withname that is currently configured for theEnterprise Common Collector.

“GET /eccapi/admin/data-sources” on page 225 Lists the existing System z HardwareManagement Consoles (HMCs) defined asdata sources in the Enterprise CommonCollector.

“GET /eccapi/admin/data-sources/{name}” on page 227 Lists the properties of a named System zHardware Management Consoles (HMCs)data source specified by name.

“POST /eccapi/admin/backup” on page 229 Restores a backup bundle created for theEnterprise Common Collector.

“POST /eccapi/admin/clients/” on page 230 Creates a client on the Enterprise CommonCollector.

“POST /eccapi/admin/collection-profiles” on page 232 Creates a collection profile for theEnterprise Common Collector.

“POST /eccapi/admin/config/loggers” on page 234 Create a logger for the Enterprise CommonCollector.

“POST /eccapi/admin/data-sources” on page 236 Creates a data source for the EnterpriseCommon Collector.

“POST /eccapi/sessions/” on page 238 Establishes a session with the EnterpriseCommon Collector, a required task beforeyou can use all other APIs.

“PUT /eccapi/admin/clients/{client-name}” on page 240 Updates the attributes of a specific clientspecified by client-name configured in theEnterprise Common Collector.

“PUT /eccapi/admin/clients/{client-name}/resume” on page 242 Unlock a client specified with client-namethat has been locked due to too manyinvalid login attempts for the EnterpriseCommon Collector.

“PUT /eccapi/admin/collection-profiles/{name}” on page 242 Updates the property values for thecollection-profile specified with name forthe Enterprise Common

“PUT /eccapi/admin/config/authentication” on page 244 Updates the authentication mechanism thatthe Enterprise Common Collector uses toauthenticate its clients: the basic mechanismor an LDAP server.

“PUT /eccapi/admin/config/certificates/{alias}” on page 247 Imports a certificate into the EnterpriseCommon Collector and assigns it the aliasspecified by alias . You select the value foralias.

“PUT /eccapi/admin/config/certificates/trust-all” on page 249 Updates the configuration of the truststorein the Enterprise Common Collector.


Table 21. Enterprise Common Collector APIs (continued)

API Function

“PUT /eccapi/admin/config/loggers/{logger-name}” on page 250 Updates the level of a the logger specifiedwith logger-name that is currentlyconfigured for the Enterprise CommonCollector.

“PUT /eccapi/admin/data-sources/{name}” on page 252 Updates the data source specified by namethat is currently configured for theEnterprise Common Collector.

DELETE /eccapi/admin/clients/{client-name}Use this API to delete the client specified with client-name from the Enterprise Common Collectordatabase.

Any sessions that deleted clients had with the Enterprise Common Collector are automatically destroyedwhen the client is deleted. Message CTGEZ0712I reports how many active sessions were destroyedbecause this client was deleted.

Role

User IDs with Administrator authorization can issue this API.

Properties

No properties are required to send this API. No properties are returned unless there is an error.

The following is a path parameter:

Property DefinitionRequired oroptional Usage notes

client-name The name of the client. Required

Status codes

Possible response status codes are as follows:

Status code Meaning

204 NO CONTENT. This status code is returned if the request is successful.

404 NOT FOUND. This status code is returned if no client exists with the specified name.

500 INTERNAL SERVER ERROR. This status code is returned if an unexpected internal erroroccurs. Look for a message containing more information in the message log.

Example requestDELETE /eccapi/admin/clients/jdoe

Example response

The response body will be empty unless there is an error.


DELETE /eccapi/admin/collection-profiles/{name}Use this API to delete the collection profile specified with name from the Enterprise Common Collector.Note that a collection profile that is in use by one or more data sources cannot be deleted.

Role


Properties




name The name assigned to thiscollection profile.

Required

Status codes


Status code Meaning


400 BAD REQUEST. This code is returned if the collection profile cannot be deleted because datasources are configured to use it.

404 NOT FOUND. This code is returned if the collection profile cannot be found.

500 INTERNAL SERVER ERROR. This code is returned if an unexpected internal error occurs.Look for a message containing more information in the message log.

Example requestDELETE /eccapi/admin/collection-profiles/raleigh

Example response


DELETE /eccapi/admin/config/certificates/{alias}This API is used to delete a certificate with the specified alias from the Enterprise Common Collectortruststore.

To work with a certificate, you must know the alias for the certificate. This alias was assigned by the userwhen the certificate is imported.

Role



Properties




alias The alias name that youassigned this certificate.

Required

Status codes


Status code Meaning


404 NOT FOUND. This status code is returned if no certificate exists with the specified alias.

500 INTERNAL SERVER ERROR. The status code is returned if an unexpected internal erroroccurs. Look for a message containing more information in the message log.

Example requestDELETE /eccapi/admin/config/certificates/mycertificate

Example response


DELETE /eccapi/admin/config/loggers/{logger-name}Use this API to delete the logger specified with logger-name that is currently configured for the EnterpriseCommon Collector.

Overview

Deleting a logger does not mean that no logging occurs for that component, but rather that loggingoccurs based on the nearest parent logger. At the very least, there is always one default logger with thename “gez” that determines logging for the entire Enterprise Common Collector. This default logger cannever be deleted.

Role


Properties





logger-name A text string beginning with“gez” that specifies whatsection of code the loggerapplies to. This is the sameas name but logger-nameshows how this property isreferenced in the URI.

Required

Status codes


Status code Meaning


400 BAD REQUEST. This status code is returned if you attempt to delete the root “gez” logger.

404 NOT FOUND. The status code is returned if the specified logger no longer exists.


Example requestDELETE /eccapi/admin/config/loggers/gez-persistence

Example response


DELETE /eccapi/admin/data-sources/{name}Use this API to delete the data source specified with name from the Enterprise Common Collectordatabase.

Role


Properties




name The unique name of the datasource to delete.

Required


Status codes


Status code Meaning

204 NO CONTENT. This status code indicates a successful response.

400 BAD REQUEST. This status code is returned if the data source if enabled or connected andcannot be deleted.

404 NOT FOUND. This status code is returned if no data source exists with the specified name.

500 INTERNAL SERVER ERROR This status code indicates that an unexpected internal error hasoccurred. Look for a message containing more information in the message log.

Example requestDELETE /eccapi/admin/data-sources/raleigh

Example response


DELETE /eccapi/sessions/this-sessionWhen a session is no longer required, it can be deleted. Use this API to delete a session with theEnterprise Common Collector.

Header fields

For this API and all APIs except POST /eccapi/sessions/, this API required to send the session-id as theX-API-Session HTTP Header field. The session identified by the session-id in this Header field isdestroyed.

Role

This API can be used to destroy all sessions, independent from the roles that are assigned to the client,that owns the session.

Properties

No properties are required to send this API.

No properties are returned by this API.

Status codes


Status code Meaning

204 NO CONTENT. This status code indicates that a session was successfully destroyed.

Example requestDELETE /eccapi/sessions/this-session


Example response

No content is returned by this API.

GET /eccapi/admin/backupUse this API to create a backup bundle for the Enterprise Common Collector.

Role


Header fields

Header field Definition Usage notes

X-API-Backup-Passphrase Creating a backup bundle requires apassphrase that is used to encrypt thereturned backup bundle. Thispassphrase is provided as HTTPHeader Field X-API-Backup-Passphrase.

The provided passphrase must meet theconform to the following rules:

v Be between 8 to 50 characters long

v Contain at least one digit

v Contain at least one lowercasecharacter and at least one uppercasecharacter

For example, ibmIBMibm1 is a validpassphrase but ibmIBMibm is not validbecause it does not contain a digit,and ibm1IBM is not valid because iscontains only 7 characters and is tooshort.

Properties

No properties are required to send this API. The following properties are returned:

Property Definition Usage notes

self The uniform resource identifier (URI)that is called for creating a backup.

A non-configurable value:/eccapi/admin/backup.

class The class of this entity. A non-configurable value: ecc-backup

name The name of the backup A non-configurable value: ECC backup

description The description of the backup A non-configurable value: Backup ofthe ECC configuration

version This is the version of the Enterprisecommon Collector with which thisbackup was created.

For example, 1.1.

date The time when the backup was created. For example, “Thu Mar 15 16:16:27CET 2012”.

timestamp The time when the backup was createdin POSIX time

For example, "1331824587717".

backup The encrypted backup data.

encryption-keygen-algorithm The algorithm used to encrypt thisbackup.

For example, AES (AdvancedEncryption Standard).

encryption-keygen-derivation-algorithm

The algorithm used to derive a keyfrom the passphrase.

For example,“PBKDF2WithHmacSHA1”.



encryption-key-length The length, measured in bits, of the keyused in a cryptographic algorithm(such as a cipher).

The default size is 128 bits.

encryption-cipher-transformation A string that describes the operation (orset of operations) to be performed onthe given input, to produce someoutput. A cipher transformationincludes the name of a cryptographicalgorithm (for example, AES), and maybe followed by a feedback mode andpadding scheme.

For example, “AES/CBC/PKCS5Padding”.

Status codes


Status code Meaning

200 OK. This code is returned if the request is successful and the response data is returned.

400 BAD REQUEST. This status code is returned if no passphrase or a weak passphrase wasprovided.


Example requestGET /eccapi/admin/backupX-API-Backup-Passphrase: My123Passphrase

Example response{

"self": "/eccapi/admin/backup","class": "ecc-backup","name": "ECC backup","description": "Backup of ECC configuration.","version": "1.1","date": "Thu Mar 15 16:16:27 CET 2012","timestamp": "1331824587717","backup": "<ENCRYPTED_DATA>","encryption-keygen-algorithm": "AES","encryption-keygen-derivation-algorithm": "PBKDF2WithHmacSHA1","encryption-key-length": 128,"encryption-cipher-transformation": "AES/CBC/PKCS5Padding"

}

GET /eccapi/admin/clientsUse this API to list the clients configured in the Enterprise Common Collector.

Role



Properties

No properties are required to send this API. The following properties are returned for each client:


name The name of the client. This is theuser ID that the client will use tologon to the Enterprise CommonCollector.

description A text string between 1 and 256characters describing the client

Optional

password The password that the client willuse to logon to the EnterpriseCommon Collector. For securitypurposes the password will alwaysbe ********.

Optional if the collector is configured to use LDAPfor authentication. Otherwise, required.

roles One or more of the three rolesdefined for all Enterprise CommonCollector clients:

v Administrator role that canperform administrative tasks,such as creating data sources orclients

v Explorer role that can performdiscovery tasks, such asdiscovering all virtual servers

v Operator role that can performmonitoring and discover tasks,such at retrieving detailedinformation about virtual serversand their performance metrics

Multiple roles can be defined for aclient. For any one client to haveaccess to all aspects of the collector,all three roles must be defined.These roles are initial capitalizedand are listed on a single line andseparated by commas andsurrounded by brackets [ ].

At least one role is required.

enabled Indicates whether the client isenabled. If the client is notenabled, logon will not bepermitted.

invalid-login-attempts Indicates how many unsuccessfullogin attempts have occurred sincethe last successful login

password-expiration-enabled

Indicates if the passwordexpiration for this specific client isenabled.



password-expiration Indicates when the password willexpire. This is indicated by aninteger specifying the number ofmilliseconds since January 1, 1970GMT. This field is ignored if thepassword-expiration-enabled fieldis set to false.

class The class to which this entitybelongs.

self The uniform resource identifier(URI) of this client.

Status codes


Status code Meaning

200 OK. This code is returned if the request is successful.


Example requestGET /eccapi/admin/clients

Example response

The example that follows shows three sample clients returned by this API.{“class” : “client”,“description” : “default admin user”,“invalid-login-attempts” : 0,“enabled” : true,“name” : “admin”,“password” : “********”,“password-expiration” : 1318533734968,“password-expiration-enabled” : true,“roles” : [ “Administrator” ],“self” : “/eccapi/admin/clients/admin”},{“class” : “client”,“description” : “Client One”,“invalid-login-attempts” : 1,“enabled” : true,“name” : “clientone”,“password” : “********”,“password-expiration” : 1318533747062,“password-expiration-enabled” : false,“roles” : [ “Operator”, “Explorer” ],“self” : “/eccapi/admin/clients/clientone”},{“class” : “client”,“description” : “Client Two”,“invalid-login-attempts” : 0,“enabled” : true,“name” : “clienttwo”,


“password” : “********”,“password-expiration” : 1318533748713,“password-expiration-enabled” : false,“roles” : [ “Administrator” ],“self” : “/eccapi/admin/clients/clienttwo”

GET /eccapi/admin/clients/{client-name}Use this API to list the attributes of the client specified by client-name that is defined in EnterpriseCommon Collector.

Role


Properties




client-name The name of the client. Thisis the user ID that the clientuses to logon to theEnterprise CommonCollector.

Required

The following properties are returned by this API:


name The name of the client. This is theuser ID that the client will use tologon to the Enterprise CommonCollector.

description A description of the client. Optional

password The password that the client willuse to logon to the EnterpriseCommon Collector. For securitypurposes the password will alwaysbe ********.

Optional if the collector is configured to use LDAPfor authentication. Otherwise, required.



roles One or more of the three rolesdefined for all Enterprise CommonCollector clients:

v Administrator role that canperform administrative tasks,such as creating data sources orclients

v Explorer role that can performdiscovery tasks, such asdiscovering all virtual servers

v Operator role that can performmonitoring and discovery tasks,such at retrieving detailedinformation about virtual serversand their performance metrics

Multiple roles can be defined for aclient. For any one client to haveaccess to all aspects of the collector,all three roles must be defined.These roles are initial capitalizedand are listed on a single line andseparated by commas andsurrounded by brackets [ ].

At least one role is required.

enabled Indicates whether the client isenabled. If the client is notenabled, logon will not bepermitted.

invalid-login-attempts Indicates how many unsuccessfullogin attempts have occurred sincethe last successful login.


Indicates if the passwordexpiration for this specific client isenabled.

password-expiration Indicates when the password willexpire. This is indicated by aninteger specifying the number ofmilliseconds since January 1, 1970GMT. This field is ignored if thepassword-expiration-enabled fieldis set to false.


self The uniform resource identifier(URI) of this resource.

Error Codes


Status code Meaning

200 OK. This status code is returned if the request is successful.

404 NOT FOUND. This status code is returned if no client with the specified name is found.


Status code Meaning


Example RequestGET /eccapi/admin/clients/UserA

Example Response

This is a sample of the information returned by the API.{“class” : “client”,“description” : “User Alpha”,“invalid-login-attempts” : 1,“enabled” : true,“name” : “userA”,“password” : “********”,“password-expiration” : 1318533747062,“password-expiration-enabled” : true,“roles” : [ “Operator”, “Explorer” ],“self” : “/eccapi/admin/clients/userA”}

GET /eccapi/admin/collection-profilesUse this API to list the properties of collection profiles defined for the Enterprise Common Collector.

Role


Properties


The following properties are returned. Note that you can change the values in the default collectionprofile, so the values specified here are the provided defaults and might be different if you have resetthem.


name A text string between 1 and 16characters in length providing aname or label for the collectionprofile.

The name of the default profile is default.

description A text string between 1 and 256characters describing the collectionprofile.

Optional

short-term-interval An integer between 60 and 600inclusive describing the amount oftime, in seconds, between retrievalsof the current set of metrics fromthe System z HardwareManagement Console (HMC).

The value of this attribute in the defaultcollection-profile is 60 seconds.



long-term-interval An integer between 300 and 1800inclusive describing the amount oftime, in seconds, between retrievalsof the current set of historicalmetrics from the System zHardware Management Console(HMC).

Optional. The value of this attribute in the defaultcollection-profile is 900 seconds.

inventory-resync-interval An integer between 300 and 86400inclusive describing the amount oftime, in seconds, that passes beforethis client resynchronizes inventorywith the System z HardwareManagement Console (HMC).


long-term-collection-enabled

Defines whether long-termcollection is enabled, meaningwhether historical metrics data isretrieved from the System zHardware Management Console(HMC). Valid values are true,meaning that long-term collectionis enabled and false, meaning it isnot.

path-accessible-collection-enabled

Defines whether path accessibilitystatus collection is enabled for thisSystem z Hardware ManagementConsole (HMC). This valuedetermines whether pathaccessibility status is collected foreach virtualization host storageresource in the inventory.

When virtualization host storageresource information is retrievedfrom the HMC, no informationabout whether the storage resourceis currently accessible to thevirtualization host via each path isretrieved. This is because pathaccessibility status can be timeconsuming to determine. After allinventory has been gathered, anoptional post processing step willgather this status information ifthis property is set to true.

Valid values are true, meaning thatpath accessible collection isenabled and false, meaning it isnot.

class The class to which this entitybelongs (collection-profile).

self The uniform resource identifier(URI) of this collection profile.


Status codes


Status code Meaning



Example requestGET /eccapi/admin/collection-profiles

Example response

This API shows three defined configuration-profiles with different characteristics.[{"class" : "collection-profile","description" : "default collection profile","inventory-resync-interval" : 3600,"long-term-collection-enabled" : true,"long-term-interval" : 900,"name" : "default","path-accessible-collection-enabled" : true,"self" : "/eccapi/admin/collection-profiles/1","short-term-interval" : 60},{"class" : "collection-profile","inventory-resync-interval" : 7200,"long-term-collection-enabled" : false,"name" : "one-interval-only","path-accessible-collection-enabled" : false,"self" : "/eccapi/admin/collection-profiles/101","short-term-interval" : 450},{"class" : "collection-profile","inventory-resync-interval" : 86400,"long-term-collection-enabled" : true,"long-term-interval" : 1800,"name" : "less frequent","path-accessible-collection-enabled" : true,"self" : "/eccapi/admin/collection-profiles/102","short-term-interval" : 600}]

GET /eccapi/admin/collection-profiles/{name}Use this API to list the properties of a specific collection profile defined in name for the EnterpriseCommon Collector.

Role



Properties




name A text string between 1 and16 characters providing aname or label for thecollection profile.

Required

The following properties are returned. Note that you can change the values in the default collectionprofile, so the values specified here are the provided defaults and might be different if you have resetthem.


name A text string between 1 and 16characters in length providing aname or label for the collectionprofile.

The name of the default profile is default.

description A text string between 1 and 256characters describing the collectionprofile.

Optional

short-term-interval An integer between 60 and 600inclusive describing the amount oftime, in seconds, between retrievalsof the current set of metrics fromthe System z HardwareManagement Console (HMC).


long-term-interval An integer between 300 and 1800inclusive describing the amount oftime, in seconds, between retrievalsof the current set of historicalmetrics from the System zHardware Management Console(HMC).

Optional. The value of this attribute in the defaultcollection-profile is 900 seconds.

inventory-resync-interval An integer between 300 and 86400inclusive describing the amount oftime, in seconds, that passes beforethis client resynchronizes inventorywith the System z HardwareManagement Console (HMC).



Defines whether long-termcollection is enabled, meaningwhether historical metrics data isretrieved from the System zHardware Management Console(HMC). Valid values are true,meaning that long-term collectionis enabled and false, meaning it isnot.

Optional




Defines whether path accessibilitystatus collection is enabled for thisSystem z Hardware ManagementConsole (HMC). This valuedetermines whether pathaccessibility status is collected foreach virtualization host storageresource in the inventory.

When virtualization host storageresource information is retrievedfrom the HMC, no informationabout whether the storage resourceis currently accessible to thevirtualization host via each path isretrieved. This is because pathaccessibility status can be timeconsuming to determine. After allinventory has been gathered, anoptional post processing step willgather this status information ifthis property is set to true.

Valid values are true, meaning thatpath accessible collection isenabled and false, meaning it isnot.

class The class to which this entitybelongs (collection-profile).

self The uniform resource identifier(URI) of this collection profile.

Status codes


Status code Meaning


404 NOT FOUND. This status code is returned if no collection profile exists with the specifiedname.


Example requestGET /eccapi/admin/collection-profiles/default

Example response

Here is an example of a returned collection profile:{"class" : "collection-profile","description" : "default collection profile","inventory-resync-interval" : 3600,"long-term-collection-enabled" : true,


"long-term-interval" : 900,"name" : "default","path-accessible-collection-enabled" : true,"self" : "/eccapi/admin/collection-profiles/default","short-term-interval" : 60}

GET /eccapi/admin/config/authenticationUse this API to determine how the Enterprise Common Collector is configured to handle theauthentication of its clients, that is, whether it is using the basic mechanism or delegating passwordverification to LDAP.

Role


Properties

No properties are required to send this API. The following properties are returned by this API:


ldap-user-provider The URL of the LDAP directoryincluding position in the directorytree where user entries are located,in the format: ldap://<hostname>[:<port>]/[user_entry_location>]

This is a subproperty of the ldap-propertiesproperty and like that property, it is present onlywhen ldap-authentication is set to true.

ldap-user-filter The LDAP search filter used tofind a matching user record for thegiven user ID.

Used to determine a user'sdistinguished name. ldap_filter isan LDAP filter string (RFC 2254).


ldap-auth-identity The identity to use whenauthenticating a user to the LDAPdirectory


ldap-use-ssl Whether to use secure socket layer(SSL) communication between theLDAP server and the EnterpriseCommon collector. Valid values aretrue is SSL should be used or falseif it is not.


ldap-properties Whether to specify the additionalLDAP properties.

Required if ldap-authentication is set to true. Notavailable if ldap-authentication is set to false.

ldap-authentication Whether LDAP authentication isrequired. Valid values are true (it isrequired) or false (it is notrequired).

password-expiration-interval

The number of days that a clientpassword is valid when it is reset

No default

name A non-configurable value:Authentication Options




self The uniform resource identifier(URI) of this resource.

Status codes


Status code Meaning

200 OK. This status code indicates a successful response.


Example requestGET /eccapi/admin/config/authentication

Example response: LDAP authentication

This example shows you that the Enterprise Common Collector is using LDAP authentication, because"ldap-authentication": true and the ldap-properties field is returned with a nested JSON object asvalue. The nested JSON object contains the concrete configuration for the LDAP server.

The HTTP 200 OK response looks similar to the following:{"self": "/eccapi/admin/config/authentication/","class" : "authentication","name": "Authentication Options","ldap-authentication": true,"ldap-properties": {"ldap-user-provider": "ldap://ldap_authentication_server","ldap-user-filter": "(&(uid={USERNAME})(objectClass=inetOrgPerson))","ldap-use-ssl": false},"password-expiration-interval": 60}

Where ldap_authentication_server is the fully qualified IP name of the server performing the LDAPauthentication.

Example response: basic authentication

This response indicated that LDAP authentication is disabled. This means that the collector is using thenative basic mechanism to handle authentication.{"self": "/eccapi/admin/config/authentication/","class" : "authentication","name": "Authentication Options","ldap-authentication": false,"password-expiration-interval": 1}

GET /eccapi/admin/config/certificates/This API is used to list all the certificates in the truststore of the Enterprise Common Collector.


Role


Properties

No parameters are required to issue this API.

This API returns the following properties for each certificate:


alias The alias name that you assigned to thiscertificate.

version The version number of the certificate in theEnterprise Common Collector.

name A non-configurable value: CertificateProperties

subject-dn The subject distinguished name value from thecertificate.

issuer-dn The issuer distinguished name value from thecertificate. This name identifies the entity thatsigned (and issued) the certificate.

not-after The date after which this certificate will nolonger be valid.

not-before The date when this certificate is in effect.

serial-number The serial number associated with the certificate.

signature-algorithm-name The signature algorithm name for the certificatesignature algorithm.

signature-algorithm-oid The signature algorithm object identifier stringfrom the certificate.

public-key-algorithm-name

The name of the certificate public key algorithm.

public-key-format The format of this certificate’s public key.

class The Java class to which this operation belongs.

self The uniform resource identifier (URI) of thisrequest.

Status codes


Status code Meaning



Example requestGET /eccapi/admin/config/certificates/


Example response

This API returns a JSON array containing the certificate:[{"alias": "mycert","version": 3,"self": "/eccapi/admin/config/certificates/mycert","class": "certificate","name": "Certificate Properties","subject-dn": "CN=Unknown, OU=Research & Development GmbH,

O=IBM Deutschland, L=Boeblingen, ST=Baden-Wuerttemberg, C=DE","issuer-dn": "CN=Unknown, OU=Research & Development GmbH,

O=IBM Deutschland, L=Boeblingen, ST=Baden-Wuerttemberg, C=DE","not-after": "Wed Mar 09 12:45:23 CET 2011","not-before": "Thu Dec 09 12:45:23 CET 2010","serial-number": "1291895123","signature-algorithm-name": "SHA1withDSA","signature-algorithm-oid": "1.2.840.10040.4.3","public-key-algorithm-name": "DSA","public-key-format": "X.509"}]

GET /eccapi/admin/config/certificates/{alias}Use this API to list the properties of a certificate for a specified alias in the Enterprise Common Collector.

Role


Properties




alias The alias name that youassigned this certificate.

Required

The following properties are returned by the API describing the certificate that was specified by the aliasvalue:

















class The class to which this entitty belongs.

self The uniform resource identifier (URI) of thisresource.

Status codes


Status code Meaning


404 NOT FOUND. This status codes is returned if no certificate exists with the specified alias


Example requestGET /eccapi/admin/config/certificates/{mycert}

Example response

This API returns a JSON array containing the certificate:{"alias": "mycert","version": 3,"self": "/eccapi/admin/config/certificates/mycert","class": "certificate","name": "Certificate Properties","subject-dn": "CN=Unknown, OU=Research & Development GmbH,


O=IBM Deutschland, L=Boeblingen, ST=Baden-Wuerttemberg, C=DE","not-after": "Wed Mar 09 12:45:23 CET 2011","not-before": "Thu Dec 09 12:45:23 CET 2010","serial-number": "1291895123","signature-algorithm-name": "SHA1withDSA","signature-algorithm-oid": "1.2.840.10040.4.3","public-key-algorithm-name": "DSA","public-key-format": "X.509"}


GET /eccapi/admin/config/certificates/trust-allUse this API to list the current setting for the “trust all certificates” property. If it is enabled, theEnterprise Common Collector does not validate the Hardware Management Console certificates whenestablishing an HTTPS connection. This property does not disable the "normal" HTTPS certificatemanagement between WebSphere Application Server Community Edition as a server and clients (such asthe Tivoli zEnterprise Monitoring Agent).

Role


Properties

No properties are required to submit this API.

The following properties are returned by this API:


trust-all-certificates Valid values are true (trust all certificates) or false(do not trust all certificates).

name The unique name of this entity; always “CertificateOptions”.

class The class to which this entity belongs.

self The uniform resource identifier (URI) of thisresource.

Example requestGET /eccapi/admin/config/certificates/trust-all/

Status codes


Status code Meaning



Example requestGET /eccapi/admin/config/certificates/trust-all/

Example response{"self": "/eccapi/admin/config/certificates/trust-all/","class": "trust-all","name": "Certificates Options","trust-all-certificates": false}

GET /eccapi/admin/config/loggersUse this API to list the loggers configured for the Enterprise Common Collector.


Role


Properties


The following properties are returned for each logger:


name A text string beginning with gezthat specifies what section of codethe logger applies to.

The name of the logger. The default logger isnamed gez. When the name is prepended with“com.ibm.tivoli”. The name designates a validEnterprise Common Collector component forcomponent-based logging. See “EnterpriseCommon Collector components” on page 162 for alist of the components. If this name does notspecify a valid logger, then the component-basedlogger has no effect (that is, no validation is doneto ensure that it is a valid component).

level A text string indicating the logginglevel. The level must be one of thefollowing levels.

v OFF: No logging occurs.

v SEVERE: Errors that causepremature termination and otherunexpected errors

v WARNING: Undesirable orunexpected conditions that arenot necessarily wrong

v INFO: Interesting runtime events

v CONFIG: Not supported. If set,shows the same level as INFO.

v FINE: Important events andexceptions

v FINER: Detailed debuginformation, low-level logic,object dumps, and so on

v FINEST: Method entry and exittracing

v ALL: Everything; essentiallyequivalent to FINEST

Note that each level includes all higher levels andapplies not only to that package but to allsubcomponents also (unless the subcomponent hasits own logger defined).

class The Java class to which thisoperation belongs (logger).

enabled Indicates whether logging isenabled.

self The uniform resource identifier(URI) of this logger.


Status codes


Status code Meaning



Example requestGET /eccapi/admin/config/loggers

Example response

This sample shows logging levels set for four components: the logger, the data provider component, theinventory gatherer component, and the metrics gatherer component.[{“class” : “logger”,“enabled" : "true”,“level” : “INFO”,“name” : “gez”,“self” : “/eccapi/admin/config/loggers/gez”},{“class” : “logger”,“enabled" : "false”,“level” : “FINE”,“name” : “gez.data”,“self” : “/eccapi/admin/config/loggers/gez.data”},{“class” : “logger”,“enabled" : "true”,“level” : “FINEST”,“name” : “gez.gatherer.inventory”,“self” : “/eccapi/admin/config/loggers/gez.gatherer.inventory”},{“class” : “logger”,“enabled" : "false”,“level” : “FINER”,“name” : “gez.gatherer.metrics”,“self” : “/eccapi/admin/config/loggers/gez.gatherer.metrics”},]

GET /eccapi/admin/config/loggers/{logger-name}Use this API to list the level of a the logger specified with logger-name that is currently configured for theEnterprise Common Collector.

Role



Properties

No properties are required to issue this API.


Property Definition Required or optional Usage notes

logger-name A text string beginning with gez thatspecifies what section of code the loggerapplies to.

Required

The following properties are returned:


logger-name A text string beginning with gezthat specifies what section of codethe logger applies to.

The name of the logger. The default logger isnamed gez. When the name is prepended with“com.ibm.tivoli”. The name designates a validEnterprise Common Collector component forcomponent-based logging. See “EnterpriseCommon Collector components” on page 162 for alist of the components. If this name does notspecify a valid logger, then the component-basedlogger has no effect (that is, no validation is doneto ensure that it is a valid component).

level A text string indicating the logginglevel. The level must be one of thefollowing levels.


v SEVERE: Errors that causepremature termination and otherunexpected errors

v WARNING: Undesirable orunexpected conditions that arenot necessarily wrong

v INFO: Interesting runtime events

v CONFIG: Not supported. If set,shows the same level as INFO.

v FINE: Important events andexceptions

v FINER: Detailed debuginformation, low-level logic,object dumps, and so on

v FINEST: Method entry and exittracing

v ALL: Everything; essentiallyequivalent to FINEST

Note that each level includes all higher levels andapplies not only to that package but to allsubcomponents also (unless the subcomponent hasits own logger defined).

class The Java class to which thisoperation belongs (logger).

enabled Indicates whether logging isenabled.

self The uniform resource identifier(URI) of this logger.


Status codes


Status code Meaning


404 NOT FOUND. The status code is returned if the specified logger does not exist.


Example requestGET /eccapi/admin/config/loggers/gez

Example response

This sample shows an example of the response body.{“class” : “logger”,“enabled" : "true”,“level” : “INFO”,“name” : “gez”,“self” : “/eccapi/admin/loggers/gez”}

GET /eccapi/admin/data-sourcesUse this API to list the existing System z Hardware Management Consoles (HMCs) defined as datasources in the Enterprise Common Collector.

Role


Properties


The following properties are returned for each data source:


name A text string 1 to 16 characters providing a unique namefor the System z Hardware Management Console (HMC).

description A text string between 1 and 64 characters in lengthdescribing the HMC.

hmc-user The user ID to use to logon to the HMC.

hmc-user-pwd The password to use to logon to the HMC. For securitypurposes the password will always be ********.

hmc-hostname A text string between 1 and 256 characters in lengthproviding the fully qualified host name of the HMC.



status The current status of the connection. Possible values are:v connected: The Enterprise Common Collector (collector)

is connected to the data source using an API session.v connecting: The collector is attempting to connect to the

data source. The collector could be waiting for aresponse from the data source or waiting a definedperiod of time before making another attempt after aprevious connection attempt failed.

v disconnected: The collector is not currently connected tothe data source and is not attempting to connect to thedata source.

v data-source-unreachable: The collector was unable toconnect to the data source and is no longer attemptingto connect to the data source. This status means that thecollector tried to connect to the HMC and failed eitherbecause of a bad user ID or password, or because of 12hours of unsuccessful attempts.

v in-doubt: The collector has determined that its inventorydata for this data source is outdated. The collector hasstarted an unscheduled inventory discovery resynch itsdata with the HMC. When the discovery process iscomplete, the status returns to connected.

enabled Whether the Enterprise Common Collector shouldestablish a session with the HMC immediately and begincollecting data. This value is true if the collector shouldestablish a session with the HMC immediately and begincollecting data, or false if the collector should wait untilexplicitly told to begin data collection.

collection profile name The name of the collection profile to use for this datasource.


self The uniform resource identifier (URI) of the data source.

Error Codes


Status code Meaning

200 OK. This code is returned if the request is successful.

500 INTERNAL SERVER ERROR. This status code is returned if an unexpected internal error hasoccurred. Look for a message containing more information in the message log.

Example requestGET /eccapi/admin/data-sources

Example response

Here is a sample of the information returned by this API.[{"class" : "data-source","description" : "HMC for internal systems","enabled" : true,"hmc-hostname" : "hmc8623.mycompany.com",


"hmc-user" : "jsmith","hmc-user-pwd" : "********","name" : "HMC1","self" : "/eccapi/admin/data-sources/HMC1","status" : "connected"},{"class" : "data-source","enabled" : true,"hmc-hostname" : "hmc2358.mycompany.com","hmc-user" : "tjones","hmc-user-pwd" : "********","name" : "HMC2","self" : "/eccapi/admin/data-sources/HMC2","status" : "data-source-unreachable"}]

GET /eccapi/admin/data-sources/{name}Use this API to list the properties of a named System z Hardware Management Consoles (HMCs) datasource specified by name in the Enterprise Common Collector.

Authentication


Properties

No properties are required to issue this API.



name A text string 1 to 16 in lengthproviding a unique name forthe System z HardwareManagement Console(HMC).

Required



name A text string 1 to 16 characters providing a unique namefor the System z Hardware Management Console (HMC).

description A text string between 1 and 64 characters in lengthdescribing the HMC.

hmc-user The user ID to use to logon to the HMC.

hmc-user-pwd The password to use to logon to the HMC. For securitypurposes the password will always be ********.

hmc-hostname A text string between 1 and 256 characters in lengthproviding the fully qualified host name of the HMC.



status The current status of the connection. Possible values are:v connected: The Enterprise Common Collector (collector)

is connected to the data source using an API session.v connecting: The collector is attempting to connect to the

data source. The collector could be waiting for aresponse from the data source or waiting a definedperiod of time before making another attempt after aprevious connection attempt failed.

v disconnected: The collector is not currently connected tothe data source and is not attempting to connect to thedata source.

v data-source-unreachable: The collector was unable toconnect to the data source and is no longer attemptingto connect to the data source. This status means that thecollector tried to connect to the HMC and failed eitherbecause of a bad user ID or password, or because of 12hours of unsuccessful attempts.

v in-doubt: The collector has determined that its inventorydata for this data source is outdated. The collector hasstarted an unscheduled inventory discovery resynch itsdata with the HMC. When the discovery process iscomplete, the status returns to connected.

enabled Whether the Enterprise Common Collector shouldestablish a session with the HMC immediately and begincollecting data. This value is true if the collector shouldestablish a session with the HMC immediately and begincollecting data, or false if the collector should wait untilexplicitly told to begin data collection.

collection profile name The name of the collection profile to use for this datasource.


self The uniform resource identifier (URI) of the data source.

Status codes


Status code Meaning


404 NOT FOUND. This status code is returned if no data source exists with the specified name.

500 INTERNAL SERVER ERROR. This status code indicates that an unexpected internal error hasoccurred. Look for a message containing more information in the message log.

Example RequestGET /eccapi/admin/data-sources/HMC1

Example response

Here is a sample of the information returned by this API.[{"class" : "data-source","description" : "HMC for internal systems",


"enabled" : true,"hmc-hostname" : "hmc8623.mycompany.com","hmc-user" : "jsmith","hmc-user-pwd" : "********","name" : "HMC1","self" : "/eccapi/admin/data-sources/HMC1","status" : "connected"},]

POST /eccapi/admin/backupUse this API to restore a backup bundle created for the Enterprise Common Collector.

Role


Note: After a backup bundle was successfully restored using this API, all of the restored data-sourcesare disabled and need to be enabled again if desired.

Header fields

Header field Definition Usage notes

X-API-Backup-Passphrase Creating a backup bundle requires apassphrase that is used to encrypt anddecrypt the returned backup bundle.This passphrase is provided as HTTPHeader Field X-API-Backup-Passphrase.The passphrase must be the samepassphrase that was used to create thebackup bundle.

Properties



In the body of the POST request, send the JSON document that you received from the previouscorresponding GET request (the request that generated the backup). See “GET /eccapi/admin/backup”on page 205 for more information.

Status codes


Status code Meaning


400 BAD REQUEST. This status code is returned if no passphrase or a weak passphrase wasprovided or if the data source is still enabled.



Example requestPOST /eccapi/admin/backupX-API-Backup-Passphrase: My123Passphrase

Example response


POST /eccapi/admin/clients/Use this API to create a new client for the Enterprise Common Collector.

Authentication


Properties

To create a client, you must provide the required values and either provide a value or accept the defaultfor the remaining properties. You can also define any of these additional properties.


name The name of the client. This is the userID that the client will use to logon tothe Enterprise Common Collector.

Required

description A description of the client Optional

password The password that the client will useto logon to the Enterprise CommonCollector.

Optional if the collector is configuredto use LDAP for authentication.Otherwise, required.

roles One or more of the three roles definedfor all Enterprise Common Collectorclients:

v Administrator role that can performadministrative tasks, such ascreating data sources or clients

v Explorer role that can performdiscovery tasks, such as discoveringall virtual servers

v Operator role that can performmonitoring and discovery tasks,such at retrieving detailedinformation about virtual serversand their performance metrics

Multiple roles can be defined for aclient. For any one client to have accessto all aspects of the collector, all threeroles must be defined. These roles areinitial capitalized and are listed on asingle line and separated by commasand surrounded by brackets [ ].

At least one role must is required.

enabled Indicates whether the client is enabled.If the client is not enabled, logon willnot be permitted.

Optional Defaults to true.




Indicates whether password expirationfor this specific client is enabled. If notprovided, defaults to true.


These properties are not part of the request JSON, but are part of the response JSON.


self The uniform resource identifier (URI) of this resource. Returned value only.

class The class to which this entity belongs Returned value only.

password-expiration Indicates when the password will expire; this isindicated by an integer specifying the number ofmilliseconds since January 1, 1970 GMT.

Returned value only.

invalid-login-attempts Indicates how many unsuccessful login attempts haveoccurred since the last successful login.


Status codes


Status code Meaning

201 CREATED. This status code indicates a successful response.

400 BAD REQUEST. This status code is displayed if any of the values are invalid. Look for amessage containing more information in the message log.

500 INTERNAL SERVER ERROR. This code is displayed if an unexpected internal error occurs.Look for a message containing more information in the message log.

Example request

Here is an example of the request. Only the properties being defined should be supplied.POST /eccapi/admin/clients/{“name” : “userA”,“password” : “fLf49hDo”,“roles” : [ “Operator”, “Explorer” ],“enabled” : true.“password-expiration-enabled” : true}

Example response

Here is an example of a returned client string:{"class" : "client",“name” : “userA”,“password” : “********”,“roles” : [ “Operator”, “Explorer” ],“enabled” : true."invalid-login-attempts" : 0,"password-expiration" : 1328117643125,“password-expiration-enabled” : true,"self" : "/eccapi/admin/clients/userA"}


POST /eccapi/admin/collection-profilesA collection profile is an entity that defines parameters for metrics and inventory collection. Use this APIto create a new collection profile for a user of the Enterprise Common Collector.

Role


Properties

To create a collection-profile, you must provide the required values and either provide a value or acceptthe default for the remaining properties. You can also define any of these additional properties.


name A text string between 1 and 16 charactersin length providing a name or label forthe collection profile

Required

description A text string describing the collectionprofile

Optional

short-term-interval An integer between 60 and 600 inclusivedescribing the amount of time, inseconds, between retrievals of the currentset of metrics from the System zHardware Management Console (HMC).

Required

long-term-interval An integer between 300 and 1800inclusive describing the amount of time,in seconds, between retrievals of thecurrent set of historical metrics from theSystem z Hardware Management Console(HMC). If long-term-collection-enabled istrue this value must be greater than theshort-term-interval value, and it must bea multiple of the short-term-intervalvalue.

Required iflong-term-collection-enabled is true.Optional iflong-term-collection-enabled is false.

long-term-collection-enabled Whether long-term collection is enabled,meaning whether historical metrics datais retrieved from the System z HardwareManagement Console (HMC). Validvalues are true, meaning that long-termcollection is enabled and false, meaning itis not.

Optional Defaults to false.

inventory-resync-interval A resync is the rediscovery of theinventory of all defined HMCs.Depending on your configuration, thisoperation can take some time. A typicalsetting for this parameter would be 7200seconds (two hours) or more. This valuecan be an integer between 300 and 86400inclusive.

Required.



path-accessible-collection-enabled Defines whether path accessibility statuscollection is enabled for this System zHardware Management Console (HMC).This value determines whether pathaccessibility status is collected for eachvirtualization host storage resource in theinventory.

When virtualization host storage resourceinformation is retrieved from the HMC,no information about whether the storageresource is currently accessible to thevirtualization host via each path isretrieved. This is because pathaccessibility status can be time consumingto determine. After all inventory has beengathered, an optional post processing stepwill gather this status information if thisproperty is set to true.

This parameter is optional. Valid valuesare true, meaning that path accessiblecollection is enabled and false, meaning itis not.

Optional Defaults to true

collection-profile-name A text string between 1 and 16 charactersin length providing a name or label forthe collection profile.



self The uniform resource identifier (URI) of this resource. Returned value only.


Status codes


Status code Meaning

201 CREATED. This code is returned if the command completes successfully.

400 BAD REQUEST. This code is returned if for some reason, the request is invalid, such as amissing required property or incorrect format for a property. Look for a message containingmore information in the message log.


Example request

Here is an example of a send collection profile string:POST /eccapi/admin/collection-profiles{“name” : “special”,


“short-term-interval” : 90,“long-term-interval” : 360,“long-term-collection-enabled” : true,“inventory-resync-interval” : 900}

Example response

Here is an example of a returned collection profile string:{ "class" : "collection-profile",

"description" : "default collection profile","inventory-resync-interval" : 3600,"long-term-collection-enabled" : true,"long-term-interval" : 900,"name" : "default","self" : "/eccapi/admin/collection-profiles/default","path-accessible-collection-enabled" : true,"short-term-interval" : 60

}

POST /eccapi/admin/config/loggersUse this API to create a logger for the Enterprise Common Collector. This action determines what kindsof errors are written to the error log.

Overview

Messages are logged to a log file called enterpriseCommonCollector.n.log in the var/log directory. The nvalue should be 0.

If a log file reaches 10 MB in size, it is closed, rotated out, and a new file opened. Successively older filesare named by adding a number (0, 1, 2...19) to the filename.

If instructed to do so by IBM Software Support, you could increasing the level of detail that is logged fora specific portion of the Enterprise Common Collector code. This is done using this API or thecorresponding command line interface (see “Setting collector logging levels by using the command-line”on page 86). These component log names are valid:





















Role


Properties

The following properties are required to send this API:


name A text string beginning withgez that specifies whatEnterprise Common Collectorcomponent this loggerapplies to.

Required The name, when pre-pended with“com.ibm.tivoli”, should designate a validEnterprise Common Collector component.If the name does not designate a validcomponent, then the logger will have noeffect (no validation is done to ensure thatit is a valid logger).

level A text string indicating thelogging level. The level mustbe one of the followinglevels.


v SEVERE: Errors that causepremature termination andother unexpected errors

v WARNING: Undesirable orunexpected conditions thatare not necessarily wrong

v INFO: Interesting runtimeevents

v CONFIG: Not supported.If set, shows the samelevel as INFO.

v FINE: Important eventsand exceptions

v FINER: Detailed debuginformation, low-levellogic, object dumps, and soon

v FINEST: Method entry andexit tracing

v ALL: Everything;essentially equivalent toFINEST

Required Note that each level includes all higherlevels and applies not only to thatpackage but to all sub-packages also(unless the sub-package has its ownlogger defined).

The default setting is FINE.



enabled Defines whether theEnterprise Common Collectorshould use this logger.Possible values are true andfalse.

Optional The default is true.



self The uniform resource identifier (URI) of thislogger.



Status codes


Status code Meaning


400 BAD REQUEST. This code is returned if for some reason, the request is invalid. Look for amessage containing more information in the message log.


Example request

The sample that follows shows logging for the data component set to FINE level.POST /eccapi/admin/config/loggers{ “name” : “gez.data.impl”, “level” : “FINE”, “enabled” : true }

Example response

This sample shows an example of the response body.{“class” : “logger”,“level” : “FINE”,“name” : “gez.data.impl”,“self” : “/eccapi/admin/loggers/gez.data.impl”}

POST /eccapi/admin/data-sourcesUse this API to create data sources for the Enterprise Common Collector.

Role



Properties

The following properties are used to send this API and can also be part of the response. The "Required oroptional" column applied to send operations only.


name A text string 1 to 16 in length providing aunique name for the System z HardwareManagement Console (HMC)

Required

description A text string describing the HMC. Optional

hmc-user The user ID to use to logon to the HMC. Required

hmc-user-pwd The password to use to logon to the HMC. Forsecurity purposes the password will always bereturned as ********.

Required

hmc-hostname A text string between 1 and 256 charactersdescribing the host name of the HMC. Ifhmc-hostname contains characters other thanalphabetic characters (a-z, A-Z), digits (0-9), -(minus sign), _ (underscore), : (colon), %(percent sign), or . (period), the command failswith a status code 400.

Required

enabled Value is true if the collector establishes a sessionwith the HMC immediately and begin to gatherdata and false if the collector waits until a latertime (in which case the HMC configurationwould need to be updated to change enabled totrue).


collection-profile-name

The name of the collection profile to use for thisdata source.



self The uniform resource identifier (URI) of this client. Returned value only.

class The class to which this entity belongs. Returned value only.

Status codes


Status code Meaning




Example request

The following is an example of syntax when this API is sent.


POST /eccapi/admin/data-sources{"description" : "HMC for internal systems","enabled" : true,"collection-profile-name" : "default""hmc-hostname" : "hmc8623.mycompany.com","hmc-user" : "jsmith","hmc-user-pwd" : "fKv63dLm","name" : "HMC1"}

Example response

There following is an example of a returned data-sources string:{"class" : "data-source","collection-profile-name" : default"description" : "HMC for internal systems","enabled" : true,"hmc-hostname" : "hmc8623.mycompany.com","hmc-user" : "jsmith","hmc-user-pwd" : "********","name" : "HMC1","self" : "/eccapi/admin/data-sources/HMC1"}

POST /eccapi/sessions/Use this API to establish a session with the Enterprise Common Collector, a required task before you canuse all other APIs.

Header fields

If the request is successful, the generated session_ID is part of the JSON document returned in responseto the request. To send additional requests to other APIs, the session_ID must be extracted from thereturned JSON document and set to the X-API-Session header for all subsequent requests in the contextof this session.

Authentication

All clients can issue this API as long as they can provide a valid User ID and password when they send arequest to this API. These values are sent as properties. If the password is correct and the User ID is notdisabled or blocked, a session is established and identified to the user in a returned session_ID.

This session_ID is bound to the user ID and its authorization roles. For example, if a session isestablished for a user ID that has the Administrator role, this session ID can be used to send APIs thatrequire an Administrator role. But if a session is established for a user ID that has only Explorer roleauthorization, this session cannot be used to issue APIs that require the Administrator role.

Properties

To establish a session, a valid user ID and password must be provided. If a client wants to change itscurrent password (or has been forced to change an expired password), the new password must also beprovided as property to this request. The following properties are required to send this API:


userid The user ID of the client that wants toestablish a session.

required



password The password belonging to the client’suser ID

required

new-password New password to change the currentone. Cannot be the same as the currentpassword.

optional The existingpassword ischanged to thenew passwordonly if thematching currentpassword isprovided as thepassword property.



api-session The session ID that identifies the successfullyestablished session. This property must be sent asX-API-Session Header to issue other API request in thecontext of this session.

64 characters in length

api-major-version The major version number of this version of theEnterprise Common Collector

api-minor-version The minor version number of this version of theEnterprise Common Collector

Status codes


Status code Meaning




Example request

Here is an example of a send credentials string to establish a session:POST /eccapi/sessions/{

"userid": "myuserid","password": "mypasswd"

}

Here is an example of a send credentials string to establish a session and change the current password:POST /eccapi/sessions/{"userid": "myuserid","password": "mypasswd","new-password": "mynewpasswd"}


Example response

Here is an example of the returned string after a session is successfully established, showing an exampleof the generated session-id that must be used in the HTTP-Header X-API-Session as part of all APIrequests that are part of this session.{"api-session":"133offk0ti4eah3k7x2p394vmowm3vx14qjshvun6ptdtmc6z3uehh4qnhycko2b""api-major-version":1,"api-minor-version":1}

PUT /eccapi/admin/clients/{client-name}Use this API to update the attributes of a specific client configured in the Enterprise Common Collector.Note that the default admin client name that denotes the administrator for the Enterprise CommonCollector is reserved. For the admin client, only the password can be updated, and a password must besupplied even if collector is configured for authentication by LDAP.

Any sessions that updated clients had with the Enterprise Common Collector are automatically destroyedwhen the client is deleted. Message CTGEZ0712I reports how many active sessions were destroyedbecause this client was updated.

Role


Properties



client-name The name of the client. This is the userID that the client will use to logon to theEnterprise Common Collector.

Required

The following properties are used to send this API and can also be part of the response. The “Required oroptional” column applied to send operations only.

Note: None of these parameters are required in the usual sense. When you update a client, specify onlythe properties that you want to update.


description A text string between 1 and 256characters in length describing the client.

Optional

password The password that the client will use tologon to the Enterprise CommonCollector.

Optional if thecollector isconfigured to useLDAP forauthentication.Otherwise,required.



roles One or more of the three roles defined forall Enterprise Common Collector clients:

v Administrator role that can performadministrative tasks, such as creatingdata sources or clients

v Explorer role that can performdiscovery tasks, such as discovering allvirtual servers

v Operator role that can performmonitoring and discovery tasks, suchat retrieving detailed information aboutvirtual servers and their performancemetrics

Multiple roles can be defined for a client.For any one client to have access to allaspects of the collector, all three rolesmust be defined. These roles are initialcapitalized and are listed on a single lineand separated by commas andsurrounded by brackets [ ].

At least one roleis required.

enabled Indicates whether the client is enabled. Ifthe client is not enabled, logon will not bepermitted.

Optional


Indicates if the password expiration forthis specific client is enabled. The value istrue if it is provided and false if it is not.

Optional

Status codes


Status code Meaning



404 NOT FOUND. This status code is displayed if no client exists with the specified name.


Example request

Here is an example of the return from this request. Only the properties that were being updated arereturned.PUT /eccapi/admin/clients/{client-name}{ “password” : “kFT87Flr”, “roles” : [ “Operator”] }

Example response



PUT /eccapi/admin/clients/{client-name}/resumeUse this API to unlock a client that has been locked due to too many invalid login attempts for theEnterprise Common Collector.

Properties




client-name A text string 1 to 64 in lengthproviding a unique name for theSystem z Hardware ManagementConsole (HMC).

Required


Status codes


Status code Meaning


404 NOT FOUND. This code is displayed if no client exists with the specified name. Look for amessage containing more information in the message log.


Example request

Here is a sample of this request.PUT /eccapi/admin/clients/client5/resume

Example response


PUT /eccapi/admin/collection-profiles/{name}Use this API to update the property values for the collection-profile specified with {name} for theEnterprise Common Collector. Only the properties being changed should be included in the request body.

Role



Properties



name A text string between 1 and 16 characters in lengthproviding a name or label for the collection profile

Required

The following properties are used to send this API and can also be part of the response. The “Required oroptional” column applied to send operations only.

Note: None of these parameters are required in the usual sense. When you update a collection-profile,specify only the properties that you want to update.


description A text string 1 to 256 characters in length describingthe collection profile

Optional

inventory-resync-interval .

An integer between 300 and 86400 inclusivedescribing the amount of time, in seconds, thatpasses before this client resynchronizes inventorywith the System z Hardware Management Console(HMC)

Required

short-term-interval A resync is the rediscovery of the inventory of alldefined HMCs. Depending on your configuration,this operation can take some time. A typical settingfor this parameter would be 7200 seconds (twohours) or more. This value can be an integerbetween 300 and 86400 inclusive.

Optional


Whether long-term collection is enabled, meaningwhether historical metrics data is retrieved from theSystem z Hardware Management Console (HMC).Valid values are true, meaning that long-termcollection is enabled and false, meaning it is not.

Optional

long-term-interval An integer between 300 and 1800 inclusivedescribing the amount of time, in seconds, betweenretrievals of the current set of historical metricsfrom the System z Hardware Management Console(HMC). If long-term-collection-enabled is true, thisvalue must be greater than the short-term-intervalvalue, and it must be a multiple of theshort-term-interval value.

Optional




Defines whether path accessibility status collectionis enabled for this System z Hardware ManagementConsole (HMC). This value determines whetherpath accessibility status is collected for eachvirtualization host storage resource in the inventory.

When virtualization host storage resourceinformation is retrieved from the HMC, noinformation about whether the storage resource iscurrently accessible to the virtualization host viaeach path is retrieved. This is because pathaccessibility status can be time consuming todetermine. After all inventory has been gathered, anoptional post processing step will gather this statusinformation if this property is set to true.

This parameter is optional unless you are using thiscommand to change it. Valid values are true,meaning that path accessible collection is enabledand false, meaning it is not.

Optional

Status codes


Status code Meaning


400 BAD REQUEST. This code is returned if for some reason, the request is invalid, such asincorrect format for a property. Look for a message containing more information in themessage log.

404 NOT FOUND. This code is returned if the collection profile cannot be found.


Example request

Here is an example of a send collection profile string for changing the short-term-interval and thelong-term-interval:PUT /eccapi/admin/collection-profiles/default{ “short-term-interval” : 120, “long-term-interval” : 480 }

Example response

The response body is empty unless an error has occurred.

PUT /eccapi/admin/config/authenticationUse this API to update the authentication mechanism that the Enterprise Common Collector uses toauthenticate its clients: using the basic mechanism or an LDAP server.

Role



Properties

Th e following properties are used to send this API:

Property DefinitionRequired orOptional Usage notes

ldap-user-provider The URL of the LDAP directoryincluding position in the directory treewhere user entries are located, in theformat: ldap://<hostname>[:<port>]/[user_entry_location>].

Optional This is a subproperty of theldap-properties property and likethat property, they are presentonly when ldap-authentication isset to true. If ldap-authenticationis set to true, this property isrequired.

ldap-user-filter The LDAP search filter used to find amatching user record for the given userID. The string {USERNAME} will bereplaced with the user ID that is loggingin.

Optional Used to determine a user'sdistinguished name. ldap_filter isan LDAP filter string (RFC 2254).

This is a subproperty of theldap-properties property and likethat property, it is used only whenldap-authentication is set to true.

ldap-auth-identity The identity to use when authenticatinga user to the LDAP directory. The string{USERNAME} will be replaced with theuser ID that is logging in.

Optional This is a subproperty of theldap-properties property and likethat property, it us used onlywhen ldap-authentication is setto true.

ldap-use-ssl Whether to use secure socket layer (SSL)communication between the LDAPserver and the Enterprise Commoncollector. Valid values are true is SSLshould be used or false if it is not.

Optional This is a subproperty of theldap-properties property and likethat property, it is used only whenldap-authentication is set to true.

ldap-properties Whether to specify the additional LDAPproperties.

Optional Required if ldap-authentication isset to true. Set to null ifldap-authentication is set to false.

ldap-authentication Whether LDAP authentication isrequired. Valid values are true (it isrequired) or false (it is not required).The default is false.

Required If ldap-authentication is set totrue in this request, theldap-properties property must beprovided.

password-expiration-interval

The number of days that a clientpassword is valid when it is reset.

Required No default

The Enterprise Common Collector can be configured in three different modes for user authenticationusing LDAP. Depending on the structure and configuration of the LDAP directory, the EnterpriseCommon Collector's administrator determines the appropriate mode.v search-first mode: The user's record is searched in the LDAP directory using an anonymous search

operation. If a user record is found, an authentication to the LDAP server is attempted with the user’sdistinguished name (from the record) and the provided password.

v authentication-first mode: In this mode, the collector first attempts to authenticate to the LDAPdirectory using the provided user ID and password. Then the user's record is search with the providedfilter. This mode can be used if the LDAP directory does not allow anonymous search operations.

v authentication-only mode: In this mode, a full distinguished name for the user record is available.The authentication process verifies that the LDAP directory supports authentication with thisdistinguished name and the provided password.

The authentication mode is determined by the ldap-user-filter and ldap-auth-identity properties.


Table 22. LDAP authentication mode setting

Authentication mode ldap-user-filter ldap-auth-identity

search-first mode set not set

authentication-first mode set set

authentication-only mode not set set

Work with your LDAP administrator to determine which mode is appropriate for your installation andwhat specific values should be used for ldap-user-filter and ldap-auth-identity.

Status codes


Status code Meaning


400 BAD REQUEST. This code is returned if for some reason, the request is invalid. Look for amessage containing more information in the message log.


Example request

What follows is an example of a request that uses basic authentication:PUT /eccapi/admin/config/authentication{"ldap-authentication": false,"password-expiration-interval": 90}

The following example configures the collector to use LDAP authentication in authentication-only mode.The example assumes that all user records are located under ou=staff,o=mycompany,c=US and thedistingusines name (DN) of a concrete user record is uid=,ou=staff,o=mycompany,c=US. Since all userrecords have the same DN schema, authentication-only mode can be used.PUT /eccapi/admin/config/authentication{"ldap-authentication": true,"ldap-properties": {"ldap-user-provider": "ldap://examplehost.com",

"ldap-auth-identity": uid={USERNAME},ou=staff,o=mycompany,c=US"ldap-use-ssl": false},"password-expiration-interval": 90}

The following example configures the collector to use LDAP authentication in search-first mode. TheLDAP directory supports anonymous search operations. The example assumes that the user records aredistributed over the directory, but that all user records own the objectClass inetOrgPerson, so the can besearched with the filter property, as shown in this example.PUT /eccapi/admin/config/authentication{"ldap-authentication": true,"ldap-properties": {"ldap-user-provider": "ldap://examplehost.com","ldap-user-filter": (&(uid={USERNAME})(objectClass=inetOrgPerson)) ,"ldap-user-identity": ,


"ldap-use-ssl": false},"password-expiration-interval": 90}

The following example configures the collector to use LDAP authentication in authentication-first mode.Authentication is first attempted to the LDAP directory using the provided user ID and password. Nextthe user's record is searched using the filter. This example assumes that the user record's distinguishedname is not known in advance and anonymous search is not allowed in this LDAP directory.PUT /eccapi/admin/config/authentication{"ldap-authentication": true,"ldap-properties": {"ldap-user-provider": "ldap://examplehost.com","ldap-user-filter": (&(uid={USERNAME})(objectClass=inetOrgPerson)) ,"ldap-auth-identity": "{USERNAME}","ldap-use-ssl": false},"password-expiration-interval": 90}

Example response


PUT /eccapi/admin/config/certificates/{alias}This API is used to import a certificate into the Enterprise Common Collector and assign it the aliasspecified by alias . You select the value for alias.

Role


Properties

This request is unique because it does not use JSON format. Instead of the application or JSON contenttypical of other Enterprise Common Collector APIs, the content type of this request ismultipart/form-data. The request body itself contains the certificate in the PEM (base64 coded X.509certificate) format.



alias The alias name that you assigned thiscertificate.

Required

This API returns the following properties:

















class The Java class to which this operation belongs.

self The uniform resource identifier (URI) of thisrequest.

Status codes


Status code Meaning

200 OK. This code is returned if the request is successful and the response data is returned.

400 BAD REQUEST. This status code is displayed if the alias is already in use for anothercertificate. Look for a message containing more information in the message log.


Example request

The request body must contain the binary data encoded in a text for the certificate in the PEM (base64coded X.509 certificate) format. The Content-Type of this request is therefore multipart/form-data.

A sample request follows:PUT /eccapi/admin/config/certificates/mycertContent-Type: multipart/form-data

-----BEGIN CERTIFICATE-----<ENCRYPTED_CERTIFICATE_DATA>-----END CERTIFICATE-----

Example response

This command returns information about the new imported certificate:{"alias": {mycert},"version": 3,


"self": "/eccapi/admin/config/certificates/mycert","name": "Certificate Properties","subject-dn": "CN=Unknown, OU=Research & Development GmbH,


O=IBM Deutschland, L=Boeblingen, ST=Baden-Wuerttemberg, C=DE","not-after": "Wed Mar 09 12:45:23 CET 2011","not-before": "Thu Dec 09 12:45:23 CET 2010","serial-number": "1291895123","signature-algorithm-name": "SHA1withDSA","signature-algorithm-oid": "1.2.840.10040.4.3","public-key-algorithm-name": "DSA","public-key-format": "X.509"}

PUT /eccapi/admin/config/certificates/trust-allThis API is used to update the configuration of the truststore in the Enterprise Common Collector.

If the trust-all parameter is enabled, the collector does not validate the Hardware Management Consolecertificates during establishing an HTTPS connection. This parameter does not disable the "normal"HTTPS certificate management between WebSphere Application Server Community Edition as a serverand clients (such as the Tivoli zEnterprise Monitoring Agent).

Role


Properties



trust-all-certificates Valid values are true (trust all certificates) orfalse (do not trust all certificates).

Required

Status codes


Status code Meaning

400 BAD REQUEST. This status code is also returned if the “trust-all-certificates” property ismissing. Look for a message containing more information in the message log.


Example requestPUT /eccapi/admin/config/certificates/trust-all{"trust-all-certificates": false}

Example response



PUT /eccapi/admin/config/loggers/{logger-name}Use this API to update the level of a the logger specified with logger-name that is currently configured forthe Enterprise Common Collector.

Overview

Messages are logged to a log file called enterpriseCommonCollector.n.log in the var/log directory. The nvalue should be 0.

If a log file reaches 10 MB in size, it is closed, rotated out, and a new file opened. Successively older filesare named by adding a number (0, 1, 2...19) to the filename.

If instructed to do so by IBM Software Support, you could increasing the level of detail that is logged fora specific portion of the Enterprise Common Collector code. This is done using this API or thecorresponding command line interface (see “Setting collector logging levels by using the command-line”on page 86). These component log names are valid:

















gez.zhmc.restapi HMC ReSTClient


Role



Properties



logger-name A text string beginning with gez that specifies whatsection of code the logger applies to, the stringused to reference the name in the uniform resource. This is the same as name but logger-name showshow this property is referenced in the URI. Asnoted earlier, if instructed to do so by IBMSoftware Support, you could increase the level ofdetail that is logged for a specific portion of theEnterprise Common Collector code.

Required

The following parameter is required to send this API.


level A text string indicating thelogging level. The level mustbe one of the followinglevels.


v SEVERE: Errors that causepremature termination andother unexpected errors

v WARNING: Undesirable orunexpected conditions thatare not necessarily wrong

v INFO: Interesting runtimeevents

v CONFIG: Not supported.If set, shows the samelevel as INFO.

v FINE: Important eventsand exceptions

v FINER: Detailed debuginformation, low-levellogic, object dumps, and soon

v FINEST: Method entry andexit tracing

v ALL: Everything;essentially equivalent toFINEST

Required Note that each level includes all higherlevels and applies not only to thatcomponent but to all subcomponents(unless the subcomponent has its ownlogger defined).

By default, only INFO and higher (INFO,WARNING, SEVERE) are logged.

No properties are returned by this API unless there is an error.


Status codes


Status code Meaning


400 BAD REQUEST. This status code is returned if the level is missing or not valid.

404 NOT FOUND. The status code is returned if the specified logger does not exist. Look for amessage containing more information in the message log.


Example request

The sample is an example of the request body for a logger level set to ALL.PUT /eccapi/admin/config/loggers/gez.utility}{ “level” : “ALL” }

Example response


PUT /eccapi/admin/data-sources/{name}Use this API update the data source specified by name that is currently configured for the EnterpriseCommon Collector.

Authentication


Properties



name A text string between 1 and 16 characters in lengthproviding a name or label for the data source

Required

None of these parameters are required in the usual sense to issue this API. When you update adata-source, specify only the properties that you want to update. The following properties can bereturned, depending on what you specified:


description A text string from 1 to 256 characters in lengthdescribing the HMC.

Optional

hmc-user The user ID to use to logon to the HMC. Required

hmc-user-pwd The password to use to logon to the HMC. Required



hmc-hostname A text string between 1 and 256 characters describingthe host name of the HMC. If hmc-hostname containscharacters other than alphabetic characters (a-z, A-Z),digits (0-9), - (minus sign), _ (underscore), : (colon), %(percent sign), or . (period), the command fails with astatus code 400.

Required

enabled Value is true if the collector establishes a session withthe HMC immediately and begin to gather data andfalse if the collector waits until a later time (in whichcase the HMC configuration would need to be updatedto change enabled to true).

Optional Defaults totrue.

collection-profile-name

The name of the collection profile to use for this datasource.

Status codes


Status code Meaning




Example request

The following is an example of a command to changed the description to “HMC for internal systems”and the enabled status to true.PUT /eccapi/admin/data-sources/HMC1{

"description" : "HMC for internal systems","enabled" : true,

}

Example response



Appendix B. Event Integration Support

The Tivoli zEnterprise Monitoring Agent supports event integration with Tivoli NetCool/OMNIbus andTivoli Business Service Manager.

About this task

The events are received by the Netcool/OMNIbus Probe for Tivoli EIF, which maps them to OMNIbusevents and then inserts them into the OMNIbus server. Updates to those events are also sent toOMNIbus. When an OMNIbus user acknowledges, closes, or reopens a forwarded event, OMNIbus sendsthose changes to back to the monitoring server that forwarded them.

zEnterprise monitoring situations can be forwarded to the Event Integration Facility (EIF) probe ofOMNIbus by enabling and configuring the Tivoli Enterprise Monitoring Server's Event IntegrationFacility adapter.

The zEnterprise Monitoring Agent provides a rules file, kze_tbsm.rules, that generates the appropriateBSM_Identity value for situations originating from its attribute groups.

To activate this rules file, perform the following steps:

Procedure1. Copy the latest version of the kze_tbsm.rules file from Tivoli Enterprise Monitoring Server or Tivoli

Enterprise Portal Server to the OMNIbus server. The rules file is found in one of these locations:

Platform Location

Linux or UNIX <itm_install_dir>/tables/cicatrsq/TECLIB

Where <itm_install_dir> is the directory where the IBM Tivoli Monitoring environment isinstalled.

Windows Tivoli Enterprise Monitoring Server:

<itm_install_dir>\ITM\CMS\teclib

Tivoli Enterprise Portal Server:

<itm_install_dir>\ITM\CNPS\teclib

Where <itm_install_dir> is the directory where the IBM Tivoli Monitoring environment isinstalled.

To copy the file to the OMNIbus server, place it into the probe directory.

Platform Location

Linux or UNIX <itm_install_dir>/IBM/tivoli/netcool/omnibus/probes/arch

Where <itm_install_dir> is the directory where the OMNIbus server is installed and archrepresents the operating system directory on which the probe is installed; for example,solaris2 when running on a Solaris system.

Windows <itm_install_dir>\IBM\tivoli\netcool\omnibus\probes\arch

Where <itm_install_dir> is the directory where the OMNIbus server is installed and archrepresents the operating system directory on which the probe is installed; for example,win32 for a Windows system.


2. Ensure the tivoli_eif.rules file has an INCLUDE statement for this kze_tbsm.rules file. TheINCLUDE must appear after the INCLUDE for the base ITM rules file, itm_event.rules, as in theexample which follows:include "itm_event.rules". . .# Uncomment the following include line to use the z/Enterprise rules# provided with the z/Enterprise monitoring agentinclude "kze_tbsm.rules"

3. If the tivoli_eif.rules file was modified (to add or uncomment the INCLUDE for kze_tbsm.rules),restart the Tivoli EIF probe service to pick up the changes. For detailed information about performingthis restart, see the "Setting up event forwarding to Netcool/OMNIbus" of the IBM Tivoli MonitoringInstallation and Setup Guide.

What to do next

For a more component explanation of this process, see the IBM Tivoli Monitoring Installation and SetupGuide. This document provides the instructions to enable situation event forwarding: configuring theOMNIbus server for program execution from scripts, updating the OMNIbus db schema, configuring theEIF probe, enabling situation forwarding on the hub monitoring server, and defining a default eventintegration facility (EIF) destination.


Documentation library

This appendix contains information about the publications related to IBM Tivoli Monitoring and to thecommonly shared components of Tivoli Management Services.

These publications are listed in the following categories:v IBM Tivoli Monitoring libraryv Related publications

See the IBM Tivoli Monitoring Documentation Guide for information about accessing and using thepublications. You can find the Documentation Guide in the IBM Tivoli Monitoring and OMEGAMON XEInformation Center at http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/index.jsp. To open theDocumentation Guide in the information center, select Using the publication in the Contents pane.

To find a list of new and changed publications, click What's new on the Welcome page of the IBM TivoliMonitoring and OMEGAMON XE Information Center. To find publications from the previous version ofa product, click Previous versions under the name of the product in the Contents pane.

IBM Tivoli Monitoring libraryThe following publications provide information about IBM Tivoli Monitoring and about the commonlyshared components of Tivoli Management Services:v Quick Start Guide

Introduces the components of IBM Tivoli Monitoring.v Installation and Setup Guide, GC32-9407

Provides instructions for installing and configuring IBM Tivoli Monitoring components on Windows,Linux, and UNIX systems.

v Program Directory for IBM Tivoli Management Services on z/OS, GI11-4105Gives instructions for the SMP/E installation of the Tivoli Management Services components on z/OS.

v Configuring the Tivoli Enterprise Monitoring Server on z/OS, SC27-2313Provides instructions for preparing, configuring, and customizing your monitoring servers on z/OS.This guide complements the IBM Tivoli OMEGAMON XE and IBM Tivoli Management Services on z/OSCommon Planning and Configuration Guide and the IBM Tivoli Monitoring Installation and Setup Guide.

v High Availability Guide for Distributed Systems, SC23-9768Gives instructions for several methods of ensuring the availability of the IBM Tivoli Monitoringcomponents.

v IBM Tivoli zEnterprise Monitoring Agent Installation and Configuration Guide, SC14-7358Provides instructions for installing and configuring Tivoli zEnterprise monitoring agent components onWindows, Linux, and UNIX systems. Also includes migration and backup information, EnterpriseCommon Collector troubleshooting, Hardware Management Console configuration, and use of thecommand line interface or APIs to customize the collector. This guide complements the TivolizEnterprise Monitoring Agent User’s Guide.

v Administrator's Guide, SC32-9408Describes the support tasks and functions required for the Tivoli Enterprise Portal Server and clients,including Tivoli Enterprise Portal user administration.

v Command Reference, SC32-6045Provides detailed syntax and parameter information, as well as examples, for the commands you canuse in IBM Tivoli Monitoring.


http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/index.jsp

v Messages, SC23-7969Lists and explains messages generated by all IBM Tivoli Monitoring components and by z/OS-basedTivoli Management Services components (such as Tivoli Enterprise Monitoring Server on z/OS andTMS:Engine).

v Troubleshooting Guide, GC32-9458Provides information to help you troubleshoot problems with the software.

v Tivoli Enterprise Portal online helpProvides context-sensitive reference information about all features and customization options of theTivoli Enterprise Portal. Also gives instructions for using and administering the Tivoli EnterprisePortal.

v Tivoli Enterprise Portal User's Guide, SC32-9409Complements the Tivoli Enterprise Portal online help. The guide provides hands-on lessons anddetailed instructions for all Tivoli Enterprise Portal features.

v Agent Builder User's Guide, SC32-1921Explains how to use the Agent Builder for creating monitoring agents and their installation packages,and for adding functions to existing agents.

v Tivoli Universal Agent User’s Guide, SC32-9459Introduces you to the IBM Tivoli Universal Agent, an agent of IBM Tivoli Monitoring. The IBM TivoliUniversal Agent enables you to use the monitoring and automation capabilities of IBM TivoliMonitoring to monitor any type of data you collect.

v Performance Analyzer User’s Guide, SC27-4004Explains how to use the Performance Analyzer to understand resource consumption trends, identifyproblems, resolve problems more quickly, and predict and avoid future problems.

v IBM Tivoli Universal Agent API and Command Programming Reference Guide, SC32-9461Explains the procedures for implementing the IBM Tivoli Universal Agent APIs and providesdescriptions, syntax, and return status codes for the API calls and command-line interface commands.

v IBM Tivoli zEnterprise Monitoring Agent User’s Guide, SC14-7359Complements the Tivoli zEnterprise monitoring agent online help. The guide provides referenceinformation about the interface, usage scenarios, agent troubleshooting information, and informationabout Tivoli Common Reporting reports. This guide complements the Tivoli zEnterprise MonitoringAgent Installation and Configuration Guide.

Documentation for the base agentsIf you purchased IBM Tivoli Monitoring as a product, you received a set of base monitoring agents aspart of the product. If you purchased a monitoring agent product (for example, an OMEGAMON XEproduct) that includes the commonly shared components of Tivoli Management Services, you did notreceive the base agents.

The following publications provide information about using the base agents.v Operating system agents:

– Windows OS Agent User's Guide, SC32-9445– UNIX OS Agent User's Guide, SC32-9446– Linux OS Agent User's Guide, SC32-9447– i5/OS Agent User's Guide, SC32-9448– UNIX Log Agent User's Guide, SC32-9471

v Agentless operating system monitors:– Agentless Monitoring for Windows Operating Systems User's Guide, SC23-9765– Agentless Monitoring for AIX Operating Systems User's Guide, SC23-9761– Agentless Monitoring for HP-UX Operating Systems User's Guide, SC23-9763


– Agentless Monitoring for Solaris Operating Systems User's Guide, SC23-9764– Agentless Monitoring for Linux Operating Systems User's Guide, SC23-9762

v Warehouse agents:– Warehouse Summarization and Pruning Agent User's Guide, SC23-9767– Warehouse Proxy Agent User's Guide, SC23-9766

v System P agents:– AIX Premium Agent User's Guide, SA23-2237– CEC Base Agent User's Guide, SC23-5239– HMC Base Agent User's Guide, SA23-2239– VIOS Premium Agent User's Guide, SA23-2238

v Other base agents:– Tivoli Log File Agent User’s Guide, SC14-7484– Systems Director base Agent User’s Guide, SC27-2872– Monitoring Agent for IBM Tivoli Monitoring 5.x Endpoint User's Guide, SC32-9490

Related publicationsYou can find useful information about related products in the IBM Tivoli Monitoring and OMEGAMONXE Information Center at http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/index.jsp.

Other sources of documentationYou can also obtain technical documentation about IBM Tivoli Monitoring and related products from thefollowing sources:v IBM Integrated Service Management Library

http://www.ibm.com/software/brandcatalog/ismlibrary/IBM Integrated Service Management Library is an online catalog that contains integrationdocumentation and other downloadable product extensions.

v Redbookshttp://www.redbooks.ibm.com/IBM Redbooks and Redpapers include information about products from platform and solutionperspectives.

v TechnotesTechnotes provide the latest information about known product limitations and workarounds. You canfind Technotes through the IBM Software Support Web site at http://www.ibm.com/software/support/.

v Tivoli wikis on the IBM developerWorks Web siteTivoli Wiki Central at http://www.ibm.com/developerworks/wikis/display/tivoli/Home is the homefor interactive wikis that offer best practices and scenarios for using Tivoli products. The wikis containwhite papers contributed by IBM employees, and content created by customers and business partners.Two of these wikis are of particular relevance to IBM Tivoli Monitoring:– Tivoli Distributed Monitoring and Application Management Wiki at http://www.ibm.com/

developerworks/wikis/display/tivolimonitoring/Home provides information about IBM TivoliMonitoring and related distributed products, including IBM Tivoli Composite ApplicationManagement products.

– Tivoli System z Monitoring and Application Management Wiki at http://www.ibm.com/developerworks/wikis/display/tivoliomegamon/Home provides information about theOMEGAMON XE products, NetView for z/OS, Tivoli Monitoring Agent for z/TPF, and otherSystem z monitoring and application management products.

Documentation library 259

http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/index.jsp

http://www-01.ibm.com/software/brandcatalog/ismlibrary/

http://www.redbooks.ibm.com/

http://www.ibm.com/software/support/

http://www.ibm.com/software/support/

http://www.ibm.com/developerworks/wikis/display/tivoli/Home

http://www.ibm.com/developerworks/wikis/display/tivolimonitoring/Home


http://www.ibm.com/developerworks/wikis/display/tivoliomegamon/Home

http://www.ibm.com/developerworks/wikis/display/tivoliomegamon/Home

Support information

If you have a problem with your IBM software, you want to resolve it quickly. IBM provides ways foryou to obtain the support you need.

OnlineThe following sites contain troubleshooting information:v Go to the IBM Software Support site at http://www.ibm.com/software/support/probsub.html

and follow the instructions.v Go to the IBM Tivoli Distributed Monitoring and Application Management Wiki at

http://www.ibm.com/developerworks/wikis/ display/tivolimonitoring/Home. Feel free tocontribute to this wiki.

IBM Support AssistantThe IBM Support Assistant (ISA) is a free local software serviceability workbench that helps youresolve questions and problems with IBM software products. The ISA provides quick access tosupport-related information and serviceability tools for problem determination. To install the ISAsoftware, go to http://www.ibm.com/software/support/isa.

Troubleshooting GuideFor more information about resolving problems, see the product's Troubleshooting Guide.

Using IBM Support AssistantThe IBM Support Assistant is a free, stand-alone application that you can install on any workstation. Youcan then enhance the application by installing product-specific plug-in modules for the IBM products youuse.

The IBM Support Assistant saves you the time it takes to search the product, support, and educationalresources. The IBM Support Assistant helps you gather support information when you need to open aproblem management record (PMR), which you can then use to track the problem.

The product-specific plug-in modules provide you with the following resources:v Support linksv Education linksv Ability to submit problem management reports

For more information, and to download the IBM Support Assistant, see http://www.ibm.com/software/support/isa. After you download and install the IBM Support Assistant, follow these steps to install theplug-in for your Tivoli product:1. Start the IBM Support Assistant application.2. Select Updater on the Welcome page.3. Select New Properties and Tools or select the New Plug-ins tab (depending on the version of IBM

Support Assistant installed).4. Under Tivoli, select your product, and then click Install. Be sure to read the license and description.

If your product is not included on the list under Tivoli, no plug-in is available yet for the product.5. Read the license and description, and click I agree.6. Restart the IBM Support Assistant.


http://www.ibm.com/software/support/probsub.html


http://www.ibm.com/software/support/isa



Obtaining fixesA product fix might be available to resolve your problem. To determine which fixes are available for yourTivoli software product, follow these steps:1. Go to the IBM Software Support website at http://www.ibm.com/software/support.2. Under Select a brand and/or product, select Tivoli.

If you click Go, the Search within all of Tivoli support section is displayed. If you don't click Go,you see the Select a product section.

3. Select your product and click Go.4. Under Download, click the name of a fix to read its description and, optionally, to download it.

If there is no Download heading for your product, supply a search term, error code, or APAR numberin the field provided under Search Support (this product), and click Search.

For more information about the types of fixes that are available, see the IBM Software Support Handbook athttp://www14.software.ibm.com/webapp/set2/sas/f/handbook/home.html.

Receiving weekly support updatesTo receive weekly e-mail notifications about fixes and other software support news, follow these steps:1. Go to the IBM Software Support website at http://www.ibm.com/software/support.2. Click My support in the far upper-right corner of the page under Personalized support.3. If you have already registered for My support, sign in and skip to the next step. If you have not

registered, click register now. Complete the registration form using your e-mail address as your IBMID and click Submit.

4. The Edit profile tab is displayed.5. In the first list under Products, select Software. In the second list, select a product category (for

example, Systems and Asset Management). In the third list, select a product sub-category (forexample, Application Performance & Availability or Systems Performance). A list of applicableproducts is displayed.

6. Select the products for which you want to receive updates.7. Click Add products.8. After selecting all products that are of interest to you, click Subscribe to email on the Edit profile

tab.9. In the Documents list, select Software.

10. Select Please send these documents by weekly email.11. Update your e-mail address as needed.12. Select the types of documents you want to receive.13. Click Update.

If you experience problems with the My support feature, you can obtain help in one of the followingways:

OnlineSend an e-mail message to [email protected], describing your problem.

By phoneCall 1-800-IBM-4You (1-800-426-4968).

Contacting IBM Software SupportIBM Software Support provides assistance with product defects. The easiest way to obtain that assistanceis to open a PMR or ETR directly from the IBM Support Assistant.


http://www.ibm.com/software/support

http://www14.software.ibm.com/webapp/set2/sas/f/handbook/home.html

http://www.ibm.com/software/support

Before contacting IBM Software Support, your company must have an active IBM software maintenancecontract, and you must be authorized to submit problems to IBM. The type of software maintenancecontract that you need depends on the type of product you have:v For IBM distributed software products (including, but not limited to, Tivoli, Lotus, and Rational

products, as well as DB2 and WebSphere products that run on Windows or UNIX operating systems),enroll in Passport Advantage in one of the following ways:

OnlineGo to the Passport Advantage website at http://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm .

By phoneFor the phone number to call in your country, go to the IBM Software Support website athttp://techsupport.services.ibm.com/guides/contacts.html and click the name of yourgeographic region.

v For customers with Subscription and Support (S & S) contracts, go to the Software Service Requestwebsite at https://techsupport.services.ibm.com/ssr/login.

v For customers with Linux, iSeries, pSeries, zSeries, and other support agreements, go to the IBMSupport Line website at http://www.ibm.com/services/us/index.wss/so/its/a1000030/dt006.

v For IBM eServer software products (including, but not limited to, DB2 and WebSphere products thatrun in zSeries, pSeries, and iSeries environments), you can purchase a software maintenance agreementby working directly with an IBM sales representative or an IBM Business Partner. For more informationabout support for eServer software products, go to the IBM Technical Support Advantage website athttp://www.ibm.com/servers/eserver/techsupport.html.

If you are not sure what type of software maintenance contract you need, call 1-800-IBMSERV(1-800-426-7378) in the United States. From other countries, go to the contacts page of the IBM SoftwareSupport Handbook on the web at http://www14.software.ibm.com/webapp/set2/sas/f/handbook/home.html and click the name of your geographic region for phone numbers of people who providesupport for your location.

Support information 263

http://www.lotus.com/services/passport.nsf/ WebDocs/Passport_Advantage_Home

http://www.lotus.com/services/passport.nsf/ WebDocs/Passport_Advantage_Home

http://techsupport.services.ibm.com/guides/contacts.html

https://techsupport.services.ibm.com/ssr/login

http://www.ibm.com/services/us/index.wss/so/its/a1000030/dt006

http://www.ibm.com/servers/eserver/techsupport.html



Notices

This information was developed for products and services offered in the U.S.A. IBM may not offer theproducts, services, or features discussed in this document in other countries. Consult your local IBMrepresentative for information on the products and services currently available in your area. Anyreference to an IBM product, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product, program, or service thatdoes not infringe any IBM intellectual property right may be used instead. However, it is the user'sresponsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in thisdocument. The furnishing of this document does not give you any license to these patents. You can sendlicense inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual PropertyDepartment in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan, Ltd.1623-14, Shimotsuruma, Yamato-shiKanagawa 242-8502 Japan

The following paragraph does not apply to the United Kingdom or any other country where suchprovisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOTLIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY ORFITNESS FOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore,this statement might not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodicallymade to the information herein; these changes will be incorporated in new editions of the publication.IBM may make improvements and/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM websites are provided for convenience only and do not inany manner serve as an endorsement of those websites. The materials at those websites are not part ofthe materials for this IBM product and use of those websites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate withoutincurring any obligation to you.


Licensees of this program who wish to have information about it for the purpose of enabling: (i) theexchange of information between independently created programs and other programs (including thisone) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758 U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some casespayment of a fee.

The licensed program described in this document and all licensed material available for it are providedby IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement orany equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, theresults obtained in other operating environments may vary significantly. Some measurements may havebeen made on development-level systems and there is no guarantee that these measurements will be thesame on generally available systems. Furthermore, some measurement may have been estimated throughextrapolation. Actual results may vary. Users of this document should verify the applicable data for theirspecific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, theirpublished announcements or other publicly available sources. IBM has not tested those products andcannot confirm the accuracy of performance, compatibility or any other claims related to non-IBMproducts. Questions on the capabilities of non-IBM products should be addressed to the suppliers ofthose products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal withoutnotice, and represent goals and objectives only.

All IBM prices shown are IBM's suggested retail prices, are current and are subject to change withoutnotice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject to change before theproducts described become available.

This information contains examples of data and reports used in daily business operations. To illustratethem as completely as possible, the examples include the names of individuals, companies, brands, andproducts. All of these names are fictitious and any similarity to the names and addresses used by anactual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programmingtechniques on various operating platforms. You may copy, modify, and distribute these sample programsin any form without payment to IBM, for the purposes of developing, using, marketing or distributingapplication programs conforming to the application programming interface for the operating platform forwhich the sample programs are written. These examples have not been thoroughly tested under allconditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of theseprograms. You may copy, modify, and distribute these sample programs in any form without payment toIBM for the purposes of developing, using, marketing, or distributing application programs conformingto IBM‘s application programming interfaces.


Each copy or any portion of these sample programs or any derivative work, must include a copyrightnotice as follows:

© IBM 2012. Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBM Corp.previous releases to 2012.

If you are viewing this information in softcopy form, the photographs and color illustrations might not bedisplayed.

TrademarksIBM, the IBM logo, and ibm.com® are trademarks or registered trademarks of International BusinessMachines Corp., registered in many jurisdictions worldwide. Other product and service names might betrademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at"Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.

Intel, Intel logo, and Intel Xeon, are trademarks or registered trademarks of Intel Corporation or itssubsidiaries in the United States and other countries.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/orits affiliates.

Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, orboth.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other company, product, or service names may be trademarks or service marks of others.

Notices 267

zEnterprise Monitoring Agent Glossary

A

accelerator. A special-purpose hardware component that can perform a limited set of specific functions; it optimizesperformance of these functions when compared to a general-purpose processor. Because of its limited function set, anaccelerator is an integrated part of a processing environment, rather than a stand-alone unit. For a zEnterprisesystem, this is referred to as an optimizer.

advanced management module (AMM). A hardware unit that provides system-management functions for all theblade servers in a zEnterprise BladeCenter chassis.

alternate HMC. A System z Hardware Management Console (HMC) that is paired with the primary HMC toprovide redundancy in case the primary HMC fails.

AMM. See advanced management module.

appliance. There are hardware appliances and software appliances. A hardware appliance is a relatively low-costdesktop computer that lacks the capabilities of a fully equipped workstation but is instead designed for eitherInternet access or specialized business use. A software appliance provides a narrow range of specialized functionsand generally runs on a specific hardware platform.

application environment. The environment that includes the software and the server or network infrastructure thatsupports it.

application response measurement (ARM). An open standard published by the Open Group for monitoring anddiagnosing performance bottlenecks within complex enterprise applications that follow loosely coupled designs orservice-oriented architectures. It includes an API for C and Java that allows timing information associated with eachstep in a transaction to be logged for later analysis.

ARM-instrumented application. An application in which application response measurement (ARM) calls areadded to the source code to enable the application's performance to be monitored by management systems. ARM isan Open Group standard.

Automate suite (Automate). The second of two functional suites associated with the IBM zEnterprise UnifiedResource Manager (URM); the first is the Manage suite. The Automate suite includes goal-oriented monitoring andmanagement of resources and energy management. The Manage suite must be installed before installing theAutomate suite.

B

blade. Hardware that provides application-specific services and components. The consistent size and shape (that is,form factor) of each blade allows it to fit in a BladeCenter chassis.

BladeCenter chassis. A modular chassis that can contain multiple blades, allowing the individual blades to shareresources such as the management, switch, power, and blower modules.

C

Capacity Back Up (CBU). A System z option that allows customers using a cross-site disaster recovery solution toorder sufficient space on a backup site to install capacity required for disaster recovery but pay only for theminimum amount of capacity (CPs) required for normal processing. In case of disaster, they are allowed totemporarily increase the capacity on the backup site from normal capacity to maximum capacity without incurringadditional cost.

capacity planning. The process of determining the hardware and software configuration required to accommodatethe anticipated workload on a system.


CBU. See Capacity Back Up.

central processor complex (CPC). A physical collection of hardware that consists of main storage, one or morecentral processors, timers, and channels. In the IBM zEnterprise System, the CPC consists of a System z mainframeand any attached IBM BladeCenter Extensions (zBX). See also node and IBM System z.

channel path identifier (CHPID). The channel subsystem communicates with I/O devices via a channel pathbetween the channel subsystem and the devices it controls. A CHPID is a value assigned to each channel path withinSystem z that uniquely identifies that path. Up to 256 CHPIDs are supported for each channel subsystem.

classification rule. A rule used by the System z Workload Manager to assign a service class to a workload.

D

discretionary goal. A service class performance goal assigned to low-priority work that does not have any specificperformance goal. Work assigned a discretionary goal is run only when system resources are available.

E

ensemble. A collection of one or more zEnterprise nodes (including any optionally attached zBXes) that aremanaged as a single logical virtualized system by the Unified Resource Manager using a Hardware ManagementConsole (HMC).

ensemble member. A zEnterprise node that has been added to an ensemble using the Hardware ManagementConsole. See also node.

ensemble membership. This zEnterprise feature ships the appropriate cabling for connectivity to the intranodemanagement network (INMN). This feature has a corequisite of two OSA-Express3 1000 base-T features for primaryand backup connectivity. A port is defined as CHPID type OSM for connectivity to the INMN.

Enterprise Common Collector. A common data repository that extracts and stores data from the HardwareManagement Console for use by a number of different components. The Enterprise Common Collector enablesgreater sharing of information currently available only to the limited set of users with access to the HardwareManagement Console and also decreases the amount of traffic to and from the Hardware Management Console.

F

firmware. Licensed Internal Code (LIC) shipped with hardware. Typically marketing materials do not referencefirmware or LIC. Note that the Unified Resource Manager is delivered as a part of the firmware of the HardwareManagement Console.

G

guest platform management provider (GPMP). An optional suite of applications that is installed in specific z/OS,Linux, AIX, and Windows operating system images to support platform-management functions. For example, theGPMP collects and aggregates performance data for virtual servers and workloads.

H

Hardware Management Console (HMC). A user interface through which data center personnel configure, control,monitor, and manage System z hardware and software resources. The HMC communicates with each centralprocessor complex (CPC) through the CPC's Support Element (SE). Using the Unified Resource Manager on theHMCs/SEs, operations personnel can also create and manage an ensemble. See also primary HMC and alternateHMC.

HiperSockets™ network traffic analyzer (HSNTA). With the HSNTA, you can trace HiperSockets network trafficand help simplify problem isolation and resolution. Supported on zEnterprise systems and the IBM System z10®.

HMC. See Hardware Management Console.


hypervisor. A program that allows multiple instances of operating systems or virtual servers to run simultaneouslyon the same hardware device. A hypervisor can run directly on the hardware, can run within an operating system, orcan be imbedded in platform firmware. Examples of hypervisors include the Processor Resource/Systems Manager™

(PR/SM), z/VM, Kernel Virtual Machine (KVM), and PowerVM.

I

IBM blade. Any zEnterprise-supported blade that can be installed in a zBX Model 002 or subsequent.

IBM PowerVM. The family of technologies, capabilities, and offerings that deliver virtualization on IBM PowerSystems™.

IBM Smart Analytics Optimizer. The IBM Smart Analytics Optimizer for DB2® for z/OS V1.1 is an optimizer thatprocesses certain types of data warehouse queries. It is supported in the zBX, accelerates System z DB2 workloads,and is enabled and managed by the Unified Resource Manager as part of the ensemble. Also known as the IBMDB2 Analytics Accelerator for z/OS.

IBM System z. Umbrella family name used when referring to multiple product lines or the IBM mainframe class ofproducts in general.

IBM System z Application Assist Processor (zAAP). A specialized processor that provides a Java executionenvironment, which enables Java-based Web applications to be integrated with core z/OS business applications andbackend database systems.

IBM System z Integrated Facility for Linux (IFL). Allows System z users to run Linux in an LPAR or virtualmachine without adding capacity that would increase license fees for other software such as z/OS or DB2. TheIntegrated Facility for Linux (IFL) is a central processor (CP) dedicated to Linux workloads that enables you topurchase additional processing capacity exclusively for Linux workloads, without affecting the MSU rating or theIBM zSeries model designation. Thus, an IFL will not increase charges for zSeries software running ongeneral-purpose (standard) System z processors.

IBM System z Integrated Information Processor (zIIP). A specialized processor that provides computing capacityfor selected data- and transaction-processing workloads, as well as for selected network-encryption workloads.

IBM zEnterprise BladeCenter Extension (zBX). A heterogeneous hardware infrastructure that consists of aBladeCenter chassis attached to a zEnterprise server. Along with the System z central processors, blades, and IBMSmart Analytics Optimizer installed in the chassis, a zBX can be managed as a single, logical, virtualized system bythe Unified Resource Manager.

IBM zEnterprise System (zEnterprise). A heterogeneous hardware infrastructure that can consist of a System zserver and an attached zBX, managed as a single, logical, virtualized system by the Unified Resource Manager.

IBM zEnterprise Unified Resource Manager (Unified Resource Manager). The Unified Resource Manager isLicensed Internal Code, also known as firmware, that is part of the Hardware Management Console. The UnifiedResource Manager provides energy monitoring and management, goal-oriented policy management, increasedsecurity, virtual networking, and data management for the physical and logical resources of a given ensemble. TheUnified Resource Manager is an integrated System z management facility responsible for zEnterprise platformmanagement.

Note: The Unified Resource Manager does not unify the management of System z with System p or System x nodes,nor does it unify the management of System z with IBM BladeCenter. It unifies the management of the componentsof zEnterprise, as well as multiple zEnterprise systems in a cluster (ensemble).

IEDN. See intraensemble data network.

IEDN TOR switch. See intraensemble data network TOR switch.

IFL. See Integrated Facility for Linux.

inbound workload queuing (IWQ). Creates multiple input queues and allows an OSA-Express3 feature todifferentiate workloads “off the wire.” It then assigns each workload to a specific input queue (per device) to z/OS.For z/OS Sysplex Distributor and bulk data traffic. Applies to the zEnterprise server and the System z10.

zEnterprise Monitoring Agent Glossary 271

INMN. See intranode management network.

Integrated Facility for Linux. See IBM System z Integrated Facility for Linux.

intraensemble data network (IEDN). A private 10-gigabit Ethernet network for application data communicationswithin an ensemble. Data communications for workloads can flow over the IEDN within and between nodes of anensemble. All of the physical and logical resources of the IEDN are configured, provisioned, and managed by theUnified Resource Manager.

intraensemble data network TOR switch (IEDN TOR switch). This 10-gigabit Ethernet (10 GbE) switch is availableexclusively on the zBX Model 002. It provides connectivity to the intraensemble data network (IEDN) supportingapplication data within an ensemble. There are two 10 GbE switches available in the zBX Model 002.

intranode management network (INMN). A private 1000 base-T Ethernet network operating at 1 Gbps that isrequired for the Unified Resource Manager to manage the resources within a single zEnterprise node. The INMNconnects the Support Element (SE) to the zEnterprise server and to any attached zBX.

inventory gatherer component. A component of the Enterprise Common Collector that retrieves and stores datafrom the Hardware Management Console in the Enterprise Common Collector. The inventory gather discovers boththe physical and logical components of zEnterprise nodes and ensembles.

IT resource. May refer to a physical or virtual server, storage, or network hardware and components, for example afirewall, middleware software such as a database or individual components thereof, and application software thatruns independently or that can be deployed within an execution container such as a Web application server. ITresources are typically represented as configuration items in a configuration management database such as CCMDB.

J

JavaScript Object Notation (JSON). JSON is a lightweight, text-based, open standard for human-readable datainterchange. It is derived from the JavaScript programming language for representing simple data structures andobjects. JSON is often used for serializing and transmitting structured data over a network connection. It is primarilyused to transmit data between a server and a web application; as such, it is an alternative to XML.

JSON is a language-independent data format; code for parsing and generating JSON data is available for a largenumber of programming languages.

JSON. See JavaScript Object Notation.

L

Licensed Internal Code (LIC). LIC is microcode that performs low-level operating system functions such as basicinput/output system code (called “BIOS”), utility programs, device drivers, diagnostics, and any other code deliveredwith an IBM machine for the purpose of enabling the machine's specified functions. LIC does not include programsand code provided under separate license agreements, such as code provided under open-source license agreements.

Linux on System x. Linux running on the Intel processors-based line of System X workstations and on the Intelx86-based line of IBM blades within an IBM zEnterprise system.

Linux on System z. Linux running on IBM's proprietary line of System z processors, either stand-alone or under ahypervisor like PR/SM or z/VM.

M

Manage suite (Manage). The first functional suite associated with the Unified Resource Manager (the second is theAutomate suite). The Manage suite includes core operational controls, installation and configuration management,and energy monitoring.

management enablement level. Unified Resource Manager feature that determines the suite of hardwaremanagement functions and operational controls that are available for a zEnterprise server and any attached zBX. Thefeatures can be the Manage suite or the Automate suite.


management TOR switch (mgmt TOR switch). This top-of-rack 1000 base-T Ethernet switch operating at 1 Gbps isavailable in the zBX Model 001 and the Model 002. With the zBX Model 001, it provides a private networkconnection to the customer's z10™ Support Element (SE). Through this connection, all hardware management tasksfor the zBX Model 001 are performed, such as physical inventory discovery, hardware operational controls, serviceupdates, and repair and verify tasks. With the zBX Model 002, this switch again provides a private connection to thecustomer's zEnterprise SE for hardware management tasks, but it provides connectivity to the ensemble's intranodemanagement network (INMN).

Hardware management functions available on the System z10 with a zBX Model 001 are also available on thezEnterprise server with the Model 002, but connectivity through the management TOR switch also providesadditional management functions through the Unified Resource Manager across the INMN. The INMN does notexist on the zBX Model 001.

There are two 1000 base-T Ethernet switches (thus, two management TOR switches) per zBX Model 001 and zBXModel 002.

member. See ensemble member.

multi-platform processor. In zEnterprise systems, a multi-platform processor is a system made up of heterogeneousvirtualized processors that work together as one infrastructure.

N

network interface card (NIC). A printed circuit board that plugs into a server. It controls the exchange of data overa network and provides the electronic functions for the data link protocol or access method, such as token ring orEthernet.

node. A single zEnterprise server together with all its optional, attached zBXes. A node can be a member of onlyone ensemble.

O

optimizer. An optimizer is special-purpose hardware designed to accelerate or provide a specific function for all orpart of a workload. One example of an optimizer is the IBM Smart Analytics Optimizer installed in the chassis ofthe zBX, an integrated part of the IBM zEnterprise System.

OSM. OSA-Express for Unified Resource Manager. Provides connectivity to the intranode management network(INMN) from zEnterprise-to-Unified Resource Manager functions. Uses OSA-Express3 1000 base-T Ethernetexclusively operating at 1 Gbps. OSM is a CHPID type.

OSX. OSA-Express for zBX. Provides connectivity and access control to the intraensemble data network (IEDN)from a zEnterprise server to one of its attached zBXes. Uses OSA-Express3 10 Gigabit Ethernet exclusively. OSX is aCHPID type.

P

performance goal. The desired level of service that Platform Performance Management will use to determine theamount of a particular resource to assign to a workload.

performance index. A number that indicates whether the performance goal for a service class was achieved,exceeded, or missed. This number represents the ratio of its actual achievement versus its goal for a given serviceclass. Since this is a ratio, a performance index of 1.0 means the service class is exactly achieving its goal. Anythingless than 1.0 indicates the service class is over-achieving, and anything over 1.0 indicates the service class isunder-achieving.

performance policy. A description of the performance objectives and importance of a workload.

platform management. The subset of systems management focused on managing hardware and virtualizationfunctions.


Power® System Control Network (PSCN). The network within a zEnterprise server node that connects the SupportElement to the hardware control elements. This network provides for communication to all field-replaceable unitsand hierarchic control through a mirrored system of control cards and IP addresses.

The power subsystems, as well as failure data collection and recovery subsystems, of the System z server arecontrolled through a fully redundant dual-Ethernet communications network. This network supports problem anderror detection, and thus is essential for serviceability. The PSCN provides a means for subsystems to communicateand control the dynamic parameters of system operation. The PSCN also supports error reporting.

POWER7® blade. The general-purpose blade that can optionally be installed in a zBX.

PowerVM Enterprise Edition. Required for all POWER7 blades installed in the zBX. It is a set of comprehensivesystems technologies and services designed to enable aggregation and management of resources through aconsolidated, logical view. Not all functions of PowerVM are available when the blade is part of a zEnterprisesystem.

primary HMC. The System z Hardware Management Console (HMC) through which data-center personnel createand manage an ensemble. This HMC owns configuration and policy information that the Unified Resource Manageruses to monitor, manage, and adjust resources for all members of the ensemble. See also Hardware ManagementConsole and alternate HMC.

PSCN. See Power System Control Network.

Q

query maximum potential power. Data-center personnel can monitor and create a limit or cap level to ensure thepower usage is kept within that limit (instead of planning for the worst case). Part of the Unified ResourceManager's Manage suite.

R

rack. A free-standing structure or frame that holds multiple servers and expansion units, such as BladeCenterblades.

Representational State Transfer (ReST). A software architectural style for distributed hypermedia systems such asthe Worldwide Web. REST is a client/server architecture: clients initiate requests to servers; servers process requestsand return appropriate responses. Requests and responses represent the transfer of resources. A resource is a sourceof information and as such can be essentially any coherent and meaningful concept that can be addressed. Arepresentation of a resource is typically a document that captures the current or intended state of that resource in aparticular format, for example JSON or XML.

Resources (sources of specific information) are referenced via a global identifier (such as a URI in HTTP). Tomanipulate these resources, clients and servers communicate using a standard interface like HTTP and exchangerepresentations of these resources (the actual documents that pass the information).

An application that conforms to the REST architectural style is said to be ReSTful. A ReST API is a tool for buildingReSTful applications.

response time. A workload's response time describes the duration for its constituent work requests after they enterthe system until the application signals to the operating system and the relevant subsystems that the workload'sexecution has completed. Response times are typically measured on a request level. A workload is governed by aservice-level agreement that defines the average or maximum response time that must be achieved to comply withthe terms of that agreement.

ReST. See Representational State Transfer.

ReST API. An Application Programming Interface for building RESTful (Representational State Transfer)applications.


S

service. According to the Information Technology Infrastructure Library (ITIL) Version 3, a service is a means ofdelivering value to customers by facilitating outcomes customers want to achieve, but without the ownership ofspecific costs and risks.

service class. A group of work that has the same service goals or performance objectives, resource requirements, oravailability requirements.

service-level agreement (SLA). A contract between a customer and a service provider that specifies the expectationsfor the level of service with respect to availability, performance, and other measurable objectives.

SLA. See service-level agreement.

Smart Analytics Optimizer. See IBM Smart Analytics Optimizer.

static power save mode. An IBM zEnterprise system function used for periods of low utilization or potentiallywhen a Capacity Back Up system is sitting idle waiting to take over in the event of a failure. The server usesfrequency and voltage reduction to reduce energy consumption of the system. Static power save mode is initiated bythe customer using the �Hardware Management Console/SE, the Active Energy Manager, or the z/OS CapacityProvisioning Manager.

System z. See IBM System Z.

T

top-of-rack (TOR) switch. A network switch located in the first rack of an IBM zEnterprise BladeCenter Extension(zBX). Also see intraensemble data network (IEDN) TOR switch and management TOR switch.

TOR switch. See top-of-rack switch. Also see intraensemble data network TOR switch and management TORswitch.

transaction. A unit of processing consisting of one or more application programs, affecting one or more objects, thatis initiated by a single request.

U

Unified Resource Manager. See IBM zEnterprise Unified Resource Manager.

V

velocity goal. A service class performance goal that defines the acceptable amount of delay for work when thework is ready to run. Velocity is the measure of how fast work should run when ready, without being delayed bycontention for managed resources.

virtual appliance. A prepackaged software application that provides some well-defined business workflow. Virtualappliances make it easier to deploy a solution with minimal configuration. Many tiers of operating systems andapplications can be packaged as a single virtual appliance. These tiers can depend on the hardware resources ofdifferent architectures. See also virtual server collection and virtual server image.

virtual server. A logical construct that appears to comprise processor, memory, and I/O resources that conform to aparticular architecture. A virtual server can support an operating system, associated middleware, and applications. Ahypervisor creates and manages virtual servers.

virtual server collection. A set (not necessarily static) of virtual servers that support a workload. The constituentsof the collection at any given point are determined by the virtual servers that are supporting the workload at thattime. See also virtual appliance and virtual server image.

virtual server image. A package containing metadata that describes the system requirements, virtual disks, and anygoals and constraints for the virtual machine (for example, isolation and availability). The Open Virtual Machine


Format (OVF) is a Distributed Management Task Force (DMTF) standard that describes a packaging format forvirtual server images. See also virtual appliance and virtual server collection.

virtual server image capture. The ability to store metadata and disk images of an existing virtual server. Themetadata describes the virtual server's storage, network needs, goals, and constraints. The captured information isstored as a virtual server image that can be referenced and used to create and deploy other similar images.

virtual server image clone. The ability to create an identical copy (clone) of a virtual server image that can be usedto create a new, similar virtual server.

W

workload resource group. A collection of virtual servers that perform a customer-defined, collective purpose. Aworkload resource group generally can be viewed as a multi-tiered application. Each workload resource group isassociated with a set of service policies that define performance, energy consumption, and availability goals. Alsoreferred to as workload.

workload service level index. A high-level indication of how the workload resource group is performing withrespect to its active performance policy. In general, the importance of a service class (lowest, low, medium, high,highest) is mapped to a workload service level index (informational, warning, minor, critical, fatal), and the workloadservice level index for the entire workload resource group is that of the most important service class that is notachieving its goal.

X

x Hyp blade. An Intel CPU-based blade installed in the zEnterprise BladeCenter Extension (zBX) Model 002 bladecontroller.

Z

z BladeCenter Extension. See IBM zEnterprise BladeCenter Extension.

zAAP. See IBM System z Application Assist Processor.

zBX. See IBM zEnterprise BladeCenter Extension. The name zBX applies to both the Model 001 and Model 002.

zCPC. An IBM System z central processor complex.

zEnterprise. See IBM zEnterprise System.

zEnterprise System. See IBM zEnterprise System.

zEnterprise Unified Resource Manager. See IBM zEnterprise Unified Resource Manager.

zEnterprise 196. See IBM zEnterprise 196.

zIIP. See IBM System z Integrated Information Processor.

zManager. See IBM zEnterprise Unified Resource Manager.


Index

AAccept all certificates 13Acquiring the Hardware Management

Console certificate 22ACSADMIN 21ActiveMQPort 36administrator

Enterprise Common Collector 71administrator command summary 90advanced management module 269agent depot 99AJPPort 36AMM

See advanced management moduleAPI

GET /eccapi/admin/backup 188POST /eccapi/admin/backup 188

APIsAdministrator APIs

DELETE /eccapi/admin/clients/{client-name} 196, 200

DELETE /eccapi/admin/collection-profiles/{name} 193,201

DELETE /eccapi/admin/data-sources/{name} 194, 203

GET /eccapi/admin/backup 197,205

GET /eccapi/admin/clients 196,206

GET /eccapi/admin/clients/{client-name} 196, 209

GET /eccapi/admin/collection-profiles 193, 211

GET /eccapi/admin/collection-profiles/{name} 213

GET /eccapi/admin/config/authentication 193, 216

GET /eccapi/admin/data-sources 194, 236

POST /eccapi/admin/backup 197, 229

POST /eccapi/admin/clients 230POST /eccapi/admin/collection-

profiles 232PUT /eccapi/admin/clients/

{client-name} 196, 240PUT /eccapi/admin/clients/

{client-name}/resume 242PUT /eccapi/admin/collection-

profiles/{name} 193, 242PUT /eccapi/admin/config/

authentication 193, 244PUT /eccapi/admin/data-sources/

{name} 252configuration APIs

DELETE /eccapi/admin/config/loggers/{logger-name} 197, 202

GET /eccapi/admin/config/loggers 197, 222

APIs (continued)configuration APIs (continued)

GET /eccapi/admin/config/loggers/{logger-name} 197, 223

POST /eccapi/admin/config/loggers 197, 234

PUT /eccapi/admin/config/loggers/{logger-name} 197, 250

Configuration APIsDELETE /eccapi/admin/config/

certificates/{alias} 195, 201GET /eccapi/admin/config/

certificates/ 195, 218GET /eccapi/admin/config/


certificates/trust-all 195, 221GET /eccapi/admin/data-

sources 194, 225GET /eccapi/admin/data-sources/

{name} 227PUT /eccapi/admin/config/

certificates/{alias} 195, 247PUT /eccapi/admin/config/

certificates/trust-al 249DELETE /eccapi/admin/clients/

{client-name} 196, 200DELETE /eccapi/admin/collection-

profiles/{collection-profile-id} 193DELETE /eccapi/admin/collection-

profiles/{name} 201DELETE /eccapi/admin/config/

certificates/{alias} 195, 201DELETE /eccapi/admin/config/

loggers/{logger-name} 197DELETE /eccapi/admin/data-

sources/{name} 194, 203DELETE /eccapi/admin/loggers/

{logger-name} 202DELETE /eccapi/sessions/this-

session 192, 204GET /eccapi/admin/backup 187,

197, 205GET /eccapi/admin/clients 196, 206GET /eccapi/admin/clients/{client-

name} 196, 209GET /eccapi/admin/collection-

profiles 193, 211GET /eccapi/admin/collection-

profiles/{name} 213GET /eccapi/admin/config/

authentication 193, 216GET /eccapi/admin/config/

certificates/ 195, 218GET /eccapi/admin/config/


certificates/trust-all 195, 221GET /eccapi/admin/config/

loggers 197, 222

APIs (continued)GET /eccapi/admin/config/loggers/

{logger-name} 197, 223GET /eccapi/admin/data-

sources 194, 225GET /eccapi/admin/data-sources/

{name} 227GPUT /eccapi/admin/clients/{client-

name} 196POST /eccapi/admin/backup 187,

197, 229POST /eccapi/admin/clients 230POST /eccapi/admin/collection-

profiles 193, 232POST /eccapi/admin/config/

loggers 197, 234POST /eccapi/admin/data-

sources 194, 236POST /eccapi/sessions/ 192, 238PUT /eccapi/admin/clients/{client-

name} 196, 240PUT /eccapi/admin/clients/{client-

name}/resume 242PUT /eccapi/admin/collection-

profiles/{name} 193, 242PUT /eccapi/admin/config/

authentication 193, 244PUT /eccapi/admin/config/


certificates/trust-al 249PUT /eccapi/admin/config/loggers/

{logger-name} 197, 250PUT /eccapi/admin/data-sources/

{name} 252authentication 11, 13, 72, 193, 216, 244

Enterprise Common Collector 72authorization 11, 13automatic backup

Enterprise Common Collector 188

Bbackup

Enterprise Common Collector 187backup bundle 187, 188backup of the Enterprise Common

Collector 205base authentication 72, 193, 216, 244base authentication for the Enterprise

Common Collector 65

CCertificate APIs

DELETE /eccapi/admin/config/certificates/{alias} 195, 201

GET /eccapi/admin/config/certificates/ 195, 218


Certificate APIs (continued)GET /eccapi/admin/config/


certificates/trust-all 195, 221PUT /eccapi/admin/config/


certificates/trust-al 249certificate validation 11, 13certificates

HMC 22Changing the authentication mechanism

that the Enterprise Common Collectoruses to authenticate its clients 72, 193,244

Changing the configuration of thetruststore for the Enterprise CommonCollectors 249

Changing the default administratorpassword for the Enterprise CommonCollector 71

Changing the default port assignmentusing the installation program 36

Changing web container administratorcredentials for the Enterprise CommonCollector 93

client admin manager 162, 164client authorization manager 162, 164client configuration 65client data provider 162, 164client inventory gatherer 162, 164client RESTApi 162, 164client security 13client session manager 162, 164Cognos reports

prerequisites 8collection profile 78

path-accessible-collection-enabledparameter 160

command file 70, 92commands

tacmd addSystem 99components 1configuration

Enterprise Common Collector 21, 22,23

fields 103monitoring agent 97remote 99values 103

Configuring the Enterprise CommonCollection 90, 92

configuring the monitoring agent 97content manager 162, 164corequisites 5COSNamingPort 36Create a new logger for an Enterprise

Common Collector component 86Creating a backup bundle for the

Enterprise Common Collector 205Creating a backup for the Enterprise

Common Collector 197Creating a new client the Enterprise

Common Collector 230

Creating a new collection profile for theuser of the Enterprise CommonCollector 232

Creating a new collection profile for theuser of the Enterprise CommonCollector. 193

Creating a new collection profile theEnterprise Common Collector 78

Creating data sources for the EnterpriseCommon Collector 83

customer support 262customization Enterprise Common

Collectorcustomization 65Enterprise Common Collector 65

Customizing the Enterprise CommonCollector 65

Ddata cache manager 162, 164Data displayed in zEnterprise workspaces

is all zeros or characters strings aredisplayed a unknown 148

Data source cannot be reached 155Data source disabled unexpectedly 153Data source user authentication

failed 156data sources commands 83DEFAULT collection profile 78Defining data sources for the Enterprise

Common Collector 194, 236, 252Defining logging levels for the Enterprise

Common Collector 197, 234DELETE /eccapi/admin/clients/{client-

name} 196, 200DELETE /eccapi/admin/collection-

profiles/{collection-profile-id} 193DELETE /eccapi/admin/collection-

profiles/{name} 201DELETE /eccapi/admin/config/

certificates/{alias} 195, 201DELETE /eccapi/admin/config/loggers/

{logger-name} 197, 202DELETE /eccapi/admin/data-sources/

{name} 194, 203DELETE /eccapi/sessions/this-

session 192, 204Deleting a certificate 73Deleting a certificate with the specified

alias value from the EnterpriseCommon Collectors 195, 201

Deleting a collection profile 201Deleting a session between the Enterprise

Common Collector and an HMC 192Deleting a session with the Enterprise

Common Collector 204Deleting a specified client configured in

the Enterprise Common Collector 75,196, 200

Deleting a specified data source from theEnterprise Common Collectordatabase 194, 203

Deleting a specified data sources from theEnterprise Common Collectordatabase 83

Deleting the configuration profilesdefined for the Enterprise CommonCollector 78

Deleting the level of a specified loggerconfigured for the Enterprise CommonCollector 86, 197, 202

Deploying the Guest PlatformManagement Provider 22

DerbyPort 36Determining how the Enterprise

Common Collector handlesauthentication of its clients 72

Determining how the EnterpriseCommon Collector to handauthentication of its clients 193

Determining how the EnterpriseCommon Collector to handleauthentication of its clients 216

EeccService 52

logging 143Editing the monitoring agent Windows

silent install file 113Enabling the Web Services API for the

HMC 22Enterprise Common Collection

exiting the command shell 70, 92import command 70, 92logging off 70, 92logging on 70, 92running a command file 70, 92utility command summary 92

Enterprise Common Collector 1, 90APIs 191application programming

interface 66automatic backup 188backup 187, 188capabilities 2changing the default administrator

password 71Changing web container administrator

credentials 93collection profile 65command file 66command line interface

changing the default administratorpassword 71

command-line interface 65, 66accessing helop 66administrator commands 90changing the default administrator

password 65client commands 75creating, listing, and updating

clients 65default collection profile 65defining whether the Enterprise

Common Collector uses baseauthentication or LDAP using thecommand-line 65

defining whether to use baseauthentication or LDAP 72

logging on 65managing certificate 73


Enterprise Common Collector (continued)command-line interface (continued)

managing certificates 65messages 66setting collector logging levels 65setting logging levels 86setting up a command file 66setting up HMC data sources 65,

83setting up the collection

profile 65, 78syntax 66utility commands 92

components 162, 164connection to the HMC 138Defining a user of the System z

Hardware Management Console foruse with the Enterprise CommonCollector 21

description 2installation considerations 2installation program

Changing the default portassignment 36

installing from the console 41Installing using the installation

program 36installing using the installation

wizard 26installing using the silent install 46known problems and

workarounds 161listing Java processes running in the

Enterprise Common Collector 53log file format 143logging 65, 86logging components 86logging for eccService 143logging locations 143managing the Web container 93manual backup 187message format 143messages 143, 162, 164, 165migration 187querying the status of the 53registering as a service with

WebSphere Application ServerCommunity Edition 52

removing 53required disk space 5resetting the eccService invalid login

count after it is locked 58restoring the Enterprise Common

Collector default configuration 59roles 66security 11, 13

managing certificates 65security certificates 73

Deleting a certificate 73Listing all the certificates in the

Enterprise Common Collectortruststore 73

Managing certificates using thecommand-line 73

Seeing the certificates associatedwith a particular alias 73

Enterprise Common Collector (continued)security certificates (continued)

Updating the configuration of thetruststore to change the currentsetting for the “trust allcertificates” option 73

setting up HMC data sources usingthe command-line for the EnterpriseCommon Collector 83

Setting up the System z HardwareManagement Console for use withthe Enterprise CommonCollector 21, 22, 23

starting 53stopping 53stopping Java processes running in

the Enterprise CommonCollector 53

supported platforms 5troubleshooting 143, 148, 154

Data source cannot bereached 155

Data source disabledunexpectedly 153

data source user authenticationfailed 156

Enterprise Common Collector userID is unknown 149

Enterprise Common Collector userrole attempting login hasinsufficient authority 150

HMC operation results in HTTPstatus code 403 and reason code1 159

Incorrect hostname or port 151No data displayed in Tivoli

Enterprise Portal 148Path accessibility information for a

virtualization host could not beretrieved 160

port conflict 158web server container Apache

Geronimo must be running asAdministrator on Windows7 158

uninstallingcommand line 62installation wiard 60

verifying correct installation 51web services interface 191WebSphere Application Server

Community Edition 93Enterprise Common Collector fails to

initialize 154Enterprise Common Collector fails to

initialize because of port conflict 158Enterprise Common Collector logging

log name 143log size 143

Enterprise Common Collectortroubleshooting

problems and workarounds 148Enterprise Common Collector user ID is

unknown 149Enterprise Common Collector user role

attempting login has insufficientauthority 150

environment verification 135Establishing a session with the Enterprise

Common Collector 192, 238event integration support 255

FFinding the alias value for a specific

certificate in the Enterprise CommonCollectors 195, 219

Firewall considerations when setting upthe HMC and Enterprise CommonCollector 23

fixes, obtaining 262

GGET /eccapi/admin/backup 187, 188,

197, 205GET /eccapi/admin/clients 196, 206GET /eccapi/admin/clients/{client-

name} 196, 209GET /eccapi/admin/collection-

profiles 193, 211GET /eccapi/admin/collection-profiles/

{name} 213GET /eccapi/admin/config/

authentication 193, 216GET /eccapi/admin/config/

certificates/ 195, 218GET /eccapi/admin/config/certificates/

{alias} 195, 219GET /eccapi/admin/config/certificates/

trust-all/ 195, 221GET /eccapi/admin/config/

loggers 197, 222GET /eccapi/admin/config/loggers/

{logger-name} 197, 223GET /eccapi/admin/data-sources 194,

225GET /eccapi/admin/data-sources/

{name} 227globalization issues

Enterprise Common Collector 161GPMP 22Guest Platform Management

Provider 21, 22

HHardware Management Console 270

connection to the Enterprise CommonCollector 138

header field 187, 205header file 229HMC 11, 21, 22, 23, 83

See Hardware Management ConsoleHMC inventory gatherer 162, 164HMC notification handler 162, 164HMC operation results in HTTP status

code 403 and reason code 1 159HMC report gatherer 162, 164HMC session manager 162, 164HTTPSPort 36hypervisor 271

Index 279

IIBM Redbooks 261IBM Support Assistant 261IBM Tivoli Distributed Monitoring and

Application Management Wiki 261IBM Tivoli Monitoring version 7IEDN

See intraensemble data networkIEDN TOR switch

See intraensemble data network TORswitch

IFLSee Integrated Facility for Linux

import command 66Incorrect hostname or port 151INMN

See intranode management networkinstallation 25, 191

Enterprise Common Collectorinstallation wizard 26installing from the console 41port assignments 36registering as a service with

WebSphere Application ServerCommunity Edition 52

silent install 46uninstalling 62verification 51

monitoring agent 97order of activities 9remote 99Tivoli Enterprise monitoring agent 4Tivoli zEnterprise monitoring agent

installation flow 9Uninstalling the Enterprise Common

Collector from the console 62installation flow 9installation tasks

installing application support onTivoli Enterprise MonitoringServer 125

installing application support onTivoli Enterprise Portal clients 126

installing application support onTivoli Enterprise Portal Server 126

installation wizardEnterprise Common Collector

uninstalling 60installing application support 97installing application support on Tivoli

Enterprise Monitoring Server 125installing application support on Tivoli

Enterprise Portal clients 126installing application support on Tivoli

Enterprise Portal Server 126installing language packs 126installing monitoring agent application

supportTivoli zEnterprise monitoring agent

installing application support 124Installing the Enterprise Common

Collector 25Installing the Enterprise Common

Collector from the console 41Installing the Enterprise Common

Collector using the silent install 46installing the monitoring agent 97

installing the monitoring agent(continued)

editing the Windows silent installfile 113, 118

from the console 122Tivoli zEnterprise monitoring agent

installation 105installation from the console 122

using the installation wizard 105Installing the monitoring agent on

Windows using the silent install 118Installing the monitoring agent on

Windows using the silent installscript 113

installing the monitoring agent using thesilent install 118

installing Tivoli Common Reporting 132Integrated Facility for Linux 271

See IBM System z Integrated Facilityfor Linux

internal security 162, 164intraensemble data network 272intraensemble data network TOR

switch 272intranode management network 272inventory update 162, 164ISA 261

JJavaScript Object Notation 272JMXPort 36JMXSecurePort 36JSON 191

See JavaScript Object Notation

Kknown problems and workarounds

Enterprise Common Collector 161

Llanguage pack installation 97language packs 126

installing 126silent installation 126

LDAP 72, 193, 216, 244LDAP authentication 21LDAP authentication for the Enterprise

Common Collector 65LDAP server 193, 244Licensed Internal Code 272Linux compatibility libraries 7Listing a specified client configured in

the Enterprise Common Collector. 75Listing all clients configured in the

Enterprise Common Collector. 75Listing all the certificates in the

Enterprise Common Collectortruststore 73

Listing existing data sources for theEnterprise Common Collector 83, 194,225

Listing loggers configured for theEnterprise Common Collector 86

Listing the attributes of a specified clientconfigured in the Enterprise CommonCollector 209

Listing the clients configured for theEnterprise Common Collector. 206

Listing the configuration profiles definedfor the Enterprise CommonCollector. 78, 211

Listing the status of Java processesrunning in the Enterprise CommonCollector 53

local authentication 21logging

Enterprise Common Collector 143Logging on to the Enterprise Common

Collection 70

Mmanaged resource roles 21Managing certificates using the

command-line 73Managing the Enterprise Common

Collector web container 93messages

Enterprise Common Collector 162,164, 165

message ranges 162, 164Enterprise Common Collector

command-line interface 66metrics manager 162, 164migration

Enterprise Common Collector 187Modifying the a collection profile for the

Enterprise Common Collector 193Modifying the a collection profile for the

Enterprise Common Collector. 193monitoring agent

requirements 7

NNamingPort 36Netcool 255network interface card 273No zEnterprise data or incorrect data in

Tivoli Enterprise Portal 148

Oobtaining Tivoli Common Reporting 131OMNIbus 255OpenEJBPort 36ORBPort 36ORBSSLPort 36

Ppassphrase 187, 205, 229Path accessibility information for a


path-accessible-collection-enabledparameter 160

persistence manager 162, 164


POST /eccapi/admin/backup 187, 188,197, 229

POST /eccapi/admin/clients 230POST /eccapi/admin/collection-

profiles 193, 232POST /eccapi/admin/config/

loggers 197, 234POST /eccapi/admin/data-sources 194,

236POST /eccapi/sessions/ 192, 238Power System Control Network 274Prerequisite Scanner 8prerequisites 5

Cognos reports 8Tivoli Common Reporting 8

problem resolution 261problems and workarounds 148product overview

Tivoli zEnterprise monitoringagent 1

PSCNSee Power System Control Network

PUT /eccapi/admin/clients/{client-name} 196, 240

PUT /eccapi/admin/clients/{client-name}/resume 242

PUT /eccapi/admin/collection-profiles/{name} 193, 242

PUT /eccapi/admin/config/authentication 193, 244

PUT /eccapi/admin/config/certificates/{alias} 195, 247

PUT /eccapi/admin/config/certificates/trust-all 249

PUT /eccapi/admin/config/loggers/{logger-name} 197, 250

PUT /eccapi/admin/data-sources/{name} 252

QQuerying a named data source for the

Enterprise Common Collector byname 227

Querying the status of the EnterpriseCommon Collector 53

RRedbooks 261Registering the Enterprise Common

Collector as a service manually 52remote

installation and configuration 99remote deployment 99remote deployment of the monitoring

agent 97Removing the Enterprise Common

Collector 53Representational State Transfer

(ReST) 274requirements

monitoring agent 7

Resetting the client counterinvalid-login-attempts to 0 after a clientexceeds the maximum number of loginattempts (3) 75

Resetting the Enterprise CommonCollector invalid login count after theadministrator interface is locked 58

response file template 126ReST

See Representational State TransferReST API 274REST API 11, 13Restoring a backup bundle created for

the Enterprise Common Collector 229Restoring a backup created for the

Enterprise Common Collector 197restoring the Enterprise Common

Collector default configuration 59Retrieving a level of a specific logger

configured for the Enterprise CommonCollector 197, 223

Retrieving a list of all certificates in thetruststore for the Enterprise CommonCollector 195, 218

Retrieving a list of all clients configuredin the Enterprise CommonCollector 196

Retrieving a list of all currentconfiguration profiles defined for theEnterprise Common Collector. 193, 213

Retrieving a list of loggers configured forthe Enterprise Common Collector 197,222

Retrieving the attributes of a specifiedclient configured in the EnterpriseCommon Collector 196

running an Enterprise Common collectorcommand file 70, 92

running the Prerequisite Scanner 8

Ssecure communications 11, 13security 11, 13

basic mechanism or an LDAPserver. 193, 244

certificate validation 11, 13configuring 13Enterprise Common Collector 11, 13LDAP server 193, 244

Security between the Enterprise CommonCollector and its clients 13

Security between the Enterprise CommonCollector and the HMC 11

Seeing the certificates associated with aparticular alias 73

self-describing agent 97service classes 1service-level agreement 275Setting up an Enterprise Common

Collector command file 66Setting up HMC data sources using the

command-line for the EnterpriseCommon Collector 83

Showing the current setting for the "trustall certificates" option for the EnterpriseCommon Collector 195, 221

silent install 113silent installation 126silent installation of language packs 126SLA

See service-level agreementSMTPPort 36Software Support 261

contacting 262receiving weekly updates 262

Starting the Enterprise CommonCollector 53

Stopping Java processes running in theEnterprise Common Collector 53

Stopping the Enterprise CommonCollector 53

support assistant 261Support Assistant 261supported platforms 5System z Hardware Management

Console 11, 21, 22, 23, 83acquiring the HMC certificate 22defining a user 21Deploying the Guest Platform

Management Provider 22enabling the Web Services API 22firewall considerations 23setting up users and roles 21

Ttacmd addSystem command 99Testing the Enterprise Common Collector

connection to the HMCs 138Tivoli Common Reporting

capabilities 5, 131description 5, 131installation considerations 5installing 132obtaining 131prerequisites 8reports 97

Tivoli Enterprise monitoring agentinstallation considerations 4

Tivoli Enterprise Monitoring Serverinstalling application support 125

Tivoli Enterprise PortalNo data or incorrect data 148

Tivoli Enterprise Portal clientsinstalling application support 126

Tivoli Enterprise Portal Serverinstalling application support 126

Tivoli zEnterprise monitoring agentcomponents 1event integration support 255installation

editing the Windows silent installfile 113, 118

overview 1prerequisites

running the PrerequisiteScanner 8

requirementshardware 5IP versions 5Java versions 5platforms 5software 5

Index 281

Tivoli zEnterprise monitoring agent(continued)

security 11self-describing agent installation 97self-describing agent

troubleshooting 97silent install 118silent installation 113supported platforms 5uninstalling 129

Tivoli zEnterprise monitoring agentapplication support

uninstalling 129Tivoli zEnterprise monitoring agent

installationapplication support 97monitoring agent 97remote dployment 99

top-of-rack switch 275TOR switch

See top-of-rack switchtroubleshooting

Enterprise Common Collector 148,154, 161

troubleshooting scenariosEnterprise Common Collector

Data displayed in zEnterpriseworkspaces is all zeros orcharacters strings are displayed aunknown 148

Data source cannot bereached 155

Data source disabledunexpectedly 153

data source user authenticationfailed 156

Enterprise Common Collector userID is unknown 149

Enterprise Common Collector userrole attempting login hasinsufficient authority 150

HMC operation results in HTTPstatus code 403 and reason code1 159

Incorrect hostname or port 151Path accessibility information for a


port conflict 158web server container Apache

Geronimo must be running asAdministrator on Windows7 158

trust-all-certificates 11

UUninstalling the Enterprise Common

Collector using the installationwizard 60

Updating the attributes of a specifiedclient configured in the EnterpriseCommon Collector 75, 196, 240, 242

Updating the configuration of thetruststore to change the current settingfor the “trust all certificates” option 73

Updating the configuration profilesdefined for the Enterprise CommonCollector 78

Updating the level of a specified loggerconfigured for the Enterprise CommonCollector 86, 197, 250

Updating the name, description,inventory-resync-interval,long-term-collection-enabled,long-term-interval, orshort-term-interval values for aspecified collection profile 78

Updating the property values for aspecified collection profile on theEnterprise Common Collector. 242

utility command summary 92

Vverification 135, 136Verifying that the Enterprise Common

Collector installed correctly 51virtual servers 1virtualization hosts 1

Wweb container

Enterprise Common Collector 93Web server container Apache Geronimo

must be running as Administrator onWindows 7 158

Web Service API 21web services interface 191WebSphere Application Server

Community Editionuse by the Enterprise Common

Collector 93wiki 261workarounds 148

ZzCPC 276zEnterprise BladeCenter Extension

(zBX) 1zEnterprise central processor complex 1zEnterprise monitoring agent

verification 135, 136zEnterprise Monitoring Agent Enterprise

Common Collectorinstallation 25, 191

zEnterprise Monitoring Agent installationEnterprise Common Collector 25,

191monitoring agent 99

zEnterprise Unified Resource Manager 1zManager 1


��

Printed in USA

SC14-7358-00