IBMTivoli zEnterprise MonitoringAgent Version 6.2.3€¦ · IBMTivoli zEnterprise MonitoringAgent Version 6.2.3.2 ... Cognos and Tivoli Common Reporting ... PUT /eccapi/admin/clients/{client-name}

IBM Tivoli zEnterprise Monitoring AgentVersion 6.2.3.2

Installation and Configuration Guide

SC14-7358-01

��

IBM Tivoli zEnterprise Monitoring AgentVersion 6.2.3.2

Installation and Configuration Guide

SC14-7358-01

��

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

This edition applies to version 6, release 3 of IBM Tivoli Monitoring (product number 5724-C04) and to allsubsequent releases and modifications until otherwise indicated in new editions.

© Copyright IBM Corporation 2012, 2013.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 . . . . . . . . . 5Tivoli Application Dependency DiscoveryManager zEnterprise sensor . . . . . . . . 6

Prerequisites and integrated applications . . . . . 6Monitoring agent requirements . . . . . . . 8Cognos and Tivoli Common Reportingprerequisites . . . . . . . . . . . . . 9Running the Prerequisite Scanner . . . . . . 9

New since Version 6.2.3 of the Tivoli zEnterprisemonitoring agent . . . . . . . . . . . . 10Installation flow . . . . . . . . . . . . . 12

Chapter 2. Security considerations . . 15Security between the collector and the HMC . . . 15Security between the collector and its clients . . . 17

Chapter 3. Setting up the System zHardware Management Console for usewith the Enterprise Common Collector . 25Defining a user . . . . . . . . . . . . . 25Enabling the Web Services API . . . . . . . . 26Deploying the Guest Platform ManagementProvider . . . . . . . . . . . . . . . 26Acquiring the Hardware Management Consolecertificate . . . . . . . . . . . . . . . 26Firewall considerations . . . . . . . . . . 27Testing the Enterprise Common Collector connectionto the HMCs . . . . . . . . . . . . . . 28

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

Using the Advanced path to set ports . . . . 40Installing the Enterprise Common Collector fromthe console . . . . . . . . . . . . . . 45Installing the Enterprise Common Collector byusing the silent installation method . . . . . . 50Verifying that the Enterprise Common Collectorinstalled correctly . . . . . . . . . . . . 56Manually registering the Enterprise CommonCollector as a service . . . . . . . . . . . 56

Starting, stopping, removing, installing, andquerying the status of the Enterprise CommonCollector . . . . . . . . . . . . . . . 58Resetting the Enterprise Common Collector invalidlogin count for the user ID admin . . . . . . . 62Restoring the Enterprise Common Collector defaultconfiguration . . . . . . . . . . . . . . 63Uninstalling the Enterprise Common Collector usingthe installation wizard . . . . . . . . . . . 64Uninstalling the Enterprise Common Collector fromthe console . . . . . . . . . . . . . . 66

Chapter 5. Upgrading the zEnterprisemonitoring agent and the EnterpriseCommon Collector . . . . . . . . . 69

Chapter 6. Customizing the EnterpriseCommon Collector . . . . . . . . . 71Understanding the command-line interface . . . . 72Logging on to the Enterprise Common Collector byusing the command-line interface . . . . . . . 76Changing the default administrator password . . . 77Defining whether the Enterprise Common Collectoruses base authentication or LDAP by using thecommand-line . . . . . . . . . . . . . 78Managing certificates by using the command-line . 79Creating, listing, updating, and deleting clients byusing the command-line . . . . . . . . . . 82Setting up the collection profile by using thecommand-line . . . . . . . . . . . . . 85Setting up HMC data sources by using thecommand-line . . . . . . . . . . . . . 89Setting collector logging levels by using thecommand-line . . . . . . . . . . . . . 92Summary of administrator commands . . . . . 96Summary of utility commands . . . . . . . . 98Managing the Enterprise Common Collector webcontainer . . . . . . . . . . . . . . . 99

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

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

Installing the monitoring agent . . . . . . . 108Installing the monitoring agent by using theinstallation wizard. . . . . . . . . . . 108Installing the monitoring agent on Windowssystems by using the silent install script . . . 116

© Copyright IBM Corp. 2012, 2013 iii

Installing the monitoring agent on Linux orUNIX by using the console install andconfiguration scripts . . . . . . . . . . 121

Installing application support . . . . . . . . 127Installing application support on TivoliEnterprise Monitoring Server . . . . . . . 128Installing application support on the TivoliEnterprise Portal Server . . . . . . . . . 129Installing application support for the TivoliEnterprise Portal desktop and browser clients . 129

Language pack installation . . . . . . . . . 129Installing language packs on Windows systems 129Installing language packs on UNIX or Linuxsystems . . . . . . . . . . . . . . 130Silent installation of language packs for agents 131

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

Chapter 8. Installing Tivoli CommonReporting and importing reports . . . 133Obtaining Tivoli Common Reporting . . . . . 133Installing Tivoli Common Reporting. . . . . . 133

Chapter 9. Verifying components afterconfiguration . . . . . . . . . . . 135Starting and verifying the core components of thezEnterprise service management environment . . 135Verifying that historical collection is configuredcorrectly . . . . . . . . . . . . . . . 136Importing the generated Enterprise CommonCollector certificate into the zEnterprise monitoringagent truststore. . . . . . . . . . . . . 138

Chapter 10. Troubleshooting thezEnterprise service managementenvironment . . . . . . . . . . . . 141Diagnosing problems using the Agent Summaryworkspace . . . . . . . . . . . . . . 147Problems and workarounds . . . . . . . . 153

No zEnterprise data or incorrect data is foundin Tivoli Enterprise Portal . . . . . . . . 153Enterprise Common Collector fails to initialize 160Known problems and workarounds . . . . . 166

Enterprise Common Collector components . . . 168Message ranges. . . . . . . . . . . . . 170Enterprise Common Collector general messages 170Enterprise Common Collector command lineinterface messages. . . . . . . . . . . . 192

Chapter 11. Migrating and backing upthe Enterprise Common Collector byusing the Migration Manager. . . . . 195Manual backup. . . . . . . . . . . . . 195Automatic backup . . . . . . . . . . . . 196

Appendix A. Customizing theEnterprise Common Collector byusing the REST APIs . . . . . . . . 199Background on the web services interface . . . . 199Starting and ending an API session . . . . . . 200Defining whether the Enterprise CommonCollector uses base authentication or LDAP usingthe REST APIs . . . . . . . . . . . . . 201Setting up collection profiles by using the RESTAPI. . . . . . . . . . . . . . . . . 201Setting up HMC data sources by using the RESTAPI. . . . . . . . . . . . . . . . . 202Managing certificates by using the REST API . . . 203Creating, listing, and updating clients by using theREST API . . . . . . . . . . . . . . 204Setting collector logging levels by using the RESTAPI. . . . . . . . . . . . . . . . . 204Managing backups by using the REST API . . . 205Enterprise Common Collector configuration APIsoverview . . . . . . . . . . . . . . . 206

DELETE /eccapi/admin/clients/{client-name} 208DELETE /eccapi/admin/collection-profiles/{name} . . . . . . . . . . . . . . . 209DELETE /eccapi/admin/config/certificates/{alias} . . . . . . . . . . . . . . . 209DELETE /eccapi/admin/config/loggers/{logger-name} . . . . . . . . . . . . . . . 210DELETE /eccapi/admin/data-sources/{name} 211DELETE /eccapi/sessions/this-session . . . . 212GET /eccapi/admin/backup . . . . . . . 213GET /eccapi/admin/clients . . . . . . . 214GET /eccapi/admin/clients/{client-name} . . . 217GET /eccapi/admin/collection-profiles. . . . 219GET /eccapi/admin/collection-profiles/{name} 221GET /eccapi/admin/config/authentication . . 224GET /eccapi/admin/config/certificates/ . . . 226GET /eccapi/admin/config/certificates/{alias} 227GET /eccapi/admin/config/certificates/trust-all 229GET /eccapi/admin/config/loggers. . . . . 230GET /eccapi/admin/config/loggers/{logger-name} . . . . . . . . . . . . . . . 232GET /eccapi/admin/data-sources . . . . . 233GET /eccapi/admin/data-sources/{name} . . . 235POST /eccapi/admin/backup . . . . . . . 237POST /eccapi/admin/clients/. . . . . . . 238POST /eccapi/admin/collection-profiles . . . 240POST /eccapi/admin/config/loggers . . . . 242POST /eccapi/admin/data-sources . . . . . 244POST /eccapi/sessions/. . . . . . . . . 246PUT /eccapi/admin/clients/{client-name} . . . 248PUT /eccapi/admin/clients/{client-name}/resume . . . . . . . . . . . . . . 250PUT /eccapi/admin/collection-profiles/{name} 250PUT /eccapi/admin/config/authentication . . 252PUT /eccapi/admin/config/certificates/{alias} 255PUT /eccapi/admin/config/certificates/trust-all 257PUT /eccapi/admin/config/loggers/{logger-name} . . . . . . . . . . . . . . . 258PUT /eccapi/admin/data-sources/{name} . . . 260

iv IBM Tivoli zEnterprise Monitoring Agent: Installation and Configuration Guide

Appendix B. Event IntegrationSupport . . . . . . . . . . . . . . 263

Documentation library . . . . . . . 265IBM Tivoli Monitoring library . . . . . . . . 265

Documentation for the base agents . . . . . 266Related publications . . . . . . . . . . . 267Other sources of documentation . . . . . . . 267

Support information . . . . . . . . 269

Notices . . . . . . . . . . . . . . 271Privacy policy considerations . . . . . . . . 273

Trademarks . . . . . . . . . . . . . . 274

zEnterprise Glossary . . . . . . . . 275

Index . . . . . . . . . . . . . . . 283

Contents v

vi IBM Tivoli zEnterprise Monitoring Agent: Installation and Configuration Guide

Figures

1. Tivoli zEnterprise monitoring and discoveryarchitecture overview . . . . . . . . . 2

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

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

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

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

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

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

screen . . . . . . . . . . . . . . 329. Enterprise Common Collector Software License

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

screen . . . . . . . . . . . . . . 3411. Enterprise Common Collector Choose Install

Folder screen . . . . . . . . . . . . 3512. Enterprise Common Collector Unsupported

Destination Folder screen . . . . . . . . 3513. Enterprise Common Collector Pre-Install

Summary screen . . . . . . . . . . . 3614. Enterprise Common Collector Installing

Enterprise Common Collector screen . . . . 3715. Enterprise Common Collector Key Pair

Generation screen . . . . . . . . . . 3816. Enterprise Common Collector Incomplete

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

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

Generation Results screen . . . . . . . . 39

19. Enterprise Common Collector successfulinstallation screen . . . . . . . . . . 40

20. Enterprise Common Collector Install Typescreen with Advanced selected . . . . . . 41

21. Enterprise Common Collector Install Typescreen with Port Settings selected . . . . . 42

22. Enterprise Common Collector Install Typescreen with Current Port Settings selected . . 45

23. Uninstall Enterprise Common CollectorUninstall Introduction screen. . . . . . . 65

24. Uninstall Enterprise Common CollectorUninstall Complete screen . . . . . . . 66

25. Tivoli zEnterprise Monitoring Agent SelectFeatures screen . . . . . . . . . . . 109

26. Tivoli Enterprise Monitoring Agent:Configuration of the Enterprise CommonCollector screen . . . . . . . . . . . 110

27. Tivoli Enterprise Monitoring Agent: Log TraceLevel Parameters screen . . . . . . . . 112

28. Tivoli Enterprise Monitoring Agent: SecureSockets Layer Communication screen . . . 113

29. Tivoli Enterprise Monitoring Agent: AllCertificates Will Be Accepted screen . . . . 114

30. Tivoli Enterprise Monitoring Agent: TruststoreCredentials screen . . . . . . . . . . 115

31. Tivoli zEnterprise Monitoring Agent -InstallShield Wizard Complete screen . . . 116

32. Agent Summary workspace . . . . . . . 14833. Manage Tivoli Enterprise Monitoring Services

screen . . . . . . . . . . . . . . 15834. Monitoring Agent for Tivoli Enterprise

Monitoring Agent: Configuration of theEnterprise Common Collector screen. . . . 158

35. Flow of automated backup processing 197

© Copyright IBM Corp. 2012, 2013 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 Enterprise CommonCollector or the zEnterprise monitoring agentcan be installed . . . . . . . . . . . 6

3. New workspaces in version 6.2.3.2. . . . . 104. New attributes and attribute groups . . . . 115. New situations . . . . . . . . . . . 116. Tasks roles that determine tasks permitted for

the managed resources . . . . . . . . . 267. Platforms and versions of the Enterprise

Common Collector installation wizard . . . 298. Platforms and versions of the Enterprise

Common Collector installation wizard . . . 309. Default port assignments for the installation

program . . . . . . . . . . . . . 4210. Platforms and versions of the Enterprise

Common Collector installation . . . . . . 4611. Default port assignments . . . . . . . . 5112. Parameters for key pair generation. . . . . 53

13. Platforms and versions of the EnterpriseCommon Collector installation . . . . . . 53

14. Summary of administrator commands . . . 9615. Summary of utility commands . . . . . . 9816. Location of KZE messages . . . . . . . 14017. Enterprise Common Collector - Data Sources

attribute group . . . . . . . . . . . 14918. Location of KZE messages . . . . . . . 15619. Possible values for the Status Reason Code

attribute . . . . . . . . . . . . . 16120. Common Java exceptions . . . . . . . 16121. Enterprise Common Collector known

problems . . . . . . . . . . . . . 16622. Enterprise Common Collector components

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

interface messages . . . . . . . . . . 19224. Enterprise Common Collector APIs . . . . 20625. LDAP authentication mode setting . . . . 254

© Copyright IBM Corp. 2012, 2013 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 the Enterprise Common Collector (collector). This component is the centralcollection point for zEnterprise data gathered from one or more System z® Hardware ManagementConsoles (HMCs). This component polls the HMCs for zEnterprise configuration and monitoring datafrom physical, virtual, and logical resources. The collector keeps the data cached, so that it can beprovided to requesting applications, such as the Tivoli zEnterprise monitoring agent or the TivoliApplication Dependency Discovery Manager (TADDM) zEnterprise sensor.

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.

© Copyright IBM Corp. 2012, 2013 1

Use Figure 1 as a reference in the discussion.

Enterprise Common CollectorThe Enterprise Common Collector (collector) is a common data repository that extracts and stores data fromthe zEnterprise System z Hardware Management Console (HMC) for use by a number of differentcomponents, including the 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 or the TADDM zEnterprise sensor. Data is exchanged between thecollector and the TADDM zEnterprise Sensor, and between the collector and Tivoli zEnterprisemonitoring agent, using a Representational State Transfer (REST) interface. REST is a client-server softwarearchitectural style for distributed hypermedia systems such as the Worldwide Web that consists of a set ofHTTP request and response flows.

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

Figure 1. Tivoli zEnterprise monitoring and discovery 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 and inventory 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 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.

If you have already installed the same version of the Enterprise Common Collector as part of anotherproduct, do not install it again. Skip to Chapter 6, “Customizing the Enterprise Common Collector,” onpage 71 and configure the version installed with the other product to support the zEnterprise monitoringagent. If you have installed an older version of the Enterprise Common Collector as part of anotherproduct, upgrade the existing collector to the version supplied with the Tivoli zEnterprise monitoringagent before customizing the collector to support the Tivoli zEnterprise monitoring agent. See Chapter 5,“Upgrading the zEnterprise monitoring agent and the Enterprise Common Collector,” on page 69 formore information about upgrading.

If you have not installed Tivoli Application Dependency Discovery Manager version 7.2.2 but plan to usethe Enterprise Common Collector to populate TADDM views with resources described in the System zHardware Management Console using the Enterprise Common Collector, do not install the EnterpriseCommon Collector with TADDM. Configure your TADDM zEnterprise Sensor to point to the version ofthe Enterprise Common Collector that was installed with the zEnterprise monitoring agent. Refer to theTADDM documentation for this information.

Chapter 1. Tivoli zEnterprise monitoring agent overview 3

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 30.v Using the console command-line interface. See “Installing the Enterprise Common Collector from the

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

silent installation method” on page 50.

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

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

Installation program Target platform for installing the collector

setup_ecc_v1102_aix_ppc64.bin AIX POWER®, 64-bit

setup_ecc_v1102_linux_s390x.bin Linux on System z, 64-bit

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

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

setup_ecc_v1102_windows_x86_32.exe Windows Server, 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.

If you have installed an earlier version of the Enterprise Common Collector, see Chapter 5, “Upgradingthe zEnterprise monitoring agent and the Enterprise Common Collector,” on page 69.

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

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


or 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 aboutzEnterprise 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.2 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 108.v Using the console interface (UNIX and Linux platforms). See “Installing the monitoring agent on UNIX

or Linux systems from the console” on page 125v 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 121 or “Installing themonitoring agent on Windows systems by using the silent install script” on page 116.

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 Fix Pack 1 or later, 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 8, “Installing TivoliCommon Reporting and importing reports,” on page 133.

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


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



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

Tivoli Application Dependency Discovery Manager zEnterprise sensorTivoli Application Dependency Discovery Manager (TADDM), IBM's solution for automating discoveryand visualization, provides a zEnterprise sensor for discovering the physical and virtual elements ofzEnterprise systems.

The zEnterprise sensor utilizes the Enterprise Common Collector for retrieving information about thezEnterprise environment. The resources that TADDM discovers using the TADDM zEnterprise sensor arestored in the TADDM Change and Configuration Management Database (CCMDB).

Having the zEnterprise resources available in the CCMDB and TADDM results in cost savings and adds anew dimension to the management capabilities of TADDM.

For additional information about the TADDM zEnterprise Sensor, see IBM Tivoli Application DependencyDiscovery Manager: Sensor Reference.


Use the information provided in the Tivoli Application Dependency Discovery Manager documentationto install and configure the TADDM zEnterprise sensor, as you would any TADDM sensor.

Prerequisites and integrated applicationsThe following prerequisite products and versions are required.

Prerequisite software

Ensure that the following products are installed and configured before you begin installation.v IBM Tivoli Monitoring version 6.2.3 Fix Pack 2 or later installation: Includes the Tivoli Enterprise Portal

browser 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 System z Hardware Management Console Hardware Management Console (HMC) version 2.11.1,Maintenance Bundle 34 or greater.

v IBM Tivoli Netcool/OMNIbus: Enables situation event forwarding from IBM Tivoli Monitoring and useof the Tivoli Event Integration Facility (EIF) interface to forward enterprise situation events to TivoliNetcool/OMNIbus (optional).

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

Supported platforms for installing the zEnterprise monitoring agent and thecollector

The Enterprise Common Collector or the zEnterprise monitoring agent can be installed on one of thefollowing platforms:

Table 2. Platforms on which the Enterprise Common Collector or the zEnterprise monitoring agent can be installed

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


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

Operating system One of these supported versions

AIX v AIX version 5.3 (Technology Level 12) or later*v 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 Server 2008 (Datacenter,Enterprise, and Standard editions)

Windows Server 2012 (Datacenter,Standard, and Essential editions)

v Windows Server 2008 SP2 or higher with the Windows 32-bit on Windows64-bit (WoW64) subsystem enabled

v Windows Server 2008 R2 or higher with the Windows 32-bit on Windows64-bit (WoW64) subsystem enabled

v Windows Server 2012 with the Windows 32-bit on Windows 64-bit (WoW64)subsystem enabled

For more information about requirements for 64-bit operating systems, see IBMTivoli Monitoring: Installation and Setup Guide.

*AIX V5.3 is not supported in Tivoli zEnterprise Monitoring Agent deployment scenarios in which theagent is colocated with IBM Tivoli Monitoring V6.3.0 monitoring components.

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 and clients. For more information aboutissues running monitoring agents and clients on the Security Enhanced Linux (SELinux) operatingsystem, see this technote: http://www-01.ibm.com/support/docview.wss?uid=swg21430478

If you are managing z/VM LPARs and guests in the System z Hardware Management Console (HMC),you must have the z/VM Systems Management Application Programming Interface (SMAPI) configuredand running. Data communications between z/VM and the HMC use the SMAPI interface. Additionally,network related metrics for z/VM guests are only available with z/VM 6.2 or later.

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.

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 the


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

configuration 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 of 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 Enterprise Common Collector and the zEnterprise monitoring agent support network addresses inboth IPv4 and IPv6.

Integrated applications

The Tivoli zEnterprise management solution works with the following product versions.

The following applications are not required, but complement the zEnterprise monitoring agent, resultingin benefit to both applications.v Tivoli Application Dependency Discovery Manager (TADDM) version 7.2.2 or later, with the TADDM

zEnterprise Sensor configured. The TADDM zEnterprise Sensor provides visibility into zEnterpriseresource as defined at the System z Hardware Management Console (HMC) and integrated them intoTADDM views and reports.

v Tivoli Business Services Manager (TBSM), version 6.1.1 or later.

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 run


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

correctly. Linux RedHat 5 and SuSE 10 also require the C++ Runtime 6.0 library (libstdc++.so.6). Seehttp://www-01.ibm.com/support/docview.wss?uid=swg21377580 for more information.

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

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

See the IBM Tivoli Monitoring Version 6.2.3 Information Center at http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.tivoli.tcr.doc_21/ic-home.html or the IBM Tivoli MonitoringVersion 6.3 Information Center athttp://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/index.jsp for thisinformation.

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

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"





http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/index.jsp

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

New since Version 6.2.3 of the Tivoli zEnterprise monitoring agentThe following changes were introduced to the Tivoli zEnterprise monitoring agent since the initial release(Version 6.2.3).

The initial release of the Tivoli zEnterprise monitoring agent focused on the new capabilities that wereintroduced with the IBM zEnterprise Systems. Specifically, the agent provided detailed monitoring of thezBX blades, hypervisors and virtual servers that reside on these blades, as well as the overall health andcomposition of Ensembles and Workload Resource Groups.

In version 6.2.3.2, new capabilities have been added to show detailed monitoring information on the CPClogical partitions (including zAware logical partitions), hypervisors, and virtual servers to complementthe hypervisor and virtual server information that was available for the zBX in the initial release.Additionally, a new Ensemble Networks Summary workspace has been added to provide insight into theperformance of each of the virtual networks defined in an Ensemble. The last major improvement in thezEnterprise monitoring agent is the ability to monitor the connections from the Enterprise CommonCollector to the System z Hardware Management Consoles that are being monitored.

New workspaces

The following workspaces were added in version 6.2.3.2.

Table 3. New workspaces in version 6.2.3.2.

Workspace name Description Associated attribute groups

Agent Health Displays self-diagnosis informationabout the Tivoli zEnterprisemonitoring agent, as well asmonitoring the connectionsbetween the Enterprise CommonCollector (ECC) and the System zHardware Management Consoles(HMCs).

v Agent Operations Log (OPLOG)v ECC Data Sources (KZEECCDS)v IBM Audit Log (KRAAUDIT)v Performance Object Status, (KZEPOBJST)

Ensemble NetworksSummary

Displays information about thevirtual networks and virtualizationhost network uplinks in theensemble.

v Ensembles (KZEENSEMBL)v Uplinks (KZEUPLINK)

PR/SM Virtual ServerDetails

Displays detailed information abouta specific virtual server on aPR/SM hypervisor and the CPU,memory, and network utilizationassociated with the virtual server.

v PR/SM Virtual Server (KZEPSMVS)v Workload Virtual Server (KZEWKLVSV)

z/VM Virtual ServerDetails

Displays detailed information abouta specific virtual server on a z/VMhypervisor and the CPU, memoryand network utilization associatedwith the virtual server.

v z/VM Virtual Server (KZEZVMVSV)v PR/SM Virtualization Host (KZEPSMVH)v Workload Virtual Server (KZEWKLVSV)


Table 3. New workspaces in version 6.2.3.2. (continued)

Workspace name Description Associated attribute groups

z/VM VirtualizationHost Details workspace

Displays detailed information abouta specific virtualization hostrepresenting a z/VM operatingsystem instance, along with theresource (CPU, memory andnetwork) utilization and virtualservers associated with thevirtualization host.

v z/VM Virtualization Host (KZEZVMVH)v z/VM Virtual Server (KZEZVMVSV)v Uplinks (KZEUPLINK)

New attributes and attribute groups

The following new attributes and attribute groups were added in version 6.2.3.2.

Table 4. New attributes and attribute groups

Attribute group Table prefix New or changed information

ECC Data Sources KZEECCDS Represents the characteristics and current status ofconnections defined from the Enterprise CommonCollector to IBM System z Hardware ManagementConsoles.

Logical Partitions KZELPAR Represents the characteristics and performance metrics ofLogical Partitions.

PR/SM Virtual Servers KZEPSMVS Represents the characteristics and performance metrics ofPR/SM Virtual Servers.

PR/SM Virtualization Hosts KZEPSMVH Represents the characteristics and performance metrics ofPR/SM Virtualization Hosts.

Virtual Networks KZEVNET Represents the characteristics and performance metrics ofVirtual Networks defined in an Ensemble.

z/VM Virtual Servers KZEZVMVS Represents the characteristics and performance metrics ofz/VM Virtual Servers.

z/VM Virtualization Hosts KZEZVMVH Represents the characteristics and performance metrics ofz/VM Virtualization Hosts.

New situations

The following new pre-defined situations were provided in this release. None of these situations areenabled by default.

Table 5. New situations

Situation Description

LPR_AcceptableStatus_Crit (Red): LPRACCSTAT = No The current status for the logical partition notAcceptable.

Data_Source_Disabled_Crit (Red): CDSENABLED = No &&CDSREASON != User_Disabled || Not_Started

The ECC data source is not enabled.

Data_Source_Status_Crit (Red): CDSSTATUS != Connected &&CDSSTATRC != Unknown

The status of the connection between the ECCand HMC is not Acceptable."

MVS_AcceptableStatus_Crit (Red): MVSACCSTAT = No The current status for the PR/SM virtual servernot Acceptable."

ZVS_AcceptableStatus_Crit (Red): ZVSACCSTAT = No The current status for the z/VM virtual servernot Acceptable.


Updated workspaces and navigation

A new Agent Health navigator item launches the Agent Health workspace, which has been updated todisplay self-diagnosis information about the Tivoli zEnterprise monitoring agent.

The zEnterprise Agent Summary workspace, which displays information about the Tivoli zEnterprisemonitoring agent, has been updated to include data presented in this view is from the ECC Data Sources(KZEECCDS) attribute group. This attribute group shows configuration and status information for theattribute groups associated with the Enterprise Common Collector.

The CPC workspace was updated to include a Logical Partition Summary table that displaysconfiguration and performance information for each logical partition defined in a CPC. Some of thecircular gauges were combined to improve usability.

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 3 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. If this is the first time you have installed the Tivoli zEnterprise monitoring agent, determine whereyou plan to install the monitor agent and its components. If you are upgrading, ensure that youknow where these components are installed.See “Prerequisites and integrated applications” on page 6 for supported environments. Threeinstallation 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. If you are installing the Enterprise Common Collector for the first time, set up the System zHardware 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 25 for information about performing these tasks.


5. Install or upgrade the Enterprise Common Collector. If installing for the first time customize theEnterprise Common Collector also.This component is the interface between the System z Hardware Management Console and the TivolizEnterprise monitoring agent. It also stores data and resources discovered by Tivoli Business ServicesManager and Tivoli Application Discovery and Manager. This component must be installed firstbecause the Tivoli zEnterprise monitoring agent needs it to install and function correctly. See:v Chapter 4, “Installing the Enterprise Common Collector,” on page 29v Chapter 6, “Customizing the Enterprise Common Collector,” on page 71

6. Install or upgrade the Tivoli zEnterprise monitoring agent, application support, and optionallanguage support:Use the installation and configuration procedures described in Chapter 7, “Installing the monitoringagent, application support files, and optional language support,” on page 103, 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 7, “Installing the monitoring agent, application support files, and optional languagesupport,” on page 103 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 or upgrade Tivoli Common Reporting. See Chapter 8, “Installing Tivoli Common Reportingand importing reports,” on page 133 for information about performing these tasks.

8. Import this agent's reports into Tivoli Common Reporting. If you are upgrading and have alreadyinstalled the reports, you can skip this step.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. If you are installing the product for the first time, a self-signed certificate was provided with theEnterprise Common Collector. You might want to import additional certificates or create newcertificates. Also, by default, the collector was set up to use its native base authentication, but youcan configure the Enterprise Common Collector to use LDAP authenticate, as discussed under“Defining whether the Enterprise Common Collector uses base authentication or LDAP by using thecommand-line” on page 78. To understand and potentially update the default security settings, seeChapter 2, “Security considerations,” on page 15.

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 9, “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. Security considerations

The zEnterprise service management environment consists of many components that are typicallydistributed across multiple systems.

It is important that interactions between these components are performed in a secure manner, to ensurethe integrity of the complete environment. Ensure that you review the following three aspects of securitywhen you install and configure this environment: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 authorizedapplications. To be viewed as an authorized application, the collector must adhere to these securityrequirements.


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. Whenthe 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 25 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 89 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 25 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 andauthenticate the communicating partner. When an application initiates an 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 79 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 15) 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.

Chapter 2. Security considerations 17

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 applicationswhen 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 78 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 page82 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 page82 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 72 for information about using the command-line interface.

Configure the zEnterprise monitoring agent to communicate with the collector, and configure the user IDand password of the collector at the same time.

The following illustration shows how the agent is configured to communicate with the collector using theinteractive graphical user interface.


See “Installing the monitoring agent” on page 108 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.v Service: allowed to retrieve information about the Enterprise Common Collector status.

Multiple roles can be assigned to a client. For a client to have access to all aspects of the collector, all fourroles 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 HTTP 403 Forbidden error response.

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

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


The credentials configured for the zEnterprise monitoring agent must be for a collector client that isassigned the Operator role and preferably the Service role. See “Creating, listing, updating, and deletingclients by using the command-line” on page 82 for information about managing the list of collectorclients and their assigned roles.

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 30 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. Whatever value your provide for the hostname must match thehostname or IP address that is in the certificate.


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 configuration process for the zEnterprisemonitoring agent. The following two illustrations show what the configuration panels look like when allcertificates 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 108 for information about how to configure the HTTPSsettings for the zEnterprise Monitoring Agent.

See “Importing the generated Enterprise Common Collector certificate into the zEnterprise monitoringagent truststore” on page 138 for information about importing the certificate generated as you install theEnterprise Common Collector into the the zEnterprise monitoring agent 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


http://publib.boulder.ibm.com/wasce/V2.1.1/en/index.html

http://publib.boulder.ibm.com/wasce/V2.1.1/en/index.html

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, so that

operating system-specific information, such as OSname and hostname, are available to the HMC andthus to the collector. This information is required for dynamic workspace linking on the zEnterprisemonitoring 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 6. 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 25).

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 so that the Enterprise Common Collector can obtaininformation (such as the operating system name or the hostname) to correlate a virtual server withsimilar information obtained from another place. This component is not required for core zEnterprisemonitoring activities and is optional.

This information is required for dynamic workspace linking on the zEnterprise monitoring agent

Note: For z/OS® systems, you need only configure and start the GPMP because this component isalready part 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 79 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.

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

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

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.

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 25 forinformation about setting up the HMC.


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” on page 30v “Installing the Enterprise Common Collector from the console” on page 45v “Installing the Enterprise Common Collector by using the silent installation method” on page 50

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

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

Installation wizard Target platform for installing the collector

setup_ecc_v1102_aix_ppc64.bin AIX POWER, 64-bit


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

setup_ecc_v1102_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 6, “Customizing the Enterprise Common Collector,” on page 71.

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

Upgrading to a new version

The sample scripts and panels in this section reflect the system defaults. However, if you are upgrading,these panels will reflect values from your existing installation that the tools migrate for you, so the valueswill be different.


For additional upgrade considerations, see Chapter 5, “Upgrading the zEnterprise monitoring agent andthe Enterprise Common Collector,” on page 69.

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 64 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.2 DVD in your DVD drive and start the

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

Table 8. 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 31

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


Note: If you are upgrading instead of performing a first time installation, you do not see this screen.If you select an invalid folder for installing the Enterprise Common Collector, this message is shown:

7. The Pre-Install Summary screen is displayed. The summary shows you the installation folder youselected 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

Figure 12. Enterprise Common Collector Unsupported Destination 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 64 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 13. Enterprise Common Collector Pre-Install Summary screen


Note: If you are upgrading, you do not see Steps 9 through 13. This is because the EnterpriseCommon Collector uses the same key pair after upgrade that was created during the initialinstallation. Skip to Step 13.

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 14. 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 15. Enterprise Common Collector Key Pair Generation screen

Figure 16. 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 17. Enterprise Common Collector Alias Already Exists popup

Figure 18. 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 defaultports, use this path in the installation program to make port changes.

Figure 19. Enterprise Common Collector successful installation screen


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

the installation wizard” on page 30.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 20. 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 9. 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.

61626

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


http://activemq.apache.org/

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

MulticastDiscoveryPort Defines the IPv6 multicast port through which the node agentsends discovery requests to its managed servers.

6142


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

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


MultipointPort Defines the port number used to communicate with a remotenode. The port must not be the default openEJB server port4201.

4212

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 netstat -tuln | grep 1050

AIX 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 66 to remove a partiallyinstalled Enterprise Common Collector image.

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

correct version for your platform:

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


Table 10. 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:

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

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 about installation and configuration of the Enterprise CommonCollector, refer to the installation manual found in the documentation libraryof the product using this component.

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

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.


8. When you press Enter, you see the prompt for choosing the install folder. If you are upgradinginstead of performing a first time installation, you will not see this prompt.===============================================================================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.If you specify an invalid folder for installing the Enterprise Common Collector, this message isshown:===============================================================================Unsupported Destination Folder------------------------------

’invalid_path’ is not supported as a destination path.The destination path should not include any blanks, brackets or other specialcharacters.

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

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: 433,057,047 BytesAvailable: 2,392,002,560 Bytes


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

Note: If you are upgrading, you do not see Steps 12 and 13. This is because the Enterprise CommonCollector uses the same key pair after upgrade that was created during the initial installation. Skip toStep 14.===============================================================================

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.2 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. If you

are upgrading, use the same response file that you created to install the Enterprise Common Collectorthe first time.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 the license agreement. If you want to review this file, itis found on the license subdirectory on the product 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 11. 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.

61626

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


http://activemq.apache.org/

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

Table 11. Default port assignments (continued)


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

MulticastDiscoveryPort Defines the IPv6 multicast port through which the node agentsends discovery requests to its managed servers.

6142

MultipointPort Defines the port number used to communicate with a remotenode. The port must not be the default openEJB server port4201.

4212

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

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 13. 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_v1102_windows.exe -f <full_path>\setup_ecc_install.rsp#### With windows, the "start /wait" command will prevent setup_ecc_v1102_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_v1102_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 license agreement.##################################################################################LICENSE_ACCEPTED=false

####################################################################### Enterprise Common Collector Install Location

# The install location of the product. Specify a valid directory# into which the product should be installed.# The directory path must not included spaces, brackets or other special# characters.# Windows file separators (\) must be escaped with a backslash character.# For example, to install the product to C:\IBM\ECC, use C:\\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 ORBPort=6882# COSNamingPort=1050 MulticastDiscoveryPort=6142 ORBSSLPort=2001# 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 6, “Customizing the Enterprise Common Collector,” onpage 71.

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

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

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 6, “Customizing theEnterprise Common Collector,” on page 71.

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 a

command 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. TheEnterprise 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 56, 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 theoperating 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 64 or “Uninstalling the Enterprise Common Collector from theconsole” on page 66.

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

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

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

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

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

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

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 58. 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 6, “Customizing the Enterprise Common Collector,” on page 71 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 collector


reconfigures 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 6,“Customizing the Enterprise Common Collector,” on page 71.

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 23. 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 will not remove the installation directory of the Enterprise Common Collector. Abackups folder is created under the installation directory that contains backups of collectorconfiguration data as well as log files. This backup information will be restored if the collector isreinstalled in the same location. Do not delete these files unless the collector will not be reinstalled onthis system. If these files are deleted manually, reinstallation of the collector on this system willrequire that the collector be reconfigured.

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

Figure 24. Uninstall Enterprise Common Collector Uninstall Complete screen



Windows <install_dir>\backups

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 uninstall process will not remove the installation directory of the Enterprise Common Collector. Abackups folder is created under the installation directory that contains backups of collectorconfiguration data as well as log files. This backup information will be restored if the collector isreinstalled in the same location. Do not delete these files unless the collector will not be reinstalled onthis system. If these files are deleted manually, reinstallation of the collector on this system willrequire that the collector be reconfigured.



Chapter 5. Upgrading the zEnterprise monitoring agent andthe Enterprise Common Collector

When upgrading the zEnterprise monitoring agent or the Enterprise Common Collector to a newerversion, ensure that the zEnterprise monitoring agent and the Enterprise Common Collector arecompatible.

A version of the Enterprise Common Collector API could have major or minor changes that make itincompatible with an older version of the zEnterprise monitoring agent. Similarly, a newer version of thezEnterprise monitoring agent might require certain API changes in order to work properly and thus notbe able to work with an older version of the Enterprise Common Collector.

Each version of the Enterprise Common Collector has an API major version and an API minor versionassociated with it. If you attempt to connect an instance of the zEnterprise monitoring agent to anEnterprise Common Collector instance that does not have a compatible API version, the connection willnot succeed. Error messages explain what API major version and API minor version were detected, aswell as what API major version is expected and what the minimum acceptable API minor version is.

When you upgrade the zEnterprise monitoring agent to a new version, upgrade the Enterprise CommonCollector to the version provided in the delivery mechanism for the zEnterprise monitoring agent. Whenyou upgrade the Enterprise Common Collector, upgrade the zEnterprise monitoring agent.

The Enterprise Common Collector is a common component that is designed to be used by multiple clientapplications. You might have a single Enterprise Common Collector instance serving multiple IBMproducts. In this case, upgrading the Enterprise Common Collector to a newer version might cause oneor more other client applications to have a compatibility problem with the Enterprise Common Collector.There are two ways to resolve this conflict:1. In some cases, IBM provides updated versions of the other client applications. See the IBM Software

Support page for the IBM Tivoli Monitoring agents. When such an update is available, this is thepreferred solution.

2. If the older version of the Enterprise Common Collector is compatible with the newer version of thezEnterprise monitoring agent, leave the Enterprise Common Collector at the older level that iscompatible with all client applications. However, if you do not upgrade your Enterprise CommonCollector, your enterprise won't benefit from new features and fixes in the new Enterprise CommonCollector version.

When you upgrade the zEnterprise Monitoring Agent to v6.2.3.2, you must also upgrade the EnterpriseCommon Collector to v1.1.0.2. If you try to connect a zEnterprise Monitoring Agent v6.2.3.2 to anEnterprise Common Collector v1.1.0.0 or v1.1.0.1, the connection fails and this message can be found inthe zEnterprise Monitoring Agent log:KZE0032E Could not connect to EnterpriseCommon Collector because the expectedCollector API version is not supported;actual api-major-version: {0}; actualapi-minor-version: {1}

This message tells you that you need to upgrade the TADDM zEnterprise Sensor or the EnterpriseCommon Collector or both so that they are at compatible levels.


http://www-947.ibm.com/support/entry/portal/overview

http://www-947.ibm.com/support/entry/portal/overview

Similarly, when upgrading the Enterprise Common Collector to v1.1.0.2 , upgrade the zEnterpriseMonitoring Agent to v6.2.3.2. If an attempt is made to connect a zEnterprise monitoring agent v6.2.3.0 orv6.2.3.1 to an Enterprise Common Collector v1.1.0.2, the connection will succeed but this configuration isnot supported and results will be unpredictable.


Chapter 6. Customizing the Enterprise Common Collector

Before you install the the zEnterprise monitoring agent, you must perform some configuration on theEnterprise 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 199.

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

2. Change the default administrator password and log on again with the new password.See “Changing the default administrator password” on page 77.

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

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 79 to understand this task. Tounderstand the larger security issues around making the Enterprise Common Collector, the System zHardware Management Consoles, and the zEnterprise monitoring agent secure, see Chapter 2,“Security considerations,” on page 15.

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

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 collector 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 collector refreshes historicalmetric data from each HMC (-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 the collector resynchronizeswith the 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 85.

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 to it. No default can be provided for this resource. You must define the HMC to the collectorin this 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 89.

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

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 73v “Accessing help from the command-line interface” on page 74v “Finding messages issued by the command-line interface” on page 75v “Types of commands” on page 75v “Paging output” on page 75

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 , Operator, or Service 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 that can be specified when you issue a particular command.Some parameters are required; others are optional. See “Summary of administrator commands”on page 96 for a quick summary of required and optional parameters.

See “Summary of administrator commands” on page 96 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 98 for a list of parameters required for utility commands.

Setting up a command file

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

The command file is plain text. Commands must be ended by a semicolon as in the example that follows:data-sources list;clients create -n newclient -p pass -r "Operator";clients list;

where this result is returned:name: HMCAcollection-profile-name: defaultenabled: truestatus: connectedhmc-user: hmcuser_1hmc-user-pwd: ********hmc-hostname: HMC510.mycompany.comdescription: HMCA datasource-----------------------------------------------------------------------------INFO: CTGEZ9810I Command clients completed.name: adminpassword: ********password-expiration-enabled: true

Chapter 6. Customizing the Enterprise Common Collector 73

invalid-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 <true|false>]

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 <true|false>]

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.

Paging output

The Command Line Interface uses a basic pager to display the output of a command one screen at atime. If the output of a command contains more lines than fit in the viewable portion of the command orterminal window, only the text that fits is displayed, followed by a line containing --More--. When yousee this --More-- indicator, you can enter one of the following:v Space (by pressing the spacebar) to see the rest of the output (or the next page of output if the rest of

the output will not fit on one screen)v Q or q to quit without viewing the rest of the output.v H or h to see help information about paging options.

Note that output of commands from a command file executed by the Import command is not paged.


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> -w <new_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 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” on page 77. This parameter is required.

new_passwordIs the new password for user ID for user. This password cannot be empty (that is, containonly white space) and must be different from the current password. Note that you can alsochange your password using a client update command, as explained in “Changing thedefault administrator password” on page 77. This parameter is optional.

When this parameter is provided, the user's password is then set to new_password, and theexpiration date is reset to the time period configured by the Enterprise Common Collectoradministrator. Note that you can use this command to change a password even if thepassword has already expired.

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. You can also perform this action during logon.

About this task

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

Procedure1. Start the Enterprise Common Collector by launching the eccAdmin command shell:

Platform Command file name

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


Platform Command file name


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

3. Enter this command to supply a new password for admin:clients update -n admin -p <client_password>

Where

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

These rules apply to passwords that you create:v The password cannot be an empty string.v The password cannot be all white space (for example, blanks or tabs).v The new password cannot be the same as the current password.

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

Changing the password logs off the current session after completion. Before you could complete theother configuration tasks in this section, you would need to log on again with the new password youdefined.

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


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

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

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

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 zEnterprise monitoring agent are covered under “Importingthe generated Enterprise Common Collector certificate into the zEnterprise monitoring agent truststore”on page 138.

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


Common Collector by using the command-line interface” on page 76 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 226. If you want to see the certificate associated with aparticular alias, you can use the “GET /eccapi/admin/config/certificates/{alias}” on page 227 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 229 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 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 255.

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

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



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


Common Collector by using the command-line interface” on page 76 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. This name should not contain anycontrol characters (for example null, new-line, or tab) or any of the following characters: "(quotation mark), / (slash), \ (backslash), # (number sign), % (percent sign), ; (semi-colon), ?(question mark), [ (square open bracket), ] (square close bracket).

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. Otherwise, it is optional.

roles Is one or more of the four 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 metricsv Service role that can retrieve information about the Enterprise Common Collector status

Multiple roles can be defined for a client. For any one client to have access to all aspects ofthe collector, all four 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, the


password 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 Operator,Service -d "monitoring 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 238.

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,Serviceenabled: truedescription: a monitoring user-----------------------------------------------------------------------------

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

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 four case-sensitive roles defined for all Enterprise Common Collectorclients:v Administrator role that can perform administrative tasks, such as creating data sources or

clients


v 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 metricsv Service role that can retrieve information about the Enterprise Common Collector status

Multiple roles can be defined for a client. For any one client to have access to all aspects ofthe collector, all four 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 248.

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 want to resume and falseif 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 250. See also “Resetting the EnterpriseCommon Collector invalid login count for the user ID admin” on page 62.

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 longer 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 175

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


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 accessibility

status 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 with

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


Common Collector by using the command-line interface” on page 76 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 244.

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 219. To list the collection profile defined by thecollection-profile-name, use this API: “GET /eccapi/admin/collection-profiles/{name}” on page 221.

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


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 interval


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

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


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


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 onTivoli Enterprise Portal.

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


Common Collector by using the command-line interface” on page 76 for more information.


2. To create a System z Hardware Management Console as a new data source for the EnterpriseCommon 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 may be outdated.The collector has started an unscheduled inventory discovery resynch its data with the HMC. Whenthe discovery process is complete, the status returns to connected.

For information about the API for performing this action, see “POST /eccapi/admin/data-sources” onpage 244.

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

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

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


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



Common Collector by using the command-line interface” on page 76 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 230. If you want to retrieve information about a specific named logger, use this API: “GET/eccapi/admin/config/loggers/{logger-name}” on page 232

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

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

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:










gez.moswos Service











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

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


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


Table 14. Summary of administrator commands (continued)


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

clients create Creates a client v -n (name)v -r (roles)

v -d (description)v -e (enabled)v -p (password)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


Table 14. Summary of administrator commands (continued)


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

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

v -u (HMC user name)v -p (HMC user

password)

v -o (HMC port)v -w (new-password)

v -o 8443

logoff Logs off theEnterpriseCommonCollector

None None None


Table 15. 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 58 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 page58.

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 58 forinformation about stopping and starting the Enterprise Common Collector.



Chapter 7. 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.2 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 or higher.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 105)

To perform the installation processes described in this section, you need the IBM Tivoli zEnterpriseMonitoring Agent v6.2.3.2 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.

When installing the agent remotely, you must provide the configuration values for the agent to operate.See “Configuration values” on page 106.

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 have installed theapplication support for that agent (Tivoli Enterprise Monitoring Server, Tivoli Enterprise Portal Server,and Tivoli Enterprise Portal). You must also have installed the agent bundle into the Remote DeployDepot.

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 7. Installing the monitoring agent, application support files, and optional language support 105

If you are using the command line, the following command is an example of remote installation andconfiguration for Windows operating systems:tacmd 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

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 appear 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 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 and integrated applications” on page 6. Ifyou do not have IBM Tivoli Monitoring installed, install and configure IBM Tivoli Monitoring 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 121

– “Installing the monitoring agent on Windows systems by using the silent install script” on page 116

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.2 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.2 and Agent Reports DVD in your DVD drive,

and change directories to the location where the Tivoli zEnterprise monitoring agent setup files arestored.


Windows itm\itm_agent\WINDOWS

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 3 or later > "Installing IBM Tivoli Monitoring" > "Installing monitoring agents". Select the versionof these 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.

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.

Figure 25. Tivoli zEnterprise Monitoring Agent Select Features screen


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.

Note: If you are upgrading, the screens that follow show the value you had previously configured. Toaccept these values, click Next to move through these configuration screens.

5. Continue installing this monitoring agent using the process described in IBM Tivoli Monitoring:Installation and Setup Guide version 6.2.3 Fix Pack 3 or later > "Installing IBM Tivoli Monitoring" >"Installing monitoring agents". Near the end of the installation process, a set of four screens isdisplayed that enable you to provide the values required for this monitoring agent. The first of thesescreens, displayed by default, is the Configuration for the Enterprise Common Collector window.

Provide values for the following fields, where:

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,and the monitoring agent will be configured to accept all certificates, then the defaultlocalhost is sufficient and does not need to be changed. If the Enterprise Common Collectorresides on different computer or the monitoring agent will not be configured to accept allcertificates, then localhost needs to be replaced with a fully qualified hostname, such astest1.somelab.raleigh.ibm.com.

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


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.

All Set tracing to the maximum and display all log messages for the Enterprise CommonCollector.

Figure 27. Tivoli Enterprise Monitoring Agent: Log Trace Level Parameters screen


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 28. 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 29. 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 30. 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 121

Note: If you are upgrading, use the same response file that you created to install the monitoring agentthe first time.

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.2 and Agent Reports DVD. Use the following steps to edit that response file as appropriate foryour environment:

Figure 31. Tivoli zEnterprise Monitoring Agent - InstallShield Wizard Complete screen


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 thedecisions 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 106


Procedure1. Locate the WINDOWS\silent.txt file in the itm_agents subdirectory of the IBM Tivoli zEnterprise

Monitoring Agent v6.2.3.2 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_CERT_LIST=YES;; Truststore certificate. The default is ze_agent_truststore.; If KZE_SSL_CERT_LIST=NO, then this parameter must be given a value.;KZE_TEMA_TRUSTSTORE=ze_agent_truststore;; Password for the truststore certificate. If KZE_SSL_CERT_LIST=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. For guidanceperforming these tasks, see "Performing a silent installation of IBM Tivoli Monitoring" section ofthe 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_CERT_LIST=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_CERT_LIST from yes to no, uncomment this line and acceptthe 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_CERT_LIST from yes to no, uncomment this line andaccept 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_CERT_LIST=NO, then this parameter must be given a value. The default password isz1manager. 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 by

using 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 systemsfrom the console” on page 125

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





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.2 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. In the version of this file provided

with this monitoring agent, the default is to install all components (INSTALL_PRODUCT=all). Each line inthis file must be either a comment (containing a # in column one) or a meaningful statement. Edit thefollowing 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 zEnterprise Monitoring Agent#INSTALL_PRODUCT=ze

# Install all productsINSTALL_PRODUCT=all

If you want to install the Tivoli zEnterprise monitoring agent and any additional available IBMTivoli Monitoring components, make sure that #INSTALL_PRODUCT=all remain uncommented.

b. If you want to install only the Tivoli zEnterprise monitoring agent, make sure that this line iscommented out:#INSTALL_PRODUCT=all

and that this line is uncommented: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_CERT_LIST=YES

# Truststore certificate. The default that is shipped is ze_agent_truststore.# If KZE_SSL_CERT_LIST=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_CERT_LIST=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.For guidance performing these tasks, see "Performing a silent installation of IBM TivoliMonitoring" 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_CERT_LIST=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_CERT_LIST from yes to no, uncomment this line and acceptthe 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_CERT_LIST from yes to no, uncomment this line andaccept 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_CERT_LIST=NO, then this parameter must be given a value. The default password isz1manager. 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.2 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.2 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.2 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.2 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 130v “Silent installation of language packs for agents” on page 131

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.2 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.2 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 8. 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.1or later, install it, configure it to work with IBM Tivoli Monitoring version 6.2.3 Fix Pack 3 or later, andimport the Tivoli zEnterprise monitoring agent predefined reports.

The sample reports provided with this monitoring agent are found on the IBM Tivoli zEnterpriseMonitoring Agent v6.2.3.2 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 Fix Pack 3 and lateris v2.1.1. The version of Tivoli Common Reporting shipped with IBM Tivoli Monitoring v6.3 and is v3.1.

See the IBM Tivoli Monitoring information center for information about installing and configuring TivoliCommon Reporting to work with IBM Tivoli Monitoring.v For IBM Tivoli Monitoring v6.2.3 Fix Pack 3and later, see http://pic.dhe.ibm.com/infocenter/tivihelp/

v15r1/index.jsp?topic=%2Fcom.ibm.itm.doc_6.2.3fp1%2Fwelcome.htmv For IBM Tivoli Monitoring v6.3 Fix Pack 3, see http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/

topic/com.ibm.itm.doc_6.3/welcome.htm

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


http://pic.dhe.ibm.com/infocenter/tivihelp/v15r1/index.jsp?topic=%2Fcom.ibm.itm.doc_6.2.3fp1%2Fwelcome.htm

http://pic.dhe.ibm.com/infocenter/tivihelp/v15r1/index.jsp?topic=%2Fcom.ibm.itm.doc_6.2.3fp1%2Fwelcome.htm

http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/topic/com.ibm.itm.doc_6.3/welcome.htm

http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/topic/com.ibm.itm.doc_6.3/welcome.htm



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 9. Verifying components after configuration

With all the components that make up zEnterprise service management environment installed 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 zEnterprise servicemanagement 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 you environment is configured and running.

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:

Platform Message content

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 89 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 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 zEnterprise monitoring agent is configured correctly to collect the data you want.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 9. 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 76). 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 85.

Importing the generated Enterprise Common Collector certificate intothe zEnterprise monitoring agent 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 zEnterprise monitoring agent keystore. Followthis procedure to 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 49 under “Installing the Enterprise Common Collector from theconsole” on page 45.

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.

Chapter 9. Verifying components after configuration 139

Platform Procedure

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 37 under “Installing the Enterprise Common Collector by usingthe installation wizard” on page 30.

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 16. 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 10. Troubleshooting the zEnterprise servicemanagement environment

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. Check the messages in the log files first to determine if the sourceis a problem in your environment or with the zEnterprise monitoring agent.

IBM Software Support might request some or all of these files while investigating a problem you havereported. If you determine that the problem is caused by this monitoring agent, see the agenttroubleshooting chapter in the IBM Tivoli zEnterprise Monitoring Agent User’s Guide for information or thesupport appendix for how to contact IBM Software Support.

This section provides information about the following topics:v “Message format”v “Runtime logging locations” on page 142v “Log file format” on page 142v “Logging for the command line interface” on page 144v “Logging for the Enterprise Common Collector service” on page 143v “Collecting the logs that IBM Software Support needs to troubleshoot collector problems” on page 144v “Finding related messages using the Correlation-ID” on page 145

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:









gez.moswos Service











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><correlation-id>2</correlation-id></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 is one of thefollowing levels.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 FINE: Important events and exceptionsv FINER: Detailed debug information, low-level logic, object dumps, and so onv FINEST: Method entry and exit tracing

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

correlation-idUsed to group related log messages generated by the same client request. This information inimportant to IBM Software Support in debugging problems (optional; for messages related to theadmin client). See “Finding related messages using the Correlation-ID” on page 145.

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 10. Troubleshooting the zEnterprise service management environment 143

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.

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 When you issue the ecc collect command, the Enterprise Common Collector generates the resultingarchive file in the directory from which the command was issued.

v If the -f option is 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.

Finding related messages using the Correlation-ID

You can find groups of messages that address the same client request, even if they are scatteredthroughout the log, by using the Correlation-ID.


The Correlation-ID is used to group log messages generated by the same client request. This identifier isreset on every restart, and is not persistent across ECC restarts. Related client request messages share thesame Correlation-ID. When an operation is completed, the Correlation-ID assigned to the operation is nolonger used.

In the sample that follows, log messages are shown in an operation where two clients perform successfullogons in parallel. Each successful logon results in three log messages. Since the logons for the two clientshappen in parallel, these two sets of three log messages per client are mixed (that is, not sequential). Bylooking at the Correlation-IDs (1 and 2 in this example), you can easily identify which messages belongto each logon instance.<record>

<date>2012-12-14T10:33:58</date><millis>1355477638552</millis><sequence>21914</sequence><level>INFO</level><class>com.ibm.tivoli.gez.servlet.requesthandler.EccCorrelationRequestHandler</class><method>handleRequest()</method><thread>40</thread><message>CTGEZ0051I Incoming POST-request from client host 0:0:0:0:0:0:0:1:45408 (Accept: ’*/*’) to

Enterprise Common Collector URI https://localhost:8443/eccapi/sessions. Assigned Correlation-ID 1 tothis client request.</message>

<correlation-id>1</correlation-id></record><record>

<date>2012-12-14T10:33:58</date><millis>1355477638553</millis><sequence>21915</sequence><level>INFO</level><class>com.ibm.tivoli.gez.servlet.requesthandler.EccCorrelationRequestHandler</class><method>handleRequest()</method><thread>41</thread><message>CTGEZ0051I Incoming POST-request from client host 0:0:0:0:0:0:0:1:45409 (Accept: ’*/*’) to

Enterprise Common Collector URI https://localhost:8443/eccapi/sessions. Assigned Correlation-ID 2 tothis client request.</message>

<correlation-id>2</correlation-id></record><record>

<date>2012-12-14T10:33:58</date><millis>1355477638621</millis><sequence>21916</sequence><level>INFO</level><class>com.ibm.tivoli.gez.restapi.SessionsApi</class><method>logon()</method><thread>41</thread><message>CTGEZ0700I Successful logon by user user01. Assigned session-id:

******************************************************gh9s6m10c5.</message><correlation-id>2</correlation-id>

</record><record>

<date>2012-12-14T10:33:58</date><millis>1355477638622</millis><sequence>21917</sequence><level>INFO</level><class>com.ibm.tivoli.gez.restapi.SessionsApi</class><method>logon()</method><thread>40</thread><message>CTGEZ0700I Successful logon by user user02. Assigned session-id:

******************************************************9834np8g3u.</message><correlation-id>1</correlation-id>

</record><record>

<date>2012-12-14T10:33:58</date><millis>1355477638635</millis><sequence>21918</sequence><level>INFO</level>


<class>com.ibm.tivoli.gez.servlet.requesthandler.EccCorrelationResponseHandler</class><method>handleRequest()</method><thread>41</thread><message>CTGEZ0052I Client request completed successfully: HTTP 200 OK. Consumed 83 milliseconds.

Message set for correlation-ID 2 is complete.</message><correlation-id>2</correlation-id>

</record><record>

<date>2012-12-14T10:33:58</date><millis>1355477638637</millis><sequence>21919</sequence><level>INFO</level><class>com.ibm.tivoli.gez.servlet.requesthandler.EccCorrelationResponseHandler</class><method>handleRequest()</method><thread>40</thread><message>CTGEZ0052I Client request completed successfully: HTTP 200 OK. Consumed 86 milliseconds.

Message set for correlation-ID 1 is complete.</message><correlation-id>1</correlation-id>

</record>

Diagnosing problems using the Agent Summary workspaceOne of the best tools to use in troubleshooting problems with the zEnterprise Monitoring Agentenvironment is the Agent Status workspace.

Clients who access this workspace must be granted the Service role. See “Creating, listing, updating, anddeleting clients by using the command-line” on page 82 for more information about defining this role.

This workspace is shown in Figure 32 on page 148:


The Agent Summary workspace displays information about the Tivoli zEnterprise monitoring agent. Thisworkspace is displayed when the user selects the Agent Health node in the Tivoli Enterprise PortalNavigator view. This workspace contains the following views:

zEnterprise Agent - Agent Operations LogA table that shows information about situation and connectivity messages that occur on themanaged system. This information is useful for diagnostic research with IBM Software Support. Itincludes message-related information about the Tivoli zEnterprise monitoring agent. The datapresented in this table is obtained from IBM Tivoli Monitoring, not from the Tivoli zEnterprisemonitoring agent.

zEnterprise Agent - ITM Audit LogA table that shows the IBM Tivoli Monitoring audit log for the agent. These attributes provideinformation on critical state-changing events in the monitoring environment, including thefollowing: what type of action the event represents; when did the event happen; what database,application, or permission was manipulated; on which machine did this event happen; whichsystem is the source of the event; and which system is the target of the event. The data presentedin this table is obtained from IBM Tivoli Monitoring, not from the Tivoli zEnterprise monitoringagent.

Enterprise Common Collector - Data SourcesA table that shows configuration and status information for the data sources defined to theEnterprise Common Collector (ECC). Each data source is represented by a row in this table. This

Figure 32. Agent Summary workspace


attribute group is most often used to determine why data is not available from a particular datasource in the other zEnterprise Monitoring Agent workspaces. Data presented in this table is fromthe Data Source attribute group.

zEnterprise Agent - Performance Object StatusA table that shows performance information for the attribute groups that make up the TivolizEnterprise monitoring agent. This information reflects the status of other attribute groups so youcan see the status of all of the performance objects that make up this application all at once. Eachof these other performance attribute groups is represented by a row in this table. The status foran attribute group reflects the result of the last attempt to collect data for that attribute group,which allows you to see whether the agent is performing correctly. Unlike other attribute groups,the Performance Object Status attribute group does not reflect the state of the monitoredapplication. This attribute group is most often used to determine why data is not available forone of the performance attribute groups. Data presented in this table is from the PerformanceObject Status attribute group.

The best of these tables from a troubleshooting perspective is the Enterprise Common Collector - DataSources table. The attributes that make up this attribute group are explained in Table 17 table thatfollows. The values for attributes in this workspace give you insight into why specific errors areoccurring. You can answer questions such as these:v Tell me about the System z Hardware Management Consoles (HMCs) that are configured as data

sources in the Enterprise Common Collector (ECC) (Name, HMC Name, HMC Version, Description,HMC API Major Version, HMC API Minor Version, TCPIP Hostname)

v What is the user name that the ECC used to connect to the data source? (User Name)v Did I configure the connection between the Enterprise Common Collector and the HMC data source

correctly?– What is the status of the connection between the ECC and each data source? (Status, Status Reason

Code, Prior Status, Status Changed Time)– Is the data source enabled? (Enabled, Disabled Reason Code)– What collection profile is the ECC using for this data source? (Collection Profile Name)– Is path accessibility status collection enabled? (Path Accessibility Enabled)

v From the ECC perspective, help me understand the inventory and metrics collection operations.– How often does this data source collect inventory data? (Inventory Start Time, Inventory End Time,

Inventory Collection Status)– How often does this data source collect metrics data? (Long Term Status, Short Term Status, Long

Term Metrics Duration, Short Term Metrics Duration,, Long-Term Metrics Interval, Short-TermMetrics Interval)

Table 17. Enterprise Common Collector - Data Sources attribute group

Attribute Definition and values

Name The name of the data source, as defined to the Enterprise Common Collector. This nameis user-defined when you configure the ECC.

Description Customer-defined text describing the data source.

Enabled Indicates whether the data source is enabled for the Enterprise Common Collector (ECC),meaning that the ECC can collect metrics from this data source. Valid values are asfollows:

v 0 = Unknown: The enabled value could not be determined.

v 1 = Yes: The data source is enabled.

v 2 = No: The data source is not enabled.


Table 17. Enterprise Common Collector - Data Sources attribute group (continued)


Disabled Reason Code Indicates the reason why the data source is disabled. Valid values are as follows:

v 0 = Unknown: Indicates that the status is unknown or cannot be determined.

v 1 = Not Applicable: Indicates that the data source is not disabled.

v 2 = Not Yet_Enabled: Indicates that the data source has not been enabled since theEnterprise Common Collector was started.

v 3 = User_Disabled: Indicates the data source was manually disabled by anadministrator.

v 4 = Unreachable: Indicates the data source is unreachable.

v 5 = Runtime_Error: Indicates the Enterprise Common Collector had an error for thisdata source and could not recover. The data source was disabled due to the error.Check the Enterprise Common Collector logs for further information.

Status The current operational status of the data source. Valid values are as follows:

v 0 = Unknown: Indicates that the status is unknown or cannot be determined.

v 1 = Connected: Indicates the Enterprise Common Collector has an active connection tothe data source.

v 2 = Connecting: Indicates the Enterprise Common Collector is attempting to connect tothe data source.

v 3 = Data_Source_Unreachable: Indicates the Enterprise Common Collector was notable to reach the data source.

v 4 = Disconnected: Indicates that the Enterprise Common Collector is not connected tothe data source.

v 5 = In_Doubt: Indicates that the Enterprise Common Collector inventory might not besynchronized with the System z Hardware Management Console (HMC). Inventorycollection from the HMC is running.

Status Reason Code Indicates the reason for the current operational status of the data source. Check the logfor additional information. Valid values are as follows:

v 0 = Unknown: Indicates that the reason for the status is unknown or cannot bedetermined.

v 1 = Not_Applicable: Indicates that the status is transitory and has no reason code.

v 2 = Bad_Credentials: Indicates the user id and or password used to the data sourcewere not accepted.

v 3 = Invalid_Response: Indicates an unexpected response was received from the datasource.

v 4 = Bad_Request: Indicates the Enterprise Common Collector sent a bad request to theSystem z Hardware Management Console (HMC). This may be seen if the ECC isattempting to connect to an unsupported version of the HMC.

v 5 = SSL_Problem: Indicates that a problem occurred with the data source during SSLnegotiations.

v 6 = Unknown_Host: The host name supplied in the data source definition could not beresolved to a valid host name.

v 7 = Connection_Problem: Indicates that a problem occurred while attempting toconnect to the data source. This condition may occur if the IP address of the datasource is invalid, or if the Web Services API is not enabled on the System z HardwareManagement Console.

HMC Name The name of the System z Hardware Management Console (HMC) to which thisEnterprise Common Collector is connected. This is the user-defined name that the systemprogrammer who set up the HMC provided. This field is empty if the collector is notconnected to the HMC.




HMC Version The version number of the System z Hardware Management Console (HMC) to whichthis Enterprise Common Collector is connected, in the format vv.rr.mm (for example2.11.1). This field is empty if the collector is not connected to the HMC.

HMC API Major Version The major-version level of the System z Hardware Management Console (HMC)firmware to which this Enterprise Common Collector is connected. This field is empty ifthe collector is not connected to the HMC.

HMC API Minor Version The minor-version level of the System z Hardware Management Console (HMC)firmware to which this Enterprise Common Collector is connected. This field is empty ifthe collector is not connected to the HMC.

TCPIP Hostname The TCP/IP host name of the system to which the Enterprise Common Collector isconnected.

User Name The user name that the Enterprise Common Collector used to connect to the data source.

Prior Status Indicates the operational status of the data source immediately prior to the currentstatus. Valid values are as follows:

v 0 = Unknown

v 1 = Not Applicable

v 2 = Connected: Indicates the Enterprise Common Collector (ECC) has an activeconnection the data source.

v 3 = Connecting: Indicates the ECC is attempting to connect to the data source.

v 4 = Data Source Unreachable: Indicates the ECC was not able to reach the data source.

v 5 = Disconnected: Indicates that the ECC is not connected to the data source.

v 6 = In Doubt: Indicates that the ECC inventory may not be synchronized with theSystem z Hardware Management Console (HMC). Inventory collection from the HMCis running.

Status Changed Time The local time of the most recent status change for the data source. Valid values are asfollows:

v Time stamp, expressed as hours:minutes:second.milliseconds.

v No Change

Session Duration The duration of the current session between the Enterprise Common Collector and thisdata sources, expressed as hours:minutes:second.milliseconds.

Collection Profile Name The name of the collection profile used to establish the collection characteristics for thisdata source.

Collection ProfileDescription

Customer-defined text describing the collection profile.

Inventory CollectionInterval

The user-configured amount of time in seconds that passes before the EnterpriseCommon Collector synchronizes inventory with the System z Hardware ManagementConsole (HMC), expressed as hours:minutes:seconds.milliseconds. Options are between0:5:0:0 and 24:0:0:0 (default is 8:0:0:0).

Short-Term MetricsInterval

The user-configured amount of time in seconds between retrievals of the current set ofmetrics from the System z Hardware Management Console (HMC), expressed ashours:minutes:second.milliseconds. Options are from 0:1:0:0 and 0:10:0:0 inclusive(default is 0:1:0:0).

Long-Term MetricsInterval

The user-configured amount of time in seconds between retrievals of the historical set ofmetrics from the System z Hardware Management Console (HMC), expressed ashours:minutes:second.milliseconds. Options are from 0:5:0:0 and 0:30:0:0 inclusive(default is 0:15:0:0).




Long-Term MetricsEnabled

Indicates whether historical metric data is retrieved from the System z HardwareManagement Console (HMC). Valid values are as follows:

v 0 = Unknown: Historical metrics collection enablement status could not bedetermined.

v 1 - Yes: Historical metrics collection is enabled.

v 2 = No: Historical metrics collection is not enabled.

Path AccessibilityEnabled

Indicates whether path accessibility status collection is enabled for this System zHardware Management Console (HMC). This might be disabled because collecting thisdata is time consuming. Valid values are as follows:

v 0 = Unknown: The path accessibility enablement could not be determined

v 1 = Yes: The path accessibility information will be collected.

v 2 = No: The path accessibility information will not be collected.

Inventory Start Time The local time when the Enterprise Common Collector started the most recent collectionof inventory data from this data source.

Inventory End Time The local time when the Enterprise Common Collector completed the most recentcollection of inventory data from this data source.

Inventory CollectionStatus

Indicates the status of the most recent inventory collection operation for this data source.Valid values are as follows:

v 0 = Unknown:


v 2 = Successful: Indicates the last inventory collection completed with no failureconditions.

v 3 = Cancelled: Indicates the last inventory collection was cancelled before completion.

v 4 = Failed: Indicates that the last inventory collection did not complete due to one ormore failure conditions.

Inventory CollectionDuration

The amount of time required to complete the current or most recent inventory collectionoperation from this data source, expressed as hours:minutes:second.milliseconds.

Short Term End Time The local time at the end of the Enterprise Common Collector short-term metricscollection operation from this data source.

Short Term Status Indicates the status of the most recent short-term metrics collection operation for thisdata source. Valid values are as follows:

v 0 = Unknown


v 2 = Successful: Indicates the last short-term metrics collection completed with nofailure conditions.

v 3 = Cancelled: Indicates the last short-term metrics collection was cancelled beforecompletion.

v 4 = Failed=4: Indicates that the last short-term metrics collection did not complete dueto one or more failure conditions.

Short Term MetricsDuration

The amount of time required to complete the current or most recent short-term metricscollection operation from this data source, expressed ashours:minutes:second.milliseconds.




Long Term Status Indicates the status of long-term metrics collection operation for this data source. Validvalues are as follows:

v 0 = Unknown


v 2 = Successful: Indicates the last short-term metrics collection completed with nofailure conditions.

v 3 = Cancelled: Indicates the last short-term metrics collection was cancelled beforecompletion.

v 4 = Failed=4: Indicates that the last short-term metrics collection did not complete dueto one or more failure conditions.

Long Term MetricsDuration

The amount of time required to complete the current or most recent long-term metricscollection operation from this data source, expressed ashours:minutes:second.milliseconds.

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

Configuration between the 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 Tivoli Enterprise Portal is all zeros or character strings are displayed as unknown.”v “Enterprise Common Collector user ID is unknown” on page 154v “Enterprise Common Collector user role attempting log in has insufficient authority” on page 155v “Incorrect hostname or port” on page 156v “Data source disabled unexpectedly” on page 159

Data displayed in Tivoli Enterprise Portal is all zeros or character strings aredisplayed as unknown.When you start Tivoli Enterprise Portal, the zEnterprise monitoring agent shows data in the workspaces,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.

Determine whether monitoring data has been retrieved by examining the Enterprise Common Collector –Data Sources view of the Agent Summary workspace. Check the value of Short Term End Time for thedata source in question. If no value is found in this table, then monitoring data has not been collected. Ifthere is no value for Short Term End Time or Inventory End Time, then the Enterprise CommonCollector might be waiting for the initial collection of inventory data to complete. If the value forInventory End Time is only a few minutes previous, then collection of monitoring data may have justbegun, and more time is needed to collect data at a second sampling interval.

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. Also check in the Agent Summary workspace to ensure that the data source is enabled and thatthe status is Connected (or In Doubt). The data source status and whether it is enabled can also beobserved by listing the data sources using the command line interface. See the enabled-value parameterunder “Setting up HMC data sources by using the command-line” on page 89.

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

The Enterprise Common Collector – Data Sources view in the Agent Summary workspace shows a StatusReason Code value of Bad Credentials for the data source in question. If you opened Tivoli EnterprisePortal 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 zEnterprise monitoring agent (during boththe monitoring agent configuration or the collector configuration) is incorrect, or the user ID has not beendefined to the collector.

A user ID must be created and given the correct level of authority (Explorer authority is most likely formonitoring) using the Enterprise Common Collector clients create command line interface. The user ID(or client ID in the Enterprise Common Collector) and password in both environments 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 zEnterprisemonitoring agent configuration that is defined to the Enterprise Common Collector, or use thecommand line interface to define a new user. See “Creating, listing, updating, and deleting clients byusing the command-line” on page 82 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 command line interface to resume this user ID. Forexample, if user ID andy is blocked, use this command:clients update -n andy -m true

See “Creating, listing, updating, and deleting clients by using the command-line” on page 82 formore information about the client command line interface.

v If you confirm that the Enterprise Common Collector user ID and password is correct, the problemmight be with the zEnterprise monitoring agent configuration. Right-click on the Agent on the ManageTivoli 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 156 or the IBM Tivoli Monitoring: Installation and Setup Guide.

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 82 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 “CTGEZ0310W” on page 173 for more information.


v If you opened the monitoring agent trace message log:

Table 18. 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 password, 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 serversv Operator role that can perform monitoring and discovery tasks, such at retrieving detailed information

about virtual servers and their performance metricsv Service role that can retrieve information about the Enterprise Common Collector status

The user ID used for communication between the Enterprise Common Collector and the zEnterprisemonitoring agent must be assigned the Operator role and preferably the Service 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 the Operatorrole and preferably the Service role. A user must be assigned the Operator role and preferably the Servicerole to retrieve metrics for monitoring. A user must be assigned the Explorer role to retrieve inventorydata 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 82.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 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.

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 are located on the same system,and the monitoring agent will be configured to accept all certificates, then the default

Figure 33. Manage Tivoli Enterprise Monitoring Services screen

Figure 34. Monitoring Agent for Tivoli Enterprise Monitoring Agent: Configuration of the Enterprise Common Collectorscreen


localhost is sufficient and does not need to be changed. If the Enterprise Common Collectorresides on different computer or the monitoring agent will not be configured to accept allcertificates, then localhost needs to be replaced with a fully qualified hostname, such astest1.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 Enterprise Common Collector – Data Sources view in the Agent Summary workspace indicates thatthe data source status (Prior Status attribute) has a value of Disconnected, the data source is not enabled(value for the Enabled attribute), and the value for Disabled Reason Code is Runtime Error. The datasource status and whether the data source is enabled can also be observed by listing the data sourcesusing the command line interface. See “Setting up HMC data sources by using the command-line” onpage 89 for information about listing a data source. Note that the Disabled Reason Code cannot beobserved using this method.

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 185 (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 184 (The API session with the data sourcenamed data source has been closed). Prior to this 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 89). 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”v “Data source user authentication failed” on page 162v “Enterprise Common Collector fails to initialize because of port conflict” on page 163v “HMC operation results in HTTP status code 403 and reason code 1” on page 164v “Path accessibility information for a virtualization host could not be retrieved” on page 165

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

The Enterprise Common Collector – Data Sources view in the Agent Summary workspace indicates thatthe data source Status is Connecting. The data source Status can also be determined by by listing thedata sources using the command line interface. See “Setting up HMC data sources by using thecommand-line” on page 89 for information about listing a data source.

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 184 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, examine the Status Reason Code in the Enterprise Common Collector– Data Sources view of the Agent Summary workspace. Possible values include the following:

Table 19. Possible values for the Status Reason Code attribute

Value Meaning

Invalid Response Indicates that an unexpected response was received from the data source

Bad Request Indicates that the Enterprise Common Collector sent a bad request to the System zHardware Management Console (HMC). This may be seen if the collector isattempting to connect to an unsupported version of the HMC.

SSL Problem Indicates that a problem occurred with the data source during SSL negotiations.

Unknown Host The host name supplied in the data source definition could not be resolved to a validhost name.

Connection Problem Indicates that a problem occurred when the HMC was attempting to connect to thedata source. This condition could occur if the IP address of the data source was invalidor if the Web Services API was not enabled on the HMC.

Unknown Indicates that the reason the data source cannot be reached is unknown or cannot bedetermined.

Not Applicable Indicates that the Enterprise Common Collector is still making its first attempt toconnect to the HMC. More time is needed for the collector to connect to the HMC orfor the first connection attempt to fail.

If the value is Unknown or if more information about the nature of the problem is needed, look forexceptions that should appear in the collector log file just before the message cited earlier. Examine thisexception to determine the nature of the problem. It is difficult to anticipate every exception that mightoccur but here are a few of the most common:

Table 20. 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 89 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.

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 page79 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. After approximatelytwelve hours have elapsed, the data source Status will change from Connecting to Data SourceUnreachable, the data source will be disabled, and the value for the Disabled Reason Code attribute willbe set to Unreachable.

In addition, 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 184 for details.

The following message will 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 185 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 89 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

The Enterprise Common Collector – Data Sources view in the Agent Summary workspace indicates thatthe data source Status is Data Source Unreachable, the value for the Status Reason Code attribute isBad Credentials, the data source is not enabled, and the value for the Disabled Reason Code attribute isUnreachable. The data source status and whether it is enabled can also be observed using thedata-sources list command interface to display the value returned for the enabled-value parameter. See“Setting up HMC data sources by using the command-line” on page 89 for more information. Note thatthe Status Reason Code cannot be determined using this method.

Additionally, 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 89 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 15.

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

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 errorwas 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 25 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 185 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 89 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 inventory gathering to complete.

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 the collection


profile specifies that path accessibility information should be collected, this operation is performed as partof the collection of inventory information.

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 85 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 21. Enterprise Common Collector known problems

Problem Solution or explanation

CPU Utilization attributes are found in both thePR/SM Virtual Server and Logical Partition attributegroups. When you are looking at a Logical Partitionvalue, and link to the PR/SM Virtual Server value,you might expect that these two values would be thesame, but they are not.

This is not an error. The two numbers show processorutilization from different perspectives. The Logical Partitionvalue is based on the amount of processor capacity the LPARis using relative to what the processor is entitled to as itsCPU share. The PR/SM Virtual Server value is calculated asprocessor time divided by the number of logical processors.The values should be different.

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.


Table 21. Enterprise Common Collector known problems (continued)

Problem Solution or explanation

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

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 170.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 the zEnterprise monitoring agent) logs in, this component assigns this client asession-id and manages 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 22. 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

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.

CTGEZ0050I Correlation-ID set to initial value {0}when the Enterprise Common Collectorstarted.

Explanation: The Correlation-ID is used to group logmessages generated by the same client request. Thisidentifier is reset on every restart, and is not persistentacross ECC restarts. The Correlation-ID can be used toanalyze the log messages that belong together in thecontext of a client request. Related client requestmessages share the same Correlation-ID. Value forcorrelation-ID of the next client request set to {0}during Enterprise Common Collector initialization.

User response: No action is required.

CTGEZ0051I Incoming {0}-request from client host{1}:{2} (Accept: '{3}') to EnterpriseCommon Collector URI {4}. AssignedCorrelation-ID {5} to this client request.

Explanation: A client at hostname or IP address {1}using port-number {2} has sent a {0} request to theEnterprise Common Collector (ECC) identified by theuniform resource indicator (URI) {4}, and the ECC hasassigned correlation ID {5} to this request. This logmessage confirms receipt of that client request. Thecontent of the Accept HTTP header is shown in {3}.Every log message related to the success or failure ofthis request uses the assigned Correlation-ID as prefix.This message makes no statement about the success orfailure of this client request. The meaning of themessage variables is explained in the information thatfollows: {0} represents the type of HTTP request (GET,POST, PUT, or DELETE). {1} represents the Hostnameor IP address of client sending the request. {2}represents the Port-number from which the clientrequest is sent. {3} represents the content of the AcceptHTTP header field the client is sending (for example,application/xml or application/json). {4} represents theECC URI to which the client sent the request. {5}represents the assigned Correlation-ID for this request.The following is a sample message in this format:Incoming POST-request from client host0:0:0:0:0:0:0:1:59226 (Accept: '*/*') to EnterpriseCommon Collector's URI https://localhost:8443/eccapi/sessions. Assigned Correlation-ID 12 to thisclient request.


CTGEZ0052I Client request completed successfully:HTTP {2} {3}. Consumed {0}milliseconds. Message set forcorrelation-ID {1} is complete.

Explanation: A client request submitted to theEnterprise Common Collector (ECC) and assignedCorrelation-ID {1} completed successfully, as indicatedby HTTP status code {2} and description {3}. This clientrequest consumed {0} milliseconds. When the clientrequest completed, the associated Correlation-ID is nolonger used. The meaning of the message variables isexplained in the information that follows: {0} representsthe amount of time the request consumed, expressed amilliseconds. {1} represents the assigned Correlation-IDfor this request. {2} represents the HTTP status code(for example, 200 or 204). {3} represents the descriptionof the HTTP status code (for example, OK or NOCONTENT).


CTGEZ0053W Client request completedunsuccessfully: HTTP {2} {3}. Consumed{0} milliseconds. Message set forcorrelation-ID {1} is complete.

Explanation: A client request submitted to theEnterprise Common Collector (ECC) and assignedCorrelation-ID {1} failed, as indicated by HTTP statuscode {2} and description {3}. This client requestconsumed {0} milliseconds. When the client requestfailed, the associated Correlation-ID {1} is no longerused. The meaning of the message variables isexplained in the information that follows: {0} representsthe amount of time the request consumed, expressed amilliseconds. {1} represents the assigned Correlation-IDfor this request. {2} represents the HTTP status code(for example, 400, 403, 404, or 500). {3} represents thedescription of the HTTP status code (for example, BADREQUEST, FORBIDDEN, NOT FOUND, or INTERNALSERVER ERROR).

User response: Analyze the log messages with thesame Correlation-ID to determine why the clientrequest failed.

CTGEZ0054W Client request cannot be completed:HTTP {4} {5}. {0}-request from client host{1}:{2} to invalid Enterprise CommonCollector URI {3}.

Explanation: A {0} client request submitted to theEnterprise Common Collector (ECC) at hostname or IPaddress {1} using port-number {2} failed, as indicatedby HTTP status code {4} and description {5}, becausethe ECC uniform resource indicator (URI) {3} requestedby the client is invalid. This rejected client request

CTGEZ0000W • CTGEZ0054W


produced only this log message. No Correlation-ID wasassigned to this client request. The meaning of themessage variables is explained in the information thatfollows: {0} represents the type of HTTP request (GET,POST, PUT, or DELETE). {1} represents the Hostnameand IP address of client sending the request. {2}represents the Port-number from which the clientrequest is sent. {3} represents the ECC URI to which theclient sent the request. {4} represents the HTTP statuscode (for example, 400, 403, 404, or 500). {5} representsthe description of the HTTP status code (for example,BAD REQUEST, FORBIDDEN, NOT FOUND, orINTERNAL SERVER ERROR).

User response: Determine why the client request sentto the Enterprise Common Collector was invalid.Correct the problem, and submit the client requestagain.

CTGEZ0055I Client request uses a valid session-idand is identified to belong to user ID{0}.

Explanation: A client request submitted to theEnterprise Common Collector provided a validsession-id. This message identifies the user ID {0} of theclient that submitted this request.


CTGEZ0056W Client request cannot be completed:HTTP {4} {5}. {0}-request from client host{1}:{2} is not allowed to EnterpriseCommon Collector URI {3}.

Explanation: A client request submitted to theEnterprise Common Collector (ECC) at hostname andIP address {1} using port-number {2} and identified bythe uniform resource indicator (URI){3} failed becausethe type of request {0} that the client submitted isinvalid for this URI. The client request wasimmediately rejected. This rejected client requestproduced only this log message. No Correlation-ID wasassigned to this request. The meaning of the messagevariables is explained in the information that follows:{0} represents the type of HTTP request (GET, POST,PUT, or DELETE). {1} represents the Hostname and IPaddress of client sending the request. {2} represents thePort-number from which the client request is sent. {3}represents the ECC URI to which the client sent therequest. {4} represents the HTTP status code (forexample, 400, 403, 404, or 500). {5} represents thedescription of the HTTP status code (for example, BADREQUEST, FORBIDDEN, NOT FOUND, or INTERNALSERVER ERROR).

User response: Determine why the client request sentto the ECC from this client was invalid. Correct theproblem, and submit the client request again.

CTGEZ0057W Client request cannot be completed:HTTP {4} {5}. Cannot handle {0}-requestfrom client host {1}:{2} (Accept: '{6}') toEnterprise Common Collector URI {3}.

Explanation: A client request {0} submitted to theEnterprise Common Collector (ECC) at hostname andIP address {1} using port-number {2} failed, as indicatedby HTTP status code {4} and description {5}, becausethe ECC uniform resource indicator (URI) {3} requestedby the client cannot handle this request. The content ofthe Accept HTTP header is shown in {6}. This rejectedclient request produced only this log message. NoCorrelation-ID was assigned to this client request. Themeaning of the message variables is explained in theinformation that follows: {0} represents the type ofHTTP request (GET, POST, PUT, or DELETE). {1}represents the Hostname and IP address of clientsending the request. {2} represents the Port-numberfrom which the client request is sent. {3} represents theECC URI to which the client sent the request. {4}represents the HTTP status code (for example, 400, 403,404, or 500). {5} represents the description of the HTTPstatus code (for example, BAD REQUEST,FORBIDDEN, NOT FOUND, or INTERNAL SERVERERROR). {6} represents the content of the Accept HTTPheader field the client is sending.

User response: Determine why the client request sentto the ECC from this client could not be processed.Correct the problem, and submit the client requestagain.

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.


CTGEZ0101I Enterprise Common Collector startedsuccessfully.

Explanation: All components of the EnterpriseCommon Collector were started successfully.


CTGEZ0055I • CTGEZ0101I


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

CTGEZ0310W Association between workloadresource group with object-id {0} andvirtual server with object-id {1} cannotbe created: Object with ID {2} unknown.

Explanation: An association between a workloadresource group and a virtual server could not bemodeled because one of these objects does not exist inthe Enterprise Common Collector's database. Thissituation can have various causes:

v The HMC found the unknown workload resourcegroup or virtual server but was not able tosuccessfully inventory it (for example, the Objectuniversal resource identifier (URI) could bedetermined, but the properties could not bedetermined) and thus an inventory error documentwas returned to the Enterprise Common Collectorinstead of the object properties.

v The HMC user accessed by the Enterprise CommonCollector is not permitted to access the unknownworkload resource group or virtual server.

System action: The association is not created.

User response: Search the Enterprise CommonCollector logs for message CTGEZ5200W, which islogged each time the Enterprise Common Collectorreceives an inventory error document from the HMC. Ifsuch a message is found for the unknown object, the

problem might rectify itself next time the inventory isgathered from the HMC. If the message persists, then aproblem with the HMC needs to be corrected.

If no inventory error documents were received for theobject, check the managed resource roles for the HMCuser, and grant the user permission to access themissing object.

CTGEZ0310W Association between workloadresource group with object-id {0} andvirtual server with object-id {1} cannotbe created: Object with ID {2} unknown.

Explanation: An association between a workloadresource group and a virtual server could not bemodeled because one of these objects does not exist inthe Enterprise Common Collector's database. Thissituation can have various causes:

v The HMC found the unknown workload resourcegroup or virtual server but was not able tosuccessfully inventory it (for example, the Objectuniversal resource identifier (URI) could bedetermined, but the properties could not bedetermined) and thus an inventory error documentwas returned to the Enterprise Common Collectorinstead of the object properties.

v The HMC user accessed by the Enterprise CommonCollector is not permitted to access the unknownworkload resource group or virtual server.

System action: The association is not created.

User response: Search the Enterprise CommonCollector logs for message CTGEZ5200W, which islogged each time the Enterprise Common Collectorreceives an inventory error document from the HMC. Ifsuch a message is found for the unknown object, theproblem might rectify itself next time the inventory isgathered from the HMC. If the message persists, then aproblem with the HMC needs to be corrected.

If no inventory error documents were received for theobject, check the managed resource roles for the HMCuser, and grant the user permission to access themissing object.

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.

CTGEZ0102E • CTGEZ0400W


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.

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

Explanation: A new password was entered, but thenew password is not sufficient. These rules apply topasswords: The password cannot be an empty string.The password cannot be all white space (for example,blanks or tabs). The new password cannot be the sameas the current password.

System action: The Enterprise Common Collectorrejects the proposed new password. The password andexpiration date are not changed.

User response: Submit a different password updaterequest using a password that conforms to thepassword rules.

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: An invalid user IDwas provided at logon. An invalid password wasprovided at logon. The logon was rejected because therequest was missing credentials, such as the user ID orthe password or both. The logon was rejected becausean internal problem occurred during the handling ofthe 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: Check your user ID and trythe logon again. Check your password and try thelogon again. Check your credentials and try the logonagain. See the log file for more information about thecause of 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 atimeout 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.

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.

CTGEZ1050E The parameter {0} is not allowed forrequests to this URI.

Explanation: The uniform resource identifier (URI)entered contains a parameter that is not supported.


User response: Submit the request again using onlyvalid parameters.

CTGEZ0709E • CTGEZ1050E


CTGEZ1051E Accept-type {0} of the HTTP Acceptheader field cannot be handled in thiscontext.

Explanation: A client has requested data the HTTPAccept header field format, which the EnterpriseCommon Collector cannot handle in this context. Onlythe following formats are supported for all APIs:application/json and application/xml. The monitoringAPIs also support text/csv.

User response: Submit the request again using asupported format.

CTGEZ1052W The provided value {0} for the hmc-idquery parameter does not specify aknown HMC console in the EnterpriseCommon Collector.

Explanation: A client has requested data using thehmc-id query parameter to retrieve objects that belongto a specific System z Hardware Management Console(HMC), but the specified HMC is not known to theEnterprise Common Collector.


User response: Submit the request again using validvalue for the hmc-id query parameter.

CTGEZ1053W A required parameter '{0}' is notprovided for this client request.

Explanation: A client sent a request that was missinga required parameter. The request could not beprocessed.


User response: Submit the request again, and supplythe missing required parameter.

CTGEZ1055E Parameter '{0}' not allowed in thiscontext.

Explanation: A client sent a request that contained aparameter that is not allowed in this context: Forexample not all parameters can be combined or thereare parameters, that are not allowed for all possibleHTTP Accept headers. The request could not beprocessed.


User response: Submit the request again, and supplyonly valid parameters.

CTGEZ1100E An internal problem occurred whilehandling the request. No data can bereturned.

Explanation: An internal problem forced theEnterprise Common Collector to stop processing arequest before the request completed.


User response: Check the trace log for a previousmessage, and submit the request again.

CTGEZ1101W Requested object with ID '{0}' isunknown. No data can be returned.

Explanation: A request was submitted for an objectidentified by its unique ID, but this object is not knownto the Enterprise Common Collector.


User response: This problem might occur occasionallyunder normal operating conditions. No action isrequired.

CTGEZ1102W Object {0} cannot be loadedcompletely. Prerequisite object {1} (type{2}) is missing.

Explanation: The object being loaded requires aprerequiste object before it can be fully loaded, but thisprerequisite object is not known to the EnterpriseCommon Collector.

System action: The object is created, and the missingdata is ignored.

User response: Analyze the trace log to determinewhy the missing object is not known to the EnterpriseCommon Collector.

CTGEZ1150W Metrics Gathering for data sourcewith name {0} is currently not enabled.Therefore no metrics are available forthe related objects. {1} objects areaffected by this missing data within therequest.

Explanation: A request for monitoring data wassubmitted, but metrics gathering is currently notenabled for the associated data source. The objectsaffected by this missing data could not be createdcompletely.

System action: The affected objects are created, butthe related metrics data portion is completed withdefault values.

User response: Enable the HMC to be monitored bythe Enterprise Common Collector. This action alsoenables metrics gathering for this HMC.

CTGEZ1151W Metrics Gathering for data sourcewith name {0} is enabled, but notenough data has been collected to beable to provide metrics data. {1} objectsare affected by this missing data withinthe request.

Explanation: A request for monitoring data wassubmitted, but initial collection of metrics data was still



in process. The objects affected by this missing datacould not be created completely.


User response: Wait until initial metrics gathering hascompleted. Then retry the request.

CTGEZ1152W A client request for long-term metricsdata was received for data source withname {0}, but long-term monitoringinterval is not enabled for this datasource. {1} objects are affected by thismissing data within the request.

Explanation: A request was submitted for long-terminterval monitoring data, but metrics gathering for thedata source is configured to collect short-term intervalmetrics only. The objects affected by this missing datacould not be created completely.


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

CTGEZ1153W No metrics for metric group {0} areavailable for data source with name {1}.{2} objects are affected by this missingdata within the request.

Explanation: Metrics Gathering is enabled for thespecified data source, but no metrics for the namedmetrics group could be collected. The objects affectedby this missing data could not be created completely.


User response: Check the trace log for previousmessages explaining why metrics for this metrics groupcould be collected.

CTGEZ1154W Some specific samples of metricgroup {0} for data source with name {1}are missing. {2} objects are affected bythis within the request.

Explanation: Metrics Gathering is enabled for thespecified data source, but some metrics from the namedmetrics group are not collected for the objects includedin the current request. The objects affected by thismissing data could not be created completely.


User response: Check the trace log for previousmessages explaining why some metrics may bemissing. This situation could occur if, for example, anobject was deleted shortly after it was created, but nonew metrics had been gathered up to that time.

CTGEZ1155W Metric group network-virtualization-host-uplink for data source with name{0} is missing. Uplinks cannot bedetected.

Explanation: Metrics Gathering is enabled for the datasource, but initial collection of the metric groupnetwork-virtualization-host-uplink is still in process.


User response: Wait until initial metrics gathering hascompleted. Then retry the request.

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: Submit the request again 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: Submit the request again with a validvalue for the indicated property.

CTGEZ1152W • CTGEZ1503E


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.


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


CTGEZ1506E Attribute {0} is required.

Explanation: The request could not be processedbecause a required attribute was not provided in theAPI request or was null.


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: Submit the request again with aunique name value.



CTGEZ1529E Unable to update data source withname {0} because no attributes to updateare supplied.

Explanation: The request to update a data sourcecannot be processed because no attributes are beingupdated. At least one attribute other than name musthave a value.

User response: Submit the request again and includean attribute to update.

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: SEVERE (highest level, bugs orcritical conditions) WARNING (undesireable orunexpected situations) INFO (high-level, heartbeatinformation) CONFIG (configuration parameters,equivalent to INFO) FINE (debugging, highest level)FINER (debugging, middle level) FINEST (debugging,lowest level) OFF (turns off all logging) ALL (enableslogging of all messages, equivalent to FINEST)

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: Submit the update logger requestagain with 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.

CTGEZ1548E Unable to update logger with name {0}because no attributes to update aresupplied.

Explanation: The request to update a logger cannot beprocessed because no attributes are being updated. Atleast one attribute other than name must have a value.


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.



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: Explorer Operator Administrator Service

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 default



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

CTGEZ1608E Unable to update client with name {0}because no attributes to update aresupplied.

Explanation: The request to update a client cannot beprocessed because no attributes are being updated. Atleast one attribute other than name must have a value.


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: Submit the request again using aunique name value.

CTGEZ1628E Unable to update collection profilewith name {0} because no attributes toupdate are supplied.

Explanation: The request to update a collection profilecannot be processed because no attributes are beingupdated. At least one attribute other than name musthave a 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 andsubmit the request again.

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 and



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


CTGEZ4301W No metric samples for metric group{0} are available for data source withname {1}, required for metricsprocessing of object with object-id {2}from metric group {3}.

Explanation: Processing metrics data for an objectfailed because it requires data from another metricgroup which is not available. The metrics data thatcould not be retrieved would have been used tocalculate aggregate data for the specified object.

System action: The affected values from the metricsample are set to zero.

User response: Check the trace log for previousmessages explaining why metrics for this metrics groupcould not be collected.

CTGEZ4302W No metric sample of metric group {0}for the object with object-id {1} isavailable for data source with name {2},required for metrics processing of objectwith object-id {3} from metric group {4}.

Explanation: Processing metrics data for an objectfailed because it requires a metric sample from anothermetric group which is not available. The metrics datathat could not be retrieved would have been used tocalculate aggregate data for the specified object.

System action: The affected values from the metricsample are set to zero.

User response: Check the trace log for previousmessages explaining why this metric set for the metricsgroup is not collected.

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 will



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

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.

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.



CTGEZ5504E Performance Management VelocityLevel Range Mappings for the ensemblewith object-id {0} could not be retrievedfrom the data source with name {1}.

Explanation: The response to a request forPerformance Management Velocity Level Range



Mappings information was invalid or could not beprocessed.

System action: Inventory gatherer processingcontinues. Velocity of service-classes from the affectedensemble cannot be calculated when using themonitoring-API.


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 more

insight 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: The response was not invalid application/json format. The response did notcontain a JSON object. The JSON object did not containa field named api-session or the value was empty. TheJSON object did not contain a field namednotification-topic or the value was empty. The JSONobject did not contain a field named api-major-versionor the value was empty. The JSON object did notcontain a field named api-minor-version or the valuewas empty.

User response: No action is necessary unless thismessage occurs mutiple 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.


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 Consolepasswords. 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: Bad key length (toolong or too short) Bad block size Problems withpadding the password to the specified block 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: Bad key length (too long or tooshort) Bad block size Problems with padding thepassword to the specified 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 is

not able to connect to the HMCs because it cannotprocess 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 cannotbe 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.

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.

System action: The Enterprise Common Collector has

created 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

CTGEZ8310W • CTGEZ8317I


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: Bad key



length (too long or too short) Bad block size Problemswith padding the password to the specified 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: Length between 8 and 50 characters Atleast one digit (0-9) At least one lowercase character(a-z) At least one uppercase character (A-Z) Specialcharacters 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:version: containing the version of the EnterpriseCommon Collector that was used to create the backupbundle 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 theArchive 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 total



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


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 defaultconfiguration 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 23. 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 Collector



accepted 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 meets



the 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 11. 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 213v “POST /eccapi/admin/backup” on page 237

Creating a backup bundle

This request to create a manual backup bundle requires a call to the “GET /eccapi/admin/backup” onpage 213 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 213 for details about this API and “Managing backups byusing the REST API” on page 205 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 page237 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 237 for details about this API and “Managing backups byusing the REST API” on page 205 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 35. Flow of automated backup processing

Chapter 11. Migrating and backing up the Enterprise Common Collector by using the Migration Manager 197

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 6, “Customizing theEnterprise Common Collector,” on page 71. 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 200v “Defining whether the Enterprise Common Collector uses base authentication or LDAP using the REST

APIs” on page 201v “Setting up collection profiles by using the REST API” on page 201v “Setting up HMC data sources by using the REST API” on page 202v “Managing certificates by using the REST API” on page 203v “Creating, listing, and updating clients by using the REST API” on page 204v “Setting collector logging levels by using the REST API” on page 204v “Managing backups by using the REST API” on page 205

To view all the APIs summarized in a table, see “Enterprise Common Collector configuration APIsoverview” on page 206. 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 datarepresentation. 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 HTTP 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 page76.

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

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 224 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 252 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 78.

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

Appendix A. Customizing the Enterprise Common Collector by using the REST APIs 201

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

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

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

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

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


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 244.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 260.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 page 211.

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

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

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

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

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

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

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 214 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 217 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 248 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 250 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 238 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 208 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 92.

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 230 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 232 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 242 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 258 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 210 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 11, “Migrating and backing upthe Enterprise Common Collector by using the Migration Manager,” on page 195.

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


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 24. Enterprise Common Collector APIs

API Function

“DELETE /eccapi/admin/clients/{client-name}” on page 208 Deletes the client specified with client-namefrom the Enterprise Common Collectordatabase.

“DELETE /eccapi/admin/collection-profiles/{name}” on page 209 Delete a collection profile for the userspecified by name on the EnterpriseCommon Collector.

“DELETE /eccapi/admin/config/certificates/{alias}” on page 209 Deletes a certificate with a specified aliasfrom the Enterprise Common Collectortruststore.

“DELETE /eccapi/admin/config/loggers/{logger-name}” on page 210 Deletes the logger specified withlogger-name that is currently configured forthe Enterprise Common Collector.

“DELETE /eccapi/admin/data-sources/{name}” on page 211 Deletes the data source specified with namefrom the Enterprise Common Collectordatabase.

“DELETE /eccapi/sessions/this-session” on page 212 Deletes a session with the EnterpriseCommon Collector.

“GET /eccapi/admin/backup” on page 213 Creates a backup bundle for the EnterpriseCommon Collector.

“GET /eccapi/admin/clients” on page 214 Lists the clients configured in theEnterprise Common Collector.

“GET /eccapi/admin/clients/{client-name}” on page 217 Lists the attributes of a specific clientdefined in Enterprise Common Collector.

“GET /eccapi/admin/collection-profiles” on page 219 Lists the properties of collection profilesdefined for the Enterprise CommonCollector.

“GET /eccapi/admin/collection-profiles/{name}” on page 221 Lists the properties of the collection profiledefined by name for the EnterpriseCommon Collector.

“GET /eccapi/admin/config/authentication” on page 224 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 226 Lists all the certificates in the truststore ofthe Enterprise Common Collector.


Table 24. Enterprise Common Collector APIs (continued)

API Function

“GET /eccapi/admin/config/certificates/{alias}” on page 227 Lists the properties of a certificate for aspecified alias in the Enterprise CommonCollector.

“GET /eccapi/admin/config/certificates/trust-all” on page 229 Lists the current setting for the “trust allcertificates” option.

“GET /eccapi/admin/config/loggers” on page 230 Lists the loggers configured for theEnterprise Common Collector.

“GET /eccapi/admin/config/loggers/{logger-name}” on page 232 Lists the level of a the logger specified withname that is currently configured for theEnterprise Common Collector.

“GET /eccapi/admin/data-sources” on page 233 Lists the existing System z HardwareManagement Consoles (HMCs) defined asdata sources in the Enterprise CommonCollector.

“GET /eccapi/admin/data-sources/{name}” on page 235 Lists the properties of a named System zHardware Management Consoles (HMCs)data source specified by name.

“POST /eccapi/admin/backup” on page 237 Restores a backup bundle created for theEnterprise Common Collector.

“POST /eccapi/admin/clients/” on page 238 Creates a client on the Enterprise CommonCollector.

“POST /eccapi/admin/collection-profiles” on page 240 Creates a collection profile for theEnterprise Common Collector.

“POST /eccapi/admin/config/loggers” on page 242 Create a logger for the Enterprise CommonCollector.

“POST /eccapi/admin/data-sources” on page 244 Creates a data source for the EnterpriseCommon Collector.

“POST /eccapi/sessions/” on page 246 Establishes a session with the EnterpriseCommon Collector, a required task beforeyou can use all other APIs.

“PUT /eccapi/admin/clients/{client-name}” on page 248 Updates the attributes of a specific clientspecified by client-name configured in theEnterprise Common Collector.

“PUT /eccapi/admin/clients/{client-name}/resume” on page 250 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 250 Updates the property values for thecollection-profile specified with name forthe Enterprise Common

“PUT /eccapi/admin/config/authentication” on page 252 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 255 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 257 Updates the configuration of the truststorein the Enterprise Common Collector.


Table 24. Enterprise Common Collector APIs (continued)

API Function

“PUT /eccapi/admin/config/loggers/{logger-name}” on page 258 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 260 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 four 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

v Service role that can retrieveinformation about the EnterpriseCommon Collector status

Multiple roles can be defined for aclient. For any one client to haveaccess to all aspects of the collector,all four 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 four 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 four 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.


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 collection-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/default","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/one-interval-only","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/long-term-interval","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



Status code Meaning


Example requestGET /eccapi/admin/config/certificates/

Example response

This API returns a JSON array containing the certificate:[{"alias": "mycert","version": 3,"class": "certificate","self": "/eccapi/admin/config/certificates/mycert","name": "Certificate Properties","fingerprint-md5": "8D:4F:61:D9:E7:DF:50:9C:F3:02:A0:1B:7B:7A:23:72","fingerprint-sha1": "D0:A5:B3:9B:2E:18:C1:CC:56:84:89:36:C6:F1:48:A8:24:5E:81:4C","subject-dn": "CN=myhost, OU=My unit, O=my organization, L=my city, ST=my state, C=US","issuer-dn": "CN=myhost, OU=My unit, O=my organization, L=my city, ST=my state, C=US","not-after": "Wed May 29 16:39:37 CEST 2013","not-before": "Thu Feb 28 15:39:37 CET 2013","serial-number": "1038040772","signature-algorithm-name": "SHA256withRSA","signature-algorithm-oid": "1.2.840.113549.1.1.11","public-key-algorithm-name": "RSA","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","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/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 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 168 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 168 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 213 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 four 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 fourroles 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 92). These component log names are valid:









gez.moswos Service













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



403 FORBIDDEN. This status code is returned if authentication fails. Authentication fails if one ofthe following is true: :v The user ID does not exist.v The password is incorrect.v The client is disabled.v The password has expired.v The client is locked because of too many failed logon attempts.

Look for a message containing more information in the response.


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 four 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 four roles mustbe 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


400 BAD REQUEST. This status code is returned if for some reason the request is invalid, such asnothing provided to update or the request body is not a valid JSON document. Look for amessage containing more information in the response

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 status code is returned if for some reason the request is invalid, suchas nothing provided to update or the request body is not a valid JSON document. Look for amessage containing more information in the response.

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 25. 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","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"}

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 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 92). These component log names are valid:









gez.moswos Service











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 resourceidentifier. This is the same as name butlogger-name shows how this property is referencedin the URI. As noted earlier, if instructed to do soby IBM Software Support, you could increase thelevel of detail that is logged for a specific portion ofthe Enterprise 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 for some reason the request is invalid, such asnothing provided to update or the request body is not a valid JSON document. Look for amessage containing more information in the response.

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


400 BAD REQUEST. This status code is returned if for some reason the request is invalid, such asnothing provided to update or the request body is not a valid JSON document. Look for amessage containing more information in the response.


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

For information about accessing and using the publications, select Using the publications in theContents pane of the IBM Tivoli Monitoring and OMEGAMON® XE Information Center athttp://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/index.jsp.

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, SC22-5445

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 High Availability Guide for Distributed Systems, SC22-5455Gives 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, SC22-5446Describes the support tasks and functions required for the Tivoli Enterprise Portal Server and clients,including Tivoli Enterprise Portal user administration.

v Command Reference, SC22-5448Provides detailed syntax and parameter information, as well as examples, for the commands you canuse in IBM Tivoli Monitoring.

v Messages, SC22-5450Lists 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, GC22-5449



Provides information to help you troubleshoot problems with the software.v Tivoli Enterprise Portal online help

Provides 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, SC22-5447Complements 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 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 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, SC22-5451– UNIX OS Agent User's Guide, SC22-5452– Linux OS Agent User's Guide, SC22-5453– IBM i Agent User's Guide, SC22-5454

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, SC22-5457– Warehouse Proxy Agent User's Guide, SC22-5456

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

Related publicationsFor information about related products and publications select OMEGAMON XE shared publications orother entries in the Contents pane of the IBM Tivoli Monitoring and OMEGAMON XE InformationCenter at http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/index.jsp .

Other sources of documentationYou can also obtain technical documentation about IBM Tivoli Monitoring and related products from thefollowing sources:v Service Management Connect (SMC)

For introductory information about SMC, see IBM Service Management Connect (http://www.ibm.com/developerworks/servicemanagement).For information about Tivoli products, see the Application Performance Management community onSMC at IBM Service Management Connect > Application Performance Management(http://www.ibm.com/developerworks/servicemanagement/apm).Connect, learn, and share with Service Management professionals. Get access to developers andproduct support technical experts who provide their perspectives and expertise. Using SMC, you can:– Become involved with transparent development, an ongoing, open engagement between external

users and developers of Tivoli products where you can access early designs, sprint demos, productroadmaps, and pre-release code.

– Connect one-on-one with the experts to collaborate and network about Tivoli and Integrated ServiceManagement.

– Benefit from the expertise and experience of others using blogs.– Collaborate with the broader user community using wikis and forums.

v Tivoli wikisIBM Service Management Connect > Application Performance Management (http://www.ibm.com/developerworks/servicemanagement/apm) includes a list of relevant Tivoli wikis that offer bestpractices and scenarios for using Tivoli products, white papers contributed by IBM employees, andcontent created by customers and business partners.Two of these wikis are of particular relevance to IBM Tivoli Monitoring:– The IBM Tivoli Monitoring Wiki (https://www.ibm.com/developerworks/mydeveloperworks/

wikis/home?lang=en#/wiki/Tivoli%20Monitoring/page/Home) provides information about IBMTivoli Monitoring and related distributed products, including IBM Tivoli Composite ApplicationManagement products.

– The Tivoli System z Monitoring and Application Management Wiki provides information about theOMEGAMON XE products, NetView® for z/OS, Tivoli Monitoring Agent for z/TPF, and otherSystem z monitoring and application management products.

v IBM Integrated Service Management Libraryhttp://www.ibm.com/software/brandcatalog/ismlibrary/IBM Integrated Service Management Library is an online catalog that contains integrationdocumentation and other downloadable product extensions.

v Redbooks®

http://www.redbooks.ibm.com/IBM Redbooks and Redpapers include information about products from platform and solutionperspectives.

v Technotes

Documentation library 267


http://www.ibm.com/developerworks/servicemanagement

http://www.ibm.com/developerworks/servicemanagement/apm/index.html


https://www.ibm.com/developerworks/mydeveloperworks/wikis/home?lang=en#/wiki/Tivoli%20Monitoring/page/Home

https://www.ibm.com/developerworks/mydeveloperworks/wikis/home?lang=en#/wiki/Tivoli%20System%20z%20Monitoring%20and%20Application%20Management

http://www-01.ibm.com/software/brandcatalog/ismlibrary/

http://www.redbooks.ibm.com/

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


http://www.ibm.com/software/support/

http://www.ibm.com/software/support/

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 Support Portal (http://www.ibm.com/support/entry/portal/software) and

follow the instructions.v Go to IBM Service Management Connect > Application Performance Management

(http://www.ibm.com/developerworks/servicemanagement/apm) and select the appropriatewiki.

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 IBM Support Assistant (http://www-01.ibm.com/software/support/isa).

Troubleshooting GuideFor more information about resolving problems, see the product's Troubleshooting Guide.


http://www.ibm.com/support/entry/portal/software


http://www-01.ibm.com/software/support/isa


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.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, 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 Web sites are provided for convenience only and do not inany manner serve as an endorsement of those Web sites. The materials at those Web sites are not part ofthe materials for this IBM product and use of those Web sites 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 2013. Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBM Corp.2013. All rights reserved.

If you are viewing this information in softcopy form, the photographs and color illustrations might not bedisplayed.

Trademarks

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

Adobe, Acrobat, PostScript and all Adobe-based trademarks are either registered trademarks ortrademarks of Adobe Systems Incorporated in the United States, other countries, or both.

IT Infrastructure Library is a registered trademark of the Central Computer and TelecommunicationsAgency which is now part of the Office of Government Commerce.

Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon,Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or itssubsidiaries in the United States and other countries.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in theUnited States, other countries, or both.

ITIL is a registered trademark, and a registered community trademark of The Minister for the CabinetOffice, and is registered in the U.S. Patent and Trademark Office.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracleand/or its affiliates.

Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the United States, othercountries, or both and is used under license therefrom.

Linear Tape-Open, LTO, the LTO Logo, Ultrium, and the Ultrium logo are trademarks of HP, IBM Corp.and Quantum in the U.S. and other countries.

Privacy policy considerationsIBM Software products, including software as a service solutions, (“Software Offerings”) may use cookiesor other technologies to collect product usage information, to help improve the end user experience, totailor interactions with the end user or for other purposes. In many cases no personally identifiableinformation is collected by the Software Offerings. Some of our Software Offerings can help enable you tocollect personally identifiable information. If this Software Offering uses cookies to collect personallyidentifiable information, specific information about this offering’s use of cookies is set forth below.

Notices 273

Depending upon the configurations deployed, this Software Offering may use session cookies that collecteach user’s user name for purposes of session management, authentication, and single sign-onconfiguration. These cookies cannot be disabled.

If the configurations deployed for this Software Offering provide you as customer the ability to collectpersonally identifiable information from end users via cookies and other technologies, you should seekyour own legal advice about any laws applicable to such data collection, including any requirements fornotice and consent.

For more information about the use of various technologies, including cookies, for these purposes, SeeIBM’s Privacy Policy at http://www.ibm.com/privacy and IBM’s Online Privacy Statement athttp://www.ibm.com/privacy/details the section entitled “Cookies, Web Beacons and OtherTechnologies” and the “IBM Software Products and Software-as-a-Service Privacy Statement” athttp://www.ibm.com/software/info/product-privacy.

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.


http://www.ibm.com/privacy

http://www.ibm.com/privacy/details

http://www.ibm.com/software/info/product-privacy

zEnterprise 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 Glossary 277

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 17Acquiring the Hardware Management

Console certificate 27ACSADMIN 25ActiveMQPort 40administrator

Enterprise Common Collector 77administrator command summary 96advanced management module 275agent depot 105Agent Summary workspace 147

Enterprise Common Collector - DataSources View 153, 154, 159, 160,162

AJPPort 40AMM

See advanced management moduleAPI

GET /eccapi/admin/backup 196POST /eccapi/admin/backup 196

APIsAdministrator APIs

DELETE /eccapi/admin/clients/{client-name} 204, 208

DELETE /eccapi/admin/collection-profiles/{name} 201,209

DELETE /eccapi/admin/data-sources/{name} 202, 211

GET /eccapi/admin/backup 205,213

GET /eccapi/admin/clients 204,214

GET /eccapi/admin/clients/{client-name} 204, 217

GET /eccapi/admin/collection-profiles 201, 219

GET /eccapi/admin/collection-profiles/{name} 222

GET /eccapi/admin/config/authentication 201, 224

GET /eccapi/admin/data-sources 202, 244

POST /eccapi/admin/backup 205, 237

POST /eccapi/admin/clients 238POST /eccapi/admin/collection-

profiles 240PUT /eccapi/admin/clients/

{client-name} 204, 248PUT /eccapi/admin/clients/

{client-name}/resume 250PUT /eccapi/admin/collection-

profiles/{name} 201, 251PUT /eccapi/admin/config/

authentication 201, 252PUT /eccapi/admin/data-sources/

{name} 260

APIs (continued)configuration APIs

DELETE /eccapi/admin/config/loggers/{logger-name} 205, 210

GET /eccapi/admin/config/loggers 205, 230

GET /eccapi/admin/config/loggers/{logger-name} 205, 232

POST /eccapi/admin/config/loggers 205, 242

PUT /eccapi/admin/config/loggers/{logger-name} 205, 258

Configuration APIsDELETE /eccapi/admin/config/

certificates/{alias} 203, 209GET /eccapi/admin/config/

certificates/ 203, 226GET /eccapi/admin/config/

certificates/{alias} 203, 227GET /eccapi/admin/config/

certificates/trust-all 203, 229GET /eccapi/admin/data-

sources 202, 233GET /eccapi/admin/data-sources/

{name} 235PUT /eccapi/admin/config/

certificates/{alias} 203, 255PUT /eccapi/admin/config/

certificates/trust-al 257DELETE /eccapi/admin/clients/

{client-name} 204, 208DELETE /eccapi/admin/collection-

profiles/{collection-profile-id} 201DELETE /eccapi/admin/collection-

profiles/{name} 209DELETE /eccapi/admin/config/

certificates/{alias} 203, 209DELETE /eccapi/admin/config/

loggers/{logger-name} 205DELETE /eccapi/admin/data-

sources/{name} 202, 211DELETE /eccapi/admin/loggers/

{logger-name} 210DELETE /eccapi/sessions/this-

session 200, 212GET /eccapi/admin/backup 195,

205, 213GET /eccapi/admin/clients 204, 214GET /eccapi/admin/clients/{client-

name} 204, 217GET /eccapi/admin/collection-

profiles 201, 219GET /eccapi/admin/collection-

profiles/{name} 222GET /eccapi/admin/config/

authentication 201, 224GET /eccapi/admin/config/

certificates/ 203, 226GET /eccapi/admin/config/

certificates/{alias} 203, 227

APIs (continued)GET /eccapi/admin/config/

certificates/trust-all 203, 229GET /eccapi/admin/config/

loggers 205, 230GET /eccapi/admin/config/loggers/

{logger-name} 205, 232GET /eccapi/admin/data-

sources 202, 233GET /eccapi/admin/data-sources/

{name} 235GPUT /eccapi/admin/clients/{client-

name} 204POST /eccapi/admin/backup 195,

205, 237POST /eccapi/admin/clients 238POST /eccapi/admin/collection-

profiles 201, 240POST /eccapi/admin/config/

loggers 205, 242POST /eccapi/admin/data-

sources 202, 244POST /eccapi/sessions/ 200, 246PUT /eccapi/admin/clients/{client-

name} 204, 248PUT /eccapi/admin/clients/{client-

name}/resume 250PUT /eccapi/admin/collection-

profiles/{name} 201, 251PUT /eccapi/admin/config/

authentication 201, 252PUT /eccapi/admin/config/

certificates/{alias} 203, 255PUT /eccapi/admin/config/

certificates/trust-al 257PUT /eccapi/admin/config/loggers/

{logger-name} 205, 258PUT /eccapi/admin/data-sources/

{name} 260authentication 15, 17, 78, 201, 224, 252

Enterprise Common Collector 78authorization 15, 17automatic backup

Enterprise Common Collector 196

Bbackup

Enterprise Common Collector 195backup bundle 195, 196backup of the Enterprise Common

Collector 213base authentication 78, 201, 224, 252base authentication for the Enterprise

Common Collector 71


CCertificate APIs

DELETE /eccapi/admin/config/certificates/{alias} 203, 209

GET /eccapi/admin/config/certificates/ 203, 226

GET /eccapi/admin/config/certificates/{alias} 203, 227

GET /eccapi/admin/config/certificates/trust-all 203, 229

PUT /eccapi/admin/config/certificates/{alias} 203, 255

PUT /eccapi/admin/config/certificates/trust-al 257

certificate validation 15, 17certificates

HMC 27Changing the authentication mechanism

that the Enterprise Common Collectoruses to authenticate its clients 78, 201,252

Changing the configuration of thetruststore for the Enterprise CommonCollectors 257

Changing the default administratorpassword for the Enterprise CommonCollector 77

Changing the default port assignmentusing the installation program 40

Changing web container administratorcredentials for the Enterprise CommonCollector 99

client admin manager 168, 170client authorization manager 168, 170client configuration 71client data provider 168, 170client inventory gatherer 168, 170client RESTApi 168, 170client security 17client session manager 168, 170Cognos reports

prerequisites 9collection profile 85

path-accessible-collection-enabledparameter 165

command file 76, 98commands

tacmd addSystem 105components 2configuration

Enterprise Common Collector 25, 26,27

fields 106monitoring agent 103remote 105values 106

Configuring the Enterprise CommonCollection 96, 98

configuring the monitoring agent 103content manager 168, 170corequisites 6COSNamingPort 40Create a new logger for an Enterprise

Common Collector component 92Creating a backup bundle for the


Creating a backup for the EnterpriseCommon Collector 205

Creating a new client the EnterpriseCommon Collector 238

Creating a new collection profile for theuser of the Enterprise CommonCollector 240

Creating a new collection profile for theuser of the Enterprise CommonCollector. 201

Creating a new collection profile theEnterprise Common Collector 85

Creating data sources for the EnterpriseCommon Collector 89

customization Enterprise CommonCollector

customization 71Enterprise Common Collector 71

Customizing the Enterprise CommonCollector 71

Ddata cache manager 168, 170Data displayed in Tivoli Enterprise Portal

is all zeros or characters strings aredisplayed a unknown 153

Data source cannot be reached 160Data source disabled unexpectedly 159Data source user authentication

failed 162data sources commands 89DEFAULT collection profile 85Defining data sources for the Enterprise

Common Collector 202, 244, 260Defining logging levels for the Enterprise

Common Collector 205, 242DELETE /eccapi/admin/clients/{client-

name} 204, 208DELETE /eccapi/admin/collection-

profiles/{collection-profile-id} 201DELETE /eccapi/admin/collection-

profiles/{name} 209DELETE /eccapi/admin/config/

certificates/{alias} 203, 209DELETE /eccapi/admin/config/loggers/

{logger-name} 205, 210DELETE /eccapi/admin/data-sources/

{name} 202, 211DELETE /eccapi/sessions/this-

session 200, 212Deleting a certificate 79Deleting a certificate with the specified

alias value from the EnterpriseCommon Collectors 203, 209

Deleting a collection profile 209Deleting a session between the Enterprise

Common Collector and an HMC 200Deleting a session with the Enterprise

Common Collector 212Deleting a specified client configured in

the Enterprise Common Collector 82,204, 208

Deleting a specified data source from theEnterprise Common Collectordatabase 202, 211

Deleting a specified data sources from theEnterprise Common Collectordatabase 89

Deleting the configuration profilesdefined for the Enterprise CommonCollector 85

Deleting the level of a specified loggerconfigured for the Enterprise CommonCollector 92, 205, 210

Deploying the Guest PlatformManagement Provider 26

DerbyPort 40Determining how the Enterprise

Common Collector handlesauthentication of its clients 78

Determining how the EnterpriseCommon Collector to handauthentication of its clients 201

Determining how the EnterpriseCommon Collector to handleauthentication of its clients 224

developerWorks 267discovery process

role of the TADDM zEnterpriseSensor 6

EeccService 56

logging 141Editing the monitoring agent Windows

silent install file 116, 117Enabling the Web Services API for the

HMC 26Enterprise Common Collection

exiting the command shell 76, 98import command 76, 98logging off 76, 98logging on 76, 98running a command file 76, 98utility command summary 98

Enterprise Common Collector 1, 96APIs 199application programming

interface 72automatic backup 196backup 195, 196capabilities 2changing the default administrator

password 77Changing web container administrator

credentials 99collection profile 71command file 72command line interface

changing the default administratorpassword 77

command-line interface 71, 72accessing helop 72administrator commands 96changing the default administrator

password 71client commands 82creating, listing, and updating

clients 71default collection profile 71


Enterprise Common Collector (continued)command-line interface (continued)

defining whether the EnterpriseCommon Collector uses baseauthentication or LDAP using thecommand-line 71

defining whether to use baseauthentication or LDAP 78

logging on 71managing certificate 79managing certificates 71messages 72setting collector logging levels 71setting logging levels 92setting up a command file 72setting up HMC data sources 71,

89setting up the collection

profile 71, 85syntax 72utility commands 98

components 168, 170connection to the HMC 28Defining a user of the System z

Hardware Management Console foruse with the Enterprise CommonCollector 25

description 2installation considerations 2installation program

Changing the default portassignment 40

installing from the console 45Installing using the installation

program 40installing using the installation

wizard 30installing using the silent install 50known problems and

workarounds 166listing Java processes running in the

Enterprise Common Collector 58log file format 141logging 71, 92logging components 92logging for eccService 141logging locations 141managing the Web container 99manual backup 195message format 141, 147messages 141, 147, 168, 170, 171migration 195querying the status of the 58registering as a service with

WebSphere Application ServerCommunity Edition 56

removing 58required disk space 6resetting the eccService invalid login

count after it is locked 62restoring the Enterprise Common

Collector default configuration 63roles 72security 15, 17

managing certificates 71security certificates 79

Deleting a certificate 79

Enterprise Common Collector (continued)security certificates (continued)

Listing all the certificates in theEnterprise Common Collectortruststore 79

Managing certificates using thecommand-line 79

Seeing the certificates associatedwith a particular alias 79

Updating the configuration of thetruststore to change the currentsetting for the “trust allcertificates” option 79

setting up HMC data sources usingthe command-line for the EnterpriseCommon Collector 89

Setting up the System z HardwareManagement Console for use withthe Enterprise CommonCollector 25, 26, 27

starting 58stopping 58stopping Java processes running in

the Enterprise CommonCollector 58

supported platforms 6troubleshooting 141, 147, 153, 160

Data source cannot bereached 160

Data source disabledunexpectedly 159

data source user authenticationfailed 162

Enterprise Common Collector userID is unknown 154

Enterprise Common Collector userrole attempting login hasinsufficient authority 155

HMC operation results in HTTPstatus code 403 and reason code1 164

Incorrect hostname or port 156No data displayed in Tivoli

Enterprise Portal 153Path accessibility information for a

virtualization host could not beretrieved 165

port conflict 163uninstalling

command line 66installation wiard 64

upgrading 69verifying correct installation 56web services interface 199WebSphere Application Server

Community Edition 99Enterprise Common Collector - Data

Sources View 153, 154, 159, 160, 162Enterprise Common Collector fails to

initialize 160Enterprise Common Collector fails to

initialize because of port conflict 163Enterprise Common Collector logging

log name 141log size 141

Enterprise Common Collectortroubleshooting

problems and workarounds 153Enterprise Common Collector user ID is

unknown 154Enterprise Common Collector user role

attempting login has insufficientauthority 155

environment verification 135Establishing a session with the Enterprise

Common Collector 200, 246event integration support 263

FFinding the alias value for a specific

certificate in the Enterprise CommonCollectors 203, 227

Firewall considerations when setting upthe HMC and Enterprise CommonCollector 27

GGET /eccapi/admin/backup 195, 196,

205, 213GET /eccapi/admin/clients 204, 214GET /eccapi/admin/clients/{client-

name} 204, 217GET /eccapi/admin/collection-

profiles 201, 219GET /eccapi/admin/collection-profiles/

{name} 222GET /eccapi/admin/config/

authentication 201, 224GET /eccapi/admin/config/

certificates/ 203, 226GET /eccapi/admin/config/certificates/

{alias} 203, 227GET /eccapi/admin/config/certificates/

trust-all/ 203, 229GET /eccapi/admin/config/

loggers 205, 230GET /eccapi/admin/config/loggers/

{logger-name} 205, 232GET /eccapi/admin/data-sources 202,

233GET /eccapi/admin/data-sources/

{name} 235globalization issues

Enterprise Common Collector 166GPMP 26Guest Platform Management

Provider 25, 26

HHardware Management Console 276

connection to the Enterprise CommonCollector 28

upgrading your Enterprise CommonCollector 69

header field 195, 213header file 237HMC 15, 25, 26, 27, 89

See Hardware Management Console

Index 285

HMC inventory gatherer 168, 170HMC notification handler 168, 170HMC operation results in HTTP status

code 403 and reason code 1 164HMC report gatherer 168, 170HMC session manager 168, 170HTTPSPort 40hypervisor 277

IIBM Support Assistant 269IBM Tivoli Monitoring version 8IEDN

See intraensemble data networkIEDN TOR switch

See intraensemble data network TORswitch

IFLSee Integrated Facility for Linux

import command 72Incorrect hostname or port 156INMN

See intranode management networkinstallation 29, 199

Enterprise Common Collectorinstallation wizard 30installing from the console 45port assignments 40registering as a service with

WebSphere Application ServerCommunity Edition 56

silent install 50uninstalling 66verification 56

monitoring agent 103order of activities 12remote 105Tivoli Enterprise monitoring agent 4Tivoli zEnterprise monitoring agent

installation flow 12Uninstalling the Enterprise Common

Collector from the console 66installation flow 12installation tasks

installing application support onTivoli Enterprise MonitoringServer 128

installing application support onTivoli Enterprise Portal clients 129

installing application support onTivoli Enterprise Portal Server 129

installation wizardEnterprise Common Collector

uninstalling 64installing application support 103installing application support on Tivoli

Enterprise Monitoring Server 128installing application support on Tivoli

Enterprise Portal clients 129installing application support on Tivoli

Enterprise Portal Server 129installing language packs 129installing monitoring agent application

supportTivoli zEnterprise monitoring agent

installing application support 127

Installing the Enterprise CommonCollector 29

Installing the Enterprise CommonCollector from the console 45

Installing the Enterprise CommonCollector using the silent install 50

installing the monitoring agent 103editing the Windows silent install

file 116, 117, 121from the console 125Tivoli zEnterprise monitoring agent

installation 108installation from the console 125

using the installation wizard 108Installing the monitoring agent on

Windows using the silent install 121Installing the monitoring agent on

Windows using the silent installscript 116

installing the monitoring agent using thesilent install 121

installing Tivoli Common Reporting 133Integrated Facility for Linux 277

See IBM System z Integrated Facilityfor Linux

Integrated Service ManagementLibrary 267

internal security 168, 170intraensemble data network 278intraensemble data network TOR

switch 278intranode management network 278inventory update 168, 170ISA 269

JJavaScript Object Notation 278JMXPort 40JMXSecurePort 40JSON 199

See JavaScript Object Notation

Kknown problems and workarounds


Llanguage pack installation 103language packs 129

installing 129silent installation 129

LDAP 78, 201, 224, 252LDAP authentication 25LDAP authentication for the Enterprise

Common Collector 71LDAP server 201, 252Licensed Internal Code 278Linux compatibility libraries 8Listing a specified client configured in

the Enterprise Common Collector. 82Listing all clients configured in the

Enterprise Common Collector. 82

Listing all the certificates in theEnterprise Common Collectortruststore 79

Listing existing data sources for theEnterprise Common Collector 89, 202,233

Listing loggers configured for theEnterprise Common Collector 92

Listing the attributes of a specified clientconfigured in the Enterprise CommonCollector 217

Listing the clients configured for theEnterprise Common Collector. 214

Listing the collection profiles defined forthe Enterprise Common Collector. 219

Listing the configuration profiles definedfor the Enterprise CommonCollector. 85

Listing the status of Java processesrunning in the Enterprise CommonCollector 58

local authentication 25logging

Enterprise Common Collector 141Logging on to the Enterprise Common

Collection 76

Mmanaged resource roles 25Managing certificates using the

command-line 79Managing the Enterprise Common

Collector web container 99messages

Enterprise Common Collector 168,170, 171

message ranges 168, 170Enterprise Common Collector

command-line interface 72metrics manager 168, 170migration

Enterprise Common Collector 195Modifying the a collection profile for the

Enterprise Common Collector 201Modifying the a collection profile for the

Enterprise Common Collector. 201monitoring agent

requirements 8

NNamingPort 40Netcool 263network interface card 279new in this release 10No zEnterprise data or incorrect data in

Tivoli Enterprise Portal 153

Oobtaining Tivoli Common Reporting 133OMNIbus 263OpenEJBPort 40ORBPort 40ORBSSLPort 40


Ppassphrase 195, 213, 237Path accessibility information for a


path-accessible-collection-enabledparameter 165

persistence manager 168, 170POST /eccapi/admin/backup 195, 196,

205, 237POST /eccapi/admin/clients 238POST /eccapi/admin/collection-

profiles 201, 240POST /eccapi/admin/config/

loggers 205, 242POST /eccapi/admin/data-sources 202,

244POST /eccapi/sessions/ 200, 246Power System Control Network 280Prerequisite Scanner 9prerequisites 6

Cognos reports 9Tivoli Common Reporting 9

problems and workarounds 153product overview

Tivoli zEnterprise monitoringagent 1

PSCNSee Power System Control Network

PUT /eccapi/admin/clients/{client-name} 204, 248

PUT /eccapi/admin/clients/{client-name}/resume 250

PUT /eccapi/admin/collection-profiles/{name} 201, 251

PUT /eccapi/admin/config/authentication 201, 252

PUT /eccapi/admin/config/certificates/{alias} 203, 255

PUT /eccapi/admin/config/certificates/trust-all 257

PUT /eccapi/admin/config/loggers/{logger-name} 205, 258

PUT /eccapi/admin/data-sources/{name} 260

QQuerying a named data source for the

Enterprise Common Collector byname 235

Querying the status of the EnterpriseCommon Collector 58

RRedbooks 267Registering the Enterprise Common

Collector as a service manually 56remote

installation and configuration 105remote deployment 105remote deployment of the monitoring

agent 103Removing the Enterprise Common

Collector 58

Representational State Transfer(ReST) 280

requirementsmonitoring agent 8

Resetting the client counterinvalid-login-attempts to 0 after a clientexceeds the maximum number of loginattempts (3) 82

Resetting the Enterprise CommonCollector invalid login count after theadministrator interface is locked 62

response file template 129ReST

See Representational State TransferReST API 280REST API 15, 17Restoring a backup bundle created for

the Enterprise Common Collector 237Restoring a backup created for the

Enterprise Common Collector 205restoring the Enterprise Common

Collector default configuration 63Retrieving a level of a specific logger

configured for the Enterprise CommonCollector 205, 232

Retrieving a list of all certificates in thetruststore for the Enterprise CommonCollector 203, 226

Retrieving a list of all clients configuredin the Enterprise CommonCollector 204

Retrieving a list of all current collectionprofiles defined for the EnterpriseCommon Collector. 222

Retrieving a list of all currentconfiguration profiles defined for theEnterprise Common Collector. 201

Retrieving a list of loggers configured forthe Enterprise Common Collector 205,230

Retrieving the attributes of a specifiedclient configured in the EnterpriseCommon Collector 204

running an Enterprise Common collectorcommand file 76, 98

running the Prerequisite Scanner 9

Ssecure communications 15, 17security 15, 17

basic mechanism or an LDAPserver. 201, 252

certificate validation 15, 17configuring 17Enterprise Common Collector 15, 17LDAP server 201, 252

Security between the Enterprise CommonCollector and its clients 17

Security between the Enterprise CommonCollector and the HMC 15

Seeing the certificates associated with aparticular alias 79

self-describing agent 103sensor 6service classes 1Service Management Connect 267, 269

service-level agreement 281Setting up an Enterprise Common

Collector command file 72Setting up HMC data sources using the

command-line for the EnterpriseCommon Collector 89

Showing the current setting for the "trustall certificates" option for the EnterpriseCommon Collector 203, 229

silent install 117silent installation 129silent installation of language packs 129SLA

See service-level agreementSMC 267, 269SMTPPort 40Software Support 269Starting the Enterprise Common

Collector 58Stopping Java processes running in the

Enterprise Common Collector 58Stopping the Enterprise Common

Collector 58support assistant 269Support Assistant 269supported platforms 6System z Hardware Management

Console 15, 25, 26, 27, 89acquiring the HMC certificate 27defining a user 25Deploying the Guest Platform

Management Provider 26enabling the Web Services API 26firewall considerations 27setting up users and roles 25

Ttacmd addSystem command 105TADDM zEnterprise Sensor 6Technotes 267Testing the Enterprise Common Collector

connection to the HMCs 28the zEnterprise monitoring agent

requirementshardware 6IP versions 6Java versions 6platforms 6software 6

security 15supported platforms 6verification 135

Tivoli Common Reportingcapabilities 5, 133description 5, 133installation considerations 5installing 133obtaining 133prerequisites 9reports 103

Tivoli Enterprise monitoring agentinstallation considerations 4

Tivoli Enterprise Monitoring Serverinstalling application support 128

Tivoli Enterprise PortalNo data or incorrect data 153

Index 287

Tivoli Enterprise Portal clientsinstalling application support 129

Tivoli Enterprise Portal Serverinstalling application support 129

Tivoli zEnterprise monitoring agentcomponents 2event integration support 263installation

editing the Windows silent installfile 116, 117, 121

overview 1prerequisites

running the PrerequisiteScanner 9

self-describing agent installation 103self-describing agent

troubleshooting 103silent install 121silent installation 116uninstalling 132

Tivoli zEnterprise monitoring agentapplication support

uninstalling 132Tivoli zEnterprise monitoring agent

installationapplication support 103monitoring agent 103remote deployment 105

top-of-rack switch 281TOR switch

See top-of-rack switchtroubleshooting 147

Enterprise Common Collector 153,160, 166

troubleshooting scenariosEnterprise Common Collector

Data displayed in Tivoli EnterprisePortal is all zeros or charactersstrings are displayed aunknown 153

Data source cannot bereached 160

Data source disabledunexpectedly 159

data source user authenticationfailed 162

Enterprise Common Collector userID is unknown 154

Enterprise Common Collector userrole attempting login hasinsufficient authority 155

HMC operation results in HTTPstatus code 403 and reason code1 164

Incorrect hostname or port 156Path accessibility information for a


port conflict 163trust-all-certificates 15

UUninstalling the Enterprise Common

Collector using the installationwizard 64

Unlocking a client that has been lockeddue to too many invalid login attemptsfor the Enterprise CommonCollector 250

Updating the attributes of a specifiedclient configured in the EnterpriseCommon Collector 82, 204, 248

Updating the configuration of thetruststore to change the current settingfor the “trust all certificates” option 79

Updating the configuration profilesdefined for the Enterprise CommonCollector 85

Updating the level of a specified loggerconfigured for the Enterprise CommonCollector 92, 205, 258

Updating the name, description,inventory-resync-interval,long-term-collection-enabled,long-term-interval, orshort-term-interval values for aspecified collection profile 85

Updating the property values for aspecified collection profile on theEnterprise Common Collector. 251

upgrading your Enterprise CommonCollector 69

utility command summary 98

Vverification 135, 136Verifying that the Enterprise Common

Collector installed correctly 56views

Agent Summary workspace 147virtual servers 1virtualization hosts 1

Wweb container

Enterprise Common Collector 99Web Service API 25web services interface 199WebSphere Application Server

Community Editionuse by the Enterprise Common

Collector 99workarounds 153workspaces

Agent Summary 147

ZzCPC 282zEnterprise BladeCenter Extension

(zBX) 1zEnterprise central processor complex 1zEnterprise monitoring agent

verification 136zEnterprise Monitoring Agent Enterprise

Common Collectorinstallation 29, 199

zEnterprise Monitoring Agent installationEnterprise Common Collector 29,

199monitoring agent 105

zEnterprise sensor 6zEnterprise Unified Resource Manager 1zManager 1


��

Printed in USA

SC14-7358-01

Documents

IBMTivoli zEnterprise MonitoringAgent Version 6.2.3€¦ · IBMTivoli zEnterprise MonitoringAgent Version 6.2.3.2 ... Cognos and Tivoli Common Reporting ... PUT /eccapi/admin/clients/{client-name}