ITM Administrator's Guide v6.3 Fix Pack 4 PDF
ITM Administrator's Guide v6.3 Fix Pack 4 PDF
ITM Administrator's Guide v6.3 Fix Pack 4 PDF
Administrator's Guide
SC22-5446-02
IBM Tivoli Monitoring
Version 6.3 Fix Pack 4
Administrator's Guide
SC22-5446-02
Note
Before using this information and the product it supports, read the information in “Notices” on page 613.
This edition applies to version 6, release 3, fix pack 2 of IBM Tivoli Monitoring (product number 5724-C04) and to
all subsequent releases and modifications until otherwise indicated in new editions.
© Copyright IBM Corporation 2005, 2014.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . ix Setting up load balancing for a high availability
dashboard environment . . . . . . . . . 53
Tables . . . . . . . . . . . . . . . xi Creating a connection to the IBM Tivoli Monitoring
dashboard data provider . . . . . . . . . . 58
Creating custom dashboard pages that display
About this information. . . . . . . . xiii monitoring data . . . . . . . . . . . . . 61
Configuring an HTTP Server to load balance
Chapter 1. Introduction . . . . . . . . 1 multiple Tivoli Enterprise Portal Servers . . . . . 63
New in this release . . . . . . . . . . . . 1 Setting Clone IDs on each Tivoli Enterprise Portal
New in Version 6.3 Fix Pack 4 . . . . . . . 1 Server . . . . . . . . . . . . . . . 64
New in Version 6.3 Fix Pack 2 . . . . . . . 2 Generating the plugin-cfg.xml file . . . . . 64
New in Version 6.3 . . . . . . . . . . . 3 Controlling UISolutions imports . . . . . . . 67
IBM Tivoli Monitoring family of products . . . . 7
Tivoli Management Services components . . . . . 7 Chapter 4. Editing your environment
Tivoli Enterprise Portal client . . . . . . . . . 9 configuration settings . . . . . . . . 69
Desktop, Browser, and Java Web Start clients . . 10
Tivoli Enterprise Portal client configuration settings 69
Historical data collection . . . . . . . . . 11
Editing the client parameters . . . . . . . 69
System administrator tasks . . . . . . . . 11
Portal client parameter list . . . . . . . . 70
Performance Monitoring service provider . . . . 12
Enabling the HTTP proxy server . . . . . . 76
Setting application properties for Linux and
Chapter 2. Preparing your Tivoli UNIX systems . . . . . . . . . . . . 77
Enterprise Portal environment . . . . 15 Setting the environment variable when the hub is
Browser client . . . . . . . . . . . . . 15 on a z/OS system . . . . . . . . . . . 78
Java runtime environment (JRE) versions . . . 15 Tivoli Enterprise Portal Server configuration settings 79
First time logon . . . . . . . . . . . . 15 Editing the portal server environment file . . . 79
Internet Explorer security settings . . . . . . 16 Portal server environment variables . . . . . 80
Windows write and delete privileges . . . . . 16 Pruning events on the portal server database . . 81
Adding your company logo and URL . . . . 17 Controlling the size of event attachments . . . 82
Starting the Tivoli Enterprise Portal client . . . . 17 Controlling the number of logon attempts . . . 83
Using Web Start to download and run the desktop Tivoli Enterprise Monitoring Server configuration
client . . . . . . . . . . . . . . . . 18 settings . . . . . . . . . . . . . . . . 84
Installing the IBM JRE . . . . . . . . . . 19 Editing the monitoring server environment file 84
Enabling tracing for the JRE . . . . . . . . 20 Duper process for optimizing situations . . . . 85
Downloading and running the desktop client . . 21 Tivoli Enterprise Monitoring Automation Server
Manually creating a shortcut for the Web Start configuration settings . . . . . . . . . . . 86
client . . . . . . . . . . . . . . . 22 Editing the Tivoli Enterprise Monitoring
Starting the desktop client on another portal server 23 Automation Server . . . . . . . . . . . 86
Starting the browser client on another portal server 24
Specifying the browser used for Launch Application Chapter 5. Enabling user authentication 89
and for online help . . . . . . . . . . . . 25 User authentication through the hub monitoring
Add operating platforms to the Navigator view . . 27 server . . . . . . . . . . . . . . . . 92
Prerequisites for configuring authentication on
Chapter 3. Preparing your dashboard the hub monitoring server . . . . . . . . 92
environment . . . . . . . . . . . . 29 Configuration procedure . . . . . . . . . 94
Roadmaps . . . . . . . . . . . . . . . 29 Ldapsearch for LDAP information . . . . . . 96
Setting up a basic monitoring environment LDAP user authentication through the portal server 99
without single sign-on and without per user Prerequisites for configuring LDAP
authorization controls . . . . . . . . . . 29 authentication on the portal server . . . . . 99
Setting up a monitoring dashboard environment About single sign-on . . . . . . . . . . 102
with single sign-on and with per user Roadmap for setting up the portal server to use
authorization controls . . . . . . . . . . 34 an LDAP user registry and single sign-on . . . 104
Migrating a basic monitoring dashboard Using Manage Tivoli Enterprise Monitoring
environment to a dashboard environment with Services to configure the portal server for LDAP
single sign-on and per user authorization authentication . . . . . . . . . . . . 107
controls. . . . . . . . . . . . . . . 45
Contents v
EIF events . . . . . . . . . . . . . . 382 How to disable the Summarization and Pruning
EIF event configuration . . . . . . . . . 383 agent . . . . . . . . . . . . . . . 497
EIF event mapping XML specification . . . . 385 Error logging for stored data . . . . . . . . 497
EIF event destination configuration XML Collecting Agent Operations Log history . . . . 498
specification . . . . . . . . . . . . . 391 Conversion process for using delimited flat files 499
Common slots for EIF emitted events . . . . 394 Estimating space required to hold historical data
EIF life cycle event . . . . . . . . . . 395 tables . . . . . . . . . . . . . . . 500
EIF heartbeat event . . . . . . . . . . 396 Limiting the growth of short-term history files 500
Master reset event . . . . . . . . . . . 397 What to do when the short-term history file
Sending private situation events by using directory size reaches its limit . . . . . . . 502
TLS/SSL communication . . . . . . . . 397 Converting short-term history files to delimited flat
Agent Service Interface . . . . . . . . . . 402 files . . . . . . . . . . . . . . . . 502
Starting the Agent Service Interface . . . . . 402 Converting files using the krarloff program . . 502
Access Authorization Group Profile . . . . . 403 Converting history files to delimited flat files on
Agent Service Interface - Agent Information . . 408 Windows systems . . . . . . . . . . . 504
Agent Service Interface - Situations . . . . . 409 Converting history files to delimited flat files on
Agent Service Interface - History . . . . . . 411 an IBM i system . . . . . . . . . . . 506
Agent Service Interface - Queries . . . . . . 411 Converting history files to delimited flat files on
Agent Service Interface - Service Interface UNIX Systems . . . . . . . . . . . . 507
Request . . . . . . . . . . . . . . 412 Converting history files to delimited flat files on
Centralized Configuration . . . . . . . . . 429 HP NonStop Kernel Systems . . . . . . . 508
Centralized Configuration overview . . . . . 429 Converting history files to delimited flat files on
Centralized Configuration design. . . . . . 430 z/OS systems . . . . . . . . . . . . 509
Configuration load list XML specification . . . 434 Using your historical data for analytic usage . . . 514
Environment variables for Centralized Warehouse Proxy agent for analytics . . . . 514
Configuration . . . . . . . . . . . . 443 Tivoli Enterprise Monitoring Agent for analytics 518
Enable password encryption in configuration Examples of historical data collection for
files on z/OS . . . . . . . . . . . . 446 analytics . . . . . . . . . . . . . . 518
Centralized Configuration sample setup . . . 447
Centralized Configuration startup . . . . . 451 Chapter 17. Tivoli Common Reporting 523
Agent autonomy on z/OS . . . . . . . . 458 Tivoli Common Reporting overview . . . . . . 523
Prerequisites for Tivoli Common Reporting . . . 524
Chapter 16. Managing historical data 461 Upgrading from a previous version of monitoring
About historical data collection . . . . . . . 461 agent reports . . . . . . . . . . . . . 526
Historical data collection configuration . . . . . 463 Limitations . . . . . . . . . . . . . . 526
Changing the directory for short-term history files 467 Ensure that historical reporting is enabled . . . . 527
Performance impact of historical data requests . . 467 Creating and maintaining the dimension tables . . 527
Impact of large amounts of historical data on Configuring the Summarization and Pruning
the monitoring server or agent . . . . . . 468 agent to create and maintain the dimension
Requests for historical data from large tables 469 tables . . . . . . . . . . . . . . . 529
Scheduling the warehousing of historical data 469 Creating the dimension tables using the Schema
Using a data mart to improve long or complex Publication Tool . . . . . . . . . . . 532
queries . . . . . . . . . . . . . . 469 Manually creating and maintaining the
Tivoli Data Warehouse and short-term history dimension tables . . . . . . . . . . . 535
configuration . . . . . . . . . . . . . 472 Importing reports by using the report installer . . 541
Tivoli Data Warehouse range partition migrations 474 Importing and running IBM Cognos reports . . . 543
Migrating non-partitioned tables to partitioned Running a prerequisites scan . . . . . . . 543
tables for DB2 on Linux, UNIX, and Windows . 475 Connecting to the Tivoli Data Warehouse using
Migrating non-partitioned tables to partitioned the database client over ODBC . . . . . . 544
tables for DB2 on z/OS . . . . . . . . . 478 Importing reports through the Dashboard
Migrating non-partitioned tables to partitioned Application Services Hub . . . . . . . . 545
tables for Oracle . . . . . . . . . . . 482 Importing and running BIRT reports . . . . . 546
Summarization and pruning configuration . . . 485 Import a BIRT report package . . . . . . . 546
About the Summarization and Pruning agent 485 Configure the data source . . . . . . . . 547
Best practices for summarization and pruning 488 Generate a sample BIRT report . . . . . . 548
Summarized and pruned data availability . . . 490
Configuring summarization and pruning for Chapter 18. Replicating the Tivoli
attribute groups . . . . . . . . . . . 490 Enterprise Portal Server database . . 551
Configuring summarization and pruning for
Understanding the Tivoli Enterprise Portal Server
managed system groups . . . . . . . . . 492
database . . . . . . . . . . . . . . . 551
Changing global configuration settings . . . . 494
Contents vii
viii IBM Tivoli Monitoring: Administrator's Guide
Figures
1. An environment that includes a single 22. The Integrated Solutions Console General
Dashboard Application Services Hub node and Properties screen . . . . . . . . . . 155
multiple portal servers . . . . . . . . . 54 23. The Integrated Solutions Console verification
2. An environment with load balancing for both screen . . . . . . . . . . . . . . 156
Dashboard Application Services Hub and 24. The Integrated Solutions Console
Tivoli Enterprise Portal Server . . . . . . 55 Configuration notebook tab . . . . . . . 156
3. Suggest LDAP user hierarchy for Tivoli 25. The Integrated Solutions Console's
Monitoring servers. . . . . . . . . . 130 Configuration tab . . . . . . . . . . 157
4. Portal server user properties . . . . . . 131 26. The Integrated Solutions Console's Repository
5. LDAP user properties . . . . . . . . . 132 reference screen . . . . . . . . . . . 157
6. Tivoli Enterprise Portal Server user 27. The Integrated Solutions Console verification
permissions . . . . . . . . . . . . 133 screen . . . . . . . . . . . . . . 158
7. Accept these default values . . . . . . . 136 28. The Integrated Solutions Console's
8. Configure the repository . . . . . . . . 137 Repositories in the realm screen . . . . . 158
9. Adding the Base entry to your realm 139 29. The Integrated Solutions Console verification
10. Save your TEPS/e configuration updates 140 screen . . . . . . . . . . . . . . 158
11. TEPS/e configuration error message . . . . 140 30. The Integrated Solutions Console's sign-in
12. Tivoli Enterprise Portal Administer Users screen . . . . . . . . . . . . . . 159
screen . . . . . . . . . . . . . . 141 31. The Integrated Solutions Console initial
13. LDAP configuration panel for monitoring screen . . . . . . . . . . . . . . 159
server users . . . . . . . . . . . . 143 32. Interactions of Agent Management Services
14. LDP query results . . . . . . . . . . 145 components with IBM Tivoli Monitoring
15. Active Directory users listing . . . . . . 147 components . . . . . . . . . . . . 316
16. Properties of an individual Tivoli Monitoring 33. Data snapshot chart and table . . . . . . 581
user. . . . . . . . . . . . . . . 148 34. Data snapshot table . . . . . . . . . 582
17. ldapbrowser window . . . . . . . . . 149 35. Universal Message Console Showing
18. Monitoring server's LDAP parameters 150 Messages Received. . . . . . . . . . 583
19. ldapsearch results for monitoring server 36. Message Log Details . . . . . . . . . 583
userids. . . . . . . . . . . . . . 151 37. Cross-product connections for the charting
20. The Integrated Solutions Console web service . . . . . . . . . . . . 586
Configuration notebook tab . . . . . . . 154
21. The Integrated Solutions Console Manage
repositories screen . . . . . . . . . . 154
Users of this book should be familiar with performance monitoring concepts and
administration. If you use the Tivoli Data Warehouse, you must be familiar with
the operating system that hosts the warehouse. To learn more about this family of
products, see Tivoli solutions for Service Availability and Performance
Management.
For information on how to use the Version 6.3 Tivoli Enterprise Portal features,
please consult the integrated help (Help → Contents and Index) or the Tivoli
Enterprise Portal User's Guide.
Chapter 1. Introduction 3
v Ad hoc, self-service reporting through Tivoli Common Reporting in Jazz
for Service Management.
For more information about Jazz for Service Management, go to the Jazz
for Service Management Information Center (http://pic.dhe.ibm.com/
infocenter/tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/psc_ic-
homepage.html).
IBM Tivoli Monitoring dashboard data provider for retrieving monitoring data
for display in IBM Dashboard Application Services Hub dashboards
The IBM Tivoli Monitoring dashboard data provider retrieves monitoring
agent data for display in the IBM Dashboard Application Services Hub
component of Jazz for Service Management. The dashboard data provider
is optionally installed during the Tivoli Enterprise Portal Server
configuration. With the dashboard data provider enabled, Dashboard
Application Services Hub users can retrieve read-only data from the hub
monitoring server and monitoring agent for display in dashboards
provided by the agents or in custom dashboards. IBM Tivoli Monitoring
V6.3 includes the Infrastructure Management Dashboards for Servers that
displays data for the OS agents. These server dashboards use the
dashboard data provider to retrieve data. A connection to the dashboard
data provider must be configured in Dashboard Application Services Hub.
See Chapter 3, “Preparing your dashboard environment,” on page 29 and
“Creating a connection to the IBM Tivoli Monitoring dashboard data
provider” on page 58.
IBM Infrastructure Management Dashboards for Servers running on the
Dashboard Application Services Hub V3.1 or later
With the IBM Tivoli Monitoring dashboard data provider enabled,
Dashboard Application Services Hub users can retrieve managed system
groups and events for all monitoring agents and Linux OS agent, UNIX OS
agent, and Windows OS agent health metrics using the Infrastructure
Management Dashboards for Servers application. This application is
installed and configured into Dashboard Application Services Hub V3.1 or
later using IBM Installation Manager. For more information, see “Installing
and configuring the IBM Infrastructure Management Dashboards for
Servers” in the IBM Tivoli Monitoring Installation and Setup Guide.
Open Services Lifecycle Collaboration Performance Monitoring service provider
The Tivoli Enterprise Monitoring Automation Server component contains
the Open Services Lifecycle Collaboration Performance Monitoring
(OSLC-PM) service provider and is installed on the same systems as your
hub Tivoli Enterprise Monitoring Server. The service provider registers
monitoring resources with the Jazz for Service Management Registry
Services component and supports integration with other products using
OSLC linked data interfaces. For more information, see “Performance
Monitoring service provider” on page 12.
Role-based authorization policies
The Tivoli Authorization Policy Server feature provides you with greater
access control capabilities than possible with the existing Tivoli Enterprise
Portal Server authorization model. You can protect your resources from
unauthorized access by users of monitoring dashboards in the IBM
Dashboard Application Services Hub. IBM Tivoli Monitoring V6.3 with the
Authorization Policy Server feature enabled provides the following
capabilities:
v The ability to restrict access for dashboard users to specific managed
system groups and to individual managed systems.
Chapter 1. Introduction 5
AAGP policy. The policy can be configured from the Agent Service
Interface and stored locally on the agent itself. See “Access Authorization
Group Profile” on page 403 and “Centralized Configuration” on page 429.
SOAP security enhancements
You can now enable security for CT_EMail and CT_Export requests using
the SOAP_IS_SECURE environment variable on the monitoring server. See
“Enabling SOAP security” on page 564.
Duper process optimization
The duper process now supports situations that contain reflex actions or
display items. See “Duper process for optimizing situations” on page 85.
Changes to default self-describing agent behavior and new tacmd commands
You can now specify what products and versions are installed on your
monitoring server and portal server by the automatic self-describing agent
process. See “Self-describing monitoring agents” on page 295 and
“Dynamically updating the self-describing installation options” on page
304.
Updates for private situations
v *REGEX predicate function
IBM Tivoli Monitoring frequently requires text scan and pattern
matching upon event and sample data, such as name, address, message,
and log record. You can add the Regular Expression predicate filter to
private situations to enhance agent monitoring event detection.
v Dynamically delete a private situation
You can now use the DELETE= attribute in a private situation to
dynamically remove a private situation without recycling the agent or
deleting the local private situation XML file.
For more information, see “Private situation XML specification” on page
335.
Ability to clear the Deployment Status table transactions
Each time you issue an IBM Tivoli Monitoring tacmd command or use the
Tivoli Enterprise Portal navigator to remotely manage a Tivoli Enterprise
Monitoring Agent, information about the transaction is preserved in the
Tivoli Enterprise Monitoring Server Deployment Status table. To make it
easier to manage the contents of this table, especially in large
environments, you can schedule the periodic removal of completed
transactions from the table. See “Clearing the Deployment Status table” on
page 292.
Use of login daemon scripts available on IBM Service Management Connect
In IBM Tivoli Monitoring V6.3 or later, monitoring servers can now use the
IBM Tivoli Monitoring login daemon solution that is available on IBM
Service Management Connect to change the monitoring server an agent
connects to. See “Changing the monitoring server an agent connects to” on
page 294.
Setting the locale for the browser client
Administrators can no longer set the locale for the Tivoli Enterprise Portal
browser client Enterprise-wide. The language can be changed through the
Java™ control panel at the client computer if the underlying OS platform
has been installed using a different locale than the one you want to use
with the Tivoli Enterprise Portal. See the user.language and user.region
parameters in “Portal client parameter list” on page 70.
IBM Tivoli Monitoring products help you manage the performance and availability
of distributed operating systems and applications. These products are based on a
set of common service components, referred to collectively as Tivoli Management
Services. Tivoli Management Services provides security, data transfer and storage,
notification mechanisms, user interface presentation, and communication services
in an agent-server-client architecture. These services are common to many product
suites such as IBM Tivoli OMEGAMON® XE mainframe monitoring and IBM Tivoli
Composite Application Manager.
After you have installed and initially configured Tivoli Management Services and
the products that rely on them, consult this guide to apply further customization in
a distributed environment. (Configuring the Tivoli Enterprise Monitoring Server on
z/OS is provided in the guide of the same name.) It also has general administrative
information for the managed systems that share these common services.
Product-specific administrative information is given in the guides for the
individual products.
For a complete list of components, see the IBM Tivoli Monitoring Installation and
Setup Guide (http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/topic/
com.ibm.itm.doc_6.3fp2/install/itm_install.htm).
Client The IBM Tivoli Monitoring client, Tivoli Enterprise Portal is a Java-based
user interface for viewing and monitoring your enterprise network.
Depending on how it was installed, you can start Tivoli Enterprise Portal
as a desktop application or through your browser as a web application.
Presentation server
The Tivoli Enterprise Portal client connects to the Tivoli Enterprise Portal
Server. The Tivoli Enterprise Portal Server is a collection of software
services for the client that enables retrieval, manipulation and analysis of
data from the monitoring agents on your enterprise.
The Tivoli Enterprise Portal Server also includes the optional dashboard
data provider which is used to retrieve read-only monitoring data for
display in monitoring dashboards.
Management server
The Tivoli Enterprise Portal Server connects to the main, or hub, Tivoli
Enterprise Monitoring Server. The monitoring server acts as a collection
and control point for alerts received from the enterprise monitoring agents,
Chapter 1. Introduction 7
and collects performance and availability data from them. The hub
monitoring server correlates the monitoring data collected by monitoring
agents and any remote monitoring servers and passes it to the portal
server for presentation in the portal console.
The automation server, Tivoli Enterprise Monitoring Automation Server, is
an optional component that can be installed on the same system as the hub
monitoring server. It extends the functionality of the hub monitoring
server. The automation server includes the Open Services Lifecycle
Collaboration Performance Monitoring (OSLC-PM) service provider. For
more information, see “Performance Monitoring service provider” on page
12.
Dashboard server
IBM Dashboard Application Services Hub is a Jazz for Service
Management component that provides dashboard visualization and
reporting services. Operators of the dashboard access it through a web
browser interface. IBM Dashboard Application Services Hub uses the
dashboard data provider component of the portal server to retrieve
monitoring data.
You can install the IBM Infrastructure Management Dashboards for
Servers application into Dashboard Application Services Hub to display
situation event information, managed system groups and key health
metrics for Windows OS agents, Linux OS agents, and UNIX OS agents.
You can also create custom dashboard pages that display monitoring data.
You can also install the Authorization Policy Server and tivcmd
Command-Line Interface for Authorization Policy (tivcmd CLI) to use
role-based authorization policies to control what monitored resources are
displayed in dashboards. For more information, see Chapter 7, “Using
role-based authorization policies,” on page 179.
Help server
The IBM User Interface Help System built on Eclipse is installed with the
portal server and provides presentation and search features for the
integrated help system.
tacmd Command-Line Interface (tacmd CLI)
The tacmd CLI is used to manage your monitoring environment and can
also be used to automate many of the administrative functions performed
using the Tivoli Enterprise Portal. The CLI commands either send requests
to the hub monitoring server or to the portal server.
Agents
Tivoli Enterprise Monitoring Agents are installed on the systems or
subsystems whose applications and resources you want to monitor. An
agent collects monitoring data from the managed system and passes it to the
monitoring server to which it is connected. The portal client and
dashboard server gathers the current values of the attributes and produces
reports formatted into tables, charts, and relational table-based topology
views. The agents and monitoring servers can also test the values of the
current attributes against a threshold. When a threshold is exceeded or a
value is matched, an alert icon can be displayed in the portal client or
monitoring dashboard and the hub monitoring server can forward an
event to an event server such as IBM Tivoli Netcool/OMNIbus. The
attribute value conditions to test are called situations.
OS agents can be installed outside the enterprise as Tivoli System Monitor
Agents. They do not connect to nor have any reliance on the Tivoli
One section of the window displays the Navigator, a tree-like view of your
monitored network, from the top level down to individual groupings of
information collected by monitoring agents. The rest of the window is filled with
views pertinent to the chosen item in the Navigator tree. From the top level or
from your home workspace, you can navigate to specific locations to check activity
and investigate problems.
This workspace was customized for the select item in the tree. This workspace was
designed with a bar chart, two plot charts, and a table that displays a background
color for cell values that exceed a certain threshold. You can create and customize
additional workspaces for every item in the tree.
The event indicators that display in the tree, or Navigator, are the results of tests,
called situations, that run on your monitored systems. When the condition
described in the situation is true, a colored icon overlays the affected items in the
tree. Use the Situation editor to set up conditional alerts that monitor your
environment automatically. Use the Workflow editor to set up policies to automate
your environment.
Chapter 1. Introduction 9
Desktop, Browser, and Java Web Start clients
The Tivoli Enterprise Portal client can be deployed in three ways, as described
briefly here and in more detail in the Installation and Setup Guide.
Desktop
The desktop client requires that you load and run the installation software
on each computer where the desktop client will be run. Users start Tivoli
Enterprise Portal the same way they do their other locally installed
applications. With the desktop client, you can also create multiple instances
for connecting to different portal servers.
Browser
The browser client installation software resides on the Tivoli Enterprise
Portal Server. The client software is downloaded from there to your
computer the first time you log on to the portal server from your browser,
and thereafter only when there are software updates.
You can start the browser client from any browser-enabled computer by
entering the URL for the portal server. In this mode of operation, each
portal workspace has a URL, so you can save a workspace to your
Favorites list.
With the browser client you can launch from the Tivoli Enterprise Portal to
other Tivoli web-based and web-enabled applications, and from those
applications into the portal without re-entering your log-on credentials.
This single sign-on solution uses a central LDAP-based user registry to
authenticate sign-on credentials.
Java Web Start
With Java Web Start, like the browser client, the client software is accessed
through a URL and downloaded from the portal server. Unlike the browser
client, which is always run inside the browser, the Web Start client is run
as a desktop application. Whenever updates to the client software are
available, they are downloaded from the portal server automatically.
References to desktop client behavior in this guide also assumes the Java
Web Start client unless otherwise stated. Single sign-on is an example: As
well as the browser client, you can use single sign-on with the Web Start
client
To ensure that data samplings are saved to populate your predefined historical
workspaces, you must first configure and start historical data collection. Real-time
workspaces are available whether you start historical collection or not.
This list represents the types of tasks a system administrator might perform:
v Establishes Tivoli Enterprise Portal user IDs and user groups with the
appropriate permissions for their jobs.
v Designs workspaces for Navigator items and makes these workspaces available
to users based on their established permissions.
v Defines queries that can be applied to table and chart views to specify the
attributes and attribute value ranges to retrieve from the monitoring server.
v Writes definitions for launching applications and makes them available to users
based on their established permissions.
v Creates command line actions that can run at the specified managed system
from the portal client, and makes them available to users who have been
granted authority.
v Creates situations using the visual programming facilities
v Sets the severity of a situation for a particular Navigator item and what, if any,
sound plays when the situation is true and an event opens
v Decides which situations apply to which managed systems, a process called
distribution
v Provides expert advice to display when certain situations evaluate true
v Creates policy workflows, which are actions to take when situations evaluate
true
v Creates, installs, upgrades, distributes and configures agents on remote hosts
from a central location
v Starts, stops, and recycles agent processes
Chapter 1. Introduction 11
Performance Monitoring service provider
The Tivoli Enterprise Monitoring Automation Server component contains the Open
Services Lifecycle Collaboration Performance Monitoring (OSLC-PM) service
provider and is installed on the same systems as your hub Tivoli Enterprise
Monitoring Server.
The Performance Monitoring service provider also supports the OSLC-PM RESTful
API for retrieving linked data about monitored resources. It accommodates the
RDF/XML, compact XML and HTML content types in HTTP GET requests. When
RDF/XML and HTML content is requested, the API returns resource health metrics
defined by the OSLC-PM domain and by the IBM Tivoli Monitoring private
namespace.
To discover the resources that have health metrics available from the Performance
Monitoring service provider, you must query Registry Services since the
Performance Monitoring service provider does not provide OSLC query capability.
Registry Services provides a query interface for retrieving service providers
records, resource registration records, and reconciled resource records. The
reconciled resource records and registration records contain HTTP URLs that can
be used to retrieve information about the resource from the service provider that
registered the resource. The Jazz for Service Management Integration Guide in the Jazz
for Service Management Information Center (http://pic.dhe.ibm.com/infocenter/
tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/psc_ic-homepage.html) contains
information on querying Registry Services to learn about service providers and
resources.
You can use the Performance Monitoring service provider with the Tivoli Business
Service Manager V6.1.1 dashboard server to display key health metrics from
monitoring agents in the service tree without launching in context to the Tivoli
Enterprise Portal. The health metrics are available if a resource such as a
ComputerSystem or SoftwareServer has been registered with Registry Services by
the Performance Monitoring service provider and the resource has also been
You can also create your own OSLC client applications that retrieve resource
information from Registry Services and health metrics for those resources from the
Performance Monitoring service provider. Alternatively you can create your own
OSLC service provider implementation to augment the information available for
registered resources. For more information on creating these types of applications,
see Getting started with Registry Services on the Jazz for Service Management
wiki.
Note: If you create your own OSLC client application, take note that the
rr:sourceRecord properties that are retrieved from Registry Services for
registration or reconciliation records can change if you have a Hot Standby
monitoring environment. The rr:sourceRecord property contains the URL that is
used to query an OSLC service provider for more details about a resource. When
Hot Standby is used, the rr:sourceRecord URL for a resource points to the
Performance Monitoring service provider for the acting hub monitoring server.
When the standby hub monitoring server becomes the acting hub, the URLs are
updated to specify the host name and port number of the Performance Monitoring
service provider for the new acting hub. Therefore, one of the following scenarios
must take place:
v If your OSLC client application caches the rr:sourceRecord property values, it
must periodically query Registry Services to determine whether the cached
URLs must be updated.
OR
v If your OSLC client application tries to use a cached rr:sourceRecord URL for a
resource and a response is not received from the Performance Monitoring service
provider, then it can query Registry Services to determine whether the
rr:sourceRecord value changed.
If the Performance Monitoring service provider for the acting and standby
monitoring servers are both up and an OSLC client sends a request to the
Performance Monitoring service provider for the standby hub monitoring server,
the service provider returns an HTTP 301 redirect response if it can determine the
host name of the acting hub and Performance Monitoring service provider;
otherwise, it returns an HTTP 404 response.
For more information about OSLC and Loosely Coupled Integration, see the
following links:
v OSLC community
v Performance Monitoring working group
v Reconciliation working group and Common Resource Type Vocabulary
v Loosely coupled integration at ISM Connect
v IBM Tivoli Monitoring OSLC private namespace schema
Chapter 1. Introduction 13
For information on installing and configuring the Tivoli Enterprise Monitoring
Automation Server and Performance Monitoring service provider, see the IBM
Tivoli Monitoring Installation and Setup Guide (http://pic.dhe.ibm.com/infocenter/
tivihelp/v61r1/topic/com.ibm.itm.doc_6.3fp2/install/itm_install.htm).
Browser client
Users start the browser client by entering the URL for the integral HTTP server on
the Tivoli Enterprise Portal Server.
Before you use IBM Web Start for Java to download the desktop client from the
Tivoli Enterprise Portal Server:
v The Tivoli Enterprise Portal Server must be installed. (See the IBM Tivoli
Monitoring Installation and Setup Guide (http://pic.dhe.ibm.com/infocenter/
tivihelp/v61r1/topic/com.ibm.itm.doc_6.3fp2/install/itm_install.htm).)
v IBM 32-bit or 64-bit Java Runtime Environment for Windows, version 7.0 must
be installed on the computer to which you want to download the desktop client.
You can download the IBM JRE installer from the Tivoli Enterprise Portal Server.
The IBM JRE must be installed as the system JVM.
If you want to run the desktop client on a system that already has a Tivoli
Management Services base component installed (such as a monitoring server or
the portal server), there is no need to install the IBM JRE. The correct version of
the IBM JRE is installed with the Tivoli Management Services component.
When you log on from a browser, a check is done for the level of Java associated
with the browser. The required version of Java is controlled at the portal server
and you might be prompted to upgrade to IBM Java 7 when you connect.
From then on the browser client software does not need to be downloaded again
until a new version has been installed. The Java plug-in maintains the version
levels of the files on users' computers and compares them with the version levels
on the integral HTTP server. If it detects files that are older than the ones on the
HTTP server, it downloads the latest files.
Be sure you have sufficient free space for the downloaded files. If the disk runs out
of space during the download, you are not warned.
If you have the Internet Explorer security level set to high, you must adjust the
settings to run the Tivoli Enterprise Portal. Otherwise, the Tivoli Enterprise Portal
browser client cannot run.
Procedure
1. In Internet Explorer, select Tools → Internet Options
2. Select the Security tab.
3. Click Internet if you are running Tivoli Enterprise Portal through the Internet;
or Intranet if you are running Tivoli Enterprise Portal through your intranet.
4. Change your security settings to Default Level
5. Click OK to save.
Procedure
1. In Internet Explorer, select Tools → Internet Options
2. Select the Security tab.
3. Click Trusted Sites → Sites, and enter the URL for Tivoli Enterprise Portal.
4. Clear the check box that checks for (https:) for all sites at this zone, click Add .
Choose the medium security level or lower for all sites in the Trusted Sites
zone.
5. Click OK to save your changes.
Note: The Windows permissions scheme affects the Tivoli Enterprise Portal
browser mode and other third-party software installed through Internet Explorer.
Procedure
1. On the computer where you installed the Tivoli Enterprise Portal Server, open
the following file in an HTML editor or text editor:
install_dir\cnb\bannerimage.html
2. Edit the HREF and IMG SRC tags for your organization's URL and logo
graphic file:
a. Replace the href ’ + URL + ’ placeholder with your organization's URL.
b. Replace the img src ’ + URL + ’ placeholder with the name of your
organization's logo GIF or JPG file.
c. Replace the alt ’ + URL + ’ placeholder with the text that should display
when the mouse pointer is over the image, such as the URL.
3. Save the file and exit the editor.
4. Copy the logo graphic to the install_dir\cnb\ directory.
Results
Users now see your logo on the right-hand side of the banner the next time they
start browser mode.
The hub Tivoli Enterprise Monitoring Server and the portal server must be running
for the portal client to start successfully. You also must have a valid user ID.
After you have successfully installed and configured all the components of your
IBM Tivoli Monitoring environment, you can verify the installation and
configuration by launching the Tivoli Enterprise Portal to view monitoring data.
You can access the portal using either the desktop client or the browser client. The
default user ID is sysadmin.
The Tivoli Enterprise Portal client supports multiple monitor configurations. For
example, if you have two display monitors, you can launch the Tivoli Enterprise
Portal client in the secondary monitor and the dialogs, message pop-ups, and
context menus are displayed in the same secondary monitor.
Procedure
v Start the desktop client:
– Click Start → Programs → IBM Tivoli Monitoring → Tivoli
Enterprise Portal. When the logon window is displayed, enter your user ID
and password and click OK.
– Enter ./itmcmd agent start cj at the command line.
v Start the browser client:
1. Start the browser.
2. Type the URL for the Tivoli Enterprise Portal Server into the Address field of
the browser, where the systemname is the host name of the computer where
the portal server is installed and 15200 is the port number for the browser
client: http://systemname:15200
3. Click Yes on the Warning - Security window.
4. When the logon window is displayed, enter your user ID and password and
click OK.
This section is reproduced from the IBM Tivoli Monitoring Installation and Setup
Guide for your convenience.
Before you use IBM Web Start for Java to download the desktop client from the
Tivoli Enterprise Portal Server:
v The Tivoli Enterprise Portal Server must be installed. (See the IBM Tivoli
Monitoring Installation and Setup Guide (http://pic.dhe.ibm.com/infocenter/
tivihelp/v61r1/topic/com.ibm.itm.doc_6.3fp2/install/itm_install.htm).)
v IBM 32-bit or 64-bit Java Runtime Environment for Windows, version 7.0 must
be installed on the computer to which you want to download the desktop client.
You can download the IBM JRE installer from the Tivoli Enterprise Portal Server.
The IBM JRE must be installed as the system JVM.
If you want to run the desktop client on a system that already has a Tivoli
Management Services base component installed (such as a monitoring server or
the portal server), there is no need to install the IBM JRE. The correct version of
the IBM JRE is installed with the Tivoli Management Services component.
If you intend to download and run the desktop client using Web Start on a
computer where no IBM Tivoli Monitoring base component is installed, you must
first install IBM Java. You download an installer from the computer where the
Tivoli Enterprise Portal Server is installed.
Take these steps to download the IBM JRE installer from the Tivoli Enterprise
Portal Server and install the JRE on a Windows computer.
Note: The following procedure assumes you are installing the IBM JRE on a 32-bit
Windows platform. If you are using a 64-bit Windows platform, the name for the
IBM JRE installer executable is ibm-java7_64.exe.
Procedure
1. Start the browser on the computer to which you want to download the
installer.
2. Enter the following URL in the Address field of the browser, where
<portal_server_host_name> is the fully qualified host name of the computer
where the portal server is installed (for example, myteps.itmlab.company.com):
http://<portal_server_host_name>:15200/java/ibm-java7.exe
3. When prompted, save the ibm-java7.exe file to a directory on your hard drive.
4. Change to the directory where you saved the ibm-java7.exe file and
double-click the file to launch the JRE installer to start the installation
program.
5. On the pop-up window, select the language from the drop-down list and click
OK.
6. Click Next on the Welcome page.
7. Click Yes to accept the license agreement.
8. Accept the default location for installing the JRE or browse to a different
directory. Click Next.
9. If you have no other system JVM's installed, click YES on the message that
asks if you want to install this JRE as the system JVM. Otherwise, click NO.
10. If another JRE is currently installed as the system JVM and you are prompted
to overwrite the current system JVM, click NO. Overwriting the current
system JVM might cause applications depending on the current JVM to fail.
11. Click Next on the Start Copying Files window to start installing the JRE.
12. On the Browser Registration window, select the browsers that you want the
IBM JRE to be associated with. These would normally be the browsers that
you want to use with the browser client.
13. Click Next.
14. Click Finish to complete the installation.
Complete the following steps to download the IBM JRE installer from the Tivoli
Enterprise Portal Server and install the JRE on a Linux computer, or install the JRE
without downloading the installer by supplying the URL to the rpm in the
command.
rpm -ivh http://portal_server_host_name:15200/java/ibm-java7.rpm
Note: The following procedure assumes you are installing the IBM JRE on a 32-bit
Linux platform. If you are using a 64-bit Linux platform, the name for the IBM JRE
.rpm file is ibm-java7_64.rpm.
Procedure
1. Start the browser on the computer to which you want to download the
installer.
2. Enter the following URL in the Address field of the browser:
http://portal_server_host_name:15200/java/ibm-java7.rpm
where portal_server_host_name is the fully qualified host name of the computer
where the portal server is installed (for example, myteps.itmlab.company.com).
3. When prompted, save the installer to disk.
4. Change to the directory where you saved the ibm-java7.rpm file and launch the
installer to start the installation program using the following command:
rpm -ivh ibm-java7.rpm
The logs for the Web Start client are located in a different place than logs for the
browser client and for the desktop client installed from the media. On Windows
computers, the logs for the Web Start client are located in the C:\Documents and
Settings\Administrator\Application Data\IBM\Java\Deployment\log or
%USERPROFILE%\AppData\LocalLow\IBM\Java\Deployment\log directory. On Linux
and UNIX computers, the logs are located in the .java/deployment/log directory
of the home directory of the user ID under which the Java JRE was installed. Java
Web Start will create a uniquely named trace file for every independent launch of
the application. The files are named javaws.nnnnn.trace, where nnnnn is an
arbitrary five-digit identifier.
Procedure
1. Launch the IBM Control Panel for Java.
v On Windows, select Start > Control Panel, then double-click IBM Control
Panel for Java. You must switch to the Classic view to see and select the
These are the basic instructions for downloading and running the desktop client
using Java Web Start. The complete instructions, with configuration notes are given
in the IBM Tivoli Monitoring Installation and Setup Guide.
Complete one of these steps to install and launch the desktop client using Java
Web Start:
Procedure
v Enter the URL of the portal server in a browser:
1. Start the browser on the computer where you want to use the desktop client.
2. Enter the following URL in the Address field of the browser, where
<portal_server_host_name> is the fully qualified host name of the computer
where the Tivoli Enterprise Portal Server is installed.
http://<portal_server_host_name>:15200/tep.jnlp
3. Click Run on the security message.
4. If you want to create a shortcut on your desktop for the Tivoli Enterprise
Portal, click Yes when prompted. The desktop client starts and displays the
logon window. If IBM Java 1.7 is not the system JVM, you cannot use this
shortcut. You must create your own, as described in the topic on “Manually
creating a shortcut for the Web Start client” in IBM Tivoli Monitoring
Installation and Setup Guide.
5. Enter the user ID and password to log on to the Tivoli Enterprise Portal or
click Cancel if you do not want to log on at this time. The default user ID is
sysadmin.
If you set the RAS trace option for the Tivoli Enterprise Portal client as
documented in IBM Tivoli Monitoring Troubleshooting Guide, when you recycle the
client the kcjras1.log should be created in the location where the client was
launched. On Windows this defaults to \Documents and Settings\<userid>\
Desktop.
v Launch the desktop client from IBM Java Control Panel:
1. Launch the IBM Java Control Panel:
In the Windows control panel, double-click IBM Java Control
C:\Program Files\IBM\Java70\jre\bin
<install_dir>/jre/<platform>/bin
2. Enter the following command, where <portal_server_host_name> is the fully
qualified host name of the computer where the Tivoli Enterprise Portal
Server is installed.
javaws http://<portal_server_host_name>:15200/tep.jnlp
./javaws http://<portal_server_host_name>:15200/tep.jnlp
Java Web Start downloads and launches the desktop client.
To create a shortcut to use to launch the desktop client using Web Start, complete
the following procedure:
Procedure
1. Right-click on the Windows desktop and select New > Shortcut from the
popup menu.
2. In the Create Shortcut window, type the following path or click Browse and
navigate to the executable as shown:
C:\Program Files\IBM\Java70\jre\bin\javaws.exe
3. Click Next and type a name for the shortcut in the Select a Title for the
Program window. For example:
ITM Web Start client
4. Click Finish. The shortcut appears on your desktop.
The typical scenario for having multiple portal servers is where there is a test and
production portal server, or where there are multiple managed networks with a
portal server connected to each hub monitoring server.
Take these steps to create another portal client instance that connects to a different
portal server.
Procedure
v
1. On the computer where the desktop client is installed, select Start →
Programs → IBM Tivoli Monitoring → Manage Tivoli Enterprise Monitoring
Services.
2. Right-click Tivoli Enterprise Portal Desktop Client and click Create
Instance. If other instances of the Tivoli Enterprise Portal have been created,
you see more than one in the list. Create Instance is disabled for all but the
original Tivoli Enterprise Portal instance.
3. In the Tivoli Enterprise Portal window, enter a name to identify the instance
and click OK.
4. In the Configure Application Instance window, enter the host name of the
Tivoli Enterprise Portal Server that you want to connect to.
5. Click OK.
v Using the command line:
1. Change directory (cd) to install_dir/bin.
2. Create a new instance using the following command:
./itmcmd config -A cj
3. Launch the new instance using the following command:
./itmcmd agent -o <instance_name> start cj
For full syntax information see the IBM Tivoli Monitoring Command Reference.
Using the GUI:
1. Change directory (cd) to install_dir/bin.
2. To start the Manage Tivoli Enterprise Monitoring Services, use the following
command:
./itmcmd manage
3. Right-click Tivoli Enterprise Portal Desktop Client and click Configure.
4. Enter the instance name and portal server hostname, then click Save.
5. To start the instance, right-click Tivoli Enterprise Portal Desktop Client and
click Start Service and enter the instance name.
What to do next
You can now start the instance at any time by double-clicking its entry.
If you no longer need a Tivoli Enterprise Portal instance, you can delete it:
right-clicking the entry and click Remove Instance.
Before starting the browser client instances, take these steps on each computer
where a portal server that you want to connect to is installed.
Procedure
v
1. In the Manage Tivoli Enterprise Monitoring Services, right-click the Tivoli
Enterprise Portal Server entry and select Reconfigure.
2. In the Configure Tivoli Enterprise Portal Browser window that opens,
double-click the cnp.browser.installdir parameter.
3. In the Edit Tivoli Enterprise Portal Browser Parm window that opens, enter
the path to the directory where the browser files should be installed, for
example, C:\\temp\\cnpBrowserFiles.
4. Select the In Use check box and click OK.
5. Click OK to save your changes.
v
1. Change to the directory where applet.html is located: install_dir/
platform/cw, where platform is the current type of operating system.
2. Open applet.html in a text editor.
3. Find the line, <!--END OF PARAMS--> and add a new line above it.
4. On the new line, add this parameter where browser_install_dir is the path to
the directory where the browser files are installed.
document.writeln( ’<PARAM NAME= "cnp.browser.installdir"
VALUE="browser_install_dir">’ )
5. Save and close applet.html.
If you are using Internet Explorer, launch each instance of the portal client that you
want.
If you are using the Firefox browser, you must create a separate profile for each
instance that you intend to start. The Mozilla support site has a topic on Managing
Profiles (http://support.mozilla.com/en-US/kb/Managing+Profiles) that you can
refer to for help with setting up profiles. After creating the profiles, launch each
instance with this command <full_path_to_firefox> -p <profile_name> -no-remote
Related reference:
“Portal client parameter list” on page 70
Most of the Tivoli Enterprise Portal client parameters are left unchanged from their
default values. Edit the client parameters to effect a specific behavior.
Specifying the browser used for Launch Application and for online
help
If you are running the desktop client on Linux, or you want to view the online
help with some browser other than the default, specify to the portal server the
location of the browser you want to use.
Complete these steps to specify a different browser to use for the online help and
launch application:
Procedure
v
1. Launch Manage Tivoli Enterprise Monitoring Services (Start > (All)
Programs > IBM Tivoli Monitoring > Manage Tivoli Enterprise Monitoring
Services).
2. In the Manage Tivoli Enterprise Monitoring Services window, right-click the
browser or desktop client and select Reconfigure. The Configure the Tivoli
Enterprise Portal Browser window is displayed. (If you are configuring the
desktop client, the Configure Application Instance window is displayed.)
3. Scroll down in the list of variables until you see the kjr.browser.default
variable.
4. Double-click kjr.browser.default. The Edit Tivoli Enterprise Portal Browser
Parm window is displayed.
5. In the Value field, type the path and the application name of the alternative
browser application. For example, C:\Program Files\Mozilla
Firefox\firefox.exe
6. Click OK to close the editing window and save the change.
7. Click OK to close the reconfiguration window.
v
1. Go to the install_dir/bin/cnp.sh and edit the cnp.sh shell script.
2. Add your web browser location to the last line of the file. In the example
below, the web browser location is /opt/foo/bin/launcher.
-Dkjr.browser.default=/opt/foo/bin/launcher The line is very long and has
various options on it, including several other –D options to define other
properties. It is very important to add the option in the correct place.
To set the browser location to /opt/foo/bin/launcher, change the line to look like the
following:
${JAVA_HOME}/bin/java -showversion -noverify -classpath ${CLASSPATH}
-Dkjr.browser.default=/opt/foo/bin/launcher
-Dkjr.trace.mode=LOCAL -Dkjr.trace.file=/opt/IBM/ITM/logs/kcjras1.log
-Dkjr.trace.params=ERROR -DORBtcpNoDelay=true -Dcnp.http.url.host=
-Dvbroker.agent.enableLocator=false
-Dhttp.proxyHost=
-Dhttp.proxyPort=candle.fw.pres.CMWApplet 2>& 1 >> ${LOGFILENAME}.log
v Java Web Start:
Java Web Start deployed applications are described in jnlp deployment files. For
IBM Tivoli Monitoring, there is one deployment file that describes the core Tivoli
Enterprise Portal framework component and associated jar files, and one
deployment file for each and every Tivoli Enterprise Portal-based monitoring
solution that is installed. The core Tivoli Enterprise Portal Server deployment file
is named tep.jnlp. The application deployment file is typically called
kxx_resources.jnlp or kxx.jnlp, where xx is the application identifier (a product
code, such as nt, ux, or lz). On a Windows computer where the Tivoli Enterprise
Portal Server is installed, the file is located in <itminstall_dir>\CNB (for
example, c:\IBM\ITM\CNB). On a Linux computer where the Tivoli Enterprise
Portal Server is installed, the file is located in <itminstall_dir>/<arch>/cw (for
example, /opt/IBM/ITM/li6263/cw).
The deployment file instances are generated whenever the Tivoli Enterprise
Portal Server is installed or reconfigured (for example, when adding a new
monitoring solution to the environment). The contents of these files are based
upon two template deployment files (.jnlpt). The core Tivoli Enterprise Portal
template deployment file is called tep.jnlpt. The application template
deployment file is named component.jnlpt. On a Windows computer where the
Tivoli Enterprise PortalTivoli Enterprise Portal is installed, the file is located in
<itminstall_dir>\Config (for example: c:\IBM\ITM\Config). On UNIX
computers, the file is located in <itminstall_dir>/config (for example,
/opt/IBM/ITM/config).
In order to add or modify JVM arguments (such as maximum heap size) or
other Tivoli Enterprise Portal-based properties (such as RAS1 trace options), it is
necessary to edit either the tep.jnlp deployment file or the tep.jnlpt
deployment template file. The deployment file is nothing more than XML syntax
that describes the Web Start application being deployed. The <resources>
element is used to define the JVM arguments, the Tivoli Enterprise Portal
properties, jar files, and references to component deployment files.
– Modify the tep.jnlp file if the change will be temporary (for example, setting
a trace option for gathering further diagnostics).
– Modify the tep.jnlpt file if the change will be permanent (for example,
increasing the maximum heap size to accommodate a larger monitored
environment or increased event load).
If you modify the deployment template file, make sure you then reconfigure
the Tivoli Enterprise Portal Server in order to regenerate the instance-level
.jnlp deployment files with your changes.
The Navigator Physical view in the Tivoli Enterprise Portal shows the operating
platform below the enterprise level. The operating platform name is followed by
the word Systems as in Linux Systems or z/OS® Systems. Some operating
platforms can be aggregated further. If your environment has such platforms and
you want each to have its own Navigator item, with all systems of that type
contained there, you can add them to the osnames file in the portal server directory
(for example, C:\IBM\ITM\CNPS and /opt/IBM/ITM/config).
Roadmaps
Tasks for setting up your environment depend on many factors. There are two
main types of dashboard environments you might have: a basic environment
without single sign-on or authorization controls per user, or an advanced
environment with single sign-on and authorization controls per user.
Note: You can also start with a basic dashboard environment to become familiar
with IBM Dashboard Application Services Hub with monitoring dashboards and
later add single sign-on and per user authorization by following the steps in
“Migrating a basic monitoring dashboard environment to a dashboard
environment with single sign-on and per user authorization controls” on page 45.
The Dashboard Application Services Hub uses a HTTP or HTTPS connection to the
dashboard data provider component of the portal server to retrieve monitoring
data. Real-time monitoring data is retrieved from the hub monitoring server and
monitoring agents and historical monitoring data is retrieved from the Tivoli Data
Warehouse. Not all monitoring dashboard applications support retrieving historical
data from the Tivoli Data Warehouse.
Prerequisites
v Install and configure the base IBM Tivoli Monitoring monitoring server, portal
server, and portal client components using the instructions in the IBM Tivoli
Monitoring Installation and Setup Guide. When configuring the portal server,
enable the dashboard data provider.
v Install and configure the monitoring agents whose data will be displayed in the
monitoring dashboards. Install their application support in the monitoring
servers, portal server, and desktop portal client if it is being used, using the
instructions in the IBM Tivoli Monitoring Installation and Setup Guide.
v Install and configure Dashboard Application Services Hub and your dashboard
monitoring applications, see “Required software and memory requirements for a
dashboard environment” in the IBM Tivoli Monitoring Installation and Setup Guide.
Also see “Installing and configuring the IBM Infrastructure Management
Dashboards for Servers” in the IBM Tivoli Monitoring Installation and Setup Guide,
if you will be installing that dashboard application.
Roadmap
After you have the basic dashboard monitoring environment setup, you might also
need to perform the following tasks:
Table 2. Additional tasks required to setup your basic monitoring environment without single sign-on and without per
user authorization controls
Task Where to find information
Create situation definitions for events that your See “Situations for event monitoring” in the Tivoli Enterprise
dashboard users will monitor. Portal User's Guide and also see the IBM Tivoli Monitoring
Command Reference for information on the tacmd commands
used to work with situations.
Create managed system groups that can be used to See “Managing the environment” in the Tivoli Enterprise
group managed systems for display in dashboard Portal User's Guide and also see the IBM Tivoli Monitoring
pages. Command Reference for information on the tacmd commands
used to work with system lists.
Configure historical data collection if you want to Chapter 16, “Managing historical data,” on page 461
display historical data in your dashboard pages.
Note: Not all monitoring dashboard applications
support retrieving historical data from the Tivoli
Data Warehouse.
By using single sign-on, your IBM Dashboard Application Services Hub users can
launch the Tivoli Enterprise Portal browser client without entering credentials
when the portal browser client is started. You can use either authorization policies
or Tivoli Enterprise Portal permissions to control what managed systems and
managed system groups individual users or members of user groups can access in
the dashboards and whether they can display situation events.
To use single sign-on, you must install and configure an LDAP user registry that
will contain the credentials of users who will login to IBM Dashboard Application
Services Hub and the portal server. Then you configure IBM Dashboard
Application Services Hub and the portal server to use the same LDAP user registry
to authenticate users and to perform single sign-on using Lightweight Third Party
Authentication (LTPA) tokens. You can also use the same LDAP user registry to
authenticate users of other applications such as Netcool/OMNIbus WebGUI or
Tivoli Business Service Manager if those users will launch the portal client browser
or Dashboard Application Services Hub.
Next you configure a dashboard data provider connection from the Dashboard
Application Services Hub to the portal server and indicate that single sign-on
should be used. The Dashboard Application Services Hub uses a HTTP or HTTPS
connection to the dashboard data provider component of the portal server to
retrieve monitoring data. Real-time monitoring data is retrieved from the hub
monitoring server and monitoring agents and historical monitoring data is
retrieved from the Tivoli Data Warehouse. Not all monitoring dashboard
applications support retrieving historical data from the Tivoli Data Warehouse.
Dashboard Application Services Hub uses roles, for users or user groups, to control
what pages a user can access. However, the dashboard data provider performs the
authorization of the monitoring resources that are displayed in those pages. You
have two options for authorizing the monitoring resources that can be accessed by
dashboard users:
v Use the Tivoli Authorization Policy Server and tivcmd Command-Line Interface
for Authorization Policy to create roles and permissions, which are collectively
called authorization policies.
These authorization policies control which managed systems and managed
system groups a dashboard user can access. Roles are created for job functions
with permissions to view specific managed systems or managed system groups.
Users acquire permissions based on the role (or roles) that user belongs to. Users
can be assigned to roles directly or the user groups that they are members of can
be assigned to roles. The permissions also specify the type of object that can be
accessed for a managed system or managed system group. The supported object
types are event (for situation events) and attribute group (for monitoring data
retrieved from an agent).
OR
When you are initially setting up your monitoring and dashboard environment,
best practice is that you start with Tivoli Enterprise Portal permissions and
monitored application assignments. After you are able to see monitoring data in
Dashboard Application Services Hub and your administrators have created
authorization policies, then reconfigure the portal server if you want to start using
authorization policies.
Note: Tivoli Enterprise Portal permissions and authorization policies only control
access to monitored resources in the dashboards. They do not control access to
monitored resources displayed in reports using Tivoli Common Reporting.
Roadmap
After you have the advanced dashboard monitoring environment setup, you might
also need to perform the following tasks:
Table 4. Additional tasks required to setup your advanced monitoring environment with single sign-on and with per
user authorization controls
Task Where to find information
Review the roadmap if you plan to set up load “Setting up load balancing for a high availability dashboard
balancing for a high availability dashboard environment” on page 53
environment.
Create situation definitions for events that your See “Situations for event monitoring” in the Tivoli Enterprise
dashboard users will monitor. Portal User's Guide and also see the IBM Tivoli Monitoring
Command Reference for information on the tacmd commands
used to work with situations.
Create managed system groups that can be used to See “Managing the environment” in the Tivoli Enterprise
group managed systems for display in dashboard Portal User's Guide and also see the IBM Tivoli Monitoring
pages. Command Reference for information on the tacmd commands
used to work with system lists.
Assign the dashboard user's Tivoli Enterprise Portal Also see “Administer Users” on page 162 for details on how
user ID or group the monitoring applications that to assign agent applications to a Tivoli Enterprise Portal user.
will be displayed in the new dashboard application,
if the dashboard user will also use the Tivoli The IBM Tivoli Monitoring Installation and Setup Guide
Enterprise Portal client, or if Tivoli Enterprise Portal includes information on how to install application support.
authorization are being used instead of authorization
policies.
Note: The application support for the agent must be
installed in the portal server and monitoring server
before you can see the agent's data in the new
dashboards.
Determine if you want to control UISolutions “Controlling UISolutions imports” on page 67
imports. (New and updated dashboard applications
automatically import their UISolutions definitions
into the dashboard data provider.)
First ensure there is a Tivoli Enterprise Portal See “Administer Users” on page 162 for details
user ID mapped to the dashboard user's LDAP on assigning monitoring applications and
distinguished name. permissions to Tivoli Enterprise Portal users and
groups.
Then determine if the Tivoli Enterprise Portal
user should be assigned to an existing Tivoli
Enterprise Portal group that is assigned the
permissions and monitoring applications required
by the new dashboard user. If there is not an
existing group that can be used, complete one of
the following tasks:
v Best practice is to create a new Tivoli
Enterprise Portal group, add the user to the
group, and assign the group the appropriate
permissions and application types.
v Assign the Tivoli Enterprise Portal user the
appropriate permissions and monitoring
applications directly.
Work load is distributed by session, not by request. When one of the servers fails,
new and existing user sessions are directed to an operational server.
When you have multiple portal servers in a monitoring environment, you must
designate one of the portal servers as the read-write portal server and the others
must be read-only portal servers. Tivoli Enterprise Portal client users and tacmd CLI
users who make customization changes must connect to the read-write portal
server to make their updates. The content from the database for the read-write
portal server must be periodically exported and then imported into the database
for each read-only portal server. Because the dashboards in Dashboard Application
Services Hub do not make customization changes, the HTTP server can redirect
dashboard requests to any of the portal servers for the monitoring environment. In
a load balancing environment, you might not know which portal server (the
read-write portal server or a read-only portal server) is serving your requests when
you launch the portal browser client from Dashboard Application Services Hub.
Because of this limitation, best practice is to not use the portal browser client to
make configuration changes when the portal client is launched from the dashboard
server. If you need to make configuration changes, configure the portal client to
connect to the read-write portal server directly and then start the client.
Tip: When using launch in context in a load balancing environment you might
receive a message if, you have already launched into the portal client and the
portal server that was serving its requests goes down and a secondary portal
server begins servicing requests. The portal client cannot register this switch and
you might receive the message KFWITM094W: The Tivoli Enterprise Client has
lost contact with the Tivoli Enterprise Portal Server. You must close the
browser window and log in again to clear this message.
Important: If you have multiple Dashboard Application Services Hub nodes and
use the Authorization Policy Server, the policy server can only be installed on one
of the dashboard nodes because it does not support load balancing. When you
enable authorization policy checking for each portal server, you specify the
hostname and port for the Dashboard Application Services Hub where the policy
server is installed. For information on what happens if the Dashboard Application
Services Hub where the policy server is installed is not available, see “Managing
the authorization policy store” on page 199.
The following figures show two types of load balancing environments with default
port numbers:
1. An environment that includes a single Dashboard Application Services Hub
node and multiple portal servers.
2. An environment with load balancing for both Dashboard Application Services
Hub and Tivoli Enterprise Portal Server.
Note: The portal server also has a local IBM HTTP server. When the load
balancing HTTP server sends requests to the portal server, it is sending those
requests to the portal server's local HTTP server on port 15200 (for HTTP) or 15201
(for HTTPS). Then the local HTTP server is responsible for forwarding the requests
Figure 1. An environment that includes a single Dashboard Application Services Hub node and multiple portal servers
The following roadmap describes the steps for configuring load balancing for your
dashboard environment. It assumes that you have an existing dashboard
environment with single sign-on support and now you are adding load balancing
to the environment. The roadmap takes you through the steps to add multiple
portal servers to your environment and then it optionally adds additional
Dashboard Application Services Hub nodes.
Table 6. Roadmap for setting up load balancing for your dashboard environment
Step Task Where to find information
1 Install and configure the additional portal servers. Also install “Installing IBM Tivoli
application support on each portal server. Monitoring” in the IBM Tivoli
Monitoring Installation and Setup
When you configure each portal server, enable the dashboard data Guide.
provider. If you already have authorization policies enabled in the
dashboard environment, enable authorization policy checking in each “Configuring TLS/SSL
portal server specifying the hostname and port number of the communication between the
Dashboard Application Services Hub node where the Authorization portal server and the
Policy Server is installed. Authorization Policy Server” on
Note: When you enable authorization policies and specify HTTPS for page 220
the protocol used to retrieve policies from the Authorization Policy
Server, you must also configure TLS/SSL communication between the
portal server and the Authorization Policy Server.
This connection procedure is one that you do not need to repeat unless the
configuration of the portal server changes.
Tip: You can create the connection with HTTP protocol for your initial testing.
Once your environment is working, then you can configure TLS/SSL between
the servers, delete the connection, and re-add it with the HTTPS protocol.
v To define a connection to the dashboard data provider, you must know which
network protocol is required, the host name and port number for the portal
server, credentials to authenticate with the portal server, and whether single
sign-on should be used.
Procedure
1. In the Dashboard Application Services Hub console, click Console
Settings and select Connections (under General).
2. Click Create new remote provider. Fields are displayed for specifying the
connection to the dashboard data provider.
3. In the Protocol field, select the application protocol for connecting to the
portal server computer: HTTP, HTTPS-SSL (Secure Socket Layer), or HTTPS-TLS
(Transport Layer Security).
4. Click inside the Host name field and enter the IP address or the fully
qualified hostname of the portal server computer.
Note: If you plan to enable single sign-on for your dashboard environment,
you must enter the fully qualified hostname of the portal server. The
hostname is included in the LTPA token that is sent from Dashboard
Application Services Hub to the portal server so that it can verify that the
request came from a server in the same Internet or Intranet domain.
5. Click inside the Port field and enter the port number for the portal server:
15200 for HTTP or 15201 for HTTPS. If using an HTTP server for load
balancing between Dashboard Application Services Hub and multiple portal
servers, enter your HTTP server port number, 80 for HTTP and 443 for
HTTPS.
6. If your configuration has a firewall between the Dashboard Application
Services Hub Server and the portal server, select the Connection goes through
Results
The connection is made to the data provider and the connections table Status
column shows the progress: Pending, Working, Failed, No data sources, or Not
configured.
If an error occurs when creating the data provider connection, see the IBM Tivoli
Monitoring Troubleshooting Guide.
A page is an arrangement of one or more widgets in the work area of the console.
A widget is a user interface component that displays information in a console
dashboard. Dashboard Application Services Hub provides a set of predefined
widgets. Each widget is configured to retrieve information from a data provider
that has a connection defined in Dashboard Application Services Hub. Each data
provider divides its information into data sets.
For detailed information on predefined widgets, how to edit and customize each
widget type, and how to create catalogs and pages with widgets, see the
Dashboard Application Services Hub online help or the Jazz for Service Management
Integration Guide in the Jazz for Service Management Information Center
(http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/
psc_ic-homepage.html).
The IBM Tivoli Monitoring dashboard data provider's data sets correspond to
agent attribute groups. These are the same attribute groups that you create queries
for when customizing Tivoli Enterprise Portal workspace views. The dashboard
data provider also has topology data sets if they are provided by a monitoring
agent such as the IBM Tivoli Monitoring for VMware monitoring agent. Refer to
the agent user guides to see a description of the agent's attribute groups and to
determine if the agent provides a topology data set.
When you create or edit a page, you choose the widgets and their placement on
the page. You edit each widget to choose a data set and select what information
Procedure
1. Choose a data set.
When you edit a widget, you choose a data set from the list of data providers
configured in Dashboard Application Services Hub. You can either elect to see
all data set names or enter search criteria for the data set name. If you list all of
the data set names, you see the data sets for all agents whose application
support is installed in the Tivoli Enterprise Portal Server as well as data sets
available from other data providers. Since this can be a large list of data sets,
you can filter the data sets by searching on a portion of the data set name. For
example, to see all of the data sets (attribute groups) for the Linux OS agent,
enter “Linux” in the search field.
2. Map the data set columns to the widget visualization attributes.
Depending on the widget type, you might be asked to specify which column(s)
from the data set you want displayed in the widget. For example, if you are
editing an analog gauge widget to show disk utilization from a Linux OS
agent, select the Disk Used Percent column for the gauge value.
3. Configure the widget visualization options.
You can also configure the visualization options of the widget such as, labels,
units of measure, and so forth.
4. Specify the data set configuration parameters.
If you selected a data set that maps to an agent's attribute group, you must
enter the name of the managed system or managed system group from which
the data is retrieved. You can also specify a time filter value to retrieve
historical data if the widget supports showing data over a time frame and you
have configured historical data collection.
The data set may have other configuration parameters to further filter what
information is displayed in the widget. For example, if you are editing a widget
such as a gauge that displays values from a single row in an agent attribute
group, the data set configuration parameters allow you to specify other data set
columns (attributes) that uniquely identify which row of data is displayed in
the widget. For example, if you are displaying disk utilization for a Linux OS
agent, in a gauge widget the Linux Disk data set configuration parameters
allow you to specify which disk and mount point to show the utilization of.
You can also specify how often the dashboard data provider provides refreshes
of the data if the widget supports auto-refresh and you have not selected the
events data set.
Many of the Dashboard Application Services Hub widgets can support
connections, or wires, between widgets so that they can exchange messages
with each other. When an action occurs in a source widget, it creates an event,
which contains information that can be sent to other widgets. The dashboard
data provider only supports incoming connections when the source widget has
the managed system name in either an ORGINNODE or NODE property. Note
that the ORGINNODE or NODE property is case sensitive.
Dashboard Application Services Hub uses roles, for users or user groups, to
control which users can create pages and work with widgets and which pages
a user can display. However, the dashboard data provider performs the
authorization of the monitoring resources that are displayed in a widget that
uses one of the data provider's data sets. Custom dashboard pages use the
authorization type that is configured for your monitoring dashboard
What to do next
For examples of how to create custom dashboard pages with monitoring data, see
Creating custom monitoring dashboard pages in the IBM Tivoli Monitoring Wiki
(https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/
wiki/Tivoli%20Monitoring).
Procedure
1. Complete the steps described in the “Setting up load balancing for a high
availability dashboard environment” on page 53 roadmap that occur before the
step for configuring the load balancing HTTP server.
2. Install and configure an HTTP server.
The IBM HTTP Server can be installed using a Jazz for Service Management
image that is provided with IBM Tivoli Monitoring. See the "Download
instructions" in the IBM Tivoli Monitoring Information Center
(http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/topic/
com.ibm.itm.doc_6.3fp2/welcome.htm) for information on the WebSphere
Application Server Supplement images that contain the IBM HTTP Server. For
instructions on installing the IBM HTTP Server Version 8.5, see IBM HTTP
Server Version 8.5 Information Center (http://pic.dhe.ibm.com/infocenter/
wasinfo/v8r5/topic/com.ibm.websphere.ihs.doc/ihs/welcome_ihs.html). The
IBM HTTP Server Information Center also provides information on how to
download and install the IBM HTTP Server from an external IBM Installation
Manager repository.
Note: The HTTP Server Plug-in for IBM WebSphere Application Server must be
installed into the HTTP server. The plug-in is provided with the IBM HTTP
Server. However, if you are using a different HTTP Server, the plug-in is
included on a Jazz for Service Management image that is provided with IBM
Tivoli Monitoring. See the "Download instructions" in the IBM Tivoli
Monitoring Information Center (http://pic.dhe.ibm.com/infocenter/tivihelp/
v61r1/topic/com.ibm.itm.doc_6.3fp2/welcome.htm) for information on the
WebSphere Application Server Supplement images that contain the HTTP
Server Plug-in for IBM WebSphere Application Server.
3. Assign a unique clone ID to each Tivoli Enterprise Portal Server. For more
information, see “Setting Clone IDs on each Tivoli Enterprise Portal Server” on
page 64.
4. Generate the plugin-cfg.xml file for each Tivoli Enterprise Portal Server and
configure the HTTP server to use the plugin details. For more information, see
“Generating the plugin-cfg.xml file” on page 64.
Assign the clone ID by following these steps for each portal server:
Procedure
1. Edit the server.xml file in the following location:
install_dir\CNPSJ\profiles\ITMProfile\config\cells\ITMCell\
nodes\ITMNode\servers\ITMServer
install_dir/interp/iw/profiles/ITMProfile/config/
cells/ITMCell/nodes/ITMNode/servers/ITMServer
2. In the server.xml file, locate the entry <components
xmi:type="applicationserver.webcontainer:WebContainer.
Within the components element, add the following entry:
<properties xmi:id="WebContainer_1183077764084"
name="HttpSessionCloneId" value="12345" required="false"/>
Where value is set to the clone ID you want to assign for this portal server.
This clone ID must be unique for each portal server.
3. Save and close the file.
4. Restart the Tivoli Enterprise Portal Server.
Procedure
1. On each Tivoli Enterprise Portal Server, run the following command:
install_dir\CNPSJ\bin\GenPluginCfg.bat
install_dir/interp/iw/bin/GenPluginCfg.sh
This command generated a file called plugin-cfg.xml and saves it to the
install_dir\CNPSJ\profiles\ITMProfile\config\cells directory on Windows
and the install_dir/interp/iw/profiles/ITMProfile/config/cells directory
on Linux and UNIX.
2. On the computer where the load balancing HTTP Server is installed, replace the
existing plugin-cfg.xml with the plugin-cfg.xml file generated for one of the
portal servers. You will copy a subset of the information from the
plugin-cfg.xml files for the other portal servers into the plugin-cfg.xml file
that is used by the HTTP server.
3. Customize the plugin-cfg.xml file for your load balancing HTTP Server
environment and each of your Tivoli Enterprise Portal Server instances:
a. On the computer where the IBM HTTP Server is installed, change to the
directory where the plugin-cfg.xml is located (such as cd c:\Program
Files(x86)\IBM\WebSphere\Plugins_1\config\webserver1 on Windows or
/opt/IBM/WebSphere/Plugins/config/webserver1 on Linux and UNIX).
b. Open the plugin-cfg.xml file in a text editor and edit the file to provide
details for your IBM HTTP Server and all portal server instances. Use the
Note: The HTTP and HTTPS port values for all portal servers must be the
same so check the plugin-cfg.xml file for each portal server to ensure they
are using the same port numbers.
c. Add the following line to the end of the UriGroup section to handle
requests for launching the Tivoli Enterprise Portal from Dashboard
Application Services Hub:
<Uri Name="/*"/>
d. In the Log section, ensure the path for the Name attribute and
PluginInstallRoot property match your load balancing HTTP server
environment. The following values are typical:
The typical value for Name attribute is PLUGIN_PATH/logs/webserver1/
http_plugin.log.
The typical value for the PluginInstallRoot property is PLUGIN_PATH/.
e. In the ServerCluster section, ensure the paths for the keyring and stashfile
properties match your load balancing HTTP server environment. The
following values are typical:
The typical keyring property value is PLUGIN_PATH/config/webserver1/
plugin-key.kdb.
The stashfile properties is PLUGIN_PATH/config/webserver1/plugin-
key.sth.
f. For each additional portal server:
v Add a Server entry which specifies its clone ID, name, and fully qualified
hostname. You can obtain the clone ID from the portal server's
plugin-cfg.xml file. Assign each portal server a unique server name.
Ensure you specify ports 15200 (for HTTP) and 15201 (for HTTPS) instead
of ports 15210 and 15211. Ports 15200 and 15201 are the ports for the local
Example
The following plugin-cfg.xml example for Windows includes values in bold that
must be customized for your load balancing HTTP server environment.
<?xml version="1.0" encoding="ISO-8859-1"?><!--HTTP server plugin config file for
the cell ITMCell generated on 2013.07.10 at 06:59:43 AM CDT-->
<Config ASDisableNagle="false" IISDisableNagle="false"
IgnoreDNSFailures="false" RefreshInterval="60"
ResponseChunkSize="64" AcceptAllContent="false"
IISPluginPriority="High" FIPSEnable="false"
AppServerPortPreference="HostHeader" VHostMatchingCompat="false"
ChunkedResponse="false">
<Log LogLevel="Trace" Name="PLUGIN_PATH\logs\webserver1\
http_plugin.log"/>
<Property Name="ESIEnable" Value="true"/>
<Property Name="ESIMaxCacheSize" Value="1024"/>
<Property Name="ESIInvalidationMonitor" Value="false"/>
<Property Name="PluginInstallRoot" Value="PLUGIN_PATH\"/>
<VirtualHostGroup Name="default_host">
<VirtualHost Name="*:9080"/>
<VirtualHost Name="*:80"/>
<VirtualHost Name="*:9443"/>
<VirtualHost Name="*:5060"/>
<VirtualHost Name="*:5061"/>
<VirtualHost Name="*:443"/>
<VirtualHost Name="*:15200"/>
<VirtualHost Name="*:15201"/>
<VirtualHost Name="*:HTTP_SERVER_PORT"/>
</VirtualHostGroup>
<ServerCluster Name="ITMServer_ITMNode_Cluster" CloneSeparatorChange="false"
LoadBalance="Round Robin" PostBufferSize="64" IgnoreAffinityRequests="true"
PostSizeLimit="-1" RemoveSpecialHeaders="true" RetryInterval="60">
<Server CloneID="CLONE_ID" ConnectTimeout="0" ExtendedHandshake="false"
MaxConnections="-1" Name="SERVER1_NAME" ServerIOTimeout="0"
WaitForContinue="false">
<Transport Hostname="SERVER1" Port="15200" Protocol="http"/>
<Transport Hostname="SERVER1" Port="15201" Protocol="https">
<Property Name="keyring" Value="PLUGIN_PATH\config\
webserver1\plugin-key.kdb"/>
<Property Name="stashfile" Value="PLUGIN_PATH\config\
webserver1\plugin-key.sth"/>
</Transport>
</Server>
<Server CloneID="CLONE_ID" ConnectTimeout="0" ExtendedHandshake="false"
MaxConnections="-1" Name="SERVER2_NAME" ServerIOTimeout="0"
WaitForContinue="false">
<Transport Hostname="SERVER2" Port="15200" Protocol="http"/>
If you want to control which user can import UISolutions then be aware that new
or updated dashboard applications with UISolutions will not be usable until the
user specified in the portal server's environment file launches the dashboard
application.
The KD8_VM_IMPORT_ID variable is optional and not set by default, which means any
dashboard user that has been authenticated can trigger the request to import
UISolutions when they launch the dashboard application.
Procedure
1. Open the Tivoli Enterprise Portal Server environment variable file.
install_dir\CNPS\kfwenv
install_dir/config/cq.ini
2. Set the KD8_VM_IMPORT_ID environment variable.
To control which user is allowed to do the import, set this variable to a
particular ID such as KD8_VM_IMPORT_ID=user1.
To disable all users from doing an import of UISolutions, set
KD8_VM_IMPORT_ID=$nouser@ or any name that you know does not match a
Dashboard user ID.
3. Restart the Tivoli Enterprise Portal Server to implement the changes.
The following topics include information that pertains to the environment variables
referenced within the Administrator's Guide. For a complete list of environment
variables, see “Environment variables” in the IBM Tivoli Monitoring Installation and
Setup Guide.
Procedure
1. Start Manage Tivoli Enterprise Monitoring Services. For the browser client and
Java WebStart, this is the computer where the portal server is installed;
otherwise, it is where the desktop client is installed.
v Click Start → Programs → IBM Tivoli Monitoring → Manage
Tivoli Enterprise Monitoring Services.
v Change to the install_dir/bin directory and enter: ./itmcmd
manage.
2. Right-click Tivoli Enterprise Portal – Desktop or Tivoli Enterprise Portal –
Browser, and click Reconfigure. The Configure Application Instance window is
displayed for the desktop client (also used for Java WebStart); the Configure
Tivoli Enterprise Portal Browser window is displayed for the browser client.
3. Double-click the parameter value you want to change.
4. To activate the parameter, type a value and select In Use in the Edit Tivoli
Enterprise Portal Parm window.
Some parameters pertain to the desktop client only, to the desktop client and Java
WebStart client only, or to the browser client only and are noted as such.
browser.cache.memory.capacity
Indicates the maximum amount of memory in KB to be used to cache
decoded images and other features by Browser views (a positive non-zero
integer). Specify a value of 0 to disable memory caching. Default: -1,
whereby the capacity value is automatically decided based on the total
amount of memory.
cnp.agentdeploy.timeout
This is the time that should pass before the agent deploy request times out.
Default: 1800 seconds (30 minutes).
cnp.attachment.segment.maxsize
For transmission across the network, file attachments are broken into
segments then reassembled at the Tivoli Enterprise Portal Server. For
example, an 8 MB file is transmitted in eight segments of 1 MB. Adjust this
parameter for the segment size that best suits your environment. Enter the
maximum size in bytes, such as 250000 for 250 KB. Default: 1000000 (1
MB).
This parameter is also available as a portal server environment variable.
See “Controlling the size of event attachments” on page 82.
cnp.attachment.total.maxsize
Use this parameter to set the maximum size of each file attached to an
acknowledgement. Enter the maximum size in bytes, such as 2500000 for
2.5 MB. Default: 10000000 (10 MB).
Note: The portal client uses cascading style sheets to render the
application text. If no localized version of a style sheet, such as
ws_press.css, is available, the English version will be used.
To edit the runtime parameters complete the following tasks:
1. Open the Java control panel:
Use the following table to find language codes and locale codes:
Table 7. Language and locale codes
Language Language code (xx) Locale code (XX)
Chinese, Simplified zh CN
Chinese, Traditional zh TW
Czech cs CZ
English en US
French fr FR
German de DE
Hungarian hu HU
Italian it IT
Japanese ja JP
Korean ko KR
Polish pl PL
Portuguese, Brazilian pt BR
Russian ru RU
Spanish es ES
Thai th TH
Related tasks:
“Editing the client parameters” on page 69
Changes you make to the browser client are applied globally because they are
downloaded automatically through the HTTP server that is installed with the
portal server. If users are deploying the desktop client themselves through Java
WebStart, the changes will also be applied globally. Otherwise, desktop client
changes must be made on each computer where it is installed if you want the
change to affect all users.
To enable the HTTP proxy server, complete these steps on every computer where
the Tivoli Enterprise Portal client is used that also uses an HTTP proxy for the
browser view:
Procedure
1. Open a workspace that contains a browser view or add a browser view to the
current workspace.
2. In the browser view's address box, type: about:config
3. In the filter field that appears at the top of the page, enter the following to see
the network proxy fields: network.proxy
4. Out of the reduced set shown, the following three entries are of interest.
Double-click an entry or select it and press Enter to modify its values:
network.proxy.http
Enter the DNS identifier or the IP address of the proxy host to use for
the HTTP protocol.
network.proxy.http_port
Enter 80, the default port number, or a different number used by the
proxy host.
network.proxy.no_proxies_on
Append any fully qualified host names or IP addresses that should be
accessed without the proxy. For example, this setting bypasses the
proxy server for any files on your local system and on the portal server
(myteps.uk.ibm.com) that are accessed from the browser view:
localhost,127.0.0.1, myteps.uk.ibm.com.
Results
After you click OK on the property edit panel, the change is saved on the Tivoli
Enterprise Portal client.
Note: All file paths are relative to your install_dir directory where you installed
IBM Tivoli Monitoring.
Table 8. File locations for changing application properties for UNIX and Linux systems
File location Purpose of file
bin/cnp.sh The default shell script that launches the
Tivoli Enterprise Portal browser client.
bin/cnp_instance.sh The shell script for a specific instance you
have created, where instance is the name of
the instance that launches the Tivoli
Enterprise Portal browser client.
platform/cj/original/cnp.sh_template The template from which the bin/cnp.sh
and bin/cnp_instance.sh shell scripts are
generated during configuration, where
platform is the code for the operating system
platform on which IBM Tivoli Monitoring is
installed. For example: li6243 for Linux 2.4
on a 32-bit Intel CPU).
You can also set instance name, browser, and Tivoli Enterprise Portal Server
properties on Linux. Refer to the IBM Tivoli Monitoring Command Reference for
details.
To change the location of the web browser you must change the above file or files
to include a new property by completing the following procedure:
Procedure
1. Go to the install_dir/bin/cnp.sh and edit the cnp.sh shell script.
2. Add your web browser location to the last line of the file. In the example
below, the web browser location is /opt/foo/bin/launcher.
-Dkjr.browser.default=/opt/foo/bin/launcher
Important: The line is very long and has various options on it, including
several other –D options to define other properties. It is very important to add
the option in the correct place.
If the last line of your bin/cnp.sh originally looked like the following:
To set the browser location to /opt/foo/bin/launcher, change the line to look like
the following:
${JAVA_HOME}/bin/java -showversion -noverify -classpath ${CLASSPATH}
-Dkjr.browser.default=/opt/foo/bin/launcher
-Dkjr.trace.mode=LOCAL -Dkjr.trace.file=/opt/IBM/ITM/logs/kcjras1.log
-Dkjr.trace.params=ERROR -DORBtcpNoDelay=true -Dcnp.http.url.host=
-Dvbroker.agent.enableLocator=false
-Dhttp.proxyHost=
-Dhttp.proxyPort=candle.fw.pres.CMWApplet 2>& 1 >> ${LOGFILENAME}.log
If the hub Tivoli Enterprise Monitoring Server is on a z/OS system that does not
have ICSF installed, an alternative, less secure encryption scheme is used. The hub
monitoring server and the portal server both must be using the same scheme.
Therefore, if the hub system does not use ICSF, you must configure the Tivoli
Enterprise Portal to use the less secure scheme (EGG1) as well. This involves
editing the Tivoli Enterprise Portal Server environment file to add a new line.
To add the new line to the environment file, complete the following steps:
Procedure
v
1. On the system where the Tivoli Enterprise Portal Server is installed, select
Start → Programs → IBM Tivoli Monitoring → Manage Tivoli Enterprise
Monitoring Services.
2. Right-click Tivoli Enterprise Portal Server, point to Advanced and select Edit
ENV File from the list.
3. If the Tivoli Enterprise Portal Server message displays, click OK to close it.
4. Add a new line: USE_EGG1_FLAG=1.
5. Click Save.
6. Click Yes to implement your changes and recycle the service.
v
1. Change directory (cd) to install_dir/config
2. Add the following line to the cq.ini file: USE_EGG1_FLAG=1
3. Save the file.
4. Recycle the portal server.
For example, when you have security enabled, you can control the number of log
in attempts before a user is locked out of the portal.
If you want to set the application properties for advanced configuration functions
on UNIX or Linux, such as the location of the web browser that the Tivoli
Enterprise Portal browser client launches, this has to be done manually.
If the portal server connects to a hub monitoring server that is on a z/OS system
that does not have the Integrated Cryptographic Service Facility (ICSF) installed,
you must edit the environment file to add a new line.
Note: Any customizations made within the TEPS/e administration console, such
as to configure TLS/SSL communications to the LDAP server, are overwritten and
cleared any time the portal server is reconfigured unless you chose the LDAP type
of Other during portal server configuration through Manage Tivoli Monitoring
Services. To prevent this from occurring, choose the LDAP type of Other during
portal server configuration. When Other is chosen, the LDAP user registry
information is handled by TEPS/e and is not affected by Tivoli Management
Services directly. See step 5 on page 109.
Procedure
1. Open the environment file on the computer where the portal server is installed:
v From Manage Tivoli Monitoring Services (Start → Programs→ IBM
Tivoli Monitoring→ Manage Tivoli Monitoring Services), right-click Tivoli
Enterprise Portal Server and click Advanced → Edit ENV File to open the
kfwenv file.
v Change to the install_dir/config directory and open
the cq.ini file in a text editor.
2. Edit the file to enable (delete # at the beginning of the line), disable (type # at
the beginning of the line) or modify any of the environment variables.
3. Save kfwenv (Windows) or cq.ini (Linux and operating systems such as UNIX)
and exit the text editor.
The file shows a number of environment variables that have been enabled and
others that are disabled by default or as a result of the way you configured the
portal server. Other variables in this list must be added manually to enable them.
KFW_AUTHORIZATION_MAX_INVALID_LOGIN=0
You can control the number of attempts a user can make to log on to the
Tivoli Enterprise Portal Server by setting this environment variable to a
value from 0 to 15. The default value, 0, indicates that there is no limit to
the number of failed attempts a user can make before being locked out.
This configuration setting is effective only when you have enabled security
through the hub Tivoli Enterprise Monitoring Server as described in the
topic, “Controlling the number of logon attempts” on page 83.
KFW_CMW_DETECT_AGENT_ADDR_CHANGE=N
The Navigator function detects when the IP address for an agent is
discovered. If the agent environment is constantly changing or has
improper configurations that generate excessive Navigator tree rebuilding,
consider adding this environment variable to have any discovery of
changes or additions of IP address ignored.
KFW_CMW_DETECT_AGENT_HOSTNAME_CHANGE=N
This variable is like the one for detect agent address change except that it
prevents the Navigator rebuilding if an agent hostname is changed.
KFW_CMW_DETECT_AGENT_PROPERTY_CHANGE=N
This is like the detect agent address change except that it prevents the
Navigator rebuilding if an agent affinity or affinity version changes.
KFW_CMW_SITUATION_ADMIN_SUPPRESS=N
When a situation is stopped, no message is sent to the situation event
console. If you prefer to have the message written to the situation event
console for each system the situation was distributed to, enable (remove
the # at the beginning of the line) this environment variable. The Stopped
message alerts the user that the situation has been stopped, thus, its state
is unknown.
KFW_CMW_SPECIAL_HUB_ENTERPRISE=Y
Associates situations to the Navigator Physical view root item,
Enterprise. The default value is Y to allow association of Managed
System Online and Offline situations to the Enterprise Navigator item. A
setting of N disables the automatic assignment of the *HUB managed
system group to the Enterprise Navigator item.
KFW_ECLIPSE_HELP_SERVER_PORT=9999
The default port number for the Eclipse help server is 9999. If 9999 is
already used by another device, add this variable and specify a port
By default, closed events are removed from the TEPS database one day after they
are closed, within the hours of 12:00 AM and 4:00 AM on the local portal server.
You can control the pruning of this data by changing the following environment
variables in the Tivoli Enterprise Portal Server configuration file.
Complete the steps for editing the environment settings of the Tivoli Enterprise
Portal or of the Tivoli Enterprise Portal Server.
Procedure
v Edit the Tivoli Enterprise Portal environment file:
1. Start Manage Tivoli Enterprise Monitoring Services:
Click Start → Programs → IBM Tivoli Monitoring → Manage
Tivoli Enterprise Monitoring Services.
Change to the install_dir/bin directory and enter: ./itmcmd
manage.
2. Right-click Tivoli Enterprise Portal – Desktop or Tivoli Enterprise Portal –
Browser, and click Reconfigure. The Configure Application Instance window
is displayed for the desktop client (also used for Java WebStart); the
Configure Tivoli Enterprise Portal Browser window is displayed for the
browser client.
3. Double-click cnp.attachment.total.maxsize and enter the maximum size in
bytes for individual files that get attached to an event acknowledgemen
(such as 2500000 for 2.5 MB), and select In Use.
4. If you want to change the segment size (the default 1000000 is 1 MB, thus a 5
MB attachment would be transmitted in 5 x 1 MB segments), double-click
cnp.attachment.segment.maxsize and enter a new segment size in bytes, and
select In Use.
See the procedures in What to next at the end of this topic to disable a user from
accessing the portal, regardless of the
KFW_AUTHORIZATION_MAX_INVALID_LOGIN setting. Complete these steps to
control the number of logon attempts to the portal server:
Procedure
1. Open the Tivoli Enterprise Portal Server environment file for editing:
v In Manage Tivoli Monitoring Services, right-click Tivoli
Enterprise Portal Server and click Advanced → Edit ENV File .
v Change to the install_dir/config directory and open
cq.ini in a text editor.
2. Locate KFW_AUTHORIZATION_MAX_INVALID_LOGIN=0 and specify a value between 0
and 15. The default value of 0 indicates that there is no limit to the number of
failed attempts a user can make before they are locked out.
3. Save and close the environment file.
4. Click Yes when a message asks if you want to recycle the service; or click No if
you prefer to have your changes take effect later by recycling the portal server.
The next time a user attempts to log on to the portal server, the number of logon
attempts will be restricted by the value you set
KFW_AUTHORIZATION_MAX_INVALID_LOGIN to in the environment file.
What to do next
Security: Validate User
The invalid login setting is effective only when you have enabled security
through the hub monitoring server.
You must also enable the Login Lockout feature by
turning on the validation setting in the monitoring server configuration
file: KDS_VALIDATE_EXT="Y".
The monitoring server configuration files are named
hostname_ms_address.config and ms.ini, and are located in the
install_dir/config/ directory.
Restoring user access
If a user is locked out, you have two options to restore their access to the
Tivoli Enterprise Portal:
v In the Tivoli Enterprise Portal , click Administer Users and select the
user ID. In the Permissions tab, click User Administration and enable
Logon Permitted.
v On the computer where the Tivoli Enterprise Portal Server is installed,
run this command line utility to enable or disable access:
Change directory to install_dir\cnps\ and enter
KfwAuthorizationAccountClient.exe ENABLE|DISABLE
user_id
Procedure
1. Open the environment file on the computer where the monitoring server is
installed:
To edit the monitoring server environment variable file, KBBENV on Windows and
KDSENV on z/OS, follow these steps:
See Configuring the Tivoli Enterprise Monitoring Server on z/OS for more
information.
Procedure
1. Open the environment file on the computer where the hub monitoring server is
installed:
v From Manage Tivoli Enterprise Monitoring Services (Start →
Programs → IBM Tivoli Monitoring → Manage Tivoli Enterprise Monitoring
Services), right-click Tivoli Enterprise Monitoring Automation Server and
click Advanced → Edit ENV File to open the KASENV file.
v Change to the install_dir/config directory and open
the as.ini file in a text editor.
2. Edit the file to enable (delete # at the beginning of the line), disable (type # at
the beginning of the line), or modify any of the environment variables.
3. Save the file and exit the text editor.
4. Click Yes when a message asks if you want to recycle the service. You must
recycle the automation server to implement the changes.
tacmd CLI login access and SOAP client requests to the hub Tivoli Enterprise
Monitoring Server are controlled by user accounts that are defined to the hub
monitoring server using either the operating system registry of the monitoring
server or an external LDAP server that is configured at the hub monitoring server.
Login access to the IBM Dashboard Application Services Hub is controlled by the
operating system user registry, an LDAP user registry, or a custom standalone user
registry. If you plan to use monitoring dashboard applications or custom
monitoring dashboards in IBM Dashboard Application Services Hub then you must
configure the Tivoli Enterprise Portal Server and Dashboard Application Services
Hub to use a federated LDAP user registry and single sign-on, if you want your
dashboard users to launch the Tivoli Enterprise Portal client without being
prompted for their credentials and if you want to control authorization to
monitored resources on a per user basis. See the roadmaps in Chapter 3,
“Preparing your dashboard environment,” on page 29 to determine if you want to
use a federated LDAP user registry and single sign-on.
Use the following roadmap to get you started with user authentication.
Table 9. Roadmap for user authentication
Task Where to find information
Setup user authentication through the hub “User authentication through the hub
monitoring server using either the local monitoring server” on page 92
operating system user registry or an LDAP
user registry.
Setup the portal server to use an LDAP user If the hub monitoring server is not using an
registry to authenticate users when single LDAP user registry, see “LDAP user
sign-on is used with IBM Dashboard authentication through the portal server” on
Application Services Hub or other page 99.
applications.
If the hub monitoring server is using an
LDAP user registry, see “Migrating LDAP
authentication from the monitoring server to
the portal server” on page 126.
If you intend to authenticate using the hub Tivoli Enterprise Monitoring Server,
make sure that user accounts for the Tivoli Enterprise Portal Server log-in IDs are
set up in the authenticating registry before authentication is enabled. At a
Note: On Windows, the installer creates a sysadmin user account in the Windows
user registry and asks you to specify a password for that ID. The password is not
required unless password authentication is enabled.
Tip: The Windows installer does not set the "Password never expires" option when
it creates the sysadmin account. If you do not set this option, the password will
expire according to the security policy on the hub computer, and you will not be
able to log in to the portal server. Use the Windows Administrative Tools to ensure
that the "Password never expires" option is selected for the sysadmin user account.
Procedure
v If you are using an external LDAP server for authentication, obtain the
information shown in the following table from the LDAP administrator before
configuring user authentication.
Table 11. LDAP configuration parameters
Parameter Description
LDAP User The attributes used to map Tivoli Enterprise Portal user IDs to LDAP
Filter log-in IDs. The attribute must contain the same name as the Tivoli
Enterprise Portal log-in ID. The portal user ID will usually become the
“%v” in the LDAP user filter. For example:
IBM Tivoli Directory Server: (&(mail=%v@yourco.com)
(objectclass=inetOrgPerson))
Microsoft Windows Active Directory: (&(mail=%v@yourco.com)
(objectclass=user))
Sun Java System Directory Server: (&(mail=%v@yourco.com)
(objectclass=inetOrgPerson)
Not all LDAPs have the mail attribute for the person. For example, the
LDAP administrator might only set the common name, in which case the
filter would look like the following:
(&(cn=%v) (objectclass=inetOrgPerson))
v If you are using Microsoft Active Directory, see “LDAP user authentication using
Microsoft Active Directory” on page 129 for planning and configuration
information specific to this type of LDAP server.
v If you intend to use TLS/SSL communication between the hub Tivoli Enterprise
Monitoring Server and the LDAP server, obtain the information described in the
following table.
Table 12. TLS/SSL parameters for communication between hub and LDAP server
Parameter Description
LDAP key The location of GSKit key store data base file. You can specify any
store file location. For example:
C:\IBM\ITM\keyfiles
LDAP key The location of the GSKit database password file. For example:
store stash C:\IBM\ITM\keyfiles\keyfile.sth
LDAP key The key store label. For example:
store label IBM_Tivoli_Monitoring_Certificate
LDAP key The password required to access the key store.
store password
Configuration procedure
Configure user authentication on the Windows-, Linux-, or UNIX-based hub
monitoring server.
Procedure
1. Select Start → Programs → IBM Tivoli Monitoring → Manage Tivoli Enterprise
Monitoring Services
2. Right-click the hub monitoring server and select Reconfigure.
3. In the configuration window that displays, select Security: Validate User. The
option LDAP Security: Validate User with LDAP becomes available.
Using the following procedure, you can configure user authentication from the
command line.
To configure the hub from the command line, perform the following procedure:
Procedure
1. Change to the install_dir/bin directory and run the following command:
./itmcmd config -S -t tems_name
where install_dir is the installation directory for IBM Tivoli Monitoring, and
tems_name is the name of the hub monitoring server. The default installation
directory on Linux or UNIX is /opt/IBM/ITM. You will see the following
prompt:
Configuring TEMS...
2. Accept the defaults for the following prompts. The defaults should reflect the
selections made during installation.
3. When you see the prompt:
Security: Validate User?
Procedure
1. Change to the install_dir/bin directory and run the following command:
./itmcmd manage [-h install_dir]
where install_dir is the installation directory for IBM Tivoli Monitoring. The
default installation directory on Linux or UNIX is /opt/IBM/ITM. The Manage
Tivoli Enterprise Monitoring Services window is displayed.
2. Right-click the hub monitoring server and click Configure.
3. Click the Advanced Setting tab. Select Security: Validate User.
4. If you want to use LDAP to authenticate users instead of the system registry,
select LDAP user authentication.
5. Click OK. If you selected the LDAP option, the LDAP configuration panel is
displayed.
6. Specify the values, then click OK.
7. Click OK.
8. Restart the hub monitoring server, using one of the following methods:
v In the Manage Tivoli Enterprise Monitoring Services window, right-click the
hub monitoring server and select Recycle.
v From the command line, enter:
./itmcmd server stop tems_name
./itmcmd server start tems_name
Note: Use this tool only if you are configuring LDAP authentication through the
hub monitoring server. If you are configuring LDAP authentication through the
Tivoli Enterprise Portal Server, use the TEPS/e (Tivoli Enterprise Portal Server
extension server) administration console to verify configuration parameters.
The ldp.exe is a Microsoft Windows LDAP search tool that has the same basic
features as the ldapsearch tool. You can download this tool from the Microsoft
website for your version of Windows. The ldp.exe tool is included in the Windows
Server 2003 CD support tools. For information on using the Microsoft Windows
ldp command, see http://support.microsoft.com/kb/224543.
Another tool that can assist in LDAP configuration is the LDAP Browser tool from
Softerra.
This is required if you intend to provide single sign-on (SSO) capability for these
scenarios:
v The Tivoli Enterprise Portal is launched from other web-based applications and
you don't want users to re-enter their credentials.
v The Tivoli Enterprise Portal is used to launch other web-based or web-enabled
applications and you don't want users to re-enter their credentials.
v IBM Dashboard Application Services Hub is used to display monitoring data
retrieved using the dashboard data provider component of the portal server. Best
practice is to use single sign-on in this case, so that dashboard users can launch
the Tivoli Enterprise Portal and user don't have to re-enter their credentials.
Additionally, single sign-on must be used if you want to control authorization to
monitored resources on a per user basis.
v The IBM Tivoli Monitoring charting web service is being used by another
application such as Tivoli Integrated Portal.
It is the starting point for user searches in the LDAP server. For example,
for a user with a distinguished name of cn=John
Doe,ou=Rochester,o=IBM,c=US, specify ou=Rochester,o=IBM,c=US for this
parameter.
Note: If you use the TEPS/e administration console to configure LDAP,
this parameter is called Distinguished name of the base entry in the
repository in the TEPS/e administration console.
Typically, you set this parameter to the distinguished name of the base
entry in the LDAP registry for the portal server users. For example, for a
user with a distinguished name of cn=John Doe,ou=Rochester,o=IBM,c=US,
specify ou=Rochester,o=IBM,c=US for this parameter.
However, when multiple LDAP repositories are being configured for the
portal server, use this field to define an additional distinguished name
(DN) that uniquely identifies the set of LDAP users from this LDAP
server. For example, the LDAP1 registry and the LDAP2 registry might both
use o=ibm,c=us as their base entry. In this case, use this parameter to
uniquely specify a different base entry for each LDAP server within the
realm. For example, specify o=ibm1,c=us when configuring the LDAP1
registry and o=ibm2,c=us when configuring the LDAP2 registry.
Note: If you have multiple LDAP registries, they cannot contain any
overlapping user names.
Example:
ibm_tivoli_sso
Note: If you are using SSO and you want to use the browser client on the
same computer as the Tivoli Enterprise Portal Server, you must reconfigure
the client to use the fully qualified name of the host computer.
Tivoli Enterprise Portal desktop client
Using the desktop client, you can start another application from a
workspace by using SSO. To do this, you must enter the URL of the
application in the address field of a browser view. However, you cannot
start the Tivoli Enterprise Portal from another application to the desktop
client.
Dashboard Application Services Hub
Dashboard users log onto IBM Dashboard Application Services Hub. When
they access a dashboard that displays monitoring data, the dashboard hub
sends a request to the dashboard data provider component of the portal
server and includes the logged in user's LTPA token. The portal server
Roadmap
Use the following scenario roadmap to help you set up the portal server to use an
LDAP user registry and single sign-on.
Determine which application will be the source of Otherwise, refer to the documentation of the
the LTPA key for all of the other participating SSO application whose LTPA key will be exported to
applications and export its LTPA key. The key file determine how to perform the export operation.
and the password used to encrypt the key must be
provided to the administrators of the other
participating applications.
You can use this utility to configure the LDAP server connection information, if all
the following conditions are met:
Configuring the portal server to use an LDAP user registry involves adding LDAP
information such as the bind ID and port number to the portal server
configuration. At the same time, best practice is to enable single sign-on by
specifying the realm name and Internet or intranet domain name used by the other
applications participating SSO. For more information about these parameters, see
“Prerequisites for configuring LDAP authentication on the portal server” on page
99.
You can also export the portal server's LTPA key or import the LTPA key from a
participating SSO application if you have already decided which application will
be the source of the LTPA key. (All participating SSO applications must use the
same key). The export or import steps can also be performed at a later time if you
want to concentrate on getting LDAP user authentication working or you don't
have an LTPA key to import.
Have the configuration information for the LDAP server at hand, as well as the
realm and Internet or intranet domain name for SSO.
If you want to export or import LTPA keys, ensure that the portal server is running
before beginning configuration. You will get a message that the portal server will
be stopped during configuration, but the server is stopped only at the end of the
configuration procedure after you click OK to close the last dialog. If you are
importing an LTPA key, you need the key file and the password that was used
when the key file was generated.
Take these steps to reconfigure the portal server for user validation with an LDAP
registry, enable SSO, and optionally export or import LTPA keys.
Procedure
1. Start Manage Tivoli Enterprise Monitoring Services on the computer where
the portal server is installed:
v Click Start → Programs →IBM Tivoli Monitoring → Manage
Tivoli Enterprise Monitoring Services.
v Where install_dir is the IBM Tivoli Monitoring
installation directory, change to the install_dir/bin directory and run
./itmcmd manage [-h install_dir].
2. Right-click Tivoli Enterprise Portal Server:
v Click Reconfigure, and click OK to accept the existing
configuration and go to the second TEP Server Configuration window.
Important: If you think you might need to edit the configuration of the
Active Directory Server or Tivoli Directory Server at a later time, such as to
configure TLS/SSL communications to the LDAP server, be sure to select
Other and use the TEPS/e administration console to configure the server
(skip step 6). Otherwise, any customization done in the TEPS/e
administration console is lost the next time you reconfigure the portal
server.
6. If you selected AD2000, AD2003, or IDS6 as the LDAP type, complete the
other fields to specify the LDAP server:
v LDAP base is the distinguished name (DN) for the base entry in the LDAP
registry.
It is the starting point for user searches in the LDAP server. For example,
for a user with a distinguished name of cn=John
Doe,ou=Rochester,o=IBM,c=US, specify ou=Rochester,o=IBM,c=US for this
parameter.
v LDAP DN base entry is typically set to the distinguished name of the base
entry in the LDAP registry for portal server users. For example, for a user
with a distinguished name of cn=John Doe,ou=Rochester,o=IBM,c=US,
specify ou=Rochester,o=IBM,c=US for this parameter.
However, when multiple LDAP repositories are being configured for the
portal server, use this field to define an additional distinguished name (DN)
that uniquely identifies the set of LDAP users from this LDAP server. For
example, the LDAP1 registry and the LDAP2 registry might both use
o=ibm,c=us as their base entry. In this case, use this parameter to uniquely
specify a different base entry for each LDAP server. For example, specify
o=ibm1,c=us when configuring the LDAP1 registry and o=ibm2,c=us when
configuring the LDAP2 registry.
Note: If you have multiple LDAP registries, they cannot contain any
overlapping user names.
The value of this parameter is displayed in the Tivoli Enterprise Portal
Administer Users dialog when you list the distinguished names that can be
mapped to Tivoli Enterprise Portal user IDs.
v LDAP bind ID is the LDAP user ID for bind authentication, in LDAP
notation, and must be authorized to search for LDAP users. The bind ID
can be omitted if an anonymous user can search for LDAP users.
Note: After the LDAP configuration is complete, provide the key file and
password to the administrators of the applications that launch Tivoli
Enterprise Portal, use the dashboard data provider in IBM Dashboard
Application Services Hub, or use the IBM Tivoli Monitoring charting web
service.
10. If another participating SSO application is providing the LTPA key, you can
import it now if you have the key file and the password that was used to
encrypt the key. Click Import Keys and complete the following steps:
a. In the Open window that is displayed, navigate to the directory where the
key file is located. The directory displayed initially, on Windows, is
ITM_dir\InstallITM; and on Linux and UNIX, it is the Root directory.
b. Type the name of the file that you want to import, and click Open. You
see a console window while the file is created and encrypted, and then
you are returned to the Single Sign On window. Repeat the import process
to import keys from additional participating servers.
c. Type the password required to decrypt the file, and click OK. You see a
console window while the file is created and encrypted, and then you are
returned to the Single Sign On window.
What to do next
If you chose Other as the LDAP type, the LDAP configuration must be completed
in the TEPS/e administration console. See “Using the TEPS/e administration
console” on page 113.
Otherwise, for all other LDAP types, follow steps 1 and 2 in the procedure above
to check if Validate User with LDAP? is still selected. If it is not selected then an
error occurred when the configuration utility attempted to connect to the LDAP
server and LDAP validation was disabled. If it is disabled, check the
install_dir/logs/ConfigureLDAPRepo.log file.
Once the LDAP registry is completely configured, you can map the Tivoli
Enterprise Portal user IDs to the LDAP distinguished names to complete the LDAP
configuration. You must log on to the Tivoli Enterprise Portal with the sysadmin
user ID or a user ID that has the same administrative authority and is not an
LDAP user. See “Mapping Tivoli Enterprise Portal user IDs to LDAP distinguished
names” on page 120.
If you enabled SSO, you will need to export or import LTPA keys. Refer back to
the “Roadmap for setting up the portal server to use an LDAP user registry and
single sign-on” on page 104 to determine when to perform these steps.
You can use the command line to configure the LDAP server connection
information, if all the following conditions are met:
v You are using Microsoft Active Directory Server or Tivoli Directory Server for
your LDAP server.
v You do not plan to configure TLS/SSL between the portal server and the LDAP
server.
v You do not need to configure any LDAP configuration parameters besides those
listed in the Table 14 on page 100 table.
Configuring the portal server to use an LDAP user registry involves adding LDAP
information such as the bind ID and port number to the portal server
configuration. At the same time, best practice is to enable single sign-on by
specifying the realm name and Internet or intranet domain name used by the other
applications participating SSO. For more information about these parameters, see
“Prerequisites for configuring LDAP authentication on the portal server” on page
99.
Procedure
1. Log on to the computer where the Tivoli Enterprise Portal Server is installed.
2. At the command line, change to the install_dir/bin directory, where install_dir
is the directory where you installed the product.
3. Run the following command to start configuring the Tivoli Enterprise Portal
Server: ./itmcmd config -A cq. The message “Agent configuration started...” is
displayed, followed by a prompt:
Edit "Common event console for IBM Tivoli Monitoring" settings?
[ 1=Yes, 2=No ] (default is: 1)
4. Enter 2. The following prompt is displayed:
Will this agent connect to a TEMS? [1=YES, 2=NO] (Default is: 1):
5. Accept the default values for this prompt and the prompts that follow it until
you see the following prompt. The default values reflect the selections made
during the original configuration.
LDAP Security: Validate User with LDAP ? (1=Yes, 2=No)(Default is: 2):
6. Enter 1 to begin configuration of LDAP authentication and provide the values
for the LDAP parameters.
LDAP type: [AD2000, AD2003, AD2008, IDS6, OTHER](Default is: OTHER):
For LDAP type, choose Other if your LDAP server is not one of those listed or
you intend to customize the LDAP configuration for the Active Directory
Server or Tivoli Directory Server or you plan to configure TLS/SSL between the
portal server and the LDAP server. After completing this procedure, start the
TEPS/e administration console to complete the LDAP server configuration. See
“Using the TEPS/e administration console” on page 113.
Important: If you think you might need to edit the configuration of the Active
Directory Server or Tivoli Directory Server at a later time, for example
configuring TLS/SSL communications to the LDAP server, be sure to select
Other and use the TEPS/e administration console to configure the server.
Otherwise, any customization done in the TEPS/e administration console is lost
the next time you reconfigure the portal server.
7. If you did not specify type of Other, you are prompted to enter additional
LDAP configuration values. (see Table 14 on page 100 for more information
about those parameters):
LDAP base: o=IBM
LDAP DN Base Entry(Default is: o=ITMSSOEntry): o=IBM
LDAP bind ID: cn=root
What to do next
If you chose Other as the LDAP type, the LDAP configuration must be completed
in the TEPS/e administration console. See “Using the TEPS/e administration
console.”
Once the LDAP registry is completely configured, you can map the Tivoli
Enterprise Portal user IDs to the LDAP distinguished names to complete the LDAP
configuration. You must log on to the Tivoli Enterprise Portal with the sysadmin
user ID or a user ID that has the same administrative authority and is not an
LDAP user. See “Mapping Tivoli Enterprise Portal user IDs to LDAP distinguished
names” on page 120.
If you enabled SSO, you will need to export or import LTPA keys. Refer back to
the “Roadmap for setting up the portal server to use an LDAP user registry and
single sign-on” on page 104 to determine when to perform these steps.
You can also use the TEPS/e administration console to configure SSL for
communication with the LDAP server and with other applications that send
requests to either the dashboard data provider or the IBM Tivoli Monitoring
charting web service.
You must use the TEPS/e administration console to configure portal server LDAP
user authentication if you specified Other as the LDAP type when you configured
the portal server during installation, or when you used the Manage Tivoli
Enterprise Monitoring Services utility or itmcmd command line interface. You must
also use the TEPS/e administration console to configure LDAP connection details
if you plan to perform the following tasks:
The TEPS/e administration console is disabled by default for security reasons and
to save system resources. The Tivoli Enterprise Portal Server must be running
before you enable the console.
Take these steps to enable and then start the TEPS/e administration console:
Procedure
1. Enable the TEPS/e administration console:
v In the Manage Tivoli Enterprise Monitoring Services window,
highlight Tivoli Enterprise Portal Server and select Advanced → TEPS/e
Administration → Enable TEPS/e Administration.
v From the command line, change to the scripts
directory (Intel Linux: ITM_dir/li6263/iw/scripts; zLinux:ITM_dir/ls3266/
iw/scripts; AIX®:ITM_dir/aix533/iw/scripts) and enter the following
command, where true starts the console and false stops the console:
./enableISCLite.sh {true/false}
The TEPS/e administration console is now enabled for logon and will remain
enabled until the portal server is stopped.
2. If this is the first time you are enabling the console, you must set the
administration password:
v In the Manage Tivoli Enterprise Monitoring Services window,
highlight Tivoli Enterprise Portal Server and select Advanced → TEPS/e
Administration → TEPS/e Administration Password.
v From the scripts directory, enter the following
command, where <username> is wasadmin, and <password> is the new
password:
updateTEPSEPass.sh <username> <password>
Results
What to do next
You can now configure an external LDAP server connection, SSL, or verify the
configuration.
If the TEPS/e administration console is running when the portal server is recycled,
you must log out and enable the console again to resynchronize with the portal
server.
Attention: Best practice is to select the LDAP type of Other in the Manage Tivoli
Enterprise Monitoring Services utility of itmcmd command line interface before
using the TEPS/e administration console to change the LDAP server configuration
in order for any future changes to persist. For example, if you selected IDS6 as the
LDAP type when you configured the portal server using the itmcmd command
and you make changes to the LDAP connection parameters through the TEPS/e
administration console, your changes are lost the next time you reconfigure the
portal server.
Procedure
1. In the TEPS/e administration console navigation tree, click Security → Global
security.
2. On the page that is displayed, ensure that Federated repositories is selected
for Available realm definition, and click Configure.
3. Configure the federated repository:
a. Verify or enter the Realm Name value. A realm identifies a set of federated
repositories in TEPS/e and other WebSphere Application Servers. You can
choose your own realm name but this value must be the same across all
applications that are configured for SSO within an Internet or intranet
domain. If you enabled single sign-on when you configured the portal
Note: If you have multiple LDAP registries, they cannot contain any
overlapping user names.
The value of this parameter is displayed in the Tivoli Enterprise Portal
Administer Users dialog when you list the distinguished names that can be
mapped to Tivoli Enterprise Portal user IDs.\
Note: If you export or import the keys now, you still need to perform the
other steps listed in “Roadmap for setting up the portal server to use an
LDAP user registry and single sign-on” on page 104 before attempting to
verify that SSO is working.
13. Restart the Tivoli Enterprise Portal Server.
Note: When the portal server is restarted, the TEPS/e administration console
is disabled automatically. You must re-enable it before it can be used again by
following the instructions in “Starting the TEPS/e administration console” on
page 114.
What to do next
Map the Tivoli Enterprise Portal user IDs to the LDAP distinguished names. See
“Mapping Tivoli Enterprise Portal user IDs to LDAP distinguished names” on page
120.
You must enable the administration console after a recycle of the portal server
before you can start the console again.
You cannot use the TEPS/e start and stop commands to control TEPS/e. If you
have already used TEPS/e commands, you can recover by following the procedure
below.
If you need to start or stop a different application server instance on TEPS/e, for
example if you have your own profile, cell, or server created on TEPS/e, you need
to use the following two scripts:
v
<ITM_home>/CNPSJ/profiles/<name_of_your_profile>/bin/startServer.bat
<name_of_your_server>
<ITM_home>/CNPSJ/profiles/<name_of_your_profile>/bin/stopServer.bat
<name_of_your_server>
v
<ITM_home>/<arch>/iw/profiles/<name_of_your_profile>/bin/startServer.sh
<name_of_your_server>
<ITM_home>/<arch>/iw/profiles/<name_of_your_profile>/bin/stopServer.sh
<name_of_your_server>
Examples:
v If you are using a profile created by IBM Tivoli Monitoring, and your
own server called <YourServer>, you need to use the following command:
<ITM_home>/CNPSJ/profiles/<ITMProfile>/bin/startServer.bat
<YourServer>
v If you have your own profile created called <YourProfile>, and your
own server called TEPS/e, to stop the server on the UNIX platform (for example
RHEL4), you need to use the following command:
<ITM_home>/<arch>/iw/profiles/<YourProfile>/bin/stopServer.sh
<YourServer>
Ensure that you already have an existing connection to an LDAP server and that
Tivoli Enterprise Portal users can login to the portal server and be authenticated by
the LDAP server. You must also ensure that the Tivoli Enterprise Portal Server is
configured to use an LDAP type of Other since the configuration of TLS/SSL for
LDAP server communication must be performed using the TEPS/e administration
console.
LDAP TLS/SSL requires some actions by an LDAP administrator that are not
covered by the Tivoli Monitoring documentation. The following topics in the IBM
Security Systems Information Center include information about setting up LDAP
servers for TLS/SSL:
v Configuring Microsoft Active Directory for SSL access
v Configuring the Tivoli Directory Server client for SSL access
v Configuring Oracle Java System Directory Server for SSL access
Start the TEPS/e administration console using the instructions in “Starting the
TEPS/e administration console” on page 114 before beginning the procedure.
Procedure
1. Perform the following steps to import your LDAP server's signer certificate into
the TEPS/e trust store:
a. Click Security → SSL certificate and key management.
b. In the Related Items area of the page, click the Key stores and certificates
link and in the table that is displayed, click the NodeDefaultTrustStore
link.
c. In the Additional Properties area, click the Signer certificates link and click
the Retrieve from port button.
d. In the relevant fields provide the hostname, port (typically 636 for SSL
connections), SSL configuration details, as well as the alias of the certificate
for your LDAP server. Then click the Retrieve signer information button
and then click OK.
2. Follow these steps to enable TLS/ SSL communications to your LDAP server:
a. Click Security → Global security.
b. In the Related Items area near the bottom of the page, select Manage
repositories.
c. In the table of repositories, select the link for the repository identifier for
your LDAP server.
d. Select the Require SSL communications check box and select the Centrally
managed option.
Note: When the portal server is restarted, the TEPS/e administration console is
disabled automatically. You must re-enable it before it can be used again by
following the instructions in “Starting the TEPS/e administration console” on
page 114.
What to do next
Verify that your Tivoli Enterprise Portal users can log in and be authenticated by
the LDAP server.
Every entry in the LDAP user registry has a distinguished name (DN). The DN is
the name that uniquely identifies an entry in the directory. A DN is made up of
attribute=value pairs, separated by commas, for example:
cn=Jim Grey,ou=users,ou=SWG,o=IBM,c=US
cn=Sally White,ou=users,ou=SWG,o=IBM,c=US
The order of the attribute value pairs is important. The DN contains one
component for each level of the directory hierarchy from the root down to the level
where the entry resides. LDAP DNs begin with the most specific attribute, usually
some sort of name, and continue with progressively broader attributes, often
ending with a country attribute. The first component of the DN is referred to as
the Relative Distinguished Name (RDN). It identifies an entry distinctly from any
other entries that have the same parent. In the examples above, the RDN cn=Jim
Grey separates the first entry from the second entry, (with RDN cn=Sally White).
These two example DNs are otherwise equivalent. These two users would log into
the Tivoli Enterprise Portal as Jim Grey and Sally White.
The default distinguished name for new users you create for the Tivoli Enterprise
Portal has the following structure:
UID=tep_userid,O=DEFAULTWIMITMBASEDREALM
This distinguished name indicates that the user is authenticated by the hub
monitoring server. Using the procedure in this topic, update the distinguished
name for any Tivoli Enterprise Portal users that are defined in the portal server's
LDAP user registry to specify their distinguished name in the LDAP user registry
instead of UID=tep_userid,O=DEFAULTWIMITMBASEDREALM.
Do not update the distinguished names for any Tivoli Enterprise Portal user IDs
that are using the o=defaultWIMFileBasedRealm suffix.
User IDs are mapped to LDAP distinguished names in the Tivoli Enterprise Portal
Administer Users window by a user with administrator authority. The tacmd
command line interface can also be used to preform this mapping. For more
information, see the tacmd edituser command in the IBM Tivoli Monitoring
Command Reference.
Complete these steps to map Tivoli Enterprise Portal user IDs to LDAP
distinguished names using the Tivoli Enterprise Portal Administer Users dialog
window:
Procedure
1. Log on to the portal using sysadmin or another user account with full
administrative authority.
2. Click Administer Users.
3. In the Administer Users window, right-click the row of the user ID to map and
select Modify User.
4. In the Modify User dialog box, click Find to locate the LDAP distinguished
name to be associated with the Tivoli Enterprise Portal user ID.
Example:UID=TEPUSER,O=SS.
Note:
v The default suffix for LDAP distinguished names that are configured through
the Tivoli Enterprise Portal Server configuration utilities is o=ITMSSOEntry,
however this value might have been customized when the portal server was
configured for LDAP.
v If the selected LDAP distinguished name contains non-alphanumeric
characters, those characters must be escaped with a backslash before the
mapping is saved. For example, if a user ID contains a pound sign, #, place a
backslash before the pound sign, \#.
5. Click OK to save the mapping and return to the Administer Users window.
6. Repeat steps 3 through 5 until you have mapped all the users that you want to
authenticate with the configured LDAP registry.
7. Click OK to exit the Administer Users window.
Reconfigure the Tivoli Enterprise Portal browser client for SSO if it will be
launched by another application on the same computer as the portal server. See
“Reconfiguring the browser client for SSO.”
Verify that your Tivoli Enterprise Portal users who have IDs that are mapped to
LDAP distinguished names, can log into the Tivoli Enterprise Portal client. They
must use their LDAP relative distinguished name to login. If the users are not
successful at logging into the Tivoli Enterprise Portal, review the TEPS/e log for
diagnostic information. This is the SystemOut.log located on the computer where
the portal server is installed at install_dir\CNPSJ\profiles\
ITMProfile\logs; install_dir/Platform/iw/profiles/
ITMProfile/log.
Refer to the “Roadmap for setting up the portal server to use an LDAP user
registry and single sign-on” on page 104 for additional steps to perform after Tivoli
Enterprise Portal users can be successfully authenticated by the portal server's
LDAP user registry.
By default, the launch URL associated with the browser client running on the same
computer as the Tivoli Enterprise Portal Server is localhost. If you want to use a
browser client on the same computer as the portal server, this value must be the
fully-qualified name of the computer, such as dev1.myco.com. The suffix myco.com is
the domain value you enter in the SSO configuration panel. Using the suffix
ensures that SSO tokens are visible only to the servers that are under the same
domain suffix.
Procedure
1. Launch the Manage Tivoli Enterprise Monitoring Services utility.
2. Right-click the Tivoli Enterprise Portal Browser entry and click Reconfigure to
open the Configure Tivoli Enterprise Portal Browser window.
3. In the Host field beneath portal server area, type the fully-qualified name of
the computer. Example: myhost.mycompany.com
Related concepts:
“About single sign-on” on page 102
The single sign-on (SSO) feature provides users with the ability to start other Tivoli
web-based or web-enabled applications from the Tivoli Enterprise Portal, or to start
the Tivoli Enterprise Portal from other applications, without having to re-enter
their credentials. It is also used when IBM Dashboard Application Services Hub
retrieves monitoring data from the portal server or the IBM Tivoli Monitoring
charting web service is being used by another application.
Ensure that the following applications are using the same LTPA key as the portal
server:
v A web-based or web-enabled application that launches the Tivoli Enterprise
Portal
v A web-based or web-enabled application that can be launched from the Tivoli
Enterprise Portal client
v IBM Dashboard Application Services Hub when it uses the dashboard data
provider component of the portal server to retrieve monitoring data
v Another application such as Tivoli Integrated Portal that uses the IBM Tivoli
Monitoring charting web service
Determine which application will be the source of the LTPA key for all of the other
participating SSO applications and export its LTPA key.
If you decide to export the portal server's LTPA key, you must export the LTPA key
into a key file. When you perform the export step, you must provide a name for
the key file and the password to use to encrypt the key. The key file and password
must be provided to the administrators of the applications listed above so that they
can import the LTPA key.
If another application will not provide the LTPA key, the administrator of that
application must export the application's LTPA key into a key file and then provide
you with the key file and the password that was used to encrypt the key. You must
import the LTPA key into the portal server and enter the password.
The Tivoli Enterprise Portal Server must be running for import and export
operations to be performed.
If you are using the TEPS/e administration console to import or export keys, you
must start the console. See “Starting the TEPS/e administration console” on page
114.
Before you can import an LTPA key, the administrator of the application that
exported the key must provide you with a key file containing the LTPA key and
the password that was used to encrypt the key.
Follow the steps for your environment to import or export LTPA keys:
Procedure
v From Manage Tivoli Enterprise Monitoring Services window, complete the
following procedure to export keys:
1. Right-click the Tivoli Enterprise Portal Server and click Advanced → TEPS/e
Administration → Export keys.
2. Navigate to the directory where you want to create the file or change the file
type, or both. The directory displayed initially, on Windows, is
ITM_dir\InstallITM; and on Linux and UNIX, it is the Root directory.
What to do next
If you exported the portal server's LTPA key, provide the key file and password
that you used to encrypt it to the administrators of the other participating SSO
applications so that they can import the key.
The Tivoli Enterprise Portal user ID should also be assigned Tivoli Enterprise
Portal permissions and the monitoring applications that can be accessed. See
“Managing user IDs” on page 167 and “Administer Users” on page 162. The only
Tivoli Enterprise Portal users who do not need any permissions or monitoring
application assignments, are monitoring dashboard users who do not use the Tivoli
Enterprise Portal client when authorization policies are used.
Note: The first time a dashboard user accesses monitoring data, a Tivoli Enterprise
Portal user ID is automatically created for the user if there is not already a user ID
mapped to the user's LDAP distinguished name. In this case, the Tivoli Enterprise
Portal user ID is a randomly generated ID and the user is not assigned any
permissions. If Tivoli Enterprise Portal permissions are being used to control access
to monitored resources in the dashboards instead of authorization policies, or if the
dashboard user can launch the Tivoli Enterprise Portal, assign the user ID
permissions and the monitored applications that can be accessed.
If the LDAP connection is broken and the normal procedure to switch off
LDAP-based authentication does not work, use the following procedure.
Procedure
1. Stop the portal server by issuing the ./itmcmd agent stop cq command at a
command prompt from the installation directory.
2. Run the ./disableLDAPRepository.sh script from candle_home/arch/iw/ scripts,
where arch is the machine architecture, for example li6263 or aix533.
3. Reconfigure the portal server and disable LDAP authentication by issuing the
./itmcmd config -A cq command at a command prompt from the installation
directory.
4. Start the portal server by issuing the ./itmcmd agent start cq command at a
command prompt from the installation directory. The portal server
authentication through the monitoring server is now enabled.
5. If the monitoring server was also configured to use LDAP, and you are using
this procedure because the LDAP is out of service, you must also change the
monitoring server configuration to not use LDAP to authenticate. Complete
these configuration changes by using the monitoring server configuration help.
Make sure that all users log off the Tivoli Enterprise Portal before you begin the
procedure and do not log on again until the procedure is completed.
Procedure
1. Temporarily disable Tivoli Enterprise Monitoring Server security validation:
v Use the Manage Tivoli Enterprise Monitoring Servicesutility to
reconfigure the hub monitoring server:
Results
Note: Registry Services and Security Services and the OSLC client applications
must be in the same the Internet and Intranet domain, for example
mycompany.com, or one of its sub-domains. They also must be configured to use
the same realm name which is set when configuring a WebSphere Application
Server to use a LDAP repository.
To configure Registry Services and Security Services for single sign-on, generate the
LTPA key for the application server where they are installed, export the key, and
then import the LTPA key into the OSLC client applications that will be sending
HTTP GET requests to the Performance Monitoring service provider. See
“Configuring Jazz for Service Management for a central user registry” and
“Configuring Jazz for Service Management for SSO” in the Jazz for Service
Management Information Center (http://pic.dhe.ibm.com/infocenter/tivihelp/
v3r1/topic/com.ibm.psc.doc_1.1.0/psc_ic-homepage.html). These chapters contain
instructions for configuring Registry Services and Security Services to use an LDAP
user registry and generating and exporting their LTPA key.
When the Performance Monitoring service provider receives a HTTP GET request
from an OSLC client, it forwards the LTPA token to Security Services to
These topics cover the steps that you must complete to incorporate LDAP as
implemented in an Active Directory environment, while presenting the procedures
from an Active Directory perspective. Two user scenarios (one illustrating
monitoring server integration with Active Directory, the other portal server
integration with Active Directory) are provided to show you how this process can
help you implement Tivoli Monitoring security in the working environment; see
“User scenarios” on page 146.
This procedure uses the TEPS/e Web browser interface to complete the portal
server configuration; see “Using the TEPS/e administration console” on page 113.
Note:
1. Configuring the portal server to use an LDAP server to authenticate users has
the advantage, that it allows user IDs longer than 10 characters, a limit that is
imposed by monitoring server authentication. It also supports SSO (single
sign-on), which monitoring server authentication does not.
Only monitoring server-based user authentication allows user IDs to make
SOAP Server requests or to issue CLI commands that invoke SOAP Server
methods.
2. The configuration procedures and steps for enabling IBM Tivoli Monitoring
LDAP user authentication are the same for all LDAP implementations (Active
Directory, Tivoli Directory Server, and so on), but the configuration values you
specify will vary. These differences are due to the differences within the LDAP
implementations themselves. The most pronounced differences are the syntax
for Distinguished Names of objects within the directory. Additionally, the
LDAP schema differences between LDAP implementations and any LDAP
schema customizations will have a high impact on the LDAP user
authentication configuration values provided.
3. Although the scenarios in this set of topics assumes a Microsoft Active
Directory version 2003 environment, these instructions and scenarios have also
been verified using Active Directory Server 2008 and Active Directory Server
2008 R2.
The configuration uses all information that is provided to connect, bind, query, and
filter records from a specified LDAP Base to the targeted LDAP user registry for
user authentication. The configurations of the monitoring server and portal server
LDAP user authentication are separate operations; these configurations (after
completion) can be enabled and disabled independently. Do not consider that the
steps for configuring the monitoring server's LDAP user authentication translates
to the portal server's LDAP user authentication, nor vice versa.
You must have installed both the Tivoli Enterprise Monitoring Server and the
Tivoli Enterprise Portal Server as explained in the IBM Tivoli Monitoring Installation
and Setup Guide. Familiarize yourself with the introductory information in
Chapter 5, “Enabling user authentication,” on page 89.
You should work with your site's Active Directory administrator when deciding
which LDAP users will be authorized for monitoring server or portal server
authentication.
Best practice is that you also create an OU hierarchy that will contain your users.
This will facilitate a Base name directory search and limit search time while
increasing the performance of Tivoli Monitoring-to-LDAP user authentication.
Figure 3 shows a sample configuration comprising an OU=ITMUsers hierarchy with
containers ITMtepsUsers and ITMtemsUsers. With this schema, the base for
searching for monitoring server users to authenticate will be
CN=ITMtemsUsers,OU=ITMUsers,DC=company,DC=com, and the base for portal server
users to authenticate will be CN=ITMtepsUsers,OU=ITMUsers,DC=company,DC=com.
You also need to be aware of your Active Directory user object/attribute schema.
This information is required when coding your monitoring server's LDAP filter
configuration and for the portal server's TEPS/e Repository Security login
property. Figure 4 on page 131 shows one user's possible account settings (this
Tivoli Enterprise Portal Server user must also be authorized as a Tivoli Enterprise
Monitoring Server user).
The configuration for TEPS/e LDAP user authentication requires that you specify
Active Directory user object attribute Login Property, which will contain the
matching user name (in this example, llassite). Figure 5 on page 132 shows the
Active Directory user class instance for user llassite.
You must make the TEPS/e uid LDAP user authentication property match the
portal server's user account. To do this, edit the Active Directory's user/uid
attribute for the llassite user, and set uid=llassite so the portal server's user account
llassite will match uid=llassite in the
CN=Lin Lassiter,CN=ITMtepsUsers,OU=ITMUsers,DC=company,DC=com LDAP object
(which can be found by searching the directory beginning with the
CN=ITMtepsUsers,OU=ITMUsers,DC=company,DC=com base record).
Figure 3 on page 130, Figure 4 on page 131, and Figure 5 are provided to give you
an idea of the Active Directory properties that will be used for LDAP
authentication. The knowledge of where LDAP users reside within Active
Directory (the Base to query or search for Tivoli Monitoring users in the directory)
and the User schema (the user object attribute that contains the exact user name
used for authentication) are critical to successful configuration of either Tivoli
Enterprise Monitoring Server or Tivoli Enterprise Portal Server LDAP user
authentication.
Note: The portal server's user account's permissions for such Tivoli Monitoring
features as applications, views, and groups will continue to be managed within the
portal server's User Administration tool, as shown in Figure 6 on page 133.
LDAP user authentication is available only for individual Tivoli Monitoring users
and user groups. The enablement of LDAP authentication for individual Tivoli
Monitoring users ensures maximum flexibility on both the IBM Tivoli Monitoring
and LDAP sides. Scripting can be employed to maintain automated
synchronization of Active Directory and Tivoli Monitoring users. Data-collection
scripts for Active Directory user accounts can ensure that modifications to Active
Directory accounts (for example, users added or deleted) are reflected back into the
corresponding Tivoli Enterprise Portal users via the tacmd CLI..
Roadmap overview
To integrate your IBM Tivoli Monitoring user authentication environment with
your site's Active Directory implementation, complete the steps outlined in this
topic.
1. “Plan and create monitoring server and portal server users within Active
Directory” on page 134
Follow the steps outlined in this topic.
2. “Create and configure the portal server user accounts and permissions, if
desired” on page 134
Skip this step: If you do not want to use an LDAP server to authenticate Tivoli
Enterprise Portal users and you do not need to configure single sign-on for
integration with other products such as IBM Dashboard Application Services
Hub.
Use either the Tivoli Enterprise Portal Administer Users interface or the tacmd
command-line interface, if your site requires portal server user authentication.
These user accounts will use LDAP for authentication; thus, the userids chosen
must exactly match those specified in Active Directory. For the attributes you
should choose, see Figure 5 on page 132.
3. “Enable and configure LDAP user authentication for the portal server, if
desired” on page 135
Skip this step: If you do not want to use an LDAP server to authenticate Tivoli
Enterprise Portal users and you do not need to configure single sign-on for
integration with other products such as IBM Dashboard Application Services
Hub.
Skip this step: If you do not want to use an LDAP user to authenticate your
monitoring server users.
Complete this step if your site requires monitoring server authentication.
Configure all required permissions, applications, views, and groups for user
account operations within IBM Tivoli Monitoring, see Chapter 6, “Using Tivoli
Enterprise Portal user authorization,” on page 161 for more information. (Note that
these user accounts' permissions, applications, views, and groups will not be
Note: You could update Active Directory's User Object schema to map the IBM
Tivoli Monitoring user permissions, applications, views, and groups into Active
Directory. Then you can leverage these new schema attributes to assist you both
with user synchronization between Tivoli Monitoring and Active Directory and
with Active Directory's management of portal server user properties via Active
Directory scripting and the Tivoli Monitoring CLI's tacmd command.
It is not recommended that you add the default sysadmin account to your LDAP
directory. The sysadmin account should be reserved for local monitoring server
Security: Validate User authorization, thereby retaining a non-LDAP method for
accessing the monitoring server and the portal server.
User ID and User Description are freeform, but for good form, you should
attempt to match the User Name and User Description you already created in
Active Directory.
The Distinguished Name is critical to binding the Tivoli Monitoring userid to the
LDAP User account based on the TEPS/e LDAP configuration. This point is
discussed further later; for now, select entry
UID=userid,O=DEFAULTWIMITMBASEDREALM.
Now that the Tivoli Enterprise Portal userids have been created with the desired
IBM Tivoli Monitoring permissions and these same userids exist within Active
Directory, you must enable LDAP user authentication for these portal server users.
Use the TEPS/e Web browser interface to set the portal server's LDAP user registry
configuration details and the Active Directory Base name configuration. The
complete procedure for TEPS/e LDAP configuration is detailed in “Configuring
the portal server for LDAP authentication using the TEPS/e administration
console” on page 115.
When performing the steps described in “Configuring the portal server for LDAP
authentication using the TEPS/e administration console” on page 115, observe the
notes below.
Figure 9. Adding the Base entry to your realm. Note that this entry is associated with the ITMtepsUsers section of the
Repository.
v When saving your Step TEPS/e configuration work use Figure 10 on page 140 as
a reference. Click Save.
Also, while configuring your Repository and Base settings, remember to click
OK when asked to verify your configuration settings. Clicking OK or Apply
connects, binds, and queries the Active Directory LDAP database using your
updated configuration settings. If there is an issue, the configuration panel
returns a red error message like the one shown in Figure 11.
Note: Once the TEPS/e configuration is completed and saved, you must recycle
the Tivoli Enterprise Portal Server to see the TEPS/e-configured users listed as
Distinguished Names (see the example for llassite in Figure 12 on page 141).
To display all available Distinguished Names, first delete any entry in the
Distinguished Name field; then click the Find button. All configured Realm →
Repository → Base Distinguished Names that uniquely identify this set of entries in
the realm are displayed with the users that were returned by IBM Tivoli
Monitoring when performing a query against Active Directory using the Login
Properties value.
These users will be displayed using their Active Directory CN format (see
Figure 12).
Option: The Active Directory LDAP configuration steps recommend the Tivoli
Enterprise Portal userids be created prior to the configuration of TEPS/e.
Note: When you are asked to select the LDAP type, select Other and do not
supply values for any other LDAP parameters.
After you have finished configuring the portal server to use LDAP, refer to topic
“Roadmap for setting up the portal server to use an LDAP user registry and single
sign-on” on page 104 for additional steps to complete the configuration.
SSL communication between the portal server and the LDAP server is configured
using the TEPS/e administration console. Follow the steps in “Configuring
TLS/SSL communication between the portal server and the LDAP server” on page
119.
“User authentication through the hub monitoring server” on page 92 provides the
steps required to enable LDAP user authentication for the Tivoli Enterprise
Monitoring Server. Additional comments are provided here for specific steps
within this process.
Note: The monitoring server's userids are limited to 10 characters, dictating that
the Active Directory user names you choose also not exceed 10 characters.
User scenarios
In these scenarios it is desired that all user authentication be done via the site's
Microsoft Server 2003 Active Directory LDAP user registry. There are two possible
ways to configure this authentication for IBM Tivoli Monitoring users:
Monitoring server LDAP authentication
Configure authentication at the Tivoli Enterprise Monitoring Server using a
username filter that maps a userid entered at the Tivoli Enterprise Portal
(such as name) to name@company.com. The user logs in as name, which then
gets translated through the filter to match the needed LDAP lookup.
This method is described in “Authenticating monitoring server userids
with Microsoft Active Directory” on page 147.
Portal server LDAP authentication
Configure authentication at the Tivoli Enterprise Portal Server so that the
userid the user supplies when logging into the Tivoli Enterprise Portal gets
looked up and authenticated against the LDAP user registry. In this
scenario, the user logs in with firstname.lastname@company.com.
This method is described in “Authenticating portal server userids with
Microsoft Active Directory” on page 151.
This scenario does not require TEPS/e configuration in order to work. The
drawback with this solution is that SSO (single sign-on) cannot be implemented;
also, userids are restricted to 10 characters maximum. The advantage is that
monitoring server-based user authentication allows your users to make SOAP
Server requests and use tacmd command that send requests to the hub monitoring
server.
Environment
The environment comprises two systems, one running the Tivoli Monitoring
monitoring server (IP address 192.168.1.240) and one running Microsoft Windows
2003 Advanced Server configured as a Microsoft Active Directory domain
controller (IP address 192.168.1.241). Note that the Tivoli Monitoring system is a
stand-alone server called itm6210 and not part of the configured domain. The
sample domain is called bjomain.com, and the Active Directory server is called
msad.
As shown in Figure 15, two users have been configured in Active Directory,
sysadmin and bjoern, both with email addresses, as shown in Figure 16 on page 148
(you will see when the LDAP filter is configured in IBM Tivoli Monitoring why the
email address is important). You can use other parameters, but this is the one the
instructions in “User authentication through the hub monitoring server” on page
92
Chapter 5. Enabling user authentication 147
92 recommend.
Browsing Active Directory: Browsing the Active Directory Repository with the
GUI browser, ldapbrowser, shows all the parameters you need, such as the
Distinguished Name and the email address for the sysadmin user (see Figure 17 on
page 149).
By right-clicking MSAD Server at the top of the tree and selecting Properties, you
can see that the Base DN (the point where Tivoli Monitoring will start searching
for users) is DC=bjomain,DC=com.
The next step is to match this information with the appropriate fields in the Tivoli
Enterprise Monitoring Server configuration dialog.
Putting the pieces together: Figure 18 on page 150 shows the monitoring server's
LDAP settings that allow you to log in as either sysadmin or bjoern (only these
users are defined to the monitoring server).
Note: If you need to activate Secure Sockets Layer, SSL, security for your Tivoli
Monitoring-to-Active Directory communications, see Chapter 8, “Securing
communications,” on page 207. Also ensure you have at hand the parameter values
listed in Table 12 on page 94.
The following are some of the more important parameters shown in Figure 18:
Enter required LDAP user filter
This parameter says to search for the mail parameter within the User object.
This is why you included the email address in the user's Active Directory
entry.
%v Is a variable that Tivoli Monitoring replaces with the userid entered on the
login screen.
LDAP base
Is the complete Base DN listed in “Browsing Active Directory” on page 148.
If IBM Tivoli Monitoring complains that the user entered the wrong password,
this is a sign that the wrong LDAP Base DN was specified here, in which case
Tivoli Monitoring starts its search at the wrong LDAP location.
LDAP bind ID
Enter the Distinguished Name for a user that has read permission to the entire
Base DN where Tivoli Monitoring will begin searching for its users.
Note: It is not enough to enter only the user name, for example, sysadmin.
Once you have gotten your parameters defined right, use the grep command to
search for the string LDAP in the monitoring server's log file to verify that there are
no error messages. Optionally, you can use the ldapsearch utility to test your
parameters without starting the monitoring server: if ldapsearch does not return
output similar to that shown in Figure 19 on page 151, your input is incorrect. You
The site attempted to use the portal sever's Manage Tivoli Enterprise Monitoring
Services utility or itmcmd command line interface to configure the LDAP
authentication. This proved unsuccessful because the built-in authentication
mechanism expects to look up an LDAP field named uid; this customer's Active
Directory LDAP records have no uid field.
The rest of this section documents the user authentication steps you should follow
via the TEPS/e Administration Console, the portal sever's built-in eWAS server
that defines the custom LDAP user mappings for Tivoli Enterprise Portal access at
this company.
To authenticate users against the customer's Active Directory LDAP user registry,
several pieces of information are required:
1. The type and location of the LDAP information store.
In this example, your site's Active Directory administrator provided the following
LDAP information:
1. LDAP type: Microsoft Active Directory Server version 2003; location: Hostname
adhost.company.com
2. Port to use: 636 (which indicates that SSL is required for connection)
3. Bind ID of svc.tivolisec@company.com, along with the appropriate password
4. The Login Properties field to use: the user's email address
5. The LDAP Base: DC=US,DC=GLOBAL,DC=company,DC=COM
Despite having all the necessary connection information, every attempt to connect
to the LDAP user registry fails. You can use the LDAP utilities described in “Active
Directory LDAP verification tools” on page 144 to look up and verify your
connection information and determine why every connection attempt failed.
In this example, two utilities are used: LDP.exe and ldapbrowser. These utilities
show you that SSL communication is not required in this customer's environment;
thus, connecting at the normal unencrypted LDAP port of 389 is valid. The tools
also reveal that the full LDAP Distinguished Name associated with the
svc.tivolisec@company.com address is
CN=svc.tivolisec,OU=ServiceAccount,DC=us,DC=global,DC=company,DC=com.
Once all these entries have been validated, it is time to use the TEPS/e
Administration (eWAS) tools to define the LDAP lookup parameters for Tivoli
Monitoring user administration.
Note: Step 1 need be done only once. The remaining steps must be done every
time you wish to use the TEPS/e administration console.
Define the wasadmin password: Before you can complete the TEPS/e administration,
you must set a password for the wasadmin account that admits you to the eWAS
server. To do this, either invoke script updateTEPSEPass.sh in the
$CANDLEHOME/iw/scripts directory or use the Manage Tivoli Enterprise Monitoring
Services interface.
This procedure need be done only once, unless at a later time you desire to change
the wasadmin user password.
To define the wasadmin password via the command line, invoke script
updateTEPSEPass.sh in the $CANDLEHOME/$INTERP/iw/scripts directory:
# cd $CANDLEHOME/$INTERP/iw/scripts
# ./updateTEPSEPass.sh wasadmin newpw
WASX7209I: Connected to process "ITMServer" on node ITMNode using SOAP connector;
The type of process is: UnManagedProcess
WASX7303I: The following options are passed to the scripting environment and are
available as arguments that are stored in the argv variable: "[wasadmin, newpw]"
Enable ISCLite (TEPS/e eWAS server administration): Anytime you need to manage
your site's LDAP authentication, you first need to enable TEPS/e administration
via the Integrated Solutions Console. Note that whenever you either reconfigure or
stop then restart the Tivoli Enterprise Portal Server, the TEPS/e console is
automatically disabled.
To enable the TEPS/e console via the command line, invoke the enableISCLite.sh
script from the $CANDLEHOME/platformcode/iw/scripts subdirectory on the portal
server machine:
# pwd /apps/TEPS_s11154cdc/li6263/iw/scripts
# ./enableISCLite.sh true
WASX7209I: Connected to process "ITMServer" on node ITMNode using SOAP connector;
The type of process is: UnManagedProcess
WASX7303I: The following options are passed to the scripting environment and are
available as arguments that are stored in the argv variable: "[true]"
ISCLite started
Log into the TEPS/e administration console: Bring up the eWAS Integrated Solutions
Console in your browser using this address:
http://tepsserver.company.com:15205/ibm/console
Log in using the username wasadmin and the password you set for that user in
“Define the wasadmin password” on page 152.
When you have completed this page, click OK. The verification screen is
shown:
6. Click Save.
Add your LDAP user registry to the eWAS realm: The next step is to add the
newly defined registry to the eWAS realm so your site can use LDAP to look up
userids.
1. On the left side of the primary Integrated Solutions Console screen, under
Security options select Global Security.
2. In the User account repository section, click Configure (at the bottom beside
Federated Repositories).
This opens the screen that lets you add registries to the realm.
3. To add the repository defined in “Define the LDAP user registry in the
Integrated Solutions Console” on page 154, click Add Base entry to Realm.
The Repository reference screen is shown, where you can add the LDAP user
registry to your site's eWAS realm:
At this screen, ensure that Repository is set to LDAP (or whatever Repository
identifier you assigned in “Define the LDAP user registry in the Integrated
Solutions Console” on page 154). In the two entry fields, enter the Bind
distinguished name, which was defined in this instance to be
DC=US,DC=GLOBAL,DC=company,DC=COM. Then click OK.
4. From the Integrated Solutions Console verification screen, click Save.
Figure 28. The Integrated Solutions Console's Repositories in the realm screen
Click OK.
6. From the Integrated Solutions Console verification screen, click Save:
7. This returns you to the initial Integrated Solutions Console sign-in screen:
Click Logout.
8. Restart the Tivoli Enterprise Portal Server.
(Optionally) test the LDAP lookup within TEPS/e: You can test the LDAP
lookup within the TEPS/e console itself. If the lookup works correctly here, it will
work within the Tivoli Enterprise Portal Server.
1. Enable the TEPS/e console again (see “Enable ISCLite (TEPS/e eWAS server
administration)” on page 153), and then log back into it using your wasadmin
userid and newly assigned password (see “Log into the TEPS/e administration
console” on page 153).
The initial TEPS/e screen is displayed:
2. Expand the list of Users and Groups; then select Manage Users.
3. Within the Manage Users pane, set Search by to E-mail, and specify your test
userid (that is, email address) in the Search for field.
4. Click Search.
If the email address you specified is found, its characteristics are listed at the
bottom of the Manage Users pane.
Administer Users is a multi-tabbed two-paned window. The top frame has two
tabs: Users and User Groups, that list the user IDs, distinguished names if
the portal server is configured for authentication to an LDAP user registry, and the
user groups that are stored on the portal server. The profile of the selected user or
user group is reflected in the bottom frame:
Permissions has a list of the portal features in the Authorities box. On the
right are the possible operations for the selected feature. A selected check box
means the selected user or user group has permission to perform that
operation; a indicator next to the check box means the permission was added
to a user group the user belongs to.
Applications shows all the applications being monitored and that are
available for assigning to the user or user group. One user or user group, for
example, can be profiled to see only the OMEGAMON applications, another to
see only Linux and Oracle, middleware, and another to see all applications.
Navigator Views shows all the Navigator views that are on the portal server
and that are available for assigning to the user or user group. The user or user
group can be restricted to seeing only a certain branch of a Navigator view
rather than the entire hierarchy.
Member of, when the Users tab is selected, or Members, when the User
Groups tab is selected, is a list of the groups the user belongs to or the user
names in the group.
The User Administration function enables you to maintain user IDs and user
groups on the portal server, and provides varying degrees of access to the features
and views of your monitored environment to accommodate any combination of job
roles, such as operators who respond to alerts and direct them to the appropriate
person for handling and administrators who plan, design, customize, and manage
the monitoring environment.
In some managed enterprises one person might assume all of these roles. In larger
enterprises, the roles are often divided. You can choose to assign roles by
individual user or by user type or both.
Tivoli Enterprise Portal user IDs are also required for users who access monitoring
dashboards in IBM Dashboard Application Services Hub. How you manage
dashboard users depends on the type of authorization configured in the portal
server and whether the dashboard users will also use the Tivoli Enterprise Portal
client. There are two types of authorization that can be configured for controlling
access to monitored resources in IBM Dashboard Application Services Hub:
Role-based authorization policies
These policies are created using the tivcmd Command-Line Interface for
Authorization Policy. They provide more granular authorization than Tivoli
Enterprise Portal monitoring application assignments. Using role-based
authorization policies, you can assign a user permission to view specific
managed system groups or managed systems. When role-based
Configuring the portal server and Dashboard Application Services Hub to share an
LDAP user registry is the best practice approach for having a federated set of
dashboard users and Tivoli Enterprise Portal client users. In this scenario, the
dashboard users login to the dashboard hub with their LDAP username and you
must map their LDAP distinguished name to a Tivoli Enterprise Portal user ID
with the required permissions.
Tivoli Enterprise Portal user IDs are automatically created with no permissions if a
dashboard user requests monitoring data and does not have a user ID mapped to
their distinguished name. See “Notes on user administration” on page 174 for
more details.
Administer Users
Your user ID and the user groups you are a member of are profiled with a set of
permissions that determines which Tivoli Enterprise Portal features you are
authorized to see and use, a list of monitored applications you are authorized to
see, and a list of Navigator views (and the highest level within a view) you can
access.
When you modify the permissions or the list of monitored applications for a Tivoli
Enterprise Portal user or user group, the authorization change does not take effect
until the user logs out of the Tivoli Enterprise Portal client and then logs back in. If
Tivoli Enterprise Portal permissions are being used to authorize monitored
resources for dashboard users, the authorization changes also do not take effect
until the user logs out of Dashboard Application Services Hub and logs back in.
Related tasks:
After you select a user or user group from one of the lists, you can click any of the
tabs in the lower half of the window to see the what permissions have been
granted and what has been assigned. User groups enable the administrator to
authorize the same set of functional permissions, applications, and Navigator
views to multiple users at one time. Management of user authorization can be
done by groups as well as individually. A user can be associated with one or more
user groups; authorization by group will be by inclusion and not exclusion (nested
groups are supported). Authorization will also be by global authority and by
association with managed system and managed system groups. This security is not
dependent on external authorization.
Permissions
You can authorize the same set of functional permissions multiple users, user
group or each user ID at one time.
The following features are enabled or disabled individually for each user ID or
user group.
Action
View allows the user to see and run a take action command from the
available list of commands in the Take Action view and in the pop-up
menu for the Navigator item.
Modify allows the user to create and save Take Action commands.
When enabled, Edit Action appears in the Navigator pop-up menu.
When issuing a take action command, you must be authorized on the
relevant system for the requested command. For example, to issue a TSO
command, your user ID must be both a valid TSO ID and a valid user ID
on the portal server. The user ID must be typed with the same letter casing
exactly as typed when logging on to the portal server (with the same letter
casing).
Agent Management
Manage allows the user to perform agent deployment throughout the
managed network. This includes installing a monitored product, keeping
the software revisions up-to-date, and removing an agent from the
managed network. This permission also requires Action - Modify to be
enabled.
Start/Stop allows the user to start a monitoring agent or to stop it
running.
Applications
Your user ID is set so you can see some or all the application types being
monitored. For example, one user might be able to see only mainframe
applications, while another can see only middleware, and another sees all
applications.
Allowed Applications
Shows the applications that you can access from Tivoli Enterprise Portal.
Navigator views
When a Navigator view is created, only the author is able to see the view, but it is
available for the administrator to assign to users. An assigned Navigator view
means the user can open it. For each assigned view, the user can be restricted to
see only a certain branch rather than the entire hierarchy.
Assigned Views
Shows the Navigator views the user is able to see and access. The first
Navigator view in this list is the default for the user; it displays
automatically whenever the user logs on. You can select any views to
which you do not want the user to have access, and click right arrow to
move them to the Available Views list. Select the appropriate entries and
click left arrow to move them to the Assigned Views. You can move a
Navigator view to the top of the list to make it the default by clicking the
up arrow.
Available Views
Shows the Navigator views not assigned to the user and available for
assignment. Select the Navigator views you want to add and move them to
the Assigned Views list by using the left arrow. After selecting the first
view, you can use Ctrl+click to select other views or Shift+click to select all
views between the first selection and this one.
Assigned Root
Shows the Navigator view chosen in Assigned Views, with the user's
assigned Navigator root highlighted. The root is the top-most level of this
Navigator view that the user can access. The user can access this item and
all items below it, but no items parallel to or above it in the Navigator.
For example, you can assign UNIX Systems as the assigned root. The user
sees the UNIX Systems workspaces and those below, but is not able to see
the Enterprise workspaces or anything under Windows Systems.
Adding a user ID
Create a user ID for all users that should be able to log onto the Tivoli Enterprise
Portal Server using a portal client or the tacmd tepsLogin command. A user ID is
also required for IBM Dashboard Application Services Hub users who request
monitoring data. You can use the default user profile or copy the profile of an
existing user.
To use this function, your user ID must have Modify permission for User
Administration.
Procedure
1. Click Administer Users.
2. Create a new user ID or create one from another:
v To create a new user ID with the default user profile, click Create New
User.
v To create a new user ID from an existing one, select the profile that you want
to use from the Users list and click Create Another User.
3. In the Create New User window, enter the user information:
v User ID: The logon name. The name must use ASCII characters, can be up to
10 characters, and can contain no spaces. The name is limited to eight
characters if user authentication is at the hub monitoring server and uses
RACF (resource access control facility) security for z/OS.
v User Name: The name of the user or job classification or both. This name can
include spaces and be up to 32 characters. The user name is displayed in
Users list.
v Distinguished Name: The unique identifier in the Lightweight Directory
Access Protocol (LDAP) user registry for the name given in the User ID
field. Click Find to locate and insert the distinguished name, such as
UID=FRIDA,O=DEFAULTWIMITMBASEDREALM
v User Description: Optional description for the user. The text can include
spaces and punctuation.
4. Click OK to close the window and see the new user ID arranged alphabetically
in the Users list.
5. To change the Permissions, select a function from the Authorities tree and
select or clear each option as appropriate for all functions with permissions that
you want to change.
6. To assign access privileges to applications (managed system types), click the
Applications tab, then select <All Applications> or the individual applications
the user should see, and click to move them to the Allowed Applications
list. After selecting the first application, you can use Ctrl+click to select other
applications or Shift+click to select all applications between the first selection
and this one.
7. To assign Navigator views, click the Navigator Views tab:
a. Select a Navigator view (or more with Ctrl + click and Shift + click) from
the Available Views and click to move it to the Assigned Views.
What to do next
The Tivoli Enterprise Portal client logon window has a field for entering a user ID
and password. If you want the user ID and password to be authenticated,
configure the monitoring server or portal server to authenticate users. See
Chapter 5, “Enabling user authentication,” on page 89 for details.
Related reference:
“Administer Users” on page 162
Your user ID and the user groups you are a member of are profiled with a set of
permissions that determines which Tivoli Enterprise Portal features you are
authorized to see and use, a list of monitored applications you are authorized to
see, and a list of Navigator views (and the highest level within a view) you can
access.
To use this function, your user ID must have Modify permission for User
Administration.
Procedure
1. Click Administer Users.
2. Do one of the following in the Users list:
v Click inside the Name or Description field to edit either of them.
v Double-click anywhere in a row to open the Modify User window for editing
any of the fields.
v Right-click the user profile you want to edit and click Modify User.
3. Edit the User Name, Distinguished Name or User Description, then click OK.
Distinguished Name is required if user authentication is through the portal
server to an LDAP user registry. You cannot change the one-word User ID
other than to change the letter casing. To edit the one-word User ID, delete the
user profile and create a new one.
v If you have not yet added the DN, click Find to locate the name that
matches the user ID.
If your monitored environment was previously configured for authentication
through the Tivoli Enterprise Monitoring Server and then reconfigured to
authenticate through the Tivoli Enterprise Portal Server, you might see two
Results
The next time the user logs on, the permission changes will be in effect.
Related reference:
“Administer Users” on page 162
Your user ID and the user groups you are a member of are profiled with a set of
permissions that determines which Tivoli Enterprise Portal features you are
authorized to see and use, a list of monitored applications you are authorized to
see, and a list of Navigator views (and the highest level within a view) you can
access.
Removing a user ID
You can remove a user ID as needed.
To use this function, your user ID must have Modify permission for User
Administration.
Procedure
1. Click Administer Users.
2. Select the user ID that you want to delete. You can select additional user IDs
with Ctrl+click, or with Shift+click to select all user IDs between the first
selection and this one.
3. Click Remove Users to delete the selected user ID and profile from the list.
4. When a message asks you to confirm the user ID removal, click Yes. The user
is permanently removed from the user ID list. If the user is currently signed on,
this does not affect their work session, but they will not be able to log on again.
Default user
The first user ID in the Users list is <Default User>.
To use this function, your user ID must have Modify permission for User
Administration.
The Default User ID is used as the template ID for users created with Create
New User. Edit this user ID if you want to change any of the default settings. The
initial defaults enable all the functions listed under Tivoli Enterprise Portal
Authorities except User Administration Create and Modify. Any changes you make
to the <Default User> ID apply to users created from this point on; they do not
affect any existing user ID settings.
A user can be associated with one or more user groups. If a permission is granted
to a user directly through their user ID, they maintain that permission even if a
user group they belong to does not grant that permission. The reverse is also true,
so that if an individual user ID is not granted a permission but the group ID is, the
user will have the permission through their membership in the user group. Thus,
the user's permission set is collected from what is given to the individual user ID
and to any and all user groups that they belong to.
When the active top tab is Users, the last tab on the bottom set of tabs reads
Member Of. When the active top tab is User Groups, you will also have a
Members tab. Assignment of users to groups can be done in either of these lower
tabs.
Click the group in the details view at the top, then go to the Members tab to
see the list of users that belong to this group. likewise, to see the groups a user
belongs to.
To use this function, your user ID must have Modify permission for User
Administration.
To use this function, your user ID must have Modify permission for User
Administration.
Procedure
1. Click Administer Users to open the Administer Users window.
2. Click the User Groups tab.
3. Do one of the following:
v To create a new user group, click Create New Group.
v To copy an existing user group, select the group name from the list and
click Create Another Group.
4. In the Create New Group or Create Another Group window, enter the
following user information:
a. Group ID: The group identifier. This name can be up to 10 characters and
can contain no spaces. The name is limited to eight characters if the hub
monitoring server uses RACF (resource access control facility) security for
z/OS.
b. Group Name: The name or job classification for the user group. This name
can include spaces..
c. Group Description: The text to describe the user group, such as their
responsibilities. The description can include spaces and punctuation.
5. Click OK to close the window and see the new user group arranged
alphabetically in the User Group list.
6. Add members to the group in the Members tab by selecting one or more
user IDs in the Available Members list and clicking to move to the
Assigned Members list.
7. To change the Permissions for the group, select a function from the
Authorities tree and select or clear each option check box for all functions.
8. To assign access privileges to applications (managed system types) for the
group, click the Applications tab, then select <All Applications> or the
individual applications the user should see, and click to move them to the
To use this function, your user ID must have Modify permission for User
Administration.
Procedure
1. Click Administer Users to open the Administer Users window.
2. Click the User Groups tab.
3. Right-click the user group to edit and click .
4. Edit the Group Name and Group Description, then click OK. You cannot
change the one-word group ID. You must, instead, create another user group
from this one and give it a new name, then delete this one.
5. To change the Permissions, select a function from the Authorities tree and
select or clear each option as appropriate for all functions with permissions that
should change.
6. To change the group access privileges to applications (managed system types),
click the Applications tab, select any applications you want to remove from
the Allowed Applications list and click ; select the applications you want to
add from the Available Applications list (or select <All Applications>), and
click . After selecting the first application, you can use Ctrl+click to select
other applications or Shift+click to select all applications between the first
selection and this one.
7. To change any Navigator view assignments for the group, click the
Navigator Views tab, then add or remove Navigator views from the Assigned
Views list, and use to place the one you want to be the default at the top of
the list. For each Navigator view, change the Assigned Root as needed.
8. When you are finished editing the user group, save your changes with Apply
to keep the Administer Users window open, or OK to close it. The user group
changes are effective the next time each group member logs on.
Note: You can change the permissions, except Create and Modify for User
Administration, of any groups you are a member of.
To use this function, your user ID must have Modify permission for User
Administration.
Procedure
1. Click Administer Users to open the Administer Users window.
2. Click the User Groups tab.
3. Select the user group to delete from the list and click Remove Selected
Group. You can select additional user IDs with Ctrl+click, or with Shift+click to
select all user groups between the first selection and this one.
4. When a message asks you to confirm the user group removal, click Yes. The
group is permanently removed from the user group list. Any members of this
user group who receive permissions from the group will not be affected until
they next log on to the portal server.
Any changes you make to workspaces, links, and terminal host session scripts in
the Tivoli Enterprise Portal are available only to your user ID. The exception is
while Workspace Administration Mode is enabled.
SYSADMIN logon ID
The Tivoli Enterprise Portal requires your logon ID whenever you start a work
session. Every ID must first have been registered on the portal server. You can log
onto the portal server with SYSADMIN and register other user IDs through the
Administer Users window. The initial user ID, SYSADMIN, has full access and
complete administrator authority. The system administrator registers additional
users and sets their access privileges and authority.
Each user ID is stored at the Tivoli Enterprise Portal Server and contains:
v The user name
v Job description
v Permissions for viewing or modifying Tivoli Enterprise Portal functions
v Assigned Navigator views and which Navigator item in each view appears as
the root (default is the first item)
v Access to specific monitoring applications
v The user groups the user belongs to and indicators to signify when a permission
has been granted to the user by a user group
Default user
The first user ID in the list is <Default User> and is used as the template ID for
users created with Create New User. Edit this user ID if you want to change any of
the default settings. The initial defaults enable all the functions listed under Tivoli
Enterprise Portal Authorities, except the Modify permission for User
Administration. Any changes you make to <Default User> ID apply to users
created from this point on; they will not affect any existing user ID settings.
You set the authority privileges for each user when you create their user IDs.
Giving users access to operational areas and customization options takes planning.
Consider the job responsibilities of each user and the company security
requirements when specifying authority privileges.
Important: Anyone with permission to create custom queries obtains access to all
of the ODBC data source names (DSNs) created at the Tivoli Enterprise Portal
Server. Add database user IDs, to be used in the DSN, to your database software,
making sure to restrict user access to only those tables, columns, and so on,
allowed by your organization's security policies.
The first time a new user accesses a monitoring dashboard in IBM Dashboard
Application Services Hub, a Tivoli Enterprise Portal user ID is automatically
created and mapped to the user's LDAP distinguished name if a Tivoli Enterprise
Portal user ID does not already exist for the user. The Tivoli Enterprise Portal user
ID is a randomly generated string. If you need to assign Tivoli Enterprise Portal
permissions and monitoring applications to a dashboard user and their Tivoli
Enterprise Portal user ID was automatically created, you can either assign the
permissions to the randomly generated user ID or perform these steps:
1. Delete the Tivoli Enterprise Portal user ID that was automatically created.
2. Create a new user Tivoli Enterprise Portal user ID, map it to the LDAP
distinguished name for the user, and then assign it permissions and monitoring
applications.
The Tivoli Enterprise Portal Server verifies user IDs whenever users log on. If a job
description changes and the user requires different access to the portal server, you
must review and perhaps change the user's permissions.
The user ID for logging on to the portal server might include a password. You do
not establish passwords in the portal. Instead, you must define a matching user ID
with password to the network domain user accounts or to the operating system
where the Tivoli Enterprise Monitoring Server resides:
v User Accounts on the Windows system
v Password file on the UNIX system
v RACF or ACF/2 host security system on the z/OS system
If the monitoring server has been installed on a distributed system, you can check
if it has been configured to Validate User:
1. Start the Manage Tivoli Enterprise Monitoring Services program:
Start → Programs → IBM Tivoli Monitoring → Manage Tivoli
Enterprise Monitoring Services.
Change to the install_dir/bin directory and run the following
command: ./itmcmd manage [-h install_dir] where install_dir is the
installation directory (default is opt/IBM/ITM).
2. Right-click the Tivoli Enterprise Monitoring Server row for TEMS1 (hub) and
select Reconfigure.
3. In the Tivoli Enterprise Monitoring Server Configuration window, observe the
setting of the Security: Validate User check box.
When this option is selected, the password is required whenever a user logs on
to the portal server; when it is cleared, the user name is required to log on but
no password is required.
Note: Be aware that passwords must follow the security requirements for your
organization. If this includes periodic password changes, you might get a Logon
password has expired message while attempting to log on to the portal server.
Should this happen, you must change your system password before you can log
on. For example, on Windows this means changing the password through the
Administrative Tools User Accounts.
In addition to any security requirements for launching into the Tivoli Enterprise
Portal (such as single sign-on requirements), the Tivoli Enterprise Portal user ID
that receives control after a launch from an external application must be
pre-authorized to access the target managed system and workspaces. The user ID
also must be authorized to issue any required take action commands.
When the Tivoli Enterprise Portal sends a Take Action command to a managed
system, the user ID might or might not be checked for authority to perform the
action. In the simplest case, the command is sent to the managed system and
executed using the user ID under which the agent is running. TheTivoli Enterprise
Portal user ID is sent along with the action command in these contexts:
v On-demand: user ID currently logged on
v Situation action: user ID of the last person to update the situation
v Workflow action: user ID of the last person to update the policy
However, the ID is ignored by the managed system unless told otherwise by a
command prefix. These are command handlers implemented in the IBM Tivoli
Monitoring products to control whether the Tivoli Enterprise Portal user ID should
be validated before passing the command to the agent for execution.
Command prefix
When a command prefix is present in the Take Action, the agent passes the
command to the application handler rather than executing the command.
The syntax of the prefix and take action command is
Tivoli Enterprise Portal permissions are the default authorization method for
controlling access to resources in monitoring dashboards. They are also the
mechanism used to authorize Tivoli Enterprise Portal client users. However,
authorization policies provide greater control over resource access. With
authorization policies, you can grant a dashboard user permission to view data
from specific managed system groups or managed systems as compared to Tivoli
Enterprise Portal authorization which assigns view permission for monitoring
applications (monitoring agents). In other words, with Tivoli Enterprise Portal
authorization, a user is assigned permission to view all managed systems of a
particular agent application type, for example all Windows OS agents.
If you want to use the role-based access control provided by authorization policies,
you must install the Tivoli Authorization Policy Server and the tivcmd
Command-Line Interface for Authorization Policy. The Authorization Policy Server
is installed with IBM Dashboard Application Services Hub along with monitoring
dashboard applications such as Infrastructure Management Dashboards for Servers
or custom dashboards. The tivcmd CLI is installed on computers used by
authorization policy administrators and provides the command-line interface for
creating and working with authorization policies. It sends HTTP or HTTPS
requests to the Authorization Policy Server which maintains the master policy
store. For installation information, see “Installing and configuring the Tivoli
Authorization Policy Server and tivcmd Command-Line Interface for Authorization
Policy” in the IBM Tivoli Monitoring Installation and Setup Guide.
After successful installation of these two packages, you can execute tivcmd CLI
commands as required to create and work with roles, grant permissions, exclude
permissions, revoke permissions, and assign users and user groups to a role. For a
complete list of tivcmd CLI commands, see the IBM Tivoli Monitoring Command
Reference.
Once the initial set of authorization policies have been created, you enable
authorization policy checking in the Tivoli Enterprise Portal Server. The portal
server periodically downloads the authorization policies from the Authorization
Policy Server application. When a dashboard user requests monitoring data, IBM
Dashboard Application Services Hub forwards the request to the dashboard data
Because both the Dashboard Application Services Hub and the portal server must
have knowledge of the dashboard user, a typical dashboard environment includes
a federated user registry provided by an LDAP server and single sign-on. For
detailed information on the set of tasks involved in setting up a dashboard
environment that uses authorization policies, see “Setting up a monitoring
dashboard environment with single sign-on and with per user authorization
controls” on page 34.
You can also revoke permissions from a role if you later decide that you need to
remove a grant or exclude permission from a role. Authorization policies are also
used to control which users can create and work with roles.
The following table lists the supported resource types, their associated object types
and operations, and the type of permission that can be assigned for resources of
this type.
Table 17. Authorization policy resource types and their supported permissions and elements
Permission Operation Object type Resource type Description
grant view attributegroup managedsystemgroup Using this combination, you can grant
permission to view monitoring data such as
metrics or status for all managed systems in a
managed system group.
grant view event managedsystemgroup Using this combination, you can grant
permission to view situation events from all
managed systems in a managed system group.
Note: If you want to grant permission to view
the monitoring data that triggered the situation
event then you must grant permission to view
monitoring data for the managed system group.
grant view attributegroup managesystem Using this combination, you can grant
permission to view monitoring data such as
metrics or status for a specific managed system.
grant view event managedsystem Using this combination, you can grant
permission to view situation events from a
specific managed system.
Note: If you want to grant permission to view
the monitoring data that triggered the situation
event then you must grant permission to view
monitoring data for the managed system group.
exclude managedsystem Using this combination, you can exclude
permission to perform any operation for a
specific managed system.
grant create role rolegroup Using this combination, you can grant
permission to create roles or events for specific
managed systems.
grant delete role rolegroup Using this combination, you can grant
permission to delete roles.
When you are granted permission to view attribute groups (monitoring data) or
events for a managed system group, you are granted permission to view the group
and you are also granted permission to view all of the group members, unless
there is an exclude permission for a group member.
A role group is a set of roles that are shared across all the IBM Tivoli Monitoring
domains using a single Authorization Policy Server. The Authorization Policy
Server supports only one role group named default. It is specified as the resource
name when creating permissions that perform operations on roles.
PolicyDistributor
The role with permission to download authorization policies.
This role, or a custom role with the same permission, must be assigned to
the user ID that is specified when authorization policies are enabled in the
portal server. The portal server uses the specified user ID and other
connection properties to periodically connect to the Authorization Policy
Server and download the latest policies. When the Authorization Policy
Server receives a request for authorization policies, it verifies that the user
who sent the request has been granted permission to distribute policies.
Table 19. PolicyDistributor permissions
Operation Object type Resource type Resource
distribute role rolegroup default
LinuxOperator
A role that has attribute group and event viewing permissions for all Linux
agents.
UNIXOperator
A role that has attribute group and event viewing permissions for all UNIX
agents.
WindowsOperator
A role that has attribute group and event viewing permissions for all
Windows agents.
Table 20. LinuxOperator, UNIXOperator, and WindowsOperator permissions
Role Operation Object type Resource type Resource
LinuxOperator view attributegroup and managedsystemgroup *LINUX_SYSTEM
event
UNIXOperator view attributegroup and managedsystemgroup *ALL_UNIX
event
WindowsOperator view attributegroup and managedsystemgroup *NT_SYSTEM
event
VCenterOperator
A role that has access to all VMWARE Virtual Centers and ESX Servers.
When you are ready to start using authorization policies, reconfigure the portal
server to enable authorization policies and to specify the connection properties for
the Authorization Policy Server. The connection properties include the user ID that
has been assigned a role with permission to distribute policies.
For a list of tasks to perform before you enable authorization policies, see “Setting
up a monitoring dashboard environment with single sign-on and with per user
authorization controls” on page 34.
A best practice is to create a user group in LDAP for your policy administrators
and assign the user group to the roles that have permission to create and work
with authorization policies. By taking this approach, you only update the group
membership (and not the authorization policies) when you add or remove policy
administrators.
Any roles that are used for role administration must have the following
permission:
Procedure
v To assign a user or user group the predefine RoleAdministrator role, use the
following steps:
Any roles that are used for policy distribution must have the following permission:
Procedure
v To assign a user the predefined PolicyDistributor role, use the following steps:
1. Define a user in LDAP, for example uid=PolicyAdmin,cn=itm,o=ibm.
2. Add the user to the predefined PolicyDistributor role using the following
command:
tivcmd addtorole --rolename PolicyDistributor
--users uid=PolicyAdmin,cn=itm,o=ibm
v To create a new role with the same permission as the PolicyDistributor role, use
the following steps:
1. Define a user in LDAP, for example uid=PolicyAdmin,cn=itm,o=ibm
2. Create a new role with the policy distribute permission and assign it to the
user using the following commands:
tivcmd createrole --rolename EastCoastDistributor --description
"East Coast user IDs for downloading policy"
You use the tivcmd Command-Line Interface for Authorization Policy commands
to managed your policies. For detailed information about the commands, see the
IBM Tivoli Monitoring Command Reference.
This example assumes you want to prevent members of the user group
cn=westcoastadmins,cn=itm,o=ibm from viewing attribute group data and events
for the Primary:server1:NT managed system. In this scenario, Primary:server1:NT
is a member of the West_Coast_DataCenter_Systems managed system group that
the user group was granted permission to view in the previous example.
tivcmd exclude --rolename "West Coast Administrators" --resourcetype
managedsystem --resources Primary:server1:NT
This example assumes you want to remove the grant permissions to view attribute
group data and events for managed system group West_Coast_DataCenter_Systems
and the exclude permission for the Primary:server1:NT managed system from the
West Coast Administrators role but leave the grant permissions for the
West_Coast_Regional_Systems managed system group.
tivcmd revoke --rolename "West Coast Administrators" --resourcetype
managedsystemgroup --resources "West_Coast_DataCenter_Systems"
--objecttype attributegroup --operations view --grantcommand
In this example, you are an IBM Tivoli Monitoring administrator who wants to
control dashboard access to the managed systems belonging to three geographic
regions: Eastern, Central, and Western. The monitoring server has managed system
group definitions for EasternRegionSystems, CentralRegionSystems, and
WesternRegionSystems, which contain managed systems for the respective
geographic regions. You want access to the managed systems in all three regions,
but want the operator named Annette to only have access to Western region
systems. This example assumes the local LDAP user registry includes user groups
Procedure
v Using Manage Tivoli Enterprise Monitoring Services
1. Start Manage Tivoli Enterprise Monitoring Services on the computer where
the portal server is installed:
Click Start → Programs →IBM Tivoli Monitoring → Manage Tivoli
Enterprise Monitoring Services.
Where install_dir is the IBM Tivoli Monitoring
installation directory, change to the install_dir/bin directory and run
./itmcmd manage [-h install_dir].
2. Right-click Tivoli Enterprise Portal Server:
Click Reconfigure, and click OK to accept the existing
configuration and go to the second TEP Server Configuration window.
Results
After you have recycled the Tivoli Enterprise Portal Server with the Enable
authorization policies box checked, the dashboard data provider will start making
authorization calls against its local policy store to allow or exclude managed
system group and managed system access for dashboard users.
The audit messages use the IBM Tivoli Monitoring audit record format and are
written to audit log files on the computer where the Authorization Policy Server is
installed. The default location is <JazzSM_install_dir>/AuthPolicyServer/
PolicyServer/audit. During installation of the Authorization Policy Server, you
can customize the location of the audit log file directory, the maximum size of the
audit log files, and the maximum number of audit log files to keep at one time.
For more details on auditing, including how to view audit messages for the portal
server and the audit record format, see Chapter 9, “Audit logging,” on page 245.
You use the WebSphere Application Server administrator console of the Dashboard
Application Services Hub where the Authorization Policy Server is installed to
change the configuration properties of the policy server. After any change is made,
you must restart the WebSphere Application Server for Dashboard Application
Services Hub to pick up the property changes.
Procedure
1. Log in to the WebSphere Administrative Console of the Dashboard Application
Services Hub where the Authorization Policy Server is installed.
a. In a browser, open the Dashboard Application Services Hub console. By
default, the URL is https://hostname:16311/ibm/console.
If your environment was configured with a port number other than the
default, enter that number instead. The default path to the server is
/ibm/console. However, this path is configurable, and might differ from the
default in your environment.
b. Enter a user name and password and click Go. The user name must be
assigned to the Dashboard Application Services Hub administrator and
iscadmins roles.
c. Click the Console Settings icon and select WebSphere Administrative
Console.
d. Click Launch WebSphere administrative console.
2. Navigate to the page that contains the configuration properties for audit
logging and policy distribution.
a. Click Resources → Resource Environment → Resource Environment entries.
b. On the page that opens, click the AuthzResourceReference link.
c. On the page that opens, under Additional Properties, click Custom
properties.
d. A table is displayed with the following properties:
AUDIT_COUNT
The maximum number of audit log files to keep at one time.
Default value is 5. Range is greater than 1 and less than 99999.
AUDIT_FILE_SIZE
The maximum size of each log file in megabytes.
AUDIT_ROOT_DIRECTORY
The directory into which the audit log files are stored.
Default value is <JAZZSM_INSTALL_DIR>\AuthPolicyServer\
PolicyServer\audit
If you modify this value to point to a different directory, you must
ensure that the directory exists and has the same permissions as the
<JAZZSM_INSTALL_DIR>\AuthPolicyServer\PolicyServer\xacml
directory.
DIST_POLL_INTERVAL
This property specifies how often the Authorization Policy Server
updates the compressed file containing the authorization policies
that is downloaded by the dashboard data provider.
Default value is 5. Range is 1 - 1440 minutes.
DIST_ROOT_DIRECTORY
The directory into which the version of the policies for distribution
is stored.
Default value is <JAZZSM_INSTALL_DIR>\AuthPolicyServer\
PolicyServer\dist
An authorization policy that is created without specifying a domain name (or with
a domain name of 'any') is applied across all IBM Tivoli Monitoring domains that
are being managed by the Authorization Policy Server. Domain names are the
same as the dashboard data provider ID and are in the format
itm.hub_monitoring_server_name. You can create a more user-friendly string to use
in place of the hub monitoring server name when you configure the portal server
and enable the dashboard data provider.
To list your domains use the tivcmd listdomains command. For example:
tivcmd listdomains
itm.HUB_DOMAIN1
itm.HUB_DOMAIN2
itm.HUB_DOMAIN3
The tivcmd listdomains command returns the list of dashboard data providers for
which a connection is defined in the Dashboard Application Services Hub that the
Authorization Policy Server is installed with. The command also returns any
domain names that were specified when creating a permission. Typically, there is a
single dashboard data provider connection defined per Dashboard Application
Services Hub.
To determine the hub names for each of your domains, use one of the following
methods:
v Run the tacmd listsystems command against each hub monitoring server to
determine the hub monitoring server's managed system name. Monitoring
servers use the EM product code.
Once you know your the name of the hub monitoring server then your domain
name is itm.hub_monitoring_server_name, for example itm.HUB_server1.
Deployment scenarios
The deployment scenarios in this topic can help you make decisions in your
environment.
This deployment scenario is useful if you want to share the same authorization
policy administration infrastructure for a set of domains. It allows you to create a
set of common authorization policies for all domains as well as policies that are
specific to one or more domains. When you grant or exclude a permission for a
role, you specify whether the policy applies to all domains or a specific domain. If
you do not specify a domain name with the tivcmd grant, tivcmd exclude, or
tivcmd revoke commands, then the policy applies to all domains. To create a
domain specific policy use the --domain argument with these commands. For more
information about the tivcmd CLI commands, see the IBM Tivoli Monitoring
Command Reference.
Preparation for deployment
The following table describes what you need for this deployment:
Table 23. Multiple domains with shared roles and policies deployment requirements
Quantity Component Description
1 per domain Dashboard Application Services Dashboard applications such as
Note: If load Hub Infrastructure Management
balancing is used, Dashboards for Servers are also
there can be installed with each domain's
multiple dashboard services hub.
dashboard
services hubs per
domain.
1 Tivoli Authorization Policy The Authorization Policy Server can
Server either be installed with Dashboard
Application Services Hub for one of
your domains or you can install an
instance of Dashboard Application
Services Hub that is just used for
authorization policy administration
and that does not have any
dashboard applications installed.
In this scenario, do not use the --domain argument because each Authorization
Policy Server is only managing policies for a single domain.
Any policies that are used for specific IBM Tivoli Monitoring domains must have
the following permission:
This example demonstrates how to grant a user access to all the UNIX OS agents
from one particular domain but not those of another domain. The *ALL_UNIX
managed system group is an created automatically and managed by each hub
monitoring server. In addition, an administrator is granted access to all UNIX OS
systems across all domains.
When a user in the EastCoastOperators group accesses the Server Dashboards page
in the Dashboard Application Services Hub for the itm.eastcoast domain, they see
the *ALL_UNIX managed system group and its members for this domain. If the
same user logs into the Dashboard Application Services Hub for the itm.westcoast
domain, they will not see the *ALL_UNIX managed system group.
If you have the same managed system group names in multiple domains and you
want dashboard users to view data from those managed system groups for all
domains, create a role and grant permissions as shown in the example commands
below:
tivcmd createrole --rolename WindowsDataCenterOperators
Because the --domain argument is not specified on the grant command example
above, the authorization policy applies to all domains. As a result, any user or user
If you do not have the same managed system group names in multiple domains,
but you have users or user groups that perform the same role for multiple
domains, you can create a common role with domain-specific permissions as
shown in the example commands below:
tivcmd createrole --rolename LinuxRegionalOperators
In this case, any user or user group assigned to the LinuxRegionalOperators role
can view data from the managed system group SeattleServers when they are
logged into the Dashboard Application Services Hub for the itm.HUB_west domain
and can view the data from the managed system group BostonServers when they
are logged into the Dashboard Application Services Hub for the itm.HUB_east
domain.
Note: By default, both protocols are used. However, you can configure a portal
client to use just HTTPS to communicate with the portal server.
Note: Requesting new certificates is best practice, but you can also use the
self-signed certificates shipped with the product in a test environment to become
familiar with the procedures for setting up secure communications.
IBM Tivoli Monitoring provides two applications that are used to work with keys
and certificate stores when setting up secure communications:
v The Global Security Toolkit (GSKit) program is installed with IBM Tivoli
Monitoring components on distributed platforms. It includes the iKeyman utility
and a command-line interface for working with certificates and keys.
v The Tivoli Enterprise Portal Server extended services (TEPS/e) administration
console (also called ISCLite) is used with the portal server to secure
communications for the services running in TEPS/e.
A default self-signed certificate and key are provided when you install IBM Tivoli
Monitoring. If you prefer to use a certificate authority signed certificate, use the
GSKit utilities to create a certificate request, and then create a key database and
import the certificates. A stash file provides the key database password for
unattended operation. When GSKit is installed with an IBM Tivoli Monitoring
component, the key file names are specified using the following environment
variables:
v KDEBE_KEYRING_FILE=C:\IBM\ITM\keyfiles\keyfile.kdb
v KDEBE_KEYRING_STASH=C:\IBM\ITM\keyfiles\keyfile.sth
v KDEBE_KEY_LABEL=IBM_Tivoli_Monitoring_Certificate
If the keyring file, stash file, or label used for the new certificate in the key store is
changed, you must complete the following steps:
1. Update all configuration files with the respective environment variable. For
example, with the environment variable
KDEBE_KEY_LABEL=Custom_Certificate_Label_Name, you would update the
following files:
On Linux and UNIX, update the agent configuration files (.ini) files directly.
On Windows, update the variables using Manage Tivoli Enterprise Monitoring
Services or update the agent environment files (*ENV) files directly.
2. Update the Tivoli Enterprise Monitoring Server
ms_<hub_monitoring_server>.config file with the same variables but with the
values in single quotes ('). For example,
KDEBE_KEY_LABEL=’Custom_Certificate_Label_Name’.
3. Restart each component.
Work with the administrators of the other products that IBM Tivoli Monitoring
communicates with to setup secure communications. If you are using any of the
Jazz for Service Management components (Dashboard Application Services Hub,
Registry Services, or Security Services) with IBM Tivoli Monitoring, use the
WebSphere Application Server administration console to work with their trust and
certificate stores.
The following table lists the communication flows that can be secured and where
to find information on how to secure the interaction.
After setting up the LDAP server for TLS/SSL and obtaining its public signer
certificate, use the hub monitoring server's GSKit iKeyman utility or command line
interface to set up a new key database of type CMS and a stash file containing the
password for the key database. Then import the LDAP server's public signer
certificate into the new key database and specify a label name for the certificate.
See “Using the GSKit command-line interface to work with key databases and
certificates” on page 239 and “Using the GSKit iKeyman utility to work with key
databases and certificates” on page 240 for information on using GSKit.
Note:
The Dashboard Application Services Hub communicates with the IBM Tivoli
Monitoring dashboard data provider using either Hypertext Transfer Protocol
(HTTP) or Hypertext Transfer Protocol Secure (HTTPS). HTTPS is intended to run
on top of Transport Layer Security (TLS) or its predecessor Secure Sockets Layer
(SSL). These layers provide encryption using key exchanges.
Roadmap
In order to use HTTPS and its security encryption features, complete the following
tasks in the roadmap.
Table 25. Roadmap for setting up TLS/SSL for the dashboard data provider
Step Description and information provided
1 You have two options for obtaining the public-private key pair used by the portal
server:
v Use the default self-signed certificates installed with IBM Tivoli Monitoring. If
you choose this option, proceed to step 2.
OR
v Use a digital certificate that has been signed by a certificate authority. In this
case, you must create a certificate request and send it to the certificate authority
for signing. Once the digital certificate has been signed, you add the certificate
authority signer's certificate to the portal server's trust stores, and then add the
new digital signature to the portal server's key stores. For more information, see
“Using third party certificate authority signed certificates for the portal server.”
2 At each Dashboard Application Services Hub with a connection configured to the
portal server's dashboard data provider, add the public signer certificate used by
the portal server to the Dashboard Application Services Hub WebSphere trust
store. Follow the steps in “Configuring TLS/SSL communication for the
Dashboard Application Services Hub server” on page 213.
Ensure the TEPS/e administration console is enabled. For detailed steps, including
information on how to log on, see “Starting the TEPS/e administration console” on
page 114.
Procedure
1. Use either the TEPS/e administration console or the GSKit command-line
interface to create a private certificate request to be signed by the certificate
authority. The following instructions explain how to perform this step using the
TEPS/e administration console.
a. Log on to the TEPS/e administration console.
b. Select Security → SSL certificate and key management.
c. In the Related Items area, click the Key stores and certificates link and in
the table click the NodeDefaultKeyStore link.
d. In the Additional Properties area, click the Personal certificate requests link
and in the page that is displayed, click New.
e. In the page that is displayed specify the following information:
v Set File name to the location to store the private certificate request. For
example, C:\dashboardcerts\TEPSCertRequest.arm.
v Set the Key label to the desired label for the certificate. For example, TEPS
Certificate.
v Set the Key size to 2048.
v Leave the Signature algorithm as SHA1withRSA.
v Set the Common name to a unique name for the TEPS/e computer.
Typically, this is a hostname.
v Set Organization to a meaningful value. Typically, this is a company
name.
v Set Organization unit to a meaningful name. For example, TEPS.
v Set Country or region to desired value. For example, US.
f. Click OK, then Save.
2. Send the certificate request generated above to the certificate authority to
request a new digital certificate. The certificate authority can take two to three
weeks to generate the new digital certificate.
3. After the certificate authority returns your new digital certificate, save it to a
location on the computer where the portal server and TEPS/e are installed. For
example, C:\dashboardcerts\TEPSSignedCert.arm.
4. Use the GSKit command-line interface to create a new key database of type CMS
and save the key database's password to a stash file. Then import the certificate
authority's signer certificate and the new digital certificate into the new key
database. This key database is used by the portal server's embedded HTTP
server.
5. You must also add the certificate authority public signer certificate into the
TEPS/e trust store using the TEPS/e administration console.
a. Log on to the TEPS/e administration console.
b. Select Security → SSL certificate and key management.
c. In the Related Items area, click the Key stores and certificates link and in
the table click the NodeDefaultTrustStore link.
Note: If you requested a new digital certificate for the portal server, wait until the
certificate has been received before performing this procedure.
Procedure
1. Log into the Dashboard Application Services Hub WebSphere Administrative
Console.
Results
The certificates are now setup for communication between the Dashboard
Application Services Hub server and to the portal server and its dashboard data
provider.
There are two IBM Tivoli Monitoring components which communicate with the
Authorization Policy Server using either Hypertext Transfer Protocol (HTTP) or
Hypertext Transfer Protocol Secure (HTTPS):
v The tivcmd Command-Line Interface for Authorization Policy sends
HTTP/HTTPS requests to the Authorization Policy Server to process CLI
commands.
v The Tivoli Enterprise Portal Server sends HTTP/HTTPS requests to the
Authorization Policy Server to obtain the latest policy store.
HTTPS is intended to run on top of Transport Layer Security (TLS) or its
predecessor Secure Sockets Layer (SSL). These layers provide encryption using key
exchanges.
In order to use HTTPS and its security encryption features, complete the following
tasks in the roadmap.
Note: The following instructions assume that the portal server and the tivcmd CLI
send requests directly to the IBM Dashboard Application Services Hub application
server, and not to a HTTP server that might be used in conjunction with the
dashboard hub. If you are using a HTTP server with IBM Dashboard Application
Services Hub, then you must also update the certificates that the HTTP server uses.
Table 26. Roadmap for setting up TLS/SSL for the Authorization Policy Server
Step Description and information provided
1 Using the WebSphere Application Server administrative console for the Dashboard
Application Services Hub where the Authorization Policy Server is installed, you
can choose one of the following options to obtain a public-private key pair:
v “Using the WebSphere generated certificates to configure TLS/SSL for the
Authorization Policy Server”
During installation, the WebSphere Application Server generates a public signer
certificate and a default private signed certificate. These certificates can be used
if desired.
v “Using third party certificates to configure TLS/SSL for the Authorization
Policy Server” on page 216
Add the third party's signer certificate to the WebSphere Application Server
trust store. A certificate request is created at the WebSphere Application Server
and forwarded to the certificate authority for signing. Once signed, it is added
to the WebSphere Application Server key store. The private signed certificate
must be set as the default certificate.
2 At each tivcmd Command-Line Interface for Authorization Policy installation:
1. Create a new clean key database.
2. Add the public signer certificate used by the Authorization Policy Server to the
new key database.
3. Set an environment variable to enable validation of the server certificate. By
default, HTTPS used between the tivcmd CLI and the Authorization Policy
Server does not exchange certificates or use security encryption. This
environment variable must be set to make this happen.
Follow the steps in “Configuring the tivcmd CLI for TLS/SSL” on page 218.
3 At each portal server configured to communicate with the Authorization Policy
Server, add the public signer certificate used by the Authorization Policy Server to
the TEPS/e trust store. Follow the steps in “Configuring TLS/SSL communication
between the portal server and the Authorization Policy Server” on page 220.
4 Use the -s argument for the tivcmd login command to indicate that the HTTPS
protocol is used when sending requests to the Authorization Policy Server.
Procedure
1. Log into the WebSphere Administrative Console for the Authorization Policy
Server and Dashboard Application Services Hub.
a. Enter the following URL in your Internet Explorer or Firefox browser:
https://hostname:16311/ibm/console.
If your environment was configured with a port number other than the
default, enter that number instead. The default path to the server is
/ibm/console. However, this path is configurable, and might differ from the
default in your environment.
b. Enter the Dashboard Application Services Hub administrative user ID and
password then click Go.
The user ID must be assigned the administrator and iscadmins roles.
c. In the Console Settings area click on WebSphere Administrative Console
and then click the Launch WebSphere administrative console button.
2. Select Security → SSL certificate and key management.
3. In the Related Items area, click the Key stores and certificates link and in the
table click the NodeDefaultTrustStore link.
4. In the Additional Properties area, click the Signer certificates link and in the
table that is displayed, select the root entry check box.
5. Click Extract and in the page that is displayed, in the File name field, enter a
certificate file name. For example, C:\policyauthcerts\
PolicyAuthServerSignerCert.arm.
6. From the Data type list select the Base64-encoded ASCII data option and click
OK.
What to do next
The extracted public signer certificate can now be distributed to the portal server
and tivcmd Command-Line Interface for Authorization Policy computers for
importing.
Procedure
v Add the certificate authority public signer certificate to the WebSphere
Application Server trust store.
1. Select Security → SSL certificate and key management.
2. In the Related Items area, click the Key stores and certificates link and in the
table click the NodeDefaultTrustStore link.
3. In the Additional Properties area, click the Signer certificates link and in the
page that is displayed, click Add.
4. In the page that is displayed specify the following information:
– Set Alias to the desired label for the certificate. For example,
Authorization Policy Server Signer Certificate.
– Set File name to the location of the certificate authority signer certificate.
For example, C:\policyauthcerts\CASignerCert.arm.
– Leave the Data type as Base64-encoded ASCII data.
5. Click OK, then Save.
The certificate authority public signer certificate can now be distributed to the
portal server and tivcmd CLI computers for importing.
v Create a private certificate request to be signed by the certificate authority.
1. Select Security → SSL certificate and key management.
2. In the Related Items area, click the Key stores and certificates link and in the
table click the NodeDefaultKeyStore link.
3. In the Additional Properties area, click the Personal certificate requests link
and in the page that is displayed, click New.
4. In the page that is displayed specify the following information:
– Set File name to the location to store the private certificate request. For
example, C:\policyauthcerts\PolicyAuthServerCertRequest.arm.
– Set the Key label to the desired label for the certificate. For example,
Authorization Policy Server Certificate.
– Leave the Signature algorithm as SHA1withRSA.
– Set the Key size to 2048.
– Set the Common name to a unique name for the Authorization Policy
Server. Typically, this is a computer name.
– Set Organization to a meaningful value. Typically, this is a company
name.
– Set Organization unit to a meaningful name. For example, PolicyAuth.
– Set Country or region to desired value. For example, US.
5. Click OK, then Save.
Send the certificate request generated above to the certificate authority to request
a new digital certificate. The certificate authority can take two to three weeks to
generate the new digital certificate.
After the certificate authority returns your new digital certificate, save it to a
location on the Authorization Policy Server computer. For example,
C:\policyauthcerts\PolicyAuthServerSignedCert.arm.
Note: If you requested a digital certificate for the Authorization Policy Server, wait
until the certificate has been received before performing this procedure.
The following instructions for managing certificates on the tivcmd CLI computers
use the GSKit command line tool that is installed with the tivcmd CLI component.
These instructions should be followed on each computer that the tivcmd CLI is
installed on.
See “Using the GSKit command-line interface to work with key databases and
certificates” on page 239 for terms that are used in this procedure. Most terms are
based upon the directory to which the tivcmd CLI is installed.
Procedure
1. Set the path to invoke the GSKit command line tool using the following
commands:
If the database is not empty, use the delete command to remove any
remaining certificates.
4. Add the public signer certificate to the new tivcmd CLI key database.
This step assumes that the public signer certificate has been placed in a location
on the tivcmd CLI computer. For example, C:\policyauthcerts\
PolicyAuthSignerCert.arm or C:\policyauthcerts\CASignerCert.arm. This
location is referenced in this step as <policyauthsignercert>.
Add the public signer certificate to the new tivcmd CLI key database using the
following command:
<gskittoolcmd> -cert -add -db <newkeydb> -pw <newkeydbpw>
-label "Authorization Policy Signer Certificate" -trust enable
-format ascii -file <policyauthsignercert> -fips
5. Enable TLS/SSL certificate exchange at each tivcmd CLI computer.
At each tivcmd CLI computer, use the following steps to enable TLS/SSL
certificate exchange using the public signed certificate.
a. Delete the current key database. Remove the <oldkeydbname>.* files in the
<keydbdir> directory.
b. Rename all new key database files. For example, <newkeydbname>.* to
<oldkeydbname>.* in the <keydbdir> directory.
c. Set the environment variable to enable authentication of the Authorization
Policy Server certificate.
Note: If you requested a new digital certificate for Authorization Policy Server,
wait until the certificate has been received before performing this procedure.
This step assumes that the public signer certificate is located on the portal server
computer. For example, C:\policyauthcerts\PolicyAuthSignerCert.arm or
C:\policyauthcerts\CASignerCert.arm. This location is referenced in this
procedure as <policyauthsignercert>.
Procedure
1. Log on to the TEPS/e administration console.
2. Select Security → SSL certificate and key management.
3. In the Related Items area, click the Key stores and certificates link and in the
table click the NodeDefaultTrustStore link.
4. In the Additional Properties area, click the Signer certificates link and in the
page that is displayed, click Add.
5. In the page that is displayed specify the following information:
v Set Alias to the desired label for the certificate. For example, Authorization
Policy Server Signer Certificate.
v Set File name to the location of the public signer certificate. For example,
<policyauthsignercert>.
v Leave the Data type as Base64-encoded ASCII data.
6. Click OK, then Save.
7. Reconfigure the portal server to use HTTPS instead of HTTP for the
Authorization Policy Server connection. For details on reconfiguring the
Authorization Policy Server connection parameters, see “Enabling authorization
policies in the portal server” on page 192.
Results
HTTPS is now used between the Authorization Policy Server and the portal server.
Roadmap
On the computer system where the portal server is installed, extract the portal
server's HTTP server certificate from the keyfile.kdb file.
Procedure
1. Start the key management utility (iKeyman) using one of these methods:
v Click Start > Programs > IBM HTTP Server V8.0 for Tivoli
Enterprise Portal Server > Start Key Management Utility.
v From the command-line run <install_dir>/<interp>/
iu/ihs/HTTPServer/bin/ikeyman or change to the <install_dir>/<interp>/
iu/ihs/HTTPServer/bin directory and type ikeyman. If you start IKEYMAN to
create a new key database file, the utility stores the file in the directory
where you start IKEYMAN.
2. Navigate to the following directory and select the keyfile.kdb to open the file.
install_dir\keyfiles\
install_dir/keyfiles
3. Enter the password to open the file. The default password is IBM61TIV.
4. From the Key database content drop down list, select Signer Certificates.
5. Select the trusted root certificate used to sign the IBM HTTP server SSL
certificate. By default it is the root certificate. If you requested a new signer
certificate from a certificate authority then it is the name that you specified
when you added the signer certificate to the key database.
Tip: If you are not sure which signer certificate is the trusted root certificate,
select a certificate and click View / Edit. In the Key information dialog
window, check if the Set the certificate as trusted root option is selected.
6. Click Extract.
7. Leave the Data Type as Base64-encoded ASCII data and then save the
certificate as hostnameITMcert.arm.
8. Click OK to export the certificate to the file name and directory specified in the
previous steps.
Copy the public signer certificate for each portal server's local HTTP server to the
computer system where the load balancing HTTP Server is installed.
Alternatively, you can use the gskcmd command-line interface to complete this
task. For detailed information on using the gskcmd command-line interface, see
“Managing keys with the gskcmd command line interface (Distributed systems)” in
the WebSphere Application Server Information Center.
Note: The plugin-key.kdb file is the one that you saved in step 7.
Roadmap
In order to use HTTPS and its security encryption features, complete the following
tasks in the roadmap.
Table 28. Roadmap to configure TLS/SSL communication between Dashboard Application
Services Hub and a HTTP server used for load balancing multiple Tivoli Enterprise Portal
Server
Step Description Where to find information
1 Determine if you want to use the If you do not want to use a self-signed
self-signed certificate that came with the certificate, see your HTTP server
HTTP server or request a certificate that documentation to determine how to
is signed by a certificate authority. request a certificate.
Alternatively, you can use the gskcmd command-line interface to complete this
task. For detailed information on using the gskcmd command-line interface, see
“Managing keys with the gskcmd command line interface (Distributed systems)” in
the WebSphere Application Server Information Center.
Procedure
1. On the computer system where the load balancing IBM HTTP Server is
installed, export the public signer certificate from the key database using the
iKeyman graphical interface.
Start the key management utility (iKeyman) using one of these methods:
v Click Start > Programs > IBM HTTP Server V8.5 > Start Key
Management Utility.
v From the command-line run <install_dir>/bin/
ikeyman or change to the <install_dir>/bin directory and type ikeyman,
where <install_dir> is the directory where the WebSphere Plugin is
installed (such as /opt/IBM/WebSphere/Plugins). If you start IKEYMAN to
create a new key database file, the utility stores the file in the directory
where you start IKEYMAN.
2. Click Key Database File from the main UI, then click Open.
3. Specify the location of the CMS key database file plugin-key.kdb that is
specified in the HTTP server plugin-cfg.xml file.
By default the file is plugin-key.kdb.
When using HTTP server V8.5, the following default locations apply:
C:\Program Files\IBM\WebSphere\Plugins_1\config\webserver1
/opt/IBM/Websphere/Plugins/config/webserver1
4. Provide the password for the key database and click OK. The default password
is WebAS.
5. From the Key database content drop down list, select Signer Certificates.
6. Select the trusted root certificate used to sign the IBM HTTP server SSL
certificate.
Tip: If you are not sure which signer certificate is the trusted root certificate,
select a certificate and click View / Edit. In the Key information dialog
window, check if the Set the certificate as trusted root option is selected.
7. Click Extract.
8. In the Extract Certificate to a File dialog box, set the following fields:
Data type: Base64-encoded ASCII data.
Certificate file name: Accept the default of cert.arm or specify a different
name.
Location: Type the drive and directory where you want to store the file or
use Browse to select a drive and directory.
9. Click OK to export the public signer certificate to the file name and directory
specified above.
Copy the public signer certificate that was exported from the load balancing HTTP
server to the computer system where Dashboard Application Services Hub is
installed.
Procedure
1. Log into the Dashboard Application Services Hub WebSphere Administrative
Console.
a. Enter the following URL in your Internet Explorer or Firefox browser:
https://hostname:16311/ibm/console.
If your environment was configured with a port number other than the
default, enter that number instead. The default path to the server is
/ibm/console. However, this path is configurable, and might differ from the
default in your environment.
b. Enter the Dashboard Application Services Hub administrative user ID and
password then click Go.
The user ID must be assigned the administrator and iscadmins roles.
c. In the Console Settings area click on WebSphere Administrative Console
and then click the Launch WebSphere administrative console button.
2. Select Security → SSL certificate and key management.
3. In the Related Items area, click the Key stores and certificates link and in the
table click the NodeDefaultTrustStore link.
4. In the Additional Properties area, click the Signer certificates link and in the
page that is displayed, click Add.
5. Enter a unique alias name. For example, TEPS_LOAD_BALANCE_SERVER.
6. Enter the file location of the HTTP server public signer certificate.
7. Ensure the Data type selection matches the format of the certificate that you
exported from the HTTP server.
8. Click OK, then Save.
Results
The certificates are now setup for communication between the Dashboard
Application Services Hub server and HTTP server used to load balance multiple
portal servers.
Procedure
Note:
If you are using Jazz for Service Management with IBM Tivoli Monitoring, see the
Jazz for Service Management Installation Guide in the Jazz for Service Management
Information Center (http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/
com.ibm.psc.doc_1.1.0/psc_ic-homepage.html) for information on how to enable
FIPS for its components.
KDEBE_FIPS_MODE_ENABLED=YES
2. Restart the automation server to implement your changes.
Note: You can use the following instructions to also configure the Warehouse
Proxy Agent and the Summarization and Pruning Agent.
1. Edit the following environment files:
Edit the KBBENV file and the KXXENV file for each monitoring agent
(where XX is your 2 letter product code).
Edit the ms.ini on the monitoring server, and *.ini for
each monitoring agent.
Change or add the following environment variable:
KDEBE_FIPS_MODE_ENABLED=YES
If using autonomous agents, you must add the KDEBE_FIPS_MODE_ENABLED
variable to your custom environment file.
For the Linux and UNIX OS agents, the KDEBE_FIPS_MODE_ENABLED variable has
additional possible values. For more information, see the IBM Tivoli Monitoring
Linux OS Agent Installation and Configuration Guide and IBM Tivoli Monitoring
UNIX OS Agent Installation and Configuration Guide.
2. Restart the monitoring server and each monitoring agent you edited to
implement your changes.
KDEBE_FIPS_MODE_ENABLED=YES
KFW_FIPS_ENFORCED=YES
2. Restart the portal server to implement your changes.
3. Enable the TEPS/e administration console. For more information, see “Starting
the TEPS/e administration console” on page 114.
4. Enable FIPS 140-2 mode by following the directions in the “Configuring
WebSphere Application Server for SP800-131 standard strict mode” topic in the
WebSphere Application Server V8.5 Information Center http://
pic.dhe.ibm.com/infocenter/wasinfo/v8r5/index.jsp.
TEPS_FIPS_MODE=YES
KDEBE_FIPS_MODE_ENABLED=YES
export TEPS_FIPS_MODE=YES
export KDEBE_FIPS_MODE_ENABLED=YES
KDEBE_FIPS_MODE_ENABLED=YES
export KDEBE_FIPS_MODE_ENABLED=YES
Results
What to do next
When in FIPS 140-2 mode, Tivoli Management Services components and Tivoli
Enterprise Monitoring Agents use one or more of these FIPS 140-2 approved
cryptographic providers: IBMJCEFIPS (certificate 497), IBMJSSEFIPS (certificate
409), and IBM Crypto for C (ICC (certificate 775) for cryptography. The certificates
are listed on the NIST website at http://csrc.nist.gov/groups/STM/cmvp/
documents/140-1/140val-all.htm.
http://www-01.ibm.com/software/sysmgmt/products/support/
IBMTivoliMonitoring.html
Search IBM Tivoli Monitoring Support for guidelines on configuring components
for FIPS 140-2 compliance.
http://csrc.nist.gov/
The Computer Security Division of the National Institute of Standards and
Technology has publications on FIPS 140-2 compliance.
SP800-131a mode for IBM Tivoli Monitoring has the following properties:
Note: In IBM Tivoli Monitoring Version 6.3 Fix Pack 2, the generated self-signed
certificates comply to the standards mentioned in this section by default.
v All communication is over TLSv1.2 protocol.
v All certificates for communication are RSA with 2048 bit keys signed, with at
least SHA-256 bit digital signatures or Elliptic curve cryptography certificates.
Use all RSA certificates or all Elliptic curve certificates.
v Any SNMP connections must conform to either SNMP V1, V2 or V3 using
authentication with SHA-1 only.
Note: SNMP V3 data privacy is not SP800-131 compliant.
v SSH connections must use certificates that are 2048-bit in size.
v Elliptic Curve Certificates can be used by any IBM Tivoli Monitoring component,
but using an Elliptic Curve Certificate implies the exclusive acceptance of only
TLSv1.2 for communication, because TLSv1.2 is the only protocol that supports
Elliptic Curve Certificates. Using Elliptic Curve Certificates at the monitoring
server allows only monitoring agents at IBM Tivoli Monitoring Version 6.3 Fix
Pack 2 or higher to connect.
v All services and autonomous agents that interface using HTTPS and IP.SPIPE
communication ports, must use the TLSv1.2 protocol. The Microsoft Internet
Explorer 8.0 or higher browser supports TLSv1.2.
v Many application agents are 32-bit agents installed on a 64-bit operating system.
32-bit application agents must be upgraded using the tacmd updateFramework
command to update their framework to Version 6.3 or higher. Updating the
framework allows the agent to communicate with an SP800-131a compliant
Tivoli Enterprise Monitoring Server. For more information on the tacmd
updateFramework command, see the IBM Tivoli Monitoring Command Reference.
v You can optionally enable TLSv1.0 in the Tivoli Enterprise Portal Server to access
the online help. If TLSv1.0 is disabled in the IBM HTTP Server, the Tivoli
Enterprise Portal functions as normal but will not provide online help. All data
and management is performed over TLSv1.2. Online help and other text content
is transmitted over TLSv1.0. You can disable TLSv1.0 if you do not need the
online help and dialog help. If TLSv1.0 is disabled, the error Secure Connection
Failed: ssl_error_no_cypher_overlap might appear in certain workspaces that
display help information. You can continue to create objects and access
workspaces over TLSv1.2.
v When the monitoring server is configured in SP800-131a mode, IBM Tivoli
Monitoring Version 6.3 Fix Pack 2 monitoring agents, the portal server, and the
tacmd command line can still communicate with the monitoring server without
being explicitly reconfigured in SP800-131a mode.
v The tacmd tepslogin and other tacmd commands directed at the portal server
must communicate over TLSv1.0 on port 15001. Additionally, tacmd commands
directed at the monitoring server must communicate over TLSv1.2 with SP800
restrictions. Ensure that you enable TLS/SSL communication for the portal client
connections at the portal server.
v Situations that use the Linux OS agent and UNIX OS agent File Information
attribute group must ensure they are using SHA-1, SHA-256, SHA-384, or
SHA-512 in SP800-131a mode.
Note:
Note: You can use the following instructions to also configure the Warehouse
Proxy Agent and the Summarization and Pruning Agent.
1. Edit the following environment files:
In the Manage Tivoli Enterprise Monitoring Services window,
right-click the component and click Advanced → Edit Variables. Alternatively,
you can edit the KBBENV file and the KXXENV file for each monitoring agent
(where XX is your 2 letter product code) directly.
Edit the ms.ini on the monitoring server, and *.ini for
each monitoring agent.
Change or add the following environment variable:
KDEBE_FIPS_MODE_ENABLED=SP800-131a
If using autonomous agents, you must add the KDEBE_FIPS_MODE_ENABLED
variable to your custom environment file.
2. Restart the monitoring server and each monitoring agent you edited to
implement your changes.
KDEBE_FIPS_MODE_ENABLED=SP800-131a
KFW_FIPS_ENFORCED=YES
3. Restart the portal server to implement your changes.
4. Enable SP800-131 Transistion mode in the TEPS/e administration console.
a. Follow the instructions in “Starting the TEPS/e administration console” on
page 114.
b. Click Security → SSL certificate and key management → Manage FIPS.
c. If you have not imported compliant certificates, select Convert Certificates.
When converting the certificates, select Algorithm Strict and then select
SHA256WithRSA or another algorithm. If you select an ECDSA Certificate
algorithm, then all browsers and clients (including the Dashboard
Application Services Hub servers) connecting to the WebSphere Server must
support TLSv1.2 and Elliptic Curve Certificates.
You must accept the new certificate using the WebSphere command line
utilities. Run one of the following commands, and then when prompted,
accept the certificate:
updateTEPSEPass.bat wasadmin <password>
updateTEPSEPass.sh wasadmin <password>
d. Select Enable SP800-131 , Transistion, and Update SSL configurations to
require TLSv1.2.
Note: Once you apply and then save your changes to the master file for
WebSphere, you might need to reconnect to the WebSphere console if you
are logged out, since the new certificate and algorithms take effect
immediately.
e. Update the ssl.client.props file to allow administration of WebSphere.
install_dir\CNPSJ\profiles\ITMProfile\properties\
ssl.client.props
install_dir/arch/iw/profiles/ITMProfile/
properties/ssl.client.props
Once the server is configured for SP800-131 transition mode, the
ssl.client.props file must be modified so that the administrative client can
communicate with the WebSphere server running in SP800-131 mode. They
are not able to make a TLSv1.2 connection to the server without the change.
Edit the ssl.client.props file by completing the following steps:
1) Modify com.ibm.security.useFIPS to be set to true.
2) Add com.ibm.websphere.security.FIPSLevel=SP800-131 directly beneath
the useFips property.
SSLServerCert IBM_Tivoli_Monitoring_Certificate
ErrorLog "<ITH_HOME>/IHS/logs/sslerror.log"
TransferLog "<ITM_HOME>/IHS/logs/sslaccess.log"
KeyFile "<ITM_HOME>/keyfiles/keyfile.kdb"
SSLStashfile "<ITM_HOME>/keyfiles/keyfile.sth"
</VirtualHost>
install_dir/arch/iu/ihs/HTTPServer/conf
<VirtualHost *:15201>
DocumentRoot "<ITM_HOME>/<arch>/cw/"
SSLEnable
SSLProtocolDisable SSLv2
SSLProtocolDisable SSLv3
SSLProtocolEnable TLSv10
SSLProtocolDisable TLSv11
SSLProtocolEnable TLSv12
SSLFIPSEnable
SSLAttributeSet 245 "GSK_TLS_SIGALG_RSA_WITH_SHA224,
GSK_TLS_SIGALG_RSA_WITH_SHA256,GSK_TLS_SIGALG_RSA_WITH_SHA384,
GSK_TLS_SIGALG_RSA_WITH_SHA512,GSK_TLS_SIGALG_ECDSA_WITH_SHA224,
GSK_TLS_SIGALG_ECDSA_WITH_SHA256,GSK_TLS_SIGALG_ECDSA_WITH_SHA384,
GSK_TLS_SIGALG_ECDSA_WITH_SHA512" BUFF
SSLServerCert IBM_Tivoli_Monitoring_Certificate
ErrorLog "<ITM_HOME>/<arch>/iu/ihs/HTTPServer/logs/sslerror.log"
TransferLog "<ITM_HOME>/<arch>/iu/ihs/HTTPServer/logs/sslaccess.log"
KeyFile "<ITM_HOME>/keyfiles/keyfile.kdb"
SSLStashfile "<ITM_HOME>/keyfiles/keyfile.sth"
</VirtualHost>
7. Update the HTTP plugin.
TEPS_FIPS_MODE=YES
KDEBE_FIPS_MODE_ENABLED=SP800-131a
KDEBE_FIPS_MODE_ENABLED=SP800-131a
export KDEBE_FIPS_MODE_ENABLED=SP800-131a
Results
What to do next
Application agents might initiate their own communications for data collection.
Those remote servers must be configured to be SP800-131a compliant to ensure the
agent's communication is SP800-131a compliant.
Use the following procedure to manually import the TEPS/e certificates into the
IBM Tivoli Monitoring keyfile database for the portal sever.
Procedure
1. Open a command prompt (Windows) or shell (AIX or Linux).
2. Set the JAVA_HOME variable as described in “Setting the JRE for GSKit and
starting Key Manager” on page 240, but do not start the GSKit Key Manager.
3. Go to the lib (32-bit) or lib64 (64-bit) directory under the GSKit home
directory. You can use either 32-bit of 64-bit.
install_dir/GSK8 or install_dir/GSK8_x64
install_dir\arch\gs\lib or install_dir\arch\gs\lib64
The GSKit binary is called gsk8capicmd (32-bit) or gsk8capicmd_64 (64-bit).
4. Execute the following commands:
v
..\bin\gsk8capicmd[_64] -cert -import -db ..\..\CNPSJ\profiles\
ITMProfile\config\cells\ITMCell\nodes\ITMNode\trust.p12 -pw WebAS
-type pkcs12 -label root -target ..\..\keyfiles\keyfile.kdb -target_pw
IBM61TIV -target_type cms -new_label root.ihs
..\bin\gsk8capicmd[_64] -cert -import -db ..\..\CNPSJ\profiles\
ITMProfile\config\cells\ITMCell\nodes\ITMNode\key.p12 -pw WebAS -type
pkcs12 -label default -target ..\..\keyfiles\keyfile.kdb -target_pw
IBM61TIV -target_type cms -new_label default.ihs
v
../bin/gsk8capicmd[_64] -cert -import -db ../../../arch/iw/profiles/
ITMProfile/config/cells/ITMCell/nodes/ITMNode/trust.p12 -pw WebAS
-type pkcs12 -label root -target ../../../keyfiles/keyfile.kdb
-target_pw IBM61TIV -target_type cms -new_label root.ihs
../bin/gsk8capicmd[_64] -cert -import -db ../../../arch/iw/profiles/
ITMProfile/config/cells/ITMCell/nodes/ITMNode/key.p12 -pw WebAS -type
pkcs12 -label default -target ../../../keyfiles/keyfile.kdb -target_pw
IBM61TIV -target_type cms -new_label default.ihs
The password for the source or target key store might be different if you
created your own keystores.
5. Restart the portal server.
For information about the GSKit command-line interface, see the IBM Global
Security Kit GSKCapiCmd V8.0 User's Guide.
The following table lists the terms that are used in procedures involving the GSKit.
Most terms are based upon the directory in which the IBM Tivoli Monitoring
component and GSKit are installed:
<authclidir> The directory into which the IBM Tivoli Monitoring component is
installed. For example:
v c:\IBM\ITM or /opt/IBM/ITM for the monitoring server, automation
server, portal server, tacmd CLI, and agents
v c:\IBM\TivoliMonitoring or /opt/IBM/TivoliMonitoring for the
tivcmd CLI
<interp> The machine specific interp. For example, sol296, li6263, or aix536.
<gskithome> The directory into which the GSKit is installed.
Windows 32-bit: <itmcompdir>\GSK8.
Windows 64-bit: <itmcompdir>\GSK8_64.
Linux and UNIX 32-bit: <itmcompdir>/<interp>/gs
Linux and UNIX 64-bit: <itmcompdir>/<interp>/gs
<gskittoolcmd> The actual GSKit CLI command syntax.
Windows 32-bit: <gskithome>\bin\gsk8capicmd.exe
Windows 64-bit: <gskithome>\bin\gsk8capicmd_64.exe
Linux and UNIX 32-bit: ./<gskithome>/bin/gsk8capicmd.exe
Linux and UNIX 64-bit: ./<gskithome>/bin/gsk8capicmd_64.exe
<keydbdir> The directory into which the default key database is stored.
Windows: <itmcompdir>\keyfiles
Linux and UNIX: <itmcompdir>/keyfiles
<oldkeydbname> The base name of the key database installed with the IBM Tivoli
Monitoring component. This base key database name is keyfile. The
four files associated with this key database are: keyfile.crl,
keyfile.kdb, keyfile.rdb, and keyfile.sth.
<oldkeydb> The name of the key database installed with the IBM Tivoli Monitoring
component. This key database name is <oldkeydbname>.kdb.
<oldkeydbpw> The installed key database password. The default is IBM61TIV.
<newkeydbname> The base name of the new key database. Any name other than keyfile
can be chosen. For example, itmcompkeyfile.
<newkeydb> The name of the new key database. This key database name is
<newkeydbname>.kdb.
<newkeydbpw> The password associated with the new key database. Any valid
password can be chosen.
In order to run the GSKit command line tool, the GSKit tool lib directory must be
included in the system path.
32-bit
set PATH=<gskithome>\lib;%PATH%
cd <gskithome>\bin
64-bit
set PATH=<gskithome>\lib64;%PATH%
cd <gskithome>\bin
32-bit
export LD_LIBRARY_PATH=<gskithome>/lib:$LD_LIBRARY_PATH
cd <gskithome>/bin
64-bit
export LD_LIBRARY_PATH=<gskithome>/lib64:$LD_LIBRARY_PATH
cd <gskithome>/bin
Using the GSKit iKeyman utility to work with key databases and
certificates
A default self-signed certificate and key are provided when you install IBM Tivoli
Monitoring. If you prefer to use a certificate authority signed certificate, use the
iKeyman utilities to create a certificate request and then create a key database and
import the certificates into the database.
Note: The iKeyman utility is available on the distributed computers where the
monitoring server, portal servers, portal client desktop client, and tacmd CLI are
installed.
For information about the iKeyman graphical user interface and its command-line
interface, see the IBM Developer Kit and Runtime Environment iKeyman V8.0 User's
Guide.
Otherwise, you might get an error similar to Failed to parse JAVA_HOME setting.
Procedure
v
1. From the command prompt, run this script to get the IBM Java location:
install_dir\InstallITM\GetJavaHome.bat
2. Set the JAVA_HOME variable to point to the IBM Java location.
3. Get the GSKit location by running this script:
install_dir\InstallITM\GetGSKitHome.bat
4. Execute the following command:
$JAVA_HOME\jre\bin\ikeyman.exe [properties]
Use the following steps to create a new public-private key pair and certificate
request:
Procedure
1. If you have not already done so, start iKeyman.
2. Click Key Database File → Open.
3. Select the keyfile.kdb key database and click Open.
4. Type the password for the key database and click OK.
Results
What to do next
Send the file to a CA to request a new digital certificate, or cut and paste the
request into the request forms on the CA's web site.
Procedure
1. Create a CA key database.
2. Create the self-signed certificate.
3. Export the self-signed certificate.
4. Receive the self-signed certificate into the key databases on the portal server.
What to do next
When you receive the CA-signed certificate, you must delete the self-signed
certificate.
After the CA returns your new digital certificate, save it on the computer where
the portal server is running. Repeat for the client. If the CA returns the certificate
as part of an e-mail message, copy and paste it from the e-mail into a text file.
Complete the following procedure to receive the digital certificate from the CA into
key database on each computer:
Procedure
1. If you have not already done so, start iKeyman.
2. Select Key Database File → Stash File. An information window is displayed
telling you that the password was saved to a stash file.
3. Click OK.
These auditing and logging records can be stored in the Tivoli Data Warehouse.
Standard reports are provided via the Tivoli Common Reporting feature.
The auditing facility covers the self-describing agents (including their auto-refresh
feature), actions of the Warehouse Proxy Agent, EIF-SSL connections, automated
Take Action commands, and the integration of IBM Tivoli Monitoring with Tivoli
Application Dependency Discovery Manager.
Supported platforms include Windows, Linux, UNIX, IBM i, and z/OS systems.
/QIBM/ProdData/IBM/ITM/support
Auditing events have three different trace levels: Minimum, Basic, and Detail.
Every event is assigned a trace level. You might want to increase or decrease the
trace level to collect additional data.
Minimum: Major state changes to the product
Basic: Any actions that modify objects or cause an access failure
Detail: Any action that causes a successful or failed access control
A record type is associated with each audit event to indicate the nature of the
audit record. The event record types are categorized in the following table:
For detailed XML syntax information, see the SAPMAudit.dtd on the IBM Tivoli
Monitoring Tools DVD.
Note:
v Some cells are intentionally blank to represent the audit log XML structure.
Empty ITM Audit attribute cells indicate that a coordinating attribute has not
been created yet for the coordinating XML element.
v XML elements and XML attributes in parenthesis ( ) indicate that the item is not
implemented by IBM Tivoli Monitoring.
v *Extra Attributes means the XML element or attribute is inserted as a
Name=Value pair in the Extra Attribute column in the Audit Log table.
ITM Audit
Logical group XML element(s) XML attribute attribute
AuditEvt AuditEvt Domain Domain
Level Trace Level
Type Event Record
Type
Ver Audit Record
Version
Who AuthID Authorization ID
(Repository)
RunAs RunAs
(Repository)
UserID User ID
(Repository)
Entity Entity
Type Entity Type
What Op (CDMID)
Name Operation Name
Type Operation Type
OpObjType Operation Object
Type
Msg Text Message
RBKey Resource Bundle
Key
Param Extra Attributes*
Order Extra Attributes*
Result Result
Environment variables
The following environment variables are defined for configuring the Auditing
Facility:
You can configure the tracing environment variable for the Auditing Facility by
using the following procedures. You can modify any of the environment variables
previously mentioned.
See Configuring the Tivoli Enterprise Monitoring Server on z/OS for more
information.
The session token leverages the common IBM Tivoli Monitoring encryption key
and synchronization of time between the IBM Tivoli Monitoring servers and
monitoring agents. If the encryption key is not synchronized, then any commands
are rejected as invalid due to validation errors with the identity. If system times
between the portal server (for Tivoli Enterprise Portal users) or the hub monitoring
server (for tacmd command users) is more than 25 minutes out of sync with that of
the target monitoring agent according to Universal Coordinated Time (UTC), then
the command is rejected as unauthorized due to a permission time out.
Situation Take Action execution and workflow policy Take Action execution
records the identity of the user who last modified the situation or workflow policy.
The audit messages are available in the audit log at the monitoring agent or
through the Tivoli Enterprise Portal as historical data or real-time queries of the
audit log.
The TEMS Security Compatibility Mode allows IBM Tivoli Monitoring server
components that are at a version before V6.3 to execute commands or Take Actions
for monitoring agents with Tivoli Enterprise Monitoring Agent Framework V6.3 or
You can also use AAGP policies to control which users can execute a TakeAction or
tacmd executecommand against a managed system. For more details, see“Access
Authorization Group Profile” on page 403.
The situation event forwarder generates a IBM Tivoli Enterprise Console event
with an event class based on the attribute group associated with the situation.
When the situation event is forwarded to the event server the associated generated
event class inherits event class attribute definitions (either directly or indirectly)
from the parent: Omegamon_Base class. Because IBM Tivoli Enterprise Console uses
hierarchical event classes, use the Omegamon_Base parent class when you want to
write a rule for all situation events that you forward to the event server.
In specialized cases where a situation event is mapped into an existing IBM Tivoli
Enterprise Console event class and the event hierarchy cannot be modified
(Omegamon_Base cannot be added to the hierarchy) it is important that the slots
from Omegamon_Base be included in the existing event class or in a class
As part of the generic mapping for these situations, the IBM Tivoli Monitoring
event forwarder assigns associated values for attributed defined in the event class
attributes when forwarding an event to the Tivoli Enterprise Console event server.
In addition to these event class attributes, values are assigned to the following
attributes inherited from the EVENT class, if available: source, hostname,
fqhostname, origin, sub_origin, adapter_host, origin, severity, and message
attributes that are inherited from the base EVENT class.
Table 29. IBM Tivoli Enterprise Console event class attributes
Event class attributes Values and meaning
adapter_host Base EVENT class attribute. Same as hostname (see below).
This is application-specific data related to the event, if any.
appl_label Reserved for future use.
cms_hostname TCP/IP host name of the Tivoli Enterprise Monitoring Server
that forwards the event.
cms_port The monitoring server port on which the web service is
listening.
fqhostname Base EVENT class attribute that contains the fully qualified
hostname, if available.
hostname Base EVENT class attribute that contains the TCP/IP
hostname of the managed system where the event originates,
if available.
integration_type Indicator to help IBM Tivoli Enterprise Console performance.
v N for a new event, the first time the event is raised
v U for update event, subsequent event status changes
master_reset_flag Master reset indicator set for master reset events. Value is
NULL for all other events:
v R for Tivoli Enterprise Monitoring Server recycle
master_reset
v S for hotstandby master_reset
msg Base EVENT class attribute that contains the situation name
and formula.
origin Base EVENT class attribute contained in the TCP/IP address
of the managed system where the event originates, if
available. The address is in dotted-decimal format.
severity Base EVENT class attribute that contains the resolved
severity.
situation_displayitem Display item of associated situation, if available.
situation_eventdata Raw situation event data starting from the second event data
row, if any. Event data attributes are in key-value pair
format. The event data can be truncated because the Event
Integration Facility imposes a 2 KB size limit.
situation_group One or more situation group names (up to 5) that the
situation is a member of.
situation_fullname Displayed name of the associated situation.
situation_name Unique identifier given to the situation.
situation_origin Managed system name where the situation event originated.
It has the same value as sub_source.
The situation name alone does not provide detailed event identification where
there are large numbers of like-events from various sources. Rather, the situation
name in the message slot sent from the hub monitoring server to the event server
is expanded to include the following event attributes:
where:
Situation-Name
The name of the situation.
formula
The formula tells how the situation is evaluated.
Managed-System-Name
The agent or the managed system.
DISPLAY-ITEM
The identifier that triggered the situation if there is more than one instance.
This is optional and is used only if a display item is specified in the
situation definition.
threshold Name-Value pairs
The raw data that the situation uses to evaluate whether it is triggered.
Examples:
NT_Critical_Process [(Process_CPU > 4 AND Thread_Count > 50)
ON IBM-AGX02:NT
(Process_CPU = 8 AND Thread_Count = 56)]
Chapter 10. Situation event integration with Tivoli Enterprise Console 257
The event class name of the IBM Tivoli Enterprise Console event is derived from
the attribute group associated with the situation. It is a combination of ITM_ plus
the attribute group name associated with the situation. For example, a situation
using the NT_Process attribute group will generate a IBM Tivoli Enterprise
Console event with class ITM_NT_Process.
Note: Some agents have very long attribute group names, which might cause the
generated event class name to exceed the limit imposed by the event server. In
these cases, the event class name will be a combination of ITM_ plus the table
name of the attribute group.
Additional event slot values are populated with situation attribute values from the
situation event data. The slot names are the attribute names after special character
processing.
For complex situations, the situation definition can involve more than one attribute
group. In this case, the IBM Tivoli Enterprise Console event class used is derived
from the first attribute group encountered in the situation event data of the
triggering situation. The exception is when the first attribute group found is
Local_Time or Universal_Time; then it is passed over and the next different
attribute group, if any, will be used.
For example, if a situation is written for the NT_Process and NT_System attribute
groups, NT_Process being the first attribute group, the IBM Tivoli Enterprise
Console event class ITM_NT_Process is used. Additional event slots are generated
based on the attributes of the attribute group selected.
Table 30. Special characters for attribute groups and names in IBM Tivoli Enterprise
Console events generated from forwarded situation events.
Character: Converts to:
<uppercase> (applies only to attribute name) <lowercase> (applies only to attribute name)
% percent sign pct_
I/O io
R/3 r3
/ forward slash _per_
\ backward slash _ (underscore)
<space> _ (underscore)
( open parenthesis _ (underscore)
) close parenthesis
< open pointed bracket _ (underscore)
> close pointed bracket
Note: After special character processing, the leading and trailing underscore in the
final event class or slot name, if any, will be removed.
The severity of a Tivoli Enterprise Console event associated with a situation can be
directly specified under the EIF tab of the Situation editor. If no Tivoli Enterprise
Console severity is specified for a situation, the event forwarder attempts to derive
a severity from the suffix of the situation name using the following rule:
Table 31. Situation name suffix mapping to Tivoli Enterprise Console event severity
Assigned IBM Tivoli Enterprise Console
Situation name suffix severity
Warn or _Warning WARNING
Cri, _Crit, _Critical CRITICAL
none of the above UNKNOWN
Some products ship with event mapping files and language bundles. The message
slots for these defined IBM Tivoli Enterprise Console events are globalized. The
language selection is done through a Tivoli Enterprise Monitoring Server
environment variable called KMS_OMTEC_GLOBALIZATION_LOC.
By default, this variable is set to American English and the message slots are filled
with the American English messages. Edit the variable to enable one of the
language packs that are installed in your environment.
Procedure
1. On the computer where the Hub Tivoli Enterprise Monitoring Server is
installed, open the KBBENV file:
v Start Manage Tivoli Monitoring Services, right-click Tivoli
Enterprise Monitoring Server, and click Advanced → Edit ENV file.
v In a text editor, open the <install_dir>/config/
<tems_name>_ms_<address>.cfg file, where <tems_name> is the value supplied
during the monitoring server configuration, and <address> is the IP address
or fully qualified name of the computer.
2. Locate (or add) the KMS_OMTEC_GLOBALIZATION_LOC environment
variable and enter the desired language and country code, where xx is the
language and XX is the country code: de_DE, en_US, en_GB, es_ES, fr_FR,
it_IT, ja_JP, ko_KR, pt_BR, zh_CN, or zh_TW (such as pt_BR for Brazilian
Portuguese or zh_CN for Simplified Chinese).
KMS_OMTEC_GLOBALIZATION_LOC=xx_XX
3. Save and close the monitoring server environment file.
Chapter 10. Situation event integration with Tivoli Enterprise Console 259
Situation event statuses and IBM Tivoli Enterprise Console
event generation
This topic describes the meaning of the situation event statuses and the setting of
the common slots in the generated IBM Tivoli Enterprise Console event.
situation is true
integration_type: N, the first time the situation is true; U, all
subsequent times
situation_status: Y
situation_name: Name of the situation
situation_display_item: Value of the attribute that was selected as the
display item in the situation definition, if any.
master_reset_flag: None
situation reset (no longer true)
integration_type: U
situation_status: N
situation_name: Name of the situation
situation_display_item: Value of attribute selected as display item in
the situation definition, if any.
master_reset_flag: None
acknowledge
integration_type: U
situation_status: A
situation_name: Name of the situation
situation_display_item: Value of the attribute that was selected as the
display item in the situation definition, if any.
master_reset_flag: None
situation start
integration_type: None
situation_status: S
situation_name: Name of the situation
situation_display_item: None
master_reset_flag: None
No IBM Tivoli Enterprise Console event is forwarded.
situation stop
integration_type: U
situation_status: P
situation_name: Name of the situation
situation_display_item: None
master_reset_flag: None
All opened situation events that originated from this Tivoli Enterprise
Monitoring Server will be closed on the event server.
situation startup error
integration_type: None
situation_status: X
situation_name: Name of the situation
Chapter 10. Situation event integration with Tivoli Enterprise Console 261
After the hub monitoring server switch takes place, a hot standby
master reset event is sent with situation_status=N. Master reset causes
the event server to close all opened situation events from the hub
monitoring server. The name of the old primary hub is in the
situation_origin slot.
Note: The integration_type value is solely used by the IBM Tivoli Enterprise
Console synchronization rule to improve its performance. It has no other meaning
related with the event.
To check the rules cache size for a running event server, run the following the IBM
Tivoli Enterprise Console command:
wlsesvrcfg -c
To set this rules cache size, run the IBM Tivoli Enterprise Console command:
wsetesvrcfg -c number_of_events
Note: For more information regarding these two commands, see the “Event server
commands” in the Tivoli Enterprise Console Command and Task Reference.
If the rules event cache become full, the IBM Tivoli Enterprise Console rules engine
generates a TEC_Notice event, Rule Cache full: forced cleaning, indicating that
5 percent of the events from the cache were removed. Events are removed in order
by age, with the oldest events removed first allowing newer events to be
processed.
When the hub monitoring server forwards a status update for a situation event
previously forwarded to the Tivoli Enterprise Console event server, if the original
situation event is deleted from the rules event cache, then a
TEC_ITM_OM_Situation_Sync_Error event is generated to indicate that the
monitoring server and the event server are out of synchronization.
When using any IBM Tivoli Enterprise Console viewer to acknowledge or close
any situation event, if the situation event has been deleted from the rules event
cache, the status change is not processed by the IBM Tivoli Enterprise Console
rules engine. Also, the situation event update is not forwarded to the originating
Tivoli Enterprise Monitoring Server. This behavior results from theIBM Tivoli
Enterprise Console rules engine not processing any event status changes for any
event not contained in the rules event cache. In this case, the event status change is
updated only in the IBM Tivoli Enterprise Console database.
You can run this command by using one of the following options:
Procedure
v Manually modify the configuration file for event synchronization (named
situpdate.conf by default and located in the and located in the
/etc/TME/TEC/OM_TEC directory on operating systems such as UNIX, and the
%SystemDrive%\Program Files\TME\TEC\OM_TEC\etc directory on
Windows), and then run the following command:
sitconfig.sh update <config_filename>
v Run the sitconfig.sh command directly, specifying only those settings that you
want to change. See IBM Tivoli Monitoring: Command Reference for the full syntax
of this command.
What to do next
After you change the configuration of the event synchronization, you must
manually stop and restart the Situation Update Forwarder process from the
$BINDIR/TME/TEC/OM_TEC/bin directory with the stopSUF and startSUF commands.
where:
serverid=server
The fully qualified host name of the monitoring server.
userid=user
The user ID to access the computer where the monitoring server is
running.
password=password
The password to access the computer.
Chapter 10. Situation event integration with Tivoli Enterprise Console 263
Repeat this command for each monitoring server that you want to add.
What to do next
After you change the configuration of the event synchronization, you must
manually stop and restart the Situation Update Forwarder process from the
$BINDIR/TME/TEC/OM_TEC/bin directory with the stopSUF and startSUF commands
(.cmd file extension on Windows; .sh on operating systems such as UNIX).
If the acknowledgment of the situation expires and the situation is still true, then a
new situation event is opened in the IBM Tivoli Enterprise Console. If the situation
becomes false, then it resets itself in IBM Tivoli Monitoring and the event remains
closed in the IBM Tivoli Enterprise Console.
Changing rule set parameters for the omegamon.rls rule set file
The omegamon.rls rule set file has parameters that you can edit, according to your
environment, to tune performance or to set your own customized values. Using
these parameters, you can write and customize IBM Tivoli Enterprise Console
rules. During installation, you can choose the location of the rule base. Otherwise,
you can use the wrb -lscurrb -path to find the current rule base.
Here are some reasons why you might want to change the behavior of the rule:
v For the omegamon.rls file, omegamon_admin is the name of the rule set but you
can name your rule set after your administrator's name or some other value.
v Similarly, the sit_ack_expired_def_action rule set name is set to REJECT by default.
This setting means that whenever a situation event acknowledgement expires in
the Tivoli Enterprise Portal and the event becomes OPEN in the portal, the IBM
Tivoli Enterprise Console event server rejects this action and re-acknowledges
the event in the portal. You have the option of accepting the change that was
initiated by the portal and changing the status in the IBM Tivoli Enterprise
Console instead.
Warning: Setting this value less than 20 events might cause contentions
within the IBM Tivoli Enterprise Console task process, causing poor
performance of events that are synchronized back to the Tivoli Enterprise
Monitoring Server.
sit_resurface_def_action
This attribute determines the default action of the rules in case a situation
update event arrives from Tivoli Enterprise Monitoring Server to resurface
or reopen an event that has already been acknowledged. The two possible
values are ACCEPT and REJECT. The default is ACCEPT.
sit_ack_expired_def_action
This attribute determines the default action of the rules in case a situation
update event arrives from the Tivoli Enterprise Monitoring Server to
reopen an event that has already been acknowledged. This happens when
a situation's acknowledgement in the monitoring server expires and the
situation event is reopened. The two possible values are ACCEPT and
REJECT. The default is REJECT.
sf_check_timer
This attribute specifies the interval at which the state of the situation
update forwarder is checked. It reads events from the cache files and send
them to the Tivoli Enterprise Monitoring Server using Web Services. The
default is 10 minutes.
After modifying any configuration parameters and saving omegamon.rls, you must
recompile and reload the rule base and recycle the event server. To recompile the
rule base, enter the following command, where Rulebase_Name is the name of the
actively loaded rule base containing the omegamon.rls rule set:
wrb -comprules Rulebase_Name
For more information regarding the wrb, wstopesvr, and wstartesvr commands,
see the Command and Task Reference at the Tivoli Enterprise Console Information
Center (http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/
com.ibm.itec.doc_3.9/welcome_nd.html).
Chapter 10. Situation event integration with Tivoli Enterprise Console 265
Tuning considerations
Integration parameters supporting actions at the IBM Tivoli Enterprise Console
event console that are reflected at the Tivoli Enterprise Portal event console
provide good response times with a reasonable system resource investment.
The delivery time of situation changes from the IBM Tivoli Enterprise Console
event console to the Tivoli Enterprise Portal event console results from the
omsync_timeout and PollingInterval settings working in parallel. To improve the
response time, you can reduce these settings down to a minimum of 1 second. .
There are two important sets of files that are used and required by the Rules Check
utility to check the possible impacts of event classes design changes to the rules:
v BAROC Event Classes Definition files:
IBM Tivoli Enterprise Console class definitions are hierarchical in nature with
inheritances. One class can inherit from another class, and all attributes from the
parent class are available in the child class. The EVENT class is the base IBM
Tivoli Enterprise Console class. The other classes usually derive from the IBM
Tivoli Enterprise Console EVENT class.
In IBM Tivoli Enterprise Console, the BAROC Event Class Definition files
(*.baroc files) are located in the actively loaded rule base's TEC_CLASSES
subdirectory. They provide the event class definitions used by the IBM Tivoli
Enterprise Console Server. Although the tool is closely integrated with IBM
Tivoli Enterprise Console and uses the active rule base's TEC_CLASSES
subdirectory by default input, the tool is not dependent on this subdirectory, and
accepts as alternative input any other directory that contains the correct BAROC
files and to which the user has read privileges.
v Rules files:
The IBM Tivoli Enterprise Console product rule language also supports the
inheritance nature of the IBM Tivoli Enterprise Console class definitions. When a
In IBM Tivoli Enterprise Console, the rule set files (*.rls files) are located in the
actively loaded rule base's TEC_RULES subdirectory. They provide the rule sets
and are deployed to the IBM Tivoli Enterprise Console Server. Although the tool is
closely integrated with IBM Tivoli Enterprise Console and uses the active rule
base's TEC_RULES subdirectory by default input, the tool is not dependent on this
subdirectory. The tool accepts as an alternative input any other directory that
contains the correct rule sets and to which the user has read privileges.
The Rules Check utility is included with IBM Tivoli Monitoring. This utility is
installed in the $BINDIR/TME/TEC/OM_TEC/bin directory as part of the IBM
Tivoli Enterprise Console Event Synchronization installation. It does not require
any specific directory configuration if the required privileges for access to the input
and output files are granted.
To run the Rules Check utility and see sample output, refer to the Command
Reference.
After the Tivoli Event Integration Facility (EIF) has been enabled on the hub
monitoring server and the default EIF server (Tivoli Enterprise Console event
server or Netcool/OMNIbus EIF probe) and port number have been specified, the
EIF configuration file is updated with the information. This configuration file
specifies the default EIF receiver of forwarded situation events.
See the Tivoli Event Integration Facility Reference for more details on the parameters
and values.
If you are enabling EIF after your environment has been installed and configured,
you must enable EIF through Manage Tivoli Enterprise Monitoring Services or
with the CLI itmcmd config -S and then recycle the monitoring server and portal
server.
See the IBM Tivoli Monitoring Installation and Setup Guide (http://pic.dhe.ibm.com/
infocenter/tivihelp/v61r1/topic/com.ibm.itm.doc_6.3fp2/install/itm_install.htm)
for instructions on configuring the monitoring server to enable the Tivoli Event
Integration Facility.
Chapter 10. Situation event integration with Tivoli Enterprise Console 267
About this task
Procedure
1. Open the om_tec.config file:
v In the Manage Tivoli Monitoring Services window, right-click
Tivoli Enterprise Monitoring Server and click Advanced → Edit EIF
Configuration.
v Open install_dir/tables/host name/TECLIB/
om_tec.config in a text editor.
2. Edit any of the event server configuration parameters for the event integration
facility.
Option Description
ServerLocation= This is the host name or ip address of the
event server. To provide event failover, you
can indicate up to five default event servers,
separating each with a comma. When the
default event server is unavailable, the
situation event goes to the next server in the
list.
Value: tec_server_addr
ServerPort= The event server listening port, which is
5529 by default. Specify 0 if the event server
uses the port mapper. If you specified
multiple server locations, add the
corresponding port numbers here, separating
each with a comma.
Value: [port:0]
EventMaxSize= Maximum number of characters allowed in
the event. This number is disabled by
default. To enable it, remove the # (pound
symbol) at the beginning of the line.
Value: 4096
RetryInterval= The number of times to retry connection
with the event server before returning an
error.
Value: 5
getport_total_timeout_usec= The number of seconds to continue
attempting to connect to the event server
port before timing out. The default is 14
hours.
Value: 50500
NO_UTF8_CONVERSION= Events are already in UTF8 format; no
conversion is needed. This parameter must
be set to YES.
Value: YES
ConnectionMode= The connection mode.
Value: co
BufferEvents= Whether the EIF buffers the event. This must
be set to YES.
Value: YES
Chapter 10. Situation event integration with Tivoli Enterprise Console 269
the monitoring server. To use this command, log into the command-line
interface with tacmd login , then run tacmd refreshTECinfo -t eif to complete
the EIF configuration.
Results
The monitoring server uses the edited EIF configuration to forward event to the
receiver.
What to do next
If this is the first time that you have configured the EIF forwarding after a Tivoli
Management Services upgrade, you also must recycle the Tivoli Enterprise Portal
Server and users must restart the Tivoli Enterprise Portal. Otherwise, the EIF tab
will be missing from the Situation editor.
An alternative method for editing the EIF configuration is provided through the
Command Line Interface tacmd createEventDest. See the IBM Tivoli Monitoring
Command Reference (http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/topic/
com.ibm.itm.doc_6.3fp2/ic/landing_cmdref.htm) for a description.
Related reference:
You can override this default for individual situations through the EIF tab of the
Situation editor in the Tivoli Enterprise Portal.
Alternate event destinations that were specified in the tecserver.txt file from earlier
releases will be defined as valid event destinations automatically as part of the
tecserver.txt file migration.
If multiple default event destinations are specified (in other words, multiple event
destination servers have Default set to 'Y'), they all must be selected in the Tivoli
Enterprise Portal for events to be forwarded to all defined default destinations.
Complete these steps to specify the destination EIF receiver and severity for
forwarded events:
Procedure
1. In the Tivoli Enterprise Portal Navigator view, either right-click the Navigator
item that the situation is associated with and click Situations or click
Situation Editor in the main toolbar.
2. Select the situation to forward.
3. Click the EIF tab.
4. Select Forward Events to an EIF Receiver to specify that an EIF event is sent
for each event that opens for this situation.
5. Select the EIF Severity to apply to forwarded events for this situation. <Default
EIF Severity> uses the same severity that is used for the situation at this
Navigator item.
6. To assign other EIF receivers instead of or in addition to the <Default EIF
Receiver>, use one of the following steps:
v To add a destination, select it from the Available EIF Receivers list and
move to the Assigned list. (After selecting the first destination, you can
use Ctrl+click to select other destinations or Shift+click to select all
destinations between the first selection and this one.)
v To remove a destination, select it from the Assigned EIF Receivers list and
move to the Available list.
The Available EIF Receivers list shows all of the defined EIF destinations that
were defined through Manage Tivoli Monitoring Services or with the tacmd
createEventDest command. See the IBM Tivoli Monitoring Command Reference
(http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/topic/
com.ibm.itm.doc_6.3fp2/ic/landing_cmdref.htm).
7. Save the situation definition with your changes by clicking Apply, to keep the
Situation editor open, or OK, to close the Situation editor.
Related reference:
Chapter 10. Situation event integration with Tivoli Enterprise Console 271
parameters and values.
When the Base Slot name is msg, the Literal value column is used for the message
template. The message template consists of fix message text and variable
substitution references, or symbols. The symbol can refer to common or event slot
data or a special reference to the situation formula. Common slots are those that
are included in all forwarded events, such as situation_name; event slots are those
specific to the situation. The following syntax rules apply when setting event slots:
v For an event slot, use the fully qualified attribute name
($Attribute_Table.Attribute_Name$)
v For a common slot, use the variable name that is not fully qualified (no .
periods) unless it is the situation symbol
v For a situation formula, use $formula$
These characters are not supported: < less than, > greater than, " quotation mark, '
single quotation mark, and & ampersand. This column is available only if no value
is selected in the Mapped attribute column. See the Tivoli Enterprise Portal online
help or the Tivoli Enterprise Portal User's Guide for more information.
For the msg slot, typical users specify a Literal value, not a Mapped attribute value.
If a value is specified in the Mapped attribute column for the msg slot, the
following occurs:
v If Map all attributes is not selected, then the Mapped attribute for the msg will
not be present in the event, and will be ignored.
v If Map all attributes is selected, then the Tivoli Enterprise Console event will
only have the default message template and not the Mapped attribute specified
in the msg slot.
If an event class specified for a rule is not found within the current event class
definition set and you continue building the rule with the current definition set,
any unrecognized event classes will be removed from the rule.
The EIF Event Customization facility uses the MCS Attribute Service to present a
list of predefined event classes in the Event class name list of the EIF Slot
Customization window, which is available through the EIF tab of the Tivoli
Enterprise Portal Situation editor. Only the event classes belonging to the OS
agents are predefined and they are in an MCS Attribute Service jar file. When a
new type of agent is added into the Tivoli Management Services infrastructure or a
new event class is added for an agent, you must generate a new MCS XML file
and point the Tivoli Enterprise Portal Server to the new XML file before the new
event classes will appear in the Event class name list.
To generate a new MCS XML file, install the Tivoli Enterprise Console Event
Definition Generator (TEDGEN) utility supplied on the IBM Tivoli Monitoring
Tools DVD. Install the TEDGEN utility on a distributed computer where the hub
monitoring server or portal server is installed, or where the Tivoli Enterprise
Console is installed. The computer on which you generate the MCS XML file must
have the necessary BAROC files.
Note: The definitions in MCS XML file supersede those defined in the shipped
MCS Attribute Services jar file (they are not merged). To obtain a MCS XML file
that contains both the event classes definitions of the OS agents as well as the new
agent, be sure all the BAROC definitions for the OS agents and new agent are
loaded at the IBM Tivoli Enterprise Console event server or are all in the same
directory on the hub monitoring server or portal server before running the
TEDGEN utility to generate the MCS XML file.
These steps assume you have installed the TEDGEN utility on the computer where
you want to run the tool: at the Tivoli Enterprise Console event server, the hub
monitoring server or portal server.
You must also install the application support for the agents whose EIF events are
customized on the hub monitoring server or portal server where you want to run
Chapter 10. Situation event integration with Tivoli Enterprise Console 273
the utility. If you want to run the TEDGEN utility on the Tivoli Enterprise Console,
you must also load the agent's BAROC files on the computer where the Tivoli
Enterprise Console is installed.
After installing the utility and application support, then run the TEDGEN
command to create a new XML file for EIF Slot Customization.
Note:
v If you have installed the TEDGEN utility on a portal server installed on Linux or
UNIX, the BAROC files will not exist unless the Install TEMS support for
remote seeding option was selected during the agent's application support
installation. See “Configuring application support for nonlocal monitoring
servers” in the IBM Tivoli Monitoring Installation and Setup Guide. This action
places the BAROC files on the portal server under the install_dir/tables/
cicatrsq/TECLIB directory where install_dir is the directory where IBM Tivoli
Monitoring is installed.
v If you installed the TEDGEN utility on a portal server on Windows, verify that
the portal server’s TECLIB directory contains the .baroc files for the agents
whose events you want to customize. Not all agents include their .baroc files in
their portal server application support. If an agent’s .baroc file is not present,
you can copy it from the hub monitoring server’s TECLIB directory.
Procedure
1. Complete one of the following steps to run the TEDGEN command:
v On the computer where the hub monitoring server or portal server is located,
issue these commands:
set CANDLE_HOME=install_dir
cd TEDGEN_Install_dir\scripts
tedgen -itmDir install_dir\{CMS|CNPS}
\TECLIB -id server_id -xmlPath output_xml_file_path
export CANDLEHOME=install_dir
cd TEDGEN_Install_dir/scripts
tedgen -itmDir
install_dir/tables/{tems_name|cicatrsq}/
TECLIB -id server_id -xmlPath output_xml_file_path
Using the NetView console through the IBM Tivoli Enterprise Console
event viewer
You can launch the IBM Tivoli NetView® Java console from the IBM Tivoli
Enterprise Console views, navigating from an event row to the associated network
topology and diagnostics. The selected event must contain a valid host name or IP
address to support the topology display of the node associated with the event.
Otherwise, the standard topology view is displayed without a specific node
selected.
Ensure that you have netview.rls and netview BAROC files in the actively loaded
rule base. For details, see the Rule Set Reference at the Tivoli Enterprise Console
Information Center (http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/
com.ibm.itec.doc_3.9/welcome_nd.html).
Chapter 10. Situation event integration with Tivoli Enterprise Console 275
If you want to use the NetView console through the IBM Tivoli Enterprise Console
view in the Tivoli Enterprise Portal, you must configure the NVWC_HOME
variable in the shell script that launches the Tivoli Enterprise Portal client, to point
to the installation directory of NetView Web Console.
Procedure
v install_dir\cnp\cnp.bat
v or install_dir/bin/cnp.sh
What to do next
The NetView Web Console must be installed on the computer where the Tivoli
Enterprise Portal client is running to launch the NetView console from IBM Tivoli
Enterprise Console view.
See the IBM Tivoli Enterprise Console product documentation for more detailed
information about using the NetView console.
Updates to those events are also sent to OMNIbus. When an OMNIbus user
acknowledges, closes, or reopens a forwarded event, OMNIbus sends those
changes to back to the monitoring server that forwarded them.
Situation events from Tivoli Enterprise Monitoring Agents that are sent as SNMP
alerts to the Netcool/OMNIbus SNMP Probe can also be used to integrate with
Netcool/OMNIbus.
A common event connector (frequently called a connector) is software that enables the
integrated display of events from multiple event systems in the common event
console. A connector retrieves event data from an event system and sends
user-initiated actions to be run in that event system. For example, if you perform
an action on a Tivoli Enterprise Console or Netcool/OMNIbus event in the
common event console, the associated common event console connector sends that
action to the originating event system (Tivoli Enterprise Console or
Netcool/OMNIbus) for execution. To have the events from a specific event system
displayed in the common event console, you must configure a connector for that
event system and set a variable in the Tivoli Enterprise Portal Server environment
file.
Procedure
v
1. Select Start → Programs → IBM Tivoli Monitoring → Manage Tivoli Enterprise
Monitoring Services.
2. In the Manage Tivoli Enterprise Monitoring Services window, right-click
Tivoli Enterprise Portal Server.
3. In the menu, click Reconfigure.
Results
The portal server stops and, after a moment, the Common Event Console
Configuration window opens with the following tabs:
v ITM Connector
v TEC Connector
v OMNIbus Connector
v Names of Extra Columns
To configure a connector, click New. The resulting TEC Connector page contains
the following information that defines an IBM Tivoli Enterprise Console connector:
Connector name
The name that is to be displayed in the common event console for this
connector.
Chapter 12. Configuring connectors for the common event console 281
If this value is set to -1 and the connector loses its connection, the
connector attempts to reconnect indefinitely.
Information for extra table columns
The common event console includes five extra table columns that you can
customize. In the remaining fields on this TEC Connector page, you can
define the Tivoli Enterprise Console attribute type and attribute name that
identify the attribute that is to be mapped to each of these customizable
columns.
For the attribute type, you can choose one of the following values:
v Base, which means that the attribute is from the Tivoli Enterprise
Console base attribute table.
v Extended, which means that the attribute is from the Tivoli Enterprise
Console extended attribute table.
Click the Names of Extra Columns tab to view or change the names of these
columns.
Chapter 12. Configuring connectors for the common event console 283
Purpose of extra table columns
The common event console displays only a basic set of information from the Tivoli
Enterprise Console base attribute table and the Tivoli Netcool/OMNIbus
alerts.status and alerts.details tables.
If, for example, you want to see an additional attribute named “origin” from a
Tivoli Enterprise Console event, you can perform the following steps:
1. In the Attribute type for extra column 1 field on the TEC Connector page,
choose the attribute type, for example, base.
2. In the Attribute name for extra column 1 field on the TEC Connector page,
enter the attribute name, for example, origin.
3. In the Name of extra column 1 field on the Names of Extra Columns page,
enter the name that you want to use for the column that you have customized.
For example, you might enter Origin.
In the “Origin” column for each row that is a Tivoli Enterprise Console event, the
common event console displays the value of the origin attribute.
Follow these best practices to restrict the common event console to include only
the Tivoli Enterprise Console or Tivoli Netcool/OMNIbus events that do not
originate as Tivoli Monitoring events:
When Tivoli Monitoring events are forwarded to Tivoli Enterprise Console event
system
1. On the Tivoli Enterprise Console server, create an event group that
defines only the Tivoli Enterprise Console events that do not originate
as Tivoli Monitoring events and is named, for example, All_but_ITM.
2. When you configure a TEC Connector, type All_but_ITM in the Event
group that defines events for common event console field.
3. When you configure the ITM Connector, click Yes in the Enable this
connector field.
When Tivoli Monitoring events are forwarded to Tivoli Netcool/OMNIbus event
system
1. When you configure an OMNIbus Connector, type ITMStatus = ’’ in
the SQL WHERE clause that restricts events for common event
console field, where ’’ is two single quotation marks with no space
between them. This clause restricts the Tivoli Netcool/OMNIbus events
in the common event console to only those that do not originate as
Tivoli Monitoring events.
2. When you configure the ITM Connector, click Yes in the Enable this
connector field.
The resulting configuration causes the common event console to retrieve Tivoli
Monitoring events directly from the Tivoli Monitoring event system rather than the
Tivoli Enterprise Console or Tivoli Netcool/OMNIbus event system, which
prevents you from having duplicate event information in the common event
console.
Chapter 12. Configuring connectors for the common event console 285
The default Linux configuration causes the connection request to be sent to
the Tivoli Enterprise Console server with the 127.0.0.1 address, which is
not the correct IP address of the computer where the Tivoli Enterprise
Portal server is installed. For the Tivoli Enterprise Portal server to connect,
it must be able to do a reverse lookup.
Solution
Ensure that the /etc/hosts file includes the local host with the correct IP
address. The following two lines show approximately what the correct
Linux configuration is, where xxx.xxx.xxx.xxx is the IP address of the
computer where the Tivoli Enterprise Portal server is installed:
127.0.0.1 localhost
xxx.xxx.xxx.xxx my_hostname
The methods available for agent maintenance depend on the size and configuration
of your managed network, the type of task, and your preferences.
Before you can remotely install and configure agents, each target computer must
have an operating system (OS) agent installed. Monitoring agents that do not
support the remote agent deployment feature do not show the Add Managed
System, Configure, and Remove options in the Navigator pop-up menu. The types
of managed systems that you can add to a computer depend on what agent
bundles are in the agent depot on the monitoring server that the OS agent is
connected to.
The types of agents that you can remotely install on a computer depend on what
agent bundles are in the agent depot on the monitoring server to which the OS
agent is connected. The “Deploying monitoring agents across your environment”
topics in the IBM Tivoli Monitoring Installation and Setup Guide describe how
establish an agent depot on the monitoring server and an OS agent on each
computer where agents will be deployed.
After the OS agents have been installed, the Navigator Physical view adds an item
for each online managed system.
To use this feature, your user ID must have Manage permission for Agent
Management.
Follow these instructions to install and configure managed systems through the
Tivoli Enterprise Portal:
To use this feature, your user ID must have Manage permission for Agent
Management.
Procedure
1. Right-click the Navigator item for the agent to configure or upgrade.
2. Click Configure to open the Configure Managed System window.
3. Edit the fields to configure the agent, clicking Next and Back to move among
the pages. Any pages besides Agent are specific to the agent type.
v Performance Analyzer, Summarization and Pruning Agent, and Warehouse
Proxy: See “Tivoli Data Warehouse solutions” in the IBM Tivoli Monitoring
Installation and Setup Guide.
v Non-base agents: See your product's installation guide in the IBM Tivoli
Monitoring Information Center (http://pic.dhe.ibm.com/infocenter/tivihelp/
v61r1/topic/com.ibm.itm.doc_6.3fp2/welcome.htm) or on IBM Tivoli
Documentation Central (https://www.ibm.com/developerworks/
community/wikis/home?lang=en#!/wiki/Tivoli%20Documentation
%20Central).
4. On the Agent page, establish the user ID that will be used to maintain the
agent:
Windows:
Accept the default Use local system account to use your Tivoli
Enterprise Portal user ID. You can also select Allow service to
interact with desktop to enable remote control. Or select Use this
account and fill in the user name and password under which the agent
will be controlled.
Non-Windows:
Enter the Username under which the agent will run and the Group
name.
5. Click Finish to complete the managed system configuration. If any of the
information provided is invalid, you will receive an error message and be
returned to the configuration window. Check your entries and edit as
appropriate to configure correctly.
To use this feature, your user ID must have Manage permission for Agent
Management.
All deployment commands are passed through the operating system agent that is
installed at the target computer. If an operating system agent is not installed, you
cannot start or stop the deployed agent.
Procedure
v To start a monitoring agent from the Tivoli Enterprise Portal:
This capability does not apply to the OS monitoring agents, z/OS-based agents, or
any products that do not support the remote agent deployment feature. The agents
to be updated must also have been originally installed using remote agent
deployment. The types of managed systems that you can add to a computer
depend on what agent bundles are in the agent depot on the monitoring server to
which the OS agent is connected. See the “Deploying monitoring agents across
your environment” topics in the IBM Tivoli Monitoring Installation and Setup Guide
for more information.
Before starting the update, you must install application support on the Tivoli
Enterprise Portal Server for any agent that you are going to deploy with the
procedure that follows.
Note: Agent application support updates are automatic and this procedure is not
necessary if your monitoring agent is running on an IBM Tivoli Monitoring Version
6.2.3 or later infrastructure, unless the self-describing capability is disabled.
Complete these steps to apply a patch for a monitoring agent through the portal
client:
Procedure
1. Right-click the Navigator item for the agent that you want to upgrade.
2. Click Configure to open the Configure Managed System window.
3. Click the Agent tab.
Results
Installation of the updates begins and might take several minutes to complete. The
list that displays reflects the contents of the deployment depot. If Install Updates
is disabled, one or more of the following conditions exist:
v The depot entry does not match the product type.
v The VVRR fields for the agent and the depot entry are not the same, where VV is
the version number and RR is the revision number. For example, an entry of 0610
prevents you from applying a fix pack intended for a version 6.2 agent.
v The depot entry is at an older version than the agent.
v The host version field of the depot entry does not contain the host platform for
the agent.
v The prereq field of the depot entry does not contain an agent of the same type
as the agent itself. For example, if 6.1 UD (DB2 monitoring) is the selected agent,
the prereq field in the depot entry must contain a deployment bundle notation
such as ud:061000000, which is one way to denote a patch deployment bundle.
To use this feature, your user ID must have Manage permission for Agent
Management.
Note: If the Manage Tivoli Enterprise Monitoring Services utility is running when
you uninstall the agent, it is shut down automatically by the uninstallation process.
Procedure
1. Right-click the Navigator item for the agent you want to remove.
2. Click Remove.
3. Click Yes when you are asked to confirm the removal of the agent. If you are
removing an agent that has subagents, another message will ask if you want
them all removed.
4. When you are asked to confirm that you want to permanently uninstall the
agent, click Yes to uninstall or No to leave the agent installed on your system.
Note: Use only tacmd commands that are included with Tivoli products to process
bundles and to execute agent deployments. Manual manipulation of the depot
directory structure or the bundles and files within it is not supported and might
void your warranty.
Procedure
1. Use the tacmd login command to log into a Tivoli Enterprise Monitoring
Server.
tacmd login {-s|-–server} {[{https|http}://]HOST[:PORT]}
[{-u|--username} USERNAME]
[{-p|--password} PASSWORD]
[{-t|--timeout} TIMEOUT] [-t TIMEOUT]
a. For example, to log in to the system ms.austin.ibm.com with the user name
Admin and the password log1n, run the following command:
tacmd login -s ms.austin.ibm.com -u Admin -p log1n
2. After logging in, use the tacmd updateAgent command to install an agent
update to a specified node.
tacmd updateAgent {-t|--type} TYPE {-n|--node} MANAGED-OS
[{-v|--version} VERSION] [{-f|--force}]
a. For example, the following command updates a UNIX agent (type UX) on
itmserver:
tacmd updateagent -t UX -n itmserver:KUX -v 6111
Procedure
v Modify the monitoring server environment file
1. Open the environment file on the computer where the monitoring server is
installed:
– Use Manage Tivoli Enterprise Monitoring Services (Start →
Programs → IBM Tivoli Monitoring → Manage Tivoli Enterprise
Monitoring Services). Right-click Tivoli Enterprise Monitoring Server and
click Advanced → Edit ENV File.
– Change to the install_dir/config directory and
open the <hostname>_ms_<temsname>.config and ms.ini files in a text
editor.
2. Add the environment variable, specifying your hourly interval. For example:
CLEARDEPLOYSTATUSFREQ=1.
3. Save the file.
4. Recycle the monitoring server to implement the changes.
v Modify the monitoring server environment file by using the IBM Tivoli
Monitoring Service Console
See “Using the IBM Tivoli Monitoring Service Console” in the IBM Tivoli
Monitoring Troubleshooting Guide for detailed information.
1. Open a web browser to http://hostname:1920, where hostname is the host
name or IP address of the system where the monitoring server is running.
The utility then displays with information about the components that are
currently running on this system.
2. Select the ms link to modify the environment variable.
3. Enter your user ID and passwords.
4. Enter the BSS1 SET CLEARDEPLOYSTATUSFREQ=1 command, where 1 is your
hourly interval.
Results
What to do next
You can change the location of the log file where the monitoring server records the
transactions which are cleared from the Deployment Status table, by adding the
environment variable CLEARLOG to the monitoring server configuration file
specifying a fully qualified path name on the local system, or any fully qualified
path name on a mounted file system.
Using a mounted file system is useful when there is a monitoring server and a
server backup. By using a mounted file system as the destination, the logs for both
systems can be set to the same fully qualified path name to accommodate failover
conditions.
Note: The acting hub monitoring server performs the automated cleansing of the
Deployment Status table for the entire enterprise. If you have a backup monitoring
server for the hub, then also set the environment variable on the backup to the
same value as specified on the hub so that the clearing process occurs at the same
time in the event of a hub failover.
Procedure
v Use the Manage Tivoli Enterprise Monitoring Services application on the
computer system where the agent is installed. Right-click the monitoring agent,
and click Reconfigure. Click OK in the first Agent Advanced Configuration
The self-describing update occurs only once for each specific agent version. The
update files are stored at the agent so that when the agent connects to a
monitoring server, the monitoring server is automatically informed of the available
application support update. If the self-describing function is enabled, the
application support is retrieved from the agent, and the monitoring server support
is updated.
Note: If you are using the Tivoli Enterprise Portal desktop client, you must use the
monitoring agent's installation images to install the Tivoli Enterprise Portal
application support on each of the desktop clients.
If you installed your monitoring server on Linux or UNIX, the application support
files for all base monitoring agents and other supported agents were automatically
installed on the monitoring server. This process is different from installing the
monitoring server on Windows, in that the Linux or UNIX installation always
automatically installs the application support files for monitoring agents. Check the
monitoring server and portal server to ensure that self-describing agent products
are installed as expected.
Roadmap
Use the following roadmap to help you configure, enable, and use the
self-describing feature. Because this roadmap is meant to provide a comprehensive
overview, when applicable, links are provided to relevant sections in other Tivoli
Monitoring guides.
In IBM Tivoli Monitoring V6.3, by default, the hub monitoring server blocks all
self-describing agent installations (even if you turned on self-describing at the
hub monitoring server with setting KMS_SDA=Y from step 2) until you issue one
of the following commands:
v tacmd addSdaInstallOptions to specify the products and versions that the
self-describing agent facility is allowed to install.
OR
v tacmd editSdaInstallOptions -t DEFAULT -i ON to allow installations for all
products and versions without any blocking. (This setting is essentially the
default self-describing agent behavior in V6.2.3 and V6.2.3 FP1.)
This feature provides more control over what products and versions are
installed on your monitoring server and portal server by the automatic
self-describing agent process.
After modifying your install options, you can use the tacmd
listSdaInstallOptions command to display the current installation
configurations for the hub monitoring server.
The following steps outline the event flow of a self-describing agent connecting to
the hub monitoring server:
1. The self-describing agent manager of the hub monitoring server determines
whether the version of the application support for the product is already
installed on the hub monitoring server. If the application support version for
the product is not already installed, the hub monitoring server retrieves the
support files from the agent.
2. The hub monitoring server begins the self-describing agent product installation
and dynamic refresh of the monitoring server internal product definition
structures. The completion status of the installation of this hub monitoring
server self-describing agent is recorded in the following locations:
v The local Tivoli Enterprise Monitoring Server application properties table.
v Tivoli Enterprise Monitoring Server audit log facility.
v Tivoli Enterprise Monitoring Server MSG2 log facility.
v Tivoli Enterprise Monitoring Server RAS1 log.
The following steps outline the event flow of a self-describing agent connecting to
the remote monitoring server:
1. The self-describing agent manager of the remote monitoring server ensures that
the product was first installed on the hub monitoring server.
2. If the product was not first installed on the hub monitoring server, the remote
monitoring server tells the hub monitoring server to install the product first.
3. After the hub monitoring server installation is complete, the remote monitoring
server determines if the product is installed locally on this monitoring server.
4. The remote monitoring server product installation occurs in the same way as
described for the hub monitoring server.
5. If the hub monitoring server product installation fails for any reason, the
remote monitoring server does not install the product.
Note:
The availability of the self-describing agent feature on a hub monitoring server
can influence the availability of the feature on a remote monitoring server. An
error message is displayed when a self-describing agent error on a hub
monitoring server causes the self-describing agent feature to be disabled on the
remote monitoring server connected to that hub. For more information about
the error messages, see the IBM Tivoli Monitoring Troubleshooting Guide.
After the self-describing agent error is fixed on the hub monitoring server, the
remote monitoring server detects, at the next reconnection to the hub, that the
self-describing agent feature is available on the hub. As a result, it re-enables
the self-describing agent locally on the remote monitoring server.
The Tivoli Enterprise Monitoring Server detects the following information during
startup:
v Products installed manually, for example applications that were not installed by
using the self-describing capability.
v Manual updates (catalog and version file changes) to installed products, for
example user-initiated product changes that happen outside of a self-describing
agent installation.
v Failed self-describing agent installations.
The Tivoli Enterprise Monitoring Server makes adjustments and corrections based
upon the changes detected in installed products. Only products that have a valid
monitoring server version file (VER file) are detected during startup. This process
happens automatically when the self-describing agent installation manager is
enabled on the monitoring server (KMS_SDA=Y). This function helps to maintain
an accurate inventory of installed products and versions. If the self-describing
agent installation manager is not enabled, this function does not run.
This table also stores self-describing information such as installation options, seed
distribution, and suspend records. For more information about the TAPPLPROPS
attributes, see the “Application Property Installation attributes” in the Tivoli
Enterprise Portal User's Guide for more information.
You can use two different tacmd commands to check the self-describing status of
your monitoring servers:
v tacmd listSdaStatus for operational status
v tacmd listappinstallrecs for product installation status
tacmd listSdaStatus
KUILSS203I: SDA functions are suspended.
HUB/RTEMS STATE STATUS
HUB_A ON 0
RTEMS_1 ON 0
RTEMS_2 OFF 16
The command returns the application support installation records and displays the
current self-describing agent product installation status for all monitoring servers
in the environment. Remember that this command is not available when the
monitoring server is not running. If the monitoring server and the portal server are
both started, you can also see self-describing agent information and settings in the
Audit Logs workspace. See Chapter 9, “Audit logging,” on page 245.
The HUB/RTEMS column lists the node name of the monitoring server where the
record was collected. Rows with IC in the STATE column stand for self-describing
agent Install Complete. You can also see in this example that the hub monitoring
server and the remote monitoring server both have an appinstallrecs entry for
monitoring server support (TMS), but the hub monitoring server has two
additional appinstallrecs entries for portal server support (TPS) and portal
browser client support (TPW) packages. These additional packages are installed
only on the hub monitoring server so they are available to the portal server.
Tip: IR, IM, and MC appinstallrecords all indicate that normal self-describing agent
installation is in progress. For information about application support installation
records with a STATE value of ME, see “Self-describing agent installation errors.”
The Tivoli Enterprise Monitoring Agents self-describing agent service decides what
types of previously failed self-describing agent registration or installation requests
are tried again. Only the following types of failures or error codes returned from
Self-describing agent installation errors that can be tried again are registration or
installation requests that started, but have not yet modified any of the Tivoli
Enterprise Monitoring Server files or internal structures.
For any error records with a STATE value of ME, the installation is not tried again.
In this example, the installation record for product code 11 displays a STATE value
of ME:
Take the following steps to try the self-describing agent installation again:
1. To avoid the same failure from occurring again, you must first correct the
condition that caused the installation to fail. In addition, the monitoring server
message facilities (Audit, MSG2, and RAS1 messages) provide more
information about the cause of the failure. Take corrective action to fix the
condition or contact IBM Software Support for assistance.
2. For each monitoring server, delete the failed installation records in the
application properties table by running the tacmd deleteappinstallrecs
command. This command removes the blocking self-describing agent product
installation record. See the IBM Tivoli Monitoring Command Reference for more
information.
3. When each monitoring server failed product installation record is cleared, the
monitoring server self-describing agent facility immediately notifies any
running self-describing agent that can provide this level of product support, to
try the product installation again. For example, if the previous installation
attempt for product pc and version 06230000 failed with a STATE of ME, and you
If the self-describing agent product installation fails only at the standby hub,
correct the reason for the failure at the standby hub. While logged on the primary
hub, you can then use the deleteappinstallrecs command with the -n
<standby_TEMS_name> option to remove the error entry at the standby monitoring
server to allow the self-describing agent installation to try again. Deleting the
application installation record from the standby hub does not automatically trigger
the self-describing agent product installation to try again the way it does when the
record is deleted from the primary monitoring server or a remote monitoring
server. There is no problem if the standby hub is temporarily missing the agent
product support.
v If the standby hub is recycled, any missing product support is discovered, and
the self-describing agent product installation takes place at that time.
v If the standby hub is promoted to the acting hub, self-describing agent product
installation takes place when the first agent of that type connects to the
promoted hub.
v You can force the self-describing agent installation to try again immediately at
the standby hub, by repeating the self-describing agent installation at the
primary hub. After clearing the error application installation record at the
standby monitoring server, use the deleteappinstallrecs -a command to delete
the non-error state record from the primary monitoring server. This command
repeats the self-describing agent installation at the primary monitoring server,
triggering the standby monitoring server installation when it completes
successfully.
Procedure
1. Suspend the self-describing capability (without recycling the hub monitoring
server) by using the tacmd suspendSda command. This command ensures that
no self-describing installations take place while you are updating the options.
2. Run one of the following commands:
304 IBM Tivoli Monitoring: Administrator's Guide
tacmd addSdaInstallOptions
Specify the products and versions that can be installed by the
self-describing agent facility.
tacmd editSdaInstallOptions
Modify an existing product version configuration, or change the default
self-describing agent installation behavior.
tacmd deleteSdaInstallOptions
Remove a specific version configuration, or remove all versions for a
product.
tacmd listSdaInstallOptions
Display the existing self-describing agent installation configurations
from the hub monitoring server.
Results
Your installations take place only on the new products of versions you specified
once self-description is enabled by setting the variable KMS_SDA=Y.
The tacmd suspendSda and tacmd resumeSda commands dynamically change the
self-describing behavior only when the hub monitoring server is configured with
KMS_SDA=Y. Issuing the tacmd suspendSda and tacmd resumeSda commands will not
override the KMS_SDA=N setting. If the tacmd resumeSda command is issued when
KMS_SDA=N, the command is ignored until KMS_SDA=Y.
Issuing either the tacmd suspendSda or tacmd resumeSda commands updates the
TAPPLPROPS table. This setting is saved regardless of the KMS_SDA setting. Best
practice is to set the hub monitoring server environment variable to KMS_SDA=Y,
then run the tacmd suspendSda or tacmd resumeSda commands.
Procedure
v To suspend the self-describing capability, issue the tacmd suspendSda command.
v To resume the self-describing capability, issue the tacmd resumeSda command.
You can run the tacmd listSdaStatus to view the suspend state of your
monitoring servers. See “Self-describing agent installation” on page 300.
Auto refresh
Each product provides application support. Before IBM Tivoli Monitoring V6.2.3 or
later, the application support was installed at a monitoring server, portal server,
and portal client, and a recycle of each component was necessary for the new
application support to be activated. For IBM Tivoli Monitoring V6.2.3, auto refresh
enables the monitoring server and portal server to provide dynamic application
refresh after a self-describing agent installation event.
The non-intrusive auto refresh operation occurs when a new self-describing agent
initiates an application installation through the IBM Tivoli Monitoring
infrastructure. The processing is triggered the first time a self-describing agent
connects to a monitoring server and the application support is not already present
at the remote monitoring server or hub monitoring server.
If the portal server database is restarted while the portal server is still running,
then the portal server must be restarted for the support to finish updating the
portal server. In order for auto refresh on the portal server to work correctly, the
portal server database must be running.
Auto refresh guarantees that you have continuous access to the product’s metadata
to support monitoring activities during a self-describing agent refresh, by using
existing metadata and when the metadata auto-refresh completes, the new
metadata becomes available. Some internal monitoring server components provide
notification when you have new metadata, for example, to move pending wait
situations to started.
<blank> The default value. This value indicates that seeding has not yet run or does not
apply to this product. The SEEDSTATE state applies only to self-describing agent
records that have an ID of TMS.
I Product seeding in progress.
Y Product seeded.
N Product not seeded (SQL file not found).
E Seeding Error.
During the monitoring server startup, messages are produced in the TEMS MSG2 log
and audit log facility when changes or self-describing agent installation errors are
detected in installed products. The monitoring server application support
installation records are updated as needed to reflect the changes indicated by the
MSG2 messages or audit log. The TEMS RAS1 log contains trace messages that show
the success or failure of application support changes. Inspect the MSG2 messages
and audit log messages in the IBM Tivoli Monitoring Troubleshooting Guide and
complete the following actions:
v Verify that detected changes in installed products were expected. If the changes
were unexpected or incorrect, take the required action to install the correct
product versions, through a self-describing agent installation or manual
installation.
v If any errors are noted in a self-describing agent installed product, clean up the
application support installation records, if required. You can do this by deleting
the records for the failed installations by using the tacmd deleteappinstallrecs
command, and reinitiate the self-describing agent installations, if required. See
the IBM Tivoli Monitoring Command Reference for commands that you can use to
perform these tasks.
Note: The self-describing agent feature does not automate the installation of agent
language packs. Language pack installation procedures for self-describing agents
are the same as the procedures for standard agents. For more information, see
“Installing language packs” in the IBM Tivoli Monitoring Installation and Setup
Guide.
Disable the self-describing feature any time you do not want automatic update and
propagation of self-described agent application metadata to occur for a specific
monitoring server. Then, the application support for the agent must be manually
installed and activated at each monitoring server and portal server. By default the
self-describing capability for remote monitoring servers is turned on, and for hub
monitoring servers it is turned off.
Best practice is to control the self-describing agent capability from the hub
monitoring server, since enabling or disabling at the hub monitoring server affects
all remote monitoring servers and agents that connect to it.
Procedure
v
1. On the computer where the monitoring server is installed, in the Manage
Tivoli Enterprise Monitoring Services application, right-click Tivoli
Enterprise Monitoring Server and select Advanced→ Edit ENV file.
2. Edit the existing environment variable: KMS_SDA=Y | N
v
1. On the computer where the monitoring server is installed, change to the
<install_dir>/config/ directory.
2. Open the <tems_hostname>_ms_<tems_name>.config file.
3. Edit the existing environment variable: KMS_SDA=Y | N
v See KMS_SDA in the IBM Tivoli OMEGAMON XE and Tivoli
Management Services on z/OS: Common Planning and Configuration Guide
(http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/topic/
com.ibm.omegamon_share.doc_6.3.0.1/zcommonconfig/zcommonconfig.htm).
What to do next
You can then review the agent support versions in the following ways:
v Review the agent and monitoring server operations logs to determine if the
agent is operating in the standard or the self-described agent mode. The
“Managed system groups” has a link to the operations log for each monitoring
agent.
v The tacmd listappinstallrecs command returns the application support
installation records and the tacmd listSdaStatus command displays the current
self-describing agent operational status for all monitoring servers in the
Disable the self-describing feature any time you do not want automatic update and
propagation of self-described agent application metadata for one or more
individual agents. Then, the application support for the agent must be manually
installed and activated at the monitoring server and portal server. By default the
self-describing capability for agents is turned on.
Best practice is to control the self-describing agent capability from the hub
monitoring server. For more information, see “Enabling or disabling the
self-describing capability at the monitoring server” on page 308.
Procedure
v
1. On the computer where the monitoring agent is installed, in the Manage
Tivoli Enterprise Monitoring Services application, right-click the agent and
select Advanced→ Edit ENV file.
2. Edit the existing environment variable: TEMA_SDA=Y | N
v
1. On the computer where the monitoring agent is installed, change to the
<install_dir>/config/ directory.
2. Open the coordinating file:
For single-instance agents: <pc>.ini
For multi-instance agents: <pc>_<instance>.ini file
Where pc is the two-character product code.
3. Edit the existing environment variable: TEMA_SDA=Y | N
v
1. Open /qautotmp/kmsparm.kbbenv.
2. Edit the existing environment variable: TEMA_SDA=Y | N
v See TEMA_SDA in the IBM Tivoli OMEGAMON XE and Tivoli
Management Services on z/OS: Common Planning and Configuration Guide
(http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/topic/
com.ibm.omegamon_share.doc_6.3.0.1/zcommonconfig/zcommonconfig.htm).
What to do next
You can review the agent support versions in the following ways:
v Review the agent and monitoring server operations logs to determine if the
agent is operating in the standard or the self-described agent mode. The
“Managed System Status workspace” has a link to the operations log for each
monitoring agent.
The IBM Tivoli Monitoring V6.2.3 or later base operating system agents are
enabled for self-description, however not all agents are enabled for self-description.
The Tivoli Performance Analyzer is not enabled for self-description. For a complete
list of agents enabled for self-description, see the IBM Tivoli Monitoring agents
enabled for self-description (SDA) topic in the IBM Tivoli Monitoring Wiki
(https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/
wiki/Tivoli%20Monitoring).
Use the following steps to determine which agents are enabled for self-description.
Procedure
v To tell prior to installation:
Look in the installation image for the K<PC>MSMAN.txt self-describing manifest
file.
– The file is located in the WINDOWS directory. For agents that run on
Windows Itanium, the file is located in the WIA64 directory.
– The file is located in the unix directory.
– For agents created using Agent Builder, the file is located in the
K<PC>/support directory.
v To tell after installation:
– Run the kincinfo -e command. Look in the SDA STATUS column to
view if the agent is enabled for self-description.
In this example, you can see the Performance Analyzer Agent has Disabled
listed in the SDA STATUS column, meaning the agent is not enabled for
self-description.
kincinfo -e
**************** Thursday, July 14, 2011 1:29:36 PM ****************
User: Administrator Group: NA
Host Name: ICVW3A03 Installer: Ver: 062300000
CandleHome : C:\IBM\d1191a\ITM
Installitm : C:\IBM\d1191a\ITM\InstallITM
********************************************************************
...Application support propagation
PC PRODUCT DESC PLAT VER BUILD SDA STATUS
<inst_dir>/bin/cinfo -e
*********** Thu Jul 14 13:19:41 EDT 2011 ******************
User: root Groups: root bin daemon sys adm disk wheel
Host name : icvr5d06 Installer Lvl:06.23.00.00
CandleHome: /data/tmv623-d1191a-201107110121/ITM
Version Format: VV.RM.FF.II (V: Version; R: Release; M: Modification; F: Fix; I: Interim Fix)
********************************************************************
...Application support propagation
PC PRODUCT DESC PLAT VER BUILD SDA STATUS
80 Monitoring Agent for Self Describing lx8266 03.00.00.00 201106281135 Enabled
Agent
hd Warehouse Proxy lx8266 06.23.00.00 d1191a Enabled
lz Monitoring Agent for Linux OS lx8266 06.23.00.00 11871 Enabled
Purpose
Parameters
Agent parameters
TEMA_SDA=Y | N
N disables the self-describing agent capability at the agent, whereas Y enables
it. A value of N blocks the monitoring server from retrieving any product
support files from this agent and provides you with control on a per agent
basis without stopping the self-describing agent feature on the monitoring
server for other products.
The default value is Y.
You can bring an agent under Agent Management Services management without
making any changes to the agent. As additional agents are added to a system, they
can easily be brought under Agent Management Services management.
Component relationships
The Agent Management Services uses three interfaces to communicate with other
components in the OS agent process.
Component descriptions
Agent Management Services includes two components: Agent watchdog and Agent
Management Services watchdog:
Agent watchdog
The agent watchdog performs specific availability monitoring actions
against an agent based on the policy in the agent's common agent package
(CAP) file. This component runs inside the OS agent process as a logical
component. Other than the OS agent itself, the agent watchdog watches
any monitoring agent that has an XML file in the CAP directory of the OS
agent installation.
Agent Management Services watchdog
Who watches the watchdog? That is the job of the Agent Management
Services watchdog, also known as the Proxy Agent Services Watchdog. You can
check the status of this watchdog in the Agents’ Runtime Status view in
the Tivoli Enterprise Portal. It provides similar monitoring as the agent
watchdog within the OS agent, but it is used only to watch the OS agent.
The agent watchdog within the OS agent provides additional capability
including the monitoring of other agents, responding to Tivoli Enterprise
Portal Desktop queries and handling the Take Actions using the
The Tivoli Enterprise Portal is the user interface for the Agent Management
Services services, with predefined take action commands for manually starting or
stopping management of an agent by the Agent Management Services, and for
starting or stopping an agent when it is being managed by the Agent Management
Services. These take action commands are available from the Agent Management
Services workspace pop-up menus and can be referenced in situations for reflex
automation.
Note: You can also continue use the familiar methods for starting and stopping an
agent, such as through Manage Tivoli Enterprise Monitoring Services and through
the Tivoli Enterprise Portal navigator pop-up menu.
With IBM Tivoli Monitoring V6.2.3 Fix Pack 1 or later OS agents are now
monitored through sockets in addition to the process status and cinfo check. The
socket monitored is a PIPE internally used by the Proxy Agent Services for external
requests. You can choose to restart the OS agent if it does not respond to the socket
in the consecutive number of tries specified by KCA_MAX_RETRIES_ON_PIPE
environment variable. Once the variable has been changed in the agent ENV file,
you must restart the agent for the changes to be implemented. By default the
variable is not defined, meaning that the OS agent is never restarted. You must use
a value for this variable that is greater than 5.
On the zLinux platform, Agent Management Services has the following behaviors:
v V6.2.3 Fix Pack 1 (with a clean installation): Enabled by default
v V6.2.3 Fix Pack 1 (for upgrades): Enabled or disabled, depending on the state
found before the upgrade
v V6.2.2 Fix Pack 2 or later: Disabled at installation or upon upgrade, regardless of
whether it was active or inactive prior to the upgrade
On Intel Linux and other supported platforms, the Agent Management Services is
enabled by default.
The CAP file installed by the agent is configured to be read-only and should not
be directly modified. If you want to customize the policy settings of this file, create
a copy of the file and name it with the convention kpc.xml. Watchdog
automatically detects when a new CAP file is added or a CAP file is removed from
the directory. Changes to an existing CAP file require the OS agent to be restarted
in order to pick up the changes. An update to a non-OS agent CAP file can be
done without needing to restart the OS agent. To complete this action remove the
CAP file from the directory and then after Watchdog has discovered the file has
been removed, copy the updated file back into the directory. An update to the OS
agent CAP file requires the OS Agent to be restarted.
You can have one CAP file govern multi-instance monitoring agents or create a
separate CAP file for each instance.
The elements defined in the CAP file can be viewed in the Tivoli Enterprise Portal
“Agent's Management definitions” view of the Agent Management Services
workspace. Note: Attributes not defined in the CAP file are not displayed in
“Agent's Management definitions” view.
The order of the elements is important. Review kwgcap.xsd for a formal definition
of the CAP file schema.
<checkFrequency>
The length of time between availability checks by Agent Management
Services of the managed agent. If system load is heavy, consider increasing
the checkFrequency interval along with the KCA_CMD_TIMEOUT agent
environment variable setting.
Enter the frequency value in multiples of 5 seconds, up to a maximum of
3600 seconds (1 hour). Default: 120.
<cpuThreshold>
The maximum average percent of CPU time that the agent process can
consume over a time interval equal to “checkFrequency” seconds before
being deemed unhealthy and then restarted by Agent Management
Services.
Enter the threshold percentage as a positive integer from 1 to 100.
<memoryThreshold>
Maximum average amount of working set memory that the agent process
can consume over a time interval equal to “checkFrequency” seconds
before being deemed unhealthy and then restarted by Agent Management
Services.
Enter the threshold value followed by the unit of measurement: KB, MB, or
GB. Example: 50 MB.
<managerType>
The entity that performs availability monitoring of the agent.
Enter a string value for the instance name within a <name> </name>
tagging pair.
The database and messaging agents are typically started as non-root users. For the
Agent Management Services to support this behavior, you can specify that an
agent start as a particular user in the start script of the CAP file.
The Agent Management Services rely on the same file that the autoscript files rely
on, kcirunas.cfg, to get configuration information about which user an agent
should RunAs. This information is used when the Agent Management Services
starts the agent to ensure that it runs as the correct user. In an environment where
agents are remotely deployed, use the hostname_kdyrunas.cfg file. The file is also
checked for RunAs information.
If you want to enable this support in an older CAP file, update the CAP file as
illustrated in the following example of the Tivoli Log File Agent (lo) on Linux (lz):
<startScript>
<command>$CANDLEHOME/$ITM_BINARCH/lz/bin/agentInstanceCommand.sh
lo START ##INSTANCE##</command>
<returnCodeList>
<returnCode type="OK">0</returnCode>
</returnCodeList>
</startScript>
<startScript>
To enable this support in an older CAP file, update the stop script:
<stopScript>
<command>$CANDLEHOME/$ITM_BINARCH/lz/bin/agentInstanceCommand.sh
lo STOP ##INSTANCE## ##USER##</command>
<returnCodeList>
<returnCode type="OK">0</returnCode>
</returnCodeList>
</stopScript>
For single instance agents, such as the Linux OS Agent on Linux, use the following
syntax:
<startScript>
<command>su -c "$CANDLEHOME/bin/itmcmd agent start lz" -
##USER##</command>
<returnCodeList>
<returnCode type="OK">0</returnCode>
</returnCodeList>
</startScript>
<stopScript>
<command>su -c "$CANDLEHOME/bin/itmcmd agent stop lz" -
##USER##</command>
<returnCodeList>
<returnCode type="OK">0</returnCode>
</returnCodeList>
</stopScript>
For single instance agents such as the UNIX Agent, use this syntax. It is identical
to the syntax on Linux except that - ##USER## is placed after su rather than at the
end:
<startScript>
<command>su - ##USER## -c "$CANDLEHOME/bin/itmcmd agent start ux"
</command>
<returnCodeList>
<returnCode type="OK">0</returnCode>
</returnCodeList>
</startScript>
<stopScript>
<command>su - ##USER## -c "$CANDLEHOME/bin/itmcmd agent stop ux"
</command>
<returnCodeList>
<returnCode type="OK">0</returnCode>
</returnCodeList>
</stopScript>
Related reference:
For agents of type Console, the Agent Management Services determines if the agent
is stopped by querying the operating system for the running application using the
value from the <agentPath> element of the CAP file.
For agents of type WinService, the determination is done by querying the Windows
service control manager for the status of the service defined in the <serviceName>
element of the CAP file.
For agents and instances of type ITM_Windows and ITM_UNIX, the Agent
Management Services determines if the agent is stopped by using the command
specified in the <availabilityStatusScript> element of the CAP file, which is
either kinconfg, or a script that calls cinfo.
If the operating system does not show the process in its list of running processes,
Agent Management Services knows the process is down and will attempt to restart
it using the command or script defined in the <startScript> element of the
common agent package file. If there is no CAP file, the operating system is
checked.
Managed agents that are configured but not started will be automatically started
by the watchdog within 30 minutes of being configured. Managed agents whose
configured instances are started by the user will be discovered immediately and
appear in the Agents' Availability Status view.
The action taken will persist until you use the opposing action or start or stop an
agent with another method (Tivoli Enterprise Portal, Manage Tivoli Monitoring
Services, or at the command line). In the Agents Management Status table view,
right-click the row of the agent whose status you want to change, then select the
action:
AMS Recycle Agent Instance
Use this action to stop and and restart a particular instance of the
monitoring agent.
AMS Reset Agent Restart Count
Use this agent to return to 0 the count of agent attempts to restart.
For example, to start managing the Windows OS Agent (displayed in the Agent
Management Services workspace, Agent Management Status view as Unmanaged),
right-click the row and click Take Action > Select. Select the AMS Start
Management action from the list of possible actions. The command reads,
NT:AMS_Start_Manage "Windows OS Agent". Click OK to start managing the agent.
After you click Refresh, the Universal Agent status changes to Managed.
For further information on each command and Take Action commands in general,
see the Tivoli Enterprise Portal User's Guide and the user's guide for the specific
agent.
Related reference:
Monitoring agents start independently of their monitoring server and they collect
data, run situations, and register events when they are disconnected from the
monitoring server. This is the default behavior, which can be adjusted for greater
or less autonomy.
You can configure specialized XML files to define and run situations locally, to
collect and save historical data locally, and to emit Simple Network Management
Protocol (SNMP) alerts or Event Integration Facility (EIF) events or both to a
corresponding receiver without connection to a monitoring server. These
specialized XML files are available for both enterprise monitoring agents and
system monitor agents.
Autonomous capabilities
In addition to the built-in autonomous capability of Tivoli Enterprise Monitoring
Agents and Tivoli System Monitor Agents, you can configure special XML files that
require no connection to a Tivoli Enterprise Monitoring Server. With these XML
files you can define and run situations locally, emit situation events as SNMP alerts
or EIF events to a receiver, collect and save historical data locally, and use
Centralized Configuration to distribute XML file updates to selected monitoring
agents.
Tivoli Enterprise Monitoring Agent
Tivoli Enterprise Monitoring Agents are configured for autonomous
operation by default: The agent starts and continues to run with or without
connection to its monitoring server. With no connection to the monitoring
server, the agent can continue running situations autonomously; when the
agent connects to the monitoring server, it uploads situation events that
took place while it was disconnected. This incurs use of additional disk
space at the agent.
Some situations might not be able to be evaluated completely on the agent
alone and are unable to run when there is no connection to the monitoring
server. For example, situations using a group function such as COUNT or
AVG in the formula must be evaluated at the monitoring server. Even if
the agent or the host system is restarted, the events are persistently
preserved and uploaded on reconnect. This happens automatically on all
Situation limitations
The types of formula functions that can be used in situations are limited. Private
situations can be defined for Tivoli Enterprise Monitoring Agents and Tivoli
System Monitor Agents.
To use private situations effectively, you need to understand how they are different
from enterprise situations.
Table 32. Availability of situation formula functions for enterprise situations whose events are
emitted from the hub monitoring server and private situations whose events are emitted
from the monitoring agent
Situation functions
that can be
evaluated at the Situation functions that can be evaluated at
monitoring server the monitoring agent
Supported in Supported in Supported in private
Formula function enterprise situations enterprise situations situations
Cell functions
CHANGE available available not available
Monitoring agents that use subnodes, such as subnode agents created with Agent
Builder, Monitoring for Energy Management, and Agentless Monitors, can emit an
SNMP alert for only one subnode per agent instance where the situation evaluates
to true; and for no other subnodes where the same situation evaluates to true.
For each agent instance, data samples are collected in one attribute group table.
These metrics are filtered by subnode when displayed in the Tivoli Enterprise
Portal, but situations running on multiple subnodes for an agent instance are
actually evaluating on a single table. If a situation becomes true on one subnode,
an SNMP alert defined for that situation is emitted, but no SNMP alerts are
emitted for that situation on any other subnodes because no further rows are
processed in the table.
Here are some alternatives to emitting SNMP alerts for agents with subnodes:
v Forward events from the monitoring server to an EIF receiver.
v When you configure the agent, define only one subnode for an agent instance.
v Define a separate situation for each subnode and distribute that situation to only
a single subnode. In the following example,
situation KAB_Log_Message is distributed to ALL LOG subnodes in the AB
agent
situation KAB_Log1only_Message is distributed to only the AB:uxlog1:LOG
subnode
ASCII characters use one byte and comprise the first 128 characters. You
can write the XML file in any text editor. For non-ASCII characters, such as
characters with diacritics and Kanji characters, an editor that can save the
file as UTF-8 is required.
Because UTF-8 is not easily displayed or edited on z/OS, the XML can be
encoded in UTF-8 or using the agent's code page. The code page is set in
the agent environment file with the environment variable LANG, such as
LANG=en_US.IBM-1047. The environment file can be found in
&hilev.&rte.RKANPARU, with member name KPCENV (where PC is the
two-character product code). The LANG variable should match your
terminal emulator if you are using the emulator to edit the file. The default
code page for FTP is IBM-1047 if you are editing the file on Windows,
Linux, or UNIX and then uploading the file as ASCII text to the host.
Procedure
1. While the watchdog process is running, move the common agent package
(CAP) file named kpc_default.xml (where pc is the two-character product code)
out of the CAP directory to a temporary location. The file is located in the
KCA_CAP_DIR directory.
install_dir\TMAITM6[_x64]\CAP\
install_dir/config/CAP
Removing the file from the CAP directory renders the agent invisible to the
Agent Management Services.
2. Modify all instances of <managerType> in the CAP file to enable or disable
management:
v <managerType>ProxyAgentServices</managerType> to enable management.
v <managerType>NotManaged</managerType> to disable management.
Results
The updated Agent Management Services settings are processed after the CAP file
is placed in KCA_CAP_DIR.
Private situations
Define private situations for monitoring criteria and the resulting events that are
pertinent to your local agent environment or to an event receiver and not relevant
to the Tivoli Enterprise Monitoring environment. Private situations can be defined
for Tivoli Enterprise Monitoring Agents and Tivoli System Monitor Agents.
Built into the agent framework of the Tivoli Management Services infrastructure is
the ability to create situations that run locally and trigger events on the computer
where you have either a Tivoli Enterprise Monitoring Agent or Tivoli System
Monitor Agent installed.
Enterprise situations are created with the Tivoli Enterprise Portal Situation editor or
with the CLI tacmd createSit command. Enterprise situations send events to the
monitoring server and can forward events to an Event Integration Facility receiver
such as a IBM Tivoli Enterprise Console event server or Netcool/OMNIbus Probe
for Tivoli EIF when the hub monitoring server has been configured to forward
events. Enterprise situation events can also be sent as SNMP alerts to a receiver
such as the Netcool/OMNIbus SNMP Probe
Private situations are created in a local private situation configuration XML file for
the agent. Eligible situation definitions that were exported from the monitored
enterprise can also be added to the file to create situations. The events generated
by private situations can remain local to your workstation or be sent as SNMP
alerts to a receiver such as the Netcool/OMNIbus SNMP Probe. The private
situation configuration file resides in the agent localconfig/pc directory, one file
per agent, and it contains all the private situation definitions for the agent.
This example of a private situation configuration XML file for the Windows OS
agent has two situations defined. You can create situations in the file by entering
them manually.
You can also create situations in this file by exporting existing enterprise situations
from the monitoring server, using the CLI tacmd bulkExportSit and then copying
the exported situations that are eligible for use as private situations from their
XML file to the agent Private Situation configuration file. The last situation (named
Disk_Queue) in the example came from an exported situation XML file.
<PRIVATECONFIGURATION>
<PRIVATESIT>
<SITUATION>NT_Missing_Scheduler_pr</SITUATION>
<CRITERIA>
<![CDATA[ *MISSING NT_Process.Process_Name *EQ ("schedule")]]>
</CRITERIA>
<INTERVAL>001000</INTERVAL>
</PRIVATESIT>
<PRIVATESIT>
<SITUATION>NT_Paging_File_Critical_pr</SITUATION>
<CRITERIA>
<![CDATA[ *VALUE NT_Paging_File.%_Usage *GE 80 ]]>
</CRITERIA>
<INTERVAL>001500</INTERVAL>
</PRIVATESIT>
<PRIVATESIT>
<SITUATION>Disk_Queue</SITUATION>
<PDT><![CDATA[ *IF *VALUE NT_Physical_Disk.Avg_Disk_Queue_Length
*GE 0.004 ]]></PDT>
<REEV_TIME>003000</REEV_TIME>
</PRIVATESIT>
</PRIVATECONFIGURATION>
When the agent is initialized, an XML parser examines and validates the private
situation definitions. All XML parsing error messages are recorded in the agent
operations log. (See the IBM Tivoli Monitoring Troubleshooting Guide
(http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/topic/
com.ibm.itm.doc_6.3fp2/ic/landing_troubleshoot.htm).)
The events that are opened when a situation becomes true can be sent as
SNMPv1/v2 traps or SNMPv3 informs when an SNMP trap configuration file is
created and a receiver such as the Netcool/OMNIbus SNMP Probe has been
configured to receive them; or as EIF events when an EIF event configuration file
is created and a receiver such as the IBM Tivoli Enterprise Console event server or
Netcool/OMNIbus Probe for Tivoli EIF is configured to receive them. As well, the
Agent Service Interface provides a summary report of situation activity.
You create a private situation file named pc_situations.xml and save it to the
install_dir/localconfig/pc (where pc is the product code). If you prefer to name
the file differently or use a different path, the IRA_PRIVATE_SITUATION_CONFIG
and IRA_LOCALCONFIG_DIR agent environment variables are provided for you
to change the file name and path.
To edit or delete a private situation, make the changes in the private configuration
XML file where it was defined, then redistribute the situation locally or remotely.
Local distribution
After editing the private configuration file and saving it, you can restart
the agent to reload the private situation definitions.
Alternatively, you can log on to the Agent Service Interface and enter
private situation requests to start, stop or recycle individual private
situations. See “Starting the Agent Service Interface” on page 402 and
“Agent Service Interface request - Private situation control” on page 422.
Remote distribution
Use a configuration load list to specify the private configuration file for the
monitoring agent to pull from the central configuration repository and
activate. See “Centralized Configuration” on page 429.
Summary
If you prefer to name the file differently or use a different path, use the
IRA_PRIVATE_SITUATION_CONFIG and IRA_LOCALCONFIG_DIR agent
environment variables to change the file name and path. For detailed information
about the environment variables, see the “Environment variables” topic in the IBM
Tivoli Monitoring Installation and Setup Guide.
Elements
XML tags are case-insensitive. All other parameters are case-sensitive. For example,
you can enter <PRIVATESIT>, <PrivateSit>, or <privatesit>.
Note: You can use the SITS.xsd schema file, located in the samples/
PrivateConfigSamples directory on the Agent DVD image, to validate private
situation XML files. However, the schema file requires the XML tag names to be in
uppercase.
The attribute description topics for your product should specify whether
the value is scaled. For distributed agents, you can also review the
attribute file for scal in the attribute definition. For example, khd.atr for
the Warehouse Proxy agent has a work queue insertion rate attribute with
scal 2. Location of kpc.atr files: <install_dir>\TMAITM6\
ATTRLIB; <install_dir>/platform/<pc>/tables/
ATTRLIB, where platform is the operating system and pc is the product
code.
This example shows a hexadecimal integer as the comparison value:
<CRITERIA><![CDATA[ *VALUE Disk.Mount_Point_U *EQ ’/opt’ *AND
*VALUE Disk.Space_Used_64 *GT 0x80000000 ]]></CRITERIA>
Usage notes:
v Integer attributes are not supported in the regular expression
predicate.
v Enumerated attributes are supported in the regular expression
predicate, however, the actual column attribute value must be
used in constructing the regular expression itself. The enumerate
tags.
<AUTOSOPT>
This is required if an action <CMD> is specified. It defines the action
command execution options, WHEN (X), FREQUENCY (Y), WHERE (Z).
The default is NNN:
WHEN= Optional. "Y" to run the command for each item; or "N" to run
the command on only the first row of data returned that meets the
situation criteria. If the attribute group returns multiple rows of data
and more than one row satisfies the condition, you can choose to issue
the command on only the first row that meets the criteria or once for
each row that meets the criteria. Default: "N".
FREQUENCY= Optional. "Y" to issue the command every time the
situation evaluates to true; or "N" to issue the command when the
situation is true, but not again until the situation evaluates to false,
followed by another true evaluation. Default: "N".
WHERE= "N" to run the command at the agent. Default: "N" Because
there is only one possible setting for “where”, you do not need to
include it in the AUTOSOPT element.
<AUTOSOPT When="Y" Frequency="Y" />
<DISTRIBUTION>
Optional. Used for subnode-based products that register and manage
subnodes. This element specifies a list of managed system names that must
be separated by only a comma (,). Each subnode managed system name
must not be longer than 32 characters. The specified MSN cannot be the
MSN of the managing agent. Managed System List (MSL) names, such as
If you already have enterprise situations for a Tivoli Enterprise Monitoring Agent,
you can run the bulk export situation command or the view situation command to
get situation definitions for the specified agent in the XML format that is
acceptable to the private situation configuration file. Not all exported situations are
valid; only those that use the *VALUE or *MISSING formula functions. See
“Situation limitations” on page 327 for other restrictions.
Elements
XML tags are case-insensitive. All other parameters are case-sensitive. For example,
you can enter <SITNAME>, <SitName>, or <sitname>.
<TABLE>
This is the root element of the exported situation XML file. In the private
situation configuration file, the TABLE tagging (and everything between)
from the exported situation is processed as a private situation definition.
<ROW>
This is the child element to follow TABLE.
<SITNAME>
Monitoring situation name. The situation name must begin with a letter
and can be up to 31 letters and numbers and _ underscores. Within each
set of SITNAME begin and end tags is the complete situation definition.
Example:
<SITNAME>Free_DiskSpace_Low</SITNAME>
Normalize the value by shifting the decimal point to the right by three
places: 0.004 is 4 or a value such as the one shown here.
<CRITERIA><![CDATA[ *IF *VALUE NT_Physical_Disk.Avg_Disk_Queue_Length
*GE 4.123 ]]></CRITERIA>
<CMD>
Optional. Defines the action command or script to invoke when the
situation is true. Enclose the command in the <![CDATA[ ]]> section.
Example:
<CMD><![CDATA[netstat >.\logs\netstat.dat]]></CMD>
<AUTOSOPT>
This is required if an action command <CMD> is specified. It defines reflex
automation action command execution options, in order XYZ, between
begin and end tags. The default is NNN:
Only take action on first item
Don't take action twice in a row (wait until situation goes false
then true again)
Execute the Action at the Managed System (Agent)
Tip: Each exported situation is given its own XML file. If your private situations
will initially result from an export of your enterprise situations, create an XML
with PRIVATECONFIGURATION begin and end tags, then paste the TABLE begin
and end tags and everything contained in them into the file for each situation that
you want to include. For exported situations, the TABLE tags are equivalent to the
PRIVATESIT tags.
Tip: Sample private situation configuration files are provided on the Tivoli
Monitoring Agent installation media in the PrivateConfigSamples directory.
Linux OS lz_situations.xml
<PRIVATECONFIGURATION>
<!-- Situation Description: Percentage of time the processor is busy
is extremely high -->
<PRIVATESIT>
<SITUATION>Linux_High_CPU_Overload_pr</SITUATION>
<CRITERIA>
<![CDATA[ *VALUE Linux_CPU.Idle_CPU *LT 10 *AND *VALUE Linux_CPU.CPU_ID
*EQ Aggregate ]]>
</CRITERIA>
<INTERVAL>001500</INTERVAL>
</PRIVATESIT>
<!-- Situation Description: Percentage of packet collisions during data
transmission is high -->
<PRIVATESIT>
<SITUATION>Linux_High_Packet_Collisons_pr</SITUATION>
<CRITERIA>
<![CDATA[ *VALUE Linux_Network.Collision_Percent *GT 10 ]]>
</CRITERIA>
<INTERVAL>000500</INTERVAL>
</PRIVATESIT>
<!-- Situation Description: Percentage of available i-nodes is low -->
<PRIVATESIT>
<SITUATION>Linux_Low_Pct_Inodes_pr</SITUATION>
<CRITERIA>
<![CDATA[ *VALUE Linux_Disk.Inodes_Used_Percent *GT 80 ]]>
</CRITERIA>
<INTERVAL>001500</INTERVAL>
</PRIVATESIT>
<!-- Situation Description: Percentage of space available on a filesystem
is low -->
<PRIVATESIT>
<SITUATION>Linux_Low_Pct_Space_pr</SITUATION>
<CRITERIA>
<![CDATA[ *VALUE Linux_Disk.Space_Available_Percent *LT 15 ]]>
</CRITERIA>
<INTERVAL>001500</INTERVAL>
UNIX OS ux_situations.xml
<PRIVATECONFIGURATION>
<!-- Situation Description: Reports High CPU processes -->
<PRIVATESIT>
<SITUATION>UNIX_CMD_Runaway_Process_pr</SITUATION>
<CRITERIA>
<![CDATA[ *IF *VALUE Process.CPU_Utilization *GT 95 ]]>
</CRITERIA>
<INTERVAL>001000</INTERVAL>
</PRIVATESIT>
<!-- Situation Description: Process CPU utilization is greater than
or equal to 85% -->
<PRIVATESIT>
<SITUATION>UNIX_CPU_Critical_pr</SITUATION>
Windows OS nt_situations.xml
<PRIVATECONFIGURATION>
<!-- Situation Description: One of the NT Logs is close to capacity -->
<PRIVATESIT>
<SITUATION>NT_Log_Space_Low_pr</SITUATION>
<CRITERIA>
<![CDATA[ *VALUE NT_Monitored_Logs_Report.%_Usage *GE 95 ]]>
</CRITERIA>
<INTERVAL>001500</INTERVAL>
</PRIVATESIT>
<!-- Situation Description: Test if the NT Scheduler process is running -->
<PRIVATESIT>
<SITUATION>NT_Missing_Scheduler_pr</SITUATION>
<CRITERIA>
<![CDATA[ *MISSING NT_Process.Process_Name *EQ ("schedule") ]]>
</CRITERIA>
<INTERVAL>001000</INTERVAL>
</PRIVATESIT>
<!-- Situation Description: Percent of the Page File in use is too high -->
<PRIVATESIT>
<SITUATION>NT_Paging_File_Critical_pr</SITUATION>
<CRITERIA>
<![CDATA[ *VALUE NT_Paging_File.%_Usage *GE 80 ]]>
</CRITERIA>
<INTERVAL>001500</INTERVAL>
</PRIVATESIT>
<!-- Situation Description: Percent of the Page File in use is rising -->
<PRIVATESIT>
<SITUATION>NT_Paging_File_Warning_pr</SITUATION>
<CRITERIA>
Private history
Private history is the collection and short-term storage of data from a local
monitoring agent. Define historical collection in a private situation configuration
file for an agent, then use the Agent Service Interface to view the short-term
history.
Private history is configured in the private situation configuration file
Local historical data collection is defined in the local private situation
configuration file for each attribute group that you want to save historical
data for. You can define private history with or without private monitoring
situations. There can be only one active history data collection per
application table (attribute group).
Use the <HISTORY> tag to specify each attribute group that you want to
collect historical data for. Optionally, you can use the EXPORT parameter
to specify an interval in minutes for exporting data to the Tivoli Data
Warehouse. You can also export data for analytical consumption by using
the USE parameter.
Use the <WAREHOUSE> tag to specify a Warehouse Proxy agent to which
historical data is exported.
See “Private situation XML specification” on page 335.
Agent Operation Log
All XML validation error messages are saved to the Agent Operation Log.
The private history is completely separate and independent of historical
data collection and the Tivoli Data Warehouse configuration within IBM
Tivoli Management Services. Each private short-term history table data
resides in its own history binary file.
Short-term history file names
The table name for an attribute group is also the history binary file name
prefixed with PVTHIST_; one unique history binary file per table. As part
of the private history configuration, you can set the RETAIN attribute to
manage the history file size. You can configure an alternative private
history file location with the CTIRA_HIST_DIR agent configuration
parameter.
Short-term history file directory
The agent outputs all private history files to this subdirectory:
<install_dir> \TMAITM6\logs
<install_dir>/<arch>/<pc>/hist
You can configure an alternative private history file location with the
CTIRA_HIST_DIR agent configuration parameter.
A table belongs to a PDS group and a number of VSAM files are allocated
for a PDS file group for storing table data. The PDS OVERRIDE statement
can be used to modify the table or group assignment (or both) and
properties. The KN3 group specification is illustrated here:
OVERRIDE TABLE=KN3BPG APPL=KN3 WRAP=0 GROUP=KN3
GROUP=KN3 FILE=DSN:CCAPI.COMMON.NV.CIDSSP13.RKN3HIS3
GROUP=KN3 FILE=DSN:CCAPI.COMMON.NV.CIDSSP13.RKN3HIS2
GROUP=KN3 FILE=DSN:CCAPI.COMMON.NV.CIDSSP13.RKN3HIS1
The PDS stores table data using the application name, table name,
WRITETIME, and any indexed columns as the VSAM file key. For Private
History, using KN3BPG table – VTAM_Buffer_Usage_By_Category as an
example, the following two configuration steps are required:
1. Add application tables that require history data collection as new tables
to PDS dictionary, in data set RKANPARU member KN3PDICT:
a. Make a copy of the KN3BPG table definition.
b. Change TABLE=KN3BPG to TABLE=ZN3BPG.
c. Change ID=N303 to a unique ID (for example, N399).
2. Add application tables OVERRIDE statement in data set RKANPARU
member KN3PG.
a. Copy the table KN3BPG OVERRIDE statement, if any.
b. Change TABLE=KN3BPG to TABLE=ZN3BPG.
Both enterprise- and private history table data are stored and read by the
PDS from the same VSAM datasets using the unique key. Alternatively,
you can assigned private history to its own PDS file group and allocate
separate VSAM dataset for the private history group.
Attention: This information does not apply to private situations. For information
about private situations see “Private situation XML specification” on page 335.
Any updates made to the local XML thresholds file take effect after the agent is
restarted. Situation overrides that go through the Tivoli Enterprise Monitoring
Server (they were defined in the Tivoli Enterprise Portal or with the CLI tacmd
setOverride) or applied through the Agent Service Interface take effect
immediately.
After reading the XML document, the agent synchronizes the defined threshold
override specifications against all data collection requests of all defined table
definitions. All threshold parameters, calendar, and situation updates and deletion
take effect immediately. The agent outputs the complete threshold override
specification XML document to the named local threshold file.
See the “Environment variables” topic in the IBM Tivoli Monitoring Installation and
Setup Guide for the agent environment variables that enable local situation override
operation.
Another way to look up the names of the columns to be used when specifying
overrides is through ASI. Open ASI > Queries and select the table name. ASI
returns complete a table schema including the table display name and display
names for all table columns.
Elements
Example
<overrides>
<situation name="Check_Event" table="NT_Event_Log">
<threshold attr="Source"
value="Symantec Antivirus"
start="08:00" stop="17:00" />
</situation>
<situation name="NT_Available_Bytes_Critical" table="NT_Memory">
<threshold attr="Available_Bytes"
value="750000"
start="08:00" stop="17:30"
cron=" * * * * 1-5" />
</situation>
<situation name="NT_Disk_Space_Low">
<threshold name="FREEMGBTES"
value="10"
cron="31-59 8-20 */2 * *"
</threshold>
</situation>
<situation name="NT_Log_Space_Low">
<threshold name="USAGE"
value="75"
start="08:00" stop="18:00"
cron="* * * * MON,WED,FRI"
</threshold>
</situation>
<situation name="Message_Queue_Warning" table="Queue_Statistics">
<KEY column="ORIGINNODE" value="SYSG:NETQ3">
<threshold attr="Queue_Depth"
value="10"
cron="0-30 8-17 * 3,6,9,12 *"
</threshold>
</KEY>
</situation>
<situation name="NT_Process_CPU_Critical" table="NT_Process">
<KEY attr="Process_Name" value="_Total">
<threshold attr="%_Processor_Time"
value="70"
start="06:00" stop="21:30"
cron="* * * * 1-5" />
</KEY>
</situation>
<situation name="NT_System_File_Critical" table="NT_System">
<threshold attr="File_Data_Operations/Sec"
value="50000"
cron="* 6-22 * * SAT,SUN"
</threshold>
</situation>
<situation name="DISKFULL">
<key column="INSTCNAME" value="C:">
<threshold column="PCFREE">5</threshold>
</key>
<key column="INSTCNAME" value="D:">
SNMP alerts
Tivoli Enterprise Monitoring Agents and Tivoli System Monitor Agents can be
configured to send alerts to an SNMP receiver like Netcool/OMNIbus, using the
Netcool/OMNIbus SNMP Probe, or Tivoli NetView. Sample OMNIbus rules files
are provided to illustrate some key integration ideas.
XML tags are case-insensitive. All other parameters are case-sensitive. For example,
you can enter ADDRESS, Address, or address.
Note: You can use the SNMP.xsd schema file, located in the samples/
PrivateConfigSamples directory on the Agent DVD image, to validate SNMP trap
configuration XML files. However, the schema file requires the XML tag names to
be in uppercase.
SNMP element
The SNMP element of the trap configuration XML specification is the top-level
XML element. TrapDest, TrapAttrGroup, and Situation are elements within the
SNMP begin and end tags.
<SNMP>
<TrapDest name="OMNIbus2" Address="nswin21a" Stat="Y" />
<situation name="*" target="OMNIbus2" />
</SNMP>
TrapDest element
Use TrapDest elements in a trap configuration XML file to define a trap receiver.
The TrapDest element requires the name and address attributes. Default values are
used for any other attributes that are not specified.
<TrapDest name=”LABEL” Address=”HOSTNAME”/>
In this syntax example, situations written for the Windows OS Paging File attribute
group will send an SNMP trap with the server name, usage percentage and the
usage peak values to the event receiver.
<TrapAttrGroup Table="NT_Paging_File" TrapAttrList="Server_Name,
%_Usage,%_Usage_Peak" />
This element can be used to decrease the amount of attribute data sent in each trap
request, reduce the possibility of trap fragmentation, and reduce the received data
to include only what is relevant.
The TrapAttrGroup element sets the default attributes that will be sent for all
situations that run against the Table. Individual situations can override the
TrapAttrGroup settings by specifying a TrapAttrList attribute in the situation
element.
Use the TrapAttrList option to include the *COUNT virtual data attribute in the list
of normal product attributes that get added to the SNMP trap. Example of the
TrapAttrList option for specific product attribute groups:
<SNMP>
<situation name="*" target=*"/><TrapAttrGroup Table="KLZ_Process"
TrapAttrList="Process_Command_Name.COUNT,System_Name,Process_ID"/>
</SNMP>
If a TrapAttrGroup element is not defined for an attribute table, all attributes in the
situation's data row are added to the sitAttributeList varbind of the traps sent for
situations based on this attribute table. Attributes used in the situation predicate
are added first and remaining attributes are added until the PDU maximum length
of 1500 bytes is reached.
The product attribute names specified in the SNMP Trap configuration file are case
insensitive. During the input validation process, the input attribute names are
normalized back to their original product definitions so that the SNMP Trap
process can match the specified input attribute name with the correct trap data.
The TrapAttrGroup element requires that you incorporate at least one <situation>
element. Any configuration without at least one <situation> element will be
rejected.
Table 34. TrapAttrGroup element XML specification
Attribute Description
Table= The name of the attribute table. For manually creating this
file, you can look in the agent's attribute file, kpc.atr to
identify the table names, where pc is the two-character
product code.
TrapAttrList= A comma delimited list of attributes to be included in the
sitAttributeList varbind of the traps sent for situations
based on this attribute table.
Note: When you use the .COUNT extension in the trap configuration file with
TrapAttrList specification, consider these restrictions:
Situation element
Use situation elements in a trap configuration XML file to define the trap sent for
the situation.
<situation name=”Situation_ID” target=”TrapDest_Name” />
The Situation element requires the name and target attributes. Default values are
used for any other attributes that are not specified. The * asterisk wildcard can be
specified for the situation name or target or both:
v Specifying the wildcard for situation name represents all situations. For example
the following line sends traps for all defined true situations to the defined
TrapDest named trapProbe1:
<situation name=”*” target=”trapProbe1” />
Note: When you use the .COUNT extension in the trap configuration file with
TrapAttrList specification, consider these restrictions:
v The .COUNT extension is case insensitive. COUNT, count, or Count is
acceptable.
v An error occurs when the attribute using the .COUNT extension in the
TrapAttrList is not the same attribute defined in the situation *COUNT
predicate. The *COUNT calculated virtual data attribute COUNT_attribute_name
is not included in the trap.
v Any situation that a <situation> element configuration applies to and that
contains a reference to the .COUNT extension must have *COUNT defined in its
predicate. Otherwise, an error message is generated.
v The mismatch between any TrapAttrList input attributes and the situation
definition is not detected until the SNMP event is processed. As this condition is
too late to reject the situation, an error message is generated and the virtual
COUNT_attribute_name is not included in the trap.
v Any value provided for the extension other than .COUNT is rejected with an
error message. For example, defining TrapAttrList="Process.MAX” generates an
error.
v Defining more than one .COUNT extension within a <situation> or
<TrapAttrGroup> element generates an error and the configuration is rejected.
v When using the situation wildcard (*), specify .COUNT. All situations must
contain the *COUNT predicate or they are flagged with an error.
StatTrap
Use the StatTrap element in an SNMP trap configuration file to modify the default
configuration of the predefined agent life cycle status traps.
In this syntax example, the predefined trap for EE_HEARTBEAT was modified to
specify severity 1 (Indeterminate) for the event, a 30-minute sampling interval, and
trap category 3 (Status).
<StatTrap name="EE_HEARTBEAT" sev="1" interval="30" cat="3" />
There are eight predefined agent life cycle traps and their default values are given
in this table. By default, these traps are sent to all TrapDest trap destinations where
the Stat attribute is “Y”. If the Stat attribute is omitted from a TrapDest element the
default value is “Y”.
Table 36. Agent life cycle status traps
Attribute Description Severity Category
EE_HEARTBEAT A heartbeat indicates that the agent is 1 – Indeterminate 3 – Status
running and events emitted can reach the
trap destination. This is the only status
trap with a set interval: 15 minutes.
EE_AUTO_ENTER The agent has entered autonomous mode. 1 – Indeterminate 3 – Status
EE_AUTO_EXIT The agent has exited autonomous mode. 1 – Indeterminate 3 – Status
The itmpwdsnmp uses GSKIT to either interactively encrypt a string or to encrypt all
SNMP password strings in a trap configuration xml file.
itmpwdsnmp [[-b |-n ]your_agent_trapcnfg.xml][-?]
where:
no arguments specifies interactive mode
-b specifies to create a backup file. There is no prompting to delete the
backup file.
-n specifies that no backup file is to be created.
your_agent_trapcnfg.xml is a trap configuration xml file that contains
plaintext SNMP password strings.
-? displays usage
If a -b or -n backup option is not specified when encrypting a Trap
Configuration xml file, you are prompted to delete the backup. The backup
of the original input Trap Configuration xml file is created in the same
directory as the original with a date and timestamp appended to the
original file name.
install_dir\TMAITM6\itmpwdsnmp.bat
install_dir/bin/itmpwdsnmp
CLI examples
This command will interactively encrypt a string:
itmpwdsnmp
Then copy the encrypted string into the trap configuration file.
Program Summary
Community strings encrypted 1
AuthPassKey strings encrypted 2
EncryptPassKey strings encrypted 1
They are defined in the canbase.mib and cansyssg.mib files that are available on
the IBM Tivoli Monitoring IBM Tivoli Monitoring Agents installation media.
agentStatusEvent
The agentStatusEvent is a monitoring agent operational status information
trap generated by the Tivoli Autonomous Agent SNMP Event Exporter to
inform and notify about a specific agent operational event.
agentSitSampledEvent
A sampled situation event was detected. This trap was generated by the
Tivoli Autonomous Agent SNMP Event Exporter in response to a situation
threshold being exceeded at the time of the data sampling.
agentSitPureEvent
A pure situation event was detected. This trap was generated by the Tivoli
Autonomous Agent SNMP Event Exporter in response to a situation
threshold being exceeded. The variables in a pure event trap are identical
to those for a sampled event trap except there is no agentSit-
SampleInterval because pure events are not sampled; rather the arrival of
unsolicited data from the monitored attribute group causes the situation to
become true. A situation created with an attribute group for a system log,
for example, opens a pure event when a log entry arrives.
Have the IBM Tivoli Monitoring V6.2.2 or later Agents DVD available. Verify that
Tivoli Netcool/OMNIbus V7.x is installed and that the SNMP Probe is installed.
Do not configure an enterprise situation for emitting SNMP alerts to the SNMP
Probe if the hub monitoring server is also configured to forward events for the
Procedure
1. Copy the Tivoli Monitoring rules file and lookup file.
a. Locate the mibs/sample_rules/omnibus directory on the Tivoli Monitoring
V6.2.2 or later Agents installation media.
b. Copy these management information base files to $OMNIHOME/probes/arch/
on the computer where the SNMP Probe is installed:
ibm-TIVOLI-CANSYSSG-MIB.include.snmptrap.rules
ibm-TIVOLI-CANSYSSG-MIB.include.snmptrap.lookup
2. Reference the files in the rules that the SNMP Probe is using.
a. Open the default rules file in a text editor. The default rules file is
$OMNIHOME/probes/arch/mttrapd.rules unless specified otherwise in the
mttrapd properties file (Step 3).
b. Add the lookup table reference as the first definition:
include "<path_to_lookup_file>/
ibm-TIVOLI-CANSYSSG-MIB.include.snmptrap.lookup"
Table definitions must appear at the start of a rules file, before any
processing statements. If you are adding this statement to mttrapd.rules,
position it after the comments at the head of the file and before the first
processing statement. The fully qualified filename must be enclosed in
double quotes. Environment variables like %OMNIHOME% or
$OMNIHOME can be used. The Linux and UNIX filename convention, with
the / forward slash to delimit the path, is also used by Windows.
c. Add the rules reference in the order in which it should be processed.
include "<path_to_rules_file>/
ibm-TIVOLI-CANSYSSG-MIB.include.snmptrap.rules"
This statement should be added in the rules file in the location where it
should be processed. For example, if adding the include to the default
mttrapd.rules file, you would want the default rules to first "Check if an
SNMPv2 trap and convert to SNMPv1 style tokens". The next block of code
in the default mttrapd.rules handles Generic traps. The include statement
for the ibm-TIVOLI-CANSYSSG-MIB.include.snmptrap.rules should go after
this, possibly as the last line of mttrap.rules. You will best know where to
include the rules if you are familiar with the SNMP Probe and your event
space.
3. Review and edit the SNMP Probe properties file:
a. Open $OMNIHOME/probes/arch/mttrapd.props in a text editor.
b. Set the Protocol property to “UDP” or “ALL”. Tivoli Monitoring SNMP alerts
are sent using UDP.
c. Set the RulesFile property if the default rules file for the probe is not
mttrapd.rules.
d. Set the MIBDirs property to the path where the mib files will reside.
4. Make the Tivoli Monitoring mib files available to the SNMP Probe:
Results
You should now have these files installed on the probe system:
ibm-TIVOLI-CANSYSSG-MIB.include.snmptrap.rules
ibm-TIVOLI-CANSYSSG-MIB.include.snmptrap.lookup
can*.mib files that are provided on the Tivoli Monitoring installation media
What to do next
To activate the new rules and begin receiving alerts from Tivoli Monitoring agents,
recycle the SNMP Probe.
Because the AlertKey is included in the information that is used to construct the
Identifier, you might encounter truncation problems with 255-character AlertKeys
used to create your Identifier.
Field Size
@Node Max length 32
$autoSit-Category fixed length 1
@Type Max length 2
@Agent Max length 31
@Manager fixed length 13
$specific-trap fixed length 2
6 space delimiters 6
Total 87
This leaves 168 characters for the @AlertKey (255-87=168). If @AlertKey is defined
as $agentSit-Name + " (" + $sitDisplayItem + ")", then $sitDisplayItem must be
less than 133 characters (168-35=133).
Field Size
agentSit-Name 32
space delimiter 1
parentheses 2
Total 35
Situations written for attribute groups (such as Event Log) that generate pure
events can be deduplicated by using the $agentSit-Name, but many might require
Use case statements based on the $agentSit-Table field to identify all events based
on a specific table.
The extract command can be used to extract the value of any of the name value
pairs from the $sitAttributeList using regex pattern matching. An example is
provided in the Sample rules for agentSitPureEvent traps based on the
NTEVTLOG $agentSit-Table.
$sitDisplayItem=extract($sitAttributeList,"Description=.(.+).;.*?")
This command extracts the value of the Description key and removes the quotes.
Compatibility notes
@ExtendedAttr
OMNIbus V7.2 and greater defines the @ExtendedAttr column in the
ObjectServer. The nvp functions are provided to allow manipulation of
name-value pairs in the @ExtendedAttr alert field. The sitAttributeList
varbind is formatted to allow direct mapping into the @ExtendedAttr, but
this function is commented out to allow the rules to parse when the
MTTRAPD probe connects to an OMNIbus ObjectServer V7.0 or V7.1.
Uncomment the two lines in the ibm-TIVOLI-CANSYSSG-
MIB.include.snmptrap.rules file that set @ExtendedAttr if you are
forwarding events to OMNIbus V7.2 or greater.
# @ExtendedAttr = $sitAttributeList
@Class
The @Class alert field is used to associate Tivoli Netcool/OMNIbus Tools
with Events displayed in the Tivoli Netcool/OMNIbus EventList.
For Tivoli Netcool/OMNIbus 7.2x and below, see the Netcool/OMNIbus
documentation for more information on creating and editing classes. By
default, these class values are not defined in your ObjectServer.
Setting @Class to a value that is not defined in the OMNIbus ObjectServer
causes no problems, but if you prefer to not set the @Class, uncomment
this line in the ibm-TIVOLI-CANSYSSG-MIB.include.snmptrap.rules file to
clear the @Class field before the event is forwarded to OMNIbus.#
@Class = ""
HEARTBEAT events from SNMP and EIF are displayed on the OMNIbus event
console as they arrive and the count is incremented as new events arrive from the
agent.
Chapter 15. Agent-based services 381
The itm_heartbeat.sql file contains sample automations for processing the
Autonomous Agent Heartbeats for both EIF and SNMP. Run the SQL file to enable
the automation.
Procedure
1. Copy itm_heartbeat.sql from the Tivoli Monitoring Agent DVD
mibs/sample_rules/omnibus directory.
2. Place the copy in the Netcool/OMNIbus installation path and run the following
command:
v Where “user” is a valid user name, “password” is the
corresponding password, and “server” is the ObjectServer name
%NCHOME%\bin\redist\isql.exe -U "user" -P "password" -S "server"
< itm_heartbeat.sql
v Where “servername” is the ObjectServer name,
“username” is a valid user name, and “psswrd01” is the corresponding
password
$NCHOME/omnibus/bin/nco_sql -server servername -user username
-password psswrd01 < itm_heartbeat.sql
Results
After the OMNIbus automation is installed, the automation registers the heartbeats
from managed systems as they arrive. Individual heartbeats are no longer
displayed and counted in the event console but, if an expected heartbeat is
overdue, the automation raises a “Heartbeat missing” alert with:
Summary = ’Heartbeat Missed for:’ + heartbeat_missed.Node +
’ last received at ’ + to_char(heartbeat_missed.LastOccurrence)
What to do next
The default interval for sending the EE_HEARTBEAT status 15 minutes. You can
adjust the value by modifying the interval attribute for the heartbeat status event
in the trapcnfg.xml file for SNMP alerts and in the eifdest.xml file for EIF events
configuration file.
Especially with SNMP, one missed heartbeat does not necessarily indicate a
problem, thus the default is to raise an alert after the heartbeat is overdue: (2 x
heartbeat interval ) + 2 minutes. You can edit this in the itm_heartbeat.sql with the
entry,
-- 2 heartbeats plus 2 minutes grace before agent missed
set time_of_expiry = (new.ExpireTime * 2 * 60 + 120) + getdate();
For example, add two more minutes and the setting looks like this:
-- 2 heartbeats plus 4 minutes grace before agent missed
set time_of_expiry = (new.ExpireTime * 2 * 60 + 240) + getdate();
EIF events
Send private situation events directly from a Tivoli Monitoring Agent to an EIF
receiver without going through the Tivoli Enterprise Monitoring Server.
Restriction: EIF is not supported on iSeries® to send events directly from the
iSeries agents.
or
<attributeTable>
<slot>
Elements
Note: You can use the EIF.xsd schema file, located in the samples/
PrivateConfigSamples directory on the Agent DVD image, to validate EIF event
mapping XML files. However, the schema file requires the XML tag names to be in
uppercase.
<itmEventMapping:agent>
itmEventMapping:agent is the root element identifying this as an event
mapping definition for the monitoring agent.
<id> Syntax:
<id>pc</id>
ID is the two character product code, such as “UX” for the UNIX OS agent.
For user defined event maps, it is recommended to use “99” as the ID.
<version>
Syntax:
<version>nnnn</version>
Optional. Use this element to specify the version of the event mapping file.
<valueList>
Syntax:
<valueList name="valueListName">
Optional. Use the valueList element to define a value list of one or more
value items where valueListName is the name of the list.
<valueItem>
Syntax:
<valueItem name="item_value">
Optional. Define a slot in the EIF event. The name of the slot is the
slot_name.
<mappedAttribute>
Syntax:
<mappedAttribute name="attribute_name" [multiplier=“nnn”] [virtual="COUNT"]>
Optional. Specify the value source for the slot being defined. This is the
value of the attribute with the name attribute_name in the event data, if
available. Otherwise, a null value is used. If the multiplier= attribute is
specified and the value of the attribute is numeric, the value assigned for
the slot is the attribute value multiplied by the number specified.
<situation name=“Linux_Process_Count”>
<class name=“ITM_KLZ_Process”/>
<slot slotName=“slot1_count”>
<mappedAttribute name=“KLZ_Process.Process_Command_Name” virtual=“COUNT”/>
</slot>
</situation>
Optional. Use the text as the value for the slot being defined. When
defining a “msg” slot, you can specify variable substitution within the text
(described next).
If the value of the msg slot is defined as a literal string (<literalString> element), it
can include substitution variables. Substitution variables are designated by the
$variable$ syntax. When formatting the msg slot, the EIF event forwarder replaces
the $variable$ symbol with its replacement value.
The following is an example taken from a predefined event mapping file where the
msg slot is customized for DM parity.
<slot slotName="msg">
<literalString value="Distributed Monitoring $sub_source$/$monitor$
on host $hostname$ $NT_LogicalDisk.Timestamp$ Formula=$formula$"/>
</slot>
If the value for the sub_source and monitor slots have values “tmpdisk” and “Disk
Read Bytes/sec”, the msg slot text is similar to this example:
Distributed Monitoring tmpdisk/Disk Read Bytes/sec on host
elaix04 08/14/2009 10:23:11 Formula=Disk_Writes/Sec > 500
The following is an example taken from a predefined event mapping file where the
msg slot specifies the calculated value from the *COUNT predicate.
<pc>_eventmap.map
The EIF event class name is defined by the name= attribute of the <class> element.
The EIF class name string can contain a substitution variable for dynamic
generation of the EIF class name. The substitution variable can appear anywhere
within the EIF class name string, except at the beginning. The substitution variable
has a syntax of $attributeGroup.attribute$. At run time, the EIF event forwarder
searches the designated valueList, if one exists, for the value of the attribute
specified in the substitution variable. If the attribute value is found in the
valueList, the variable (and delimiting $ dollar sign) is replaced by the attribute
value (after being normalized) in the EIF class name string. If no match is found in
the valueList or the designated valueList is not defined, the EIF class name
defined in the defaultClass= attribute is used as the EIF class name for the event.
If no defaultClass= is specified, the variable in the EIF class name is replaced with
a null string.
When the situation is not true (status is not “Y”), the situation status record does
not contain any event attribute data. Consequently, there is no way to determine
the value of any substitution variablea in the class name. The EIF event forwarder
uses the defaultClass= attribute if one is specified. Otherwise, it uses the EIF event
class of the EIF event last sent for the same situation name.
This is the relevant part of a sample event mapping definition uses to map a
situation event “Test_Syslog” to a set of EIF events based on the value of the
“Message_Number” attribute.
<situation name="Test_Syslog">
<class name="SAP_Syslog_$R/3_System_Log.Message_Number$"
valueList="SyslogIDList" defaultClass="SAP_Syslog_Default" />
:
:
</situation>
This example has a “SyslogIDList” value list with valueItems AB0, AB1, A08, BV7,
EAS, and R45 and a “Test_Syslog” situation that monitors for message IDs AB0,
AB1, AB2, BV7, and BV8, The “Test_Syslog” situation evaluates to true for each of
these message ids. The generated EIF events are of the following classes:
1. AB0: SAP_Syslog_AB0 x
2. AB1: SAP_Syslog_AB1
3. AB2: SAP_Syslog_Default
4. BV7: SAP_Syslog_BV7
5. BV8: SAP_Syslog_Default
<id>NT</id>
<version>6.2.0</version>
<event_mapping>
<situation name="NT_LDDBPS*">
<class name="w2k_LogDskDskBytesPerSec"/>
<slot slotName="source">
<literalString value="SENTRY"/>
</slot>
<slot slotName="probe">
<literalString value="DskBytesPerSec"/>
</slot>
<slot slotName="probe_arg">
<mappedAttribute name="NT_Logical_Disk.Disk_Name"/>
</slot>
<slot slotName="collection">
<literalString value="w2k_LogicalDisk"/>
</slot>
<slot slotName="monitor">
<literalString value="Disk Bytes/sec"/>
</slot>
<slot slotName="units">
<literalString value="(per second)"/>
</slot>
<slot slotName="value">
<mappedAttribute name="NT_Logical_Disk.Disk_Bytes/Sec"/>
</slot>
<slot slotName="effective_value">
<mappedAttribute name="NT_Logical_Disk.Disk_Bytes/Sec"/>
</slot>
<slot slotName="msg">
<literalString value="Distributed Monitoring $sub_source$/Disk
Bytes/sec on host $hostname$ $NT_Logical_Disk.Timestamp.TIMESTAMP$"/>
</slot>
</situation>
</event_mapping>
</itmEventMapping:agent>
Sample EIF files are provided on the Tivoli Monitoring Agent installation media in
the PrivateConfigSamples/EIF directory.
Elements
The elements and their attributes are not case-sensitive. For example, you can enter
EVENTDEST=, EventDest=, or eventdest=.
<EventDest>
EVENTDEST is the root element identifying this as an event destinations
definition for the monitoring agent.
<Destination>
Start of an event destination definition. Specify the destination index.
Example
Here, the second destination will not receive life cycle events because stat
parameter is set to "N".
Here, the second destination illustrates that the same SSL value is not required
when multiple server locations are defined where a SSL connection is used for the
primary server and a non-SSL connection is used for the secondary server.
Tip: Sample EIF files are provided on the Tivoli Monitoring Agent installation
media in the PrivateConfigSamples/EIF directory.
All emitted EIF events will have a common set of slots in addition to the slots
from the event attribute data. All attributes, except hidden attributes, that are
defined in the attribute table used by the event are included in the emitted event
(subject to the total event and slot size limitation). The set of common slots are
explained in the following table.
Table 38. Set of common slots for emitted EIF events.
Slots Values and meaning
adapter_host Base EVENT class attribute. Same as hostname (see below).
This is application-specific data related to the event, if any.
appl_label Use to indicate the source of the event is from a private
situation or agent online status. The value has the following
syntax:
source : sit_type : event_type
where
source is always “A” for agent
sit_type is “P” for private situation or “E” for enterprise
situation
event_type is “S” for situation events or “L” for life cycle
status events
For example, A : P
Note: For enterprise situation events, the appl_label value is
not set. Thus, there is no appl_label=“A:E:S”.
cms_hostname Not used or null for agent emitted event.
Note: Because the Tivoli Enterprise Monitoring Server is not
used for EIF emitted events, the IBM Tivoli Enterprise
Console event server logs no error message in the event
synchronization synch_trace.log file after a private situation
event has been closed.
cms_port Not used or null for agent emitted event.
fqhostname Base EVENT class attribute that contains the fully qualified
hostname, if available.
hostname Base EVENT class attribute that contains the TCP/IP
hostname of the managed system where the event originates,
if available.
integration_type Indicator to help performance.
v N for a new event, the first time the event is raised
v U for update event, subsequent event status changes
master_reset_flag Master reset indicator set for master reset events. Value is
NULL for all other events:
v R for agent restart
v Otherwise, NULL
msg Base EVENT class attribute that contains the situation name
and formula, without the use of customization.
Life cycle events are emitted when the agent or situation changes state, as shown
in the EIF life cycle events table. The heartbeat event is a life cycle event that needs
no state change to be emitted: it is sent at regular intervals to confirm that the
agent is running.
Table 39. EIF life cycle events.
Event Meaning
EE_AUTO_ENTER The situation has entered autonomous mode operation.
EE_AUTO_EXIT The situation has exited autonomous mode operation.
All life cycle EIF events are ITM_StatEvent, which is a derived class of Event, with
the following slot values:
Table 40. EIF life cycle event ITM_StatEvent class slot values.
Slot Value
source “ITM Agent: Status Event”
appl_label “A:E:L” for stopped enterprise situation; “A:P:L” for all others.
hostname Hostname or IP address of agent machine
fqhostname Fully qualified hostname if available
origin The IP address of the agent computer
situation_name Life cycle status value, such as EE_AUTO_ENTER. If the life
cycle event is a EE_SIT_STOP, the situation_displayitem slot
contains the situation name being stopped.
situation_time Datetime the life cycle event occurred
date Date of life cycle event
severity “HARMLESS”
msg Message describing the life cycle event
The destination server receives an EIF event with a class name of “ITM_Heartbeat”
containing a slot called “interval” whose value is the heartbeat interval. SNMP
events received contain an attribute “AlertGroup” whose value is “ITM_Heartbeat”
and an attribute “HeartbeatInterval” whose value is the heartbeat interval. The
situation_eventdata slot is also set to the heartbeat interval.
Complete the following steps to send private situation events by using TLS/SSL
communication:
1. For any monitoring agent, define one or more private situations in the agent’s
situation XML file. See “Private situations” on page 332.
Certificate management
If the Netcool/Omnibus EIF probe uses a CA-signed digital certificate and
channel_nameSSLRequireClientAuthentication=YES is specified in the probe’s
configuration file, you must ensure that the monitoring agent’s key database has
imported a corresponding CA-signed digital certificate.
IBM Tivoli Monitoring and Netcool/OMNIbus rely on GSKit for their SSL
implementations. IBM Tivoli Monitoring V6.3 or later installs GSKit V8, which
provides the GUI utility in the gsk8ikm binary and the CLI utility in the
<gskittoolcmd> binary. Netcool/OMNIbus is based on GSKit V8, which runs only
in CLI mode; for GUI mode, you must use the iKeyman utility, which is included
in IBM JRE V6 or later.
Example
The example monitoring agent runs on a Windows system and includes a key
database file called omnieif.kdb with a password of ITMPWD, a previously
configured Netcool/OMNIbus keystore file called omni.jks with a password of
EIFPWD, and a certificate label named eifca. A copy of the omni.jks file is locally
available in the install_dir\keyfiles directory.
GSKit keystroke configuration (GUI mode): To invoke the GSKit GUI tool on a
Windows system, complete the following steps:
The Agent Service Interface is accessed through the IBM Tivoli Monitoring Service
Index utility. The interface operates as an Internet server, accepting and validating
requests, dispatching requests to the agent for processing, and gathering and
formatting reply data using the HTTP or HTTPS application protocol over TCP/IP.
You must have an administrator user ID for the operating system where the
monitoring agent is installed to access the Agent Service Interface and its functions.
Follow these steps to start the IBM Tivoli Monitoring Service Index utility and then
log onto the Agent Service Interface for the agent that you want to get information
about.
Procedure
1. Start the IBM Tivoli Monitoring Service Index by entering http://<host
name>:1920 or https//<host name>:3661, where host name is the fully qualified
name or IP address of the computer where the agent is installed. A list of the
started services is displayed.
2. Click the IBM Tivoli <PC> Agent Service Interface (where pc is the
two-character component code) link for the application to work with.
3. As prompted, enter the administrator-level user name and password for the
operating system.
Results
After you have been authenticated, the Agent Service Interface Navigator page is
displayed with links to Agent Information, Situations, History, Queries, and
Service Interface Request. The Navigator page is the navigator.htm file that is
installed at this location by default:
The security administrator can define any access authorization group name with
the exception of the Restricted group, which is mandatory. Each access
authorization group has at least one agent component category, such as Service
Interface (SIAPI element) and services published by that agent component. Each
agent component calls upon the AAGP facility to get the user ID, component
category, and the requested service name for access authorization. After
authorization, the agent component executes the requested service; otherwise the
agent returns a status of unauthorized.
The AAGP is not an authentication service and it assumes that the user ID
provided has been authenticated. The same assumption is made for the Service
Interface because all users must first sign onto the system with a valid ID and
password. However, the agent can perform work on behalf of other agents or the
Tivoli Enterprise Monitoring Server, such as automation actions, and the user ID
on hand could be unknown to the local system. In such a scenario, the agent
considers that the virtual user is a trusted Tivoli Monitoring member and therefore
authentic and calls upon AAGP for authorization. Alternatively, the AAGP can be
enhanced to leverage a centralized authentication and authorization service where
such facility becomes available.
The following default AAGP groups are predefined and they are automatically
loaded upon agent startup.
Restricted group
The default group. The Service Interface category in this group consists of
services that provide system information, operation configuration,
workload monitoring, and historical data reporting capabilities. All users
are in this mandatory group, including those that are not specifically
defined.
Operation group
This group includes Restricted group category services and the Service
Interface services that provide operation control, configuration
management, and application customized access capabilities.
The Restricted group definition is required. If it is not included in the AAGP, the
agent default specification shown in Table 42 is in effect.
Specifying the keyword *NONE for a component category prohibits all non-explicit
users from accessing that component service. For example, <SIAPI>*NONE</SIAPI>
specified in Restricted group disallows general access to the Agent Service
Interface.
FileObj allows you to push or pull files on an agent using an HTTP request. For
Centralized Configuration, FileObj is the API that is used to allow a monitoring
agent to act as a central configuration server. The Agent Service Interface is
available in the basic services of the monitoring agent and can be used to serve
files or you can send HTTP requests to any agent to push or pull files. The AAGP
function provides additional security. By default, only root on Linux or UNIX and
Administrator on Windows are members of the AD group that has permission to
use the FileObj API. See the example in “Monitoring agent as the central
configuration server” on page 432.
The security administrator defines the agent User Group Authorization Profile in
simple XML specification format:
<AAGP>
This element identifies the XML file as an agent Access Authorization Group
Profile document. All AAGP specifications must be enclosed by begin <AAGP>
and end </AAGP> root-level element tags. The contents of the AAGP file are
merged with the existing AAGP being used by the agent and you can add
users to the default Access Authorization Groups. If you prefer to completely
replace the existing AAGP, use the REFRESH attribute with the AAGP element.
REFRESH="Y"
Deletes the current active AAGP and replaces it with the AAGP definition
from this AAGP specification.
LOCAL="LOCK | UNLOCK"
Optional, with no default value. LOCK and UNLOCK are only accepted
when an AAGP update originated from the ASI.
LOCAL="LOCK" locks the local AAGP configuration, which cannot be
updated by either the ASI or by a Centralized Configuration Facility
AAGP file download.
LOCAL="UNLOCK" unlocks the local AAGP configuration and AAGP
can now be updated by ASI or a Centralized Configuration Facility file
download. UNLOCK is valid only when LOCK is in effect, otherwise it
is ignored. In other words, <AAGP LOCAL="UNLOCK"> must be
preceded by a prior <AAGP LOCAL="LOCK"> operation.
<AAGP LOCAL="LOCK"></AAGP> and <AAGP
LOCAL="UNLOCK"></AAGP> can be independent stand-alone AAGP
ASI transactions.
<AAGROUP>
Defines an Access Authorization Group. Begin <AAGROUP> and end
</AAGroup> element tags enclose a set of group definitions.
<GROUPNAME>
Defines the Access Authorization Group name. Specify the name between
begin <GROUPNAME> and end </GROUPNAME> element tags. The group
name can be up to 32 characters and the first two characters must be unique
among all user group names.
<INCLUDE>
Optional. Specifies the AAGROUP definitions to be included in this
AAGROUP. Enclose the AAGROUP name within begin <INCLUDE> and end
</INCLUDE> tags.
<SIAPI>
Specifies the agent Service Interface API name and is not case-sensitive. Only
the component category is defined at this time. Enclose the name within begin
<SIAPI> and end </SIAPI> tags.
<other>
The <other> element is not available in the current release; it is reserved for
future use. It specifies the other agent component services to be managed.
<AAUSER>
Defines an authorized user ID and its associated Access Authorization Group
by name. Enclose each user definition within begin <AAUSER> and end
</AAUSER> tags.
Example
<AAGP>
<AAGROUP>
<GROUPNAME>Restricted</GROUPNAME>
<SIAPI>AgentInfo</SIAPI>
<SIAPI>AttrList</SIAPI>
<SIAPI>ReadAttr</SIAPI>
<SIAPI>ListSubnode</SIAPI>
<SIAPI>TableSit</SIAPI>
<SIAPI>ListTable</SIAPI>
<SIAPI>SitStats</SIAPI>
<SIAPI>SitSummary</SIAPI>
<SIAPI>HistRead</SIAPI>
<SIAPI>Report</SIAPI>
<REFLEXAUTO>ExecAction</REFLEXAUTO>
</AAGROUP>
<AAGROUP>
<GROUPNAME>Operation</GROUPNAME>
<INCLUDE>Restricted</INCLUDE>
<SIAPI>PvtControl</SIAPI>
<SIAPI>CnfgControl</SIAPI>
<SIAPI>CnfgCommand</SIAPI>
<SIAPI>ConfigurationArtifact</SIAPI>
<SIAPI>PrivateConfiguration</SIAPI>
<SIAPI>Overrides</SIAPI>
<SIAPI>XMSClientSpec</SIAPI>
<SIAPI>ListAAGP</SIAPI>
<CLI>ExecCommand</CLI>
<TAKEACTION>ExecAction</TAKEACTION>
</AAGROUP>
<AAGROUP>
<GROUPNAME>Administrative</GROUPNAME>
<INCLUDE>Operation</INCLUDE>
<SIAPI>FileObj</SIAPI>
<SIAPI>AAGP</SIAPI>
</AAGROUP>
<AAUSER>
<ID>default</ID>
<ASSIGN>OP</ASSIGN>
</AAUSER>
</AAGP>
All valid system users are automatically authorized for Restricted group access.
Authorized, Administrative group, and other groups users are defined by the
enterprise security administrator through the AAGP. The following procedure
illustrates AAGP methodology.
1. The enterprise security administrator creates a customized AAGP and stores it
at a secure central configuration server. The predefined authorization group
content can be customized and additional custom authorization groups added.
For example, <AUTOCMD>KILL</AUTOCMD> could be included in the Operation
group.
406 IBM Tivoli Monitoring: Administrator's Guide
2. The monitoring agent starts and activates the default AAGP. An administrative
ID is defined as a member of the Administrative group by default:
Administrator on Windows; root on Linux or UNIX.
3. The monitoring agent leverages Centralized Configuration and retrieves its own
customized AAGP from a central configuration server. The agent always
chooses the HTTPS protocol for this operation. If there is no AAGP included in
agent's configuration load list or if the AAGP cannot be downloaded from the
central configuration server, the agent operates in this mode until the next
restart.
4. Agent components check the AAGP for authorization, which provides the user
ID, component category, and service name. The AAGP grants or denies access
based on the access authorization group and user ID assignment.
5. The monitoring agent checks for AAGP updates periodically as specified in the
configuration load list or when the Service Interface configuration command is
issued.
6. The monitoring agent does not save or store the User Authorization Profile
locally.
The Situations report gives some vital statistics about each situation on the agent.
The setting of the agent environment variable IRA_EVENT_EXPORT_SIT_STATS
determines the level of detail given.
Situation name
Above each situation summary page is the name of the situation. If this is
a private situation, the name will be appended with _pr.
TYPE Sampled or Pure. A situation is sampled if it samples data at regular
intervals. Pure events are unsolicited notifications. The Windows Event Log
and Windows File Change attribute are examples of attribute groups that
report pure events.
INTERVAL
The interval between data samples, in seconds. If situations for this
attribute group trigger pure events, there is no sampling interval and the
value shows as 0.
ROWSIZE
This is the row size.
All situations are shown for an agent, including the subnodes. In this sample
TestLab agent with subnodes called ComputerA and ComputerB, ten situations
would be listed:
TestLab
You can filter the report to show only the attributes that you are interested in by
clearing the check box next to any unwanted attributes. Select a start date and time
and an end date and time, then click Report. The report is displayed in a table
below the attributes, showing historical data samples for the attribute group, one
column per attribute and one row per sampling, for the time period specified, up
to 5000 rows. If you do not see the rows you are interested in within the 5000
limit, you can generate another report after narrowing the time range.
All collected historical data is shown for the agent, including any subnodes.
Select a table name from the list to see the component attributes and a report of
the sampled data.
Table name
This is the table name for the attribute group taken from the
<install_dir>/TMAITM6/ATTRLIB/kpc.atr file (where pc is the two-character
product code).
Name This is the column name for the attribute. It is not used in private
situations or private history, but is what you would see if you were to look
up the stored data in the Tivoli Data Warehouse.
Display
This is the detailed name of the attribute, formatted as
Attribute_Group_Name.Attribute_Name, and is what you enter in the private
situation and private history definitions. For example,
KHD_CONFIG.Connection_Pool_Size or NT_Registry.Server_Name.
Type Displayed in this column is a number that represents the type of attribute
this is, such as 4 to denote an integer-enumerated attribute. The type is not
used directly in a private situation or private history definition, but
informs you of the required format for the attribute value.
Length
This is the number of bytes or maximum number of bytes possible for the
attribute value. For TIMESTAMP attributes, 16 indicates the following
format: CYYMMDDHHMMSSmmm, such as 1090819160501000 for the 21st
century on August 19, 2009 at 4:05:01 PM
Minimum
The lowest possible value for the attribute is displayed here. If the field is
empty, there is no minimum value for the attribute.
These two reports show the results of a query to the Windows IP Address attribute
group, table name NTIPADDR. The first report is a listing of the attributes in the
table as they appear in the kpc.atr file. When creating private situations or private
history definitions, you must use the name shown in the Display column.
Table 43. Agent Service Interface - Queries sample attribute listing
Name Display Type Length Minimum Maximum ENUMS
ORIGINNODE NT_IP_Address.System_Name 2 64
TIMESTAMP NT_IP_Address.Timestamp 2 16
INTFNAME NT_IP_Address.Network_ 3 Not Available for
Interface_Name Windows 2000
IPADDRESS NT_IP_Address.IP_Address 2 50
DNSNAME NT_IP_Address.DNS_Name 10 388 No DNS Entry
IPVERSION NT_IP_Address.IP_Version 4 -2147483648 2147483647 4 IPv4
6 IPv6
10 IPv4_IPv6
MACADDRESS NT_IP_Address.MAC_Address 2 28
The second report is displayed with the current sampled values of the attribute
group.
Table 44. Agent Service Interface - Queries sample report
ORIGINNODE TIMESTAMP INTFNAME IPADDRESS DNSNAME IPVERSION MACADDRESS
Primary:East:NT 1090819142128111 11a_b_g 9.52.100.111 East.ibm.com 4 00054e48f5bd
Wireless
LAN Mini
PCI Adapter
Primary:East:NT 1090819142128111 MS TCP 127.0.0.1 NO_DNS_ 4 000d608b2938
Loopback ENTRY
interface
Request input
Table 45. Agent Service Interface <AGENTINFO> request.
Tag Description
<AGENTINFO> Enter begin and end AGENTINFO tags to make an agent
property request..
Sample request:
<AGENTINFO>
</AGENTINFO>
Report output
Table 46. Agent Service Interface <AGENTINFO> request output.
Output tag Description
<HOSTNAME> Agent host name
<NODENAME> Agent Managed System name
<SUBSYSID> Agent Subsystem ID
<NODEINFO> Agent system OS information
<PRODUCT> ITM product name
<VERSION> Agent version
<LEVEL> Agent installation and maintenance level
<PATCHLEVEL> Agent maintenance patch level
<AFFINITY> Agent affinity in effect
<BOOTTIME> Agent boot time
<ENVFILE> Agent configuration file enclosed by CDATA[] control data tags
Request input
Table 47. Agent Service Interface <LISTSUBNODE> request.
Tag Description
<LISTSUBNODE> Enter begin and end LISTSUBNODE tags to make a subnode
list request.
Sample request:
<LISTSUBNODE>
</LISTSUBNODE>
Report output
Table 48. Agent Service Interface <LISTSUBNODE> request output.
Output tag Description
<SUBNODELIST> Subnode list.
<NODECOUNT> Subnode count.
<NAME> Subnode name.
Sample output: The agent returns a listing of all known subnodes of the agent
<SUBNODELIST>
<NODECOUNT>3</NODECOUNT>
<NAME>dyang7ASFSdp:UAGENT00</NAME>
<NAME>dyang7:TS100</NAME>
<NAME>dyang7:TS200</NAME>
</SUBNODELIST>
Sample request:
<ATTRLIST>
</ATTRLIST>
Report output
Table 50. Agent Service Interface <ATTRLIST> request output.
Output tag Description
<LISTATTRFILE> List of available attribute file names.
<ATTRCOUNT> The total number of attribute files in the list.
<NAME> Name fo the attribute file.
Sample output: The agent returns a listing of all known attribute files that are
available on the computer
<LISTATTRFILE>
<ATTRCOUNT>16</ATTRCOUNT>
<NAME>DM3ATR00</NAME>
<NAME>TS1ATR00</NAME>
<NAME>TS2ATR00</NAME>
<NAME>UAGATR00</NAME>
<NAME>kdy.atr</NAME>
<NAME>khd.atr</NAME>
<NAME>kib.atr</NAME>
<NAME>knt.atr</NAME>
<NAME>kr2.atr</NAME>
<NAME>kr3.atr</NAME>
<NAME>kr4.atr</NAME>
<NAME>kr5.atr</NAME>
<NAME>kr6.atr</NAME>
<NAME>ksh.atr</NAME>
<NAME>ksy.atr</NAME>
<NAME>kum.atr</NAME>
</LISTATTRFILE>
Request input
Table 51. Agent Service Interface <READATTR> request.
Tag Description
<READATTR> Enter begin and end READATTR tags to make an attribute file
request.
<ATTRFILE> Attribute file name.
Report output
Table 52. Agent Service Interface <READATTR> request output.
Output tag Description
<ATTRFILE> Attribute file name.
<ATTRDATA> Attribute file records.
This example shows an excerpt from the klz.atr attribute file contents:
<ATTROUTPUT><ATTRFILE>klz.atr</ATTRFILE>
<ATTRDATA>
<![CDATA[// 1130415173632000 KLZ/6.2.0 = KLZ/01
// DO NOT EDIT THIS GENERATED FILE
//
entr AFF
afid %IBM.STATIC134
asym LINUX_SYSTEM
atxt "Linux OS"
acod KLZ
//
entr ATTR
name KLZ_User_Login.System_Name
affi "%IBM.STATIC134 0000000008000000000"
appl KLZ
aplv 01
stmp 1130415173632000
cvrm 6.2.0
lvrm 0.0.0
tabl KLZLOGIN
mult 1
samp 3
doop Y
colu ORIGINNODE
type 2
slng 64
msid KLZ####
opgr 2048
atid 00030001
//
entr ATTR
name KLZ_User_Login.Timestamp
unit CYYMMDDHHMMSSmmm
affi "%IBM.STATIC134 0000000008000000000"
colu TIMESTAMP
type 2
slng 16
msid KLZ####
opgr 2048
atid 00030002
//
entr ATTR
name KLZ_User_Login.User_Name
affi "%IBM.STATIC134 0000000008000000000"
colu USRNAME
pkey 1
atom Y
type 10
slng 96
Request input
Table 53. Agent Service Interface <REPORT> request
Tag Description
<REPORT> Enter begin and end REPORT tags to retrieve application table
data for the table specified.
<SQLTABLE> The SQLTABLE begin and end tags enclose the TABLENAME
tagging pair to identify the SQL table definition set.
<TABLENAME> The TABLENAME begin and end tags enclose the table name to
report. This is the name as it appears bracketed by begin and
end tags. If you are not sure what the spelling is of the table,
you can find it in the tabl field of the agent .atr file, located in
the <install_dir>/TMAITM6/ATTRLIB directory.
<OUTPUT> Optional. Use OUTPUT begin and end tags and their
subordinate tags to filter and refine the report.
<COLUMN> Define selected column name bracketed by begin
and end tags.
<FILTER> Define output data rows filter criteria with begin
and end tags. The filter follows the same syntax as the private
situation <CRITERIA> element. See “Private situation XML
specification” on page 335.
<SUBNODES> Optional. Use SUBNODES begin and end tags to specify
subnode-based products that register and manage subnodes.
The <SUBNODES> option works the same as the
<DISTRIBUTION> option, except the former is used for Agent
Service Interface requests using the <ASISREQUEST> while the
latter is used in the context of the <PRIVATESIT> definition for
for situations. See “Private situation XML specification” on page
335 for a complete description of the <DISTRIBUTION> option.
Report output
Table 54. Agent Service Interface <REPORT> request output.
Output tag Description
<REPORTDATA> Identify output report data set.
<ROWCOUNT> Output table row count.
<ROW> Identify an output row data.
<NAME> Define output column name enclosed by begin and end tags.
<DATA> Specify output column data value enclosed by begin and end
tags.
Numeric output
The report does not format numeric values; they remain unformatted.
For example, if you were to get a report containing an attribute with a
scale factor of 2, a value of 7 for that attribute would show in a table view
in the Tivoli Enterprise Portal as 0.07. You can look up the scale factor,
shown as scal in the attribute definition, in the attribute file:
<install_dir>\TMAITM6\ATTRLIB\kpc.atr
<install_dir>/platform/<pc>/tables/ATTRLIB/
kpc.atr, where platform is the operating system and pc is the product
code.
Enumerated values are also unformatted, so values shown in the report as
1 and 2, for example, would show their text equivalent (such as Started
and Stopped) in the portal client. Enumerated attributes are defined in the
kpc.atr attribute file: vale for the display value; vali for the unformatted
value.
Request input
Table 55. Agent Service Interface <TABLESIT> request
Tag Description
<TABLESIT> Enter begin and end TABLESIT tags to retrieve the agent table
and situation list.
<SQLTABLE> The SQLTABLE begin and end tags enclose the TABLENAME
tagging pair to identify the SQL table definition set.
<TABLENAME> The TABLENAME begin and end tags enclose the table name to
report. This is the name as it appears bracketed by begin and
end tags. If you are not sure what the spelling is of the table,
you can see it in the Agent Service Interface Queries report or
find it in the tabl field of the agent .atr file, located in the
<install_dir>/TMAITM6/ATTRLIB directory.
Sample request 1: Active Windows OS situations for Process and Logical Disk
<TABLESIT>
<SQLTABLE>
<TABLENAME>NTPROCESS</TABLENAME>
</SQLTABLE>
<SQLTABLE>
<TABLENAME>WTLOGCLDSK</TABLENAME>
</SQLTABLE>
</TABLESIT>
Report output
Table 56. Agent Service Interface <TABLESIT> request output.
Output tag Description
<SITUATION> Defines the output situation set.
<NAME> Specifies the situation name.
<TYPE> E – Enterprise situation; P – Private situation
<STATUS> Returns the status code bracketed by begin and end tags
Sample output: The Windows OS agent returns all running Process and Logical
Disk situations
<TABLESIT>
<SQLTABLE>
<TABLENAME>NTPROCESS</TABLENAME>
<SITUATION>
<NAME>Check_Process_CPU_Usage</NAME>
</SITUATION>
<TYPE>P</TYPE>
<SITUATION>
<NAME>Check_Process_CPU_Usage</NAME>
Private situations start running automatically when the monitoring agent they are
written for, whether a Tivoli Enterprise Monitoring Agent or a Tivoli System
Monitor Agent, is started. The PVTCONTROL command enables you to start, stop,
or recycle the specified situation without having to stop and restart the agent.
Request input
Table 57. Agent Service Interface <PVTCONTROL> request.
Tag Description
<PVTCONTROL> Specify private situation control request.
<PVTCOMMAND> Specify private situation command.
<PVTSITNAME> Specify private situation name.
<PVTACTION> START – Start a known situation request.
STOP – Stop an active situation.
RECYCLE – Stop and restart an active situation.
Report output
Table 58. Agent Service Interface <PVTCONTROL> request output.
Output tag Description
<STATUS> Return status code bracketed by begin and end tag.
<SITSUMMARY>
</SITSUMMARY>
The output from the request looks like the private situation configuration files
shown in the “Private situation examples” on page 353.
Report output
Table 60. Agent Service Interface <SITSUMMARY> request output.
Output tag Description
<NUMBSIT> The number of private situations running on the
monitoring agent.
<SITUATION> Define situation selection properties.
<NAME> Specifies the situation name.
<SOURCE> Indicates the source of the event. The value “E” means
enterprise situation. The value “P” means private
situation.
<TYPE> Situation type – Sample or Pure-Event.
<INTERVAL> Situation sample interval; or 0 – Pure-Event.
<ROWSIZE> Sample data row size.
<FIRSTSTARTTIME> The situation's initial start time.
<LASTSTARTTIME> The situation's most recent start time.
<LAST STOPTIME> The situation's last stop time.
<FIRSTEVENTTIME> The time that the situation first opened an event.
<LASTTRUETIME> The last time the situation evaluated to True.
<LASTFALSETIME> The last time the situation evaluated to False.
<TIMESRECYCLED> Number of times the situation restarted.
<TIMESAUTONOMOUS> Number of times the situation entered autonomous mode.
<PREDICATE> The situation formula.
Request input
Table 61. Agent Service Interface <AGENTSTAT> request.
Tag Description
<AGENTSTAT> Specify Agent statistic request.
<SITUATION> Define situation selection properties.
<NAME> Specify the situation name or *ALL for all known situations.
Default: *ALL
<DAYS> Optional. Specify the period to display, such as 1 for today's
data. Up to 7 days history data can be retrieved.
<DETAILS> Optional. Yes – output hourly detail data
No- output state information only
Default: No
Report output
Table 62. Agent Service Interface <AGENTSTAT> request output.
Output tag Description
<TYPE> Situation type – Sample or Pure-Event.
<INTERVAL> Situation sample interval; or 0 – Pure-Event.
<ROWSIZE> Sample data row size.
<FIRSTSTARTTIME> The situation's initial start time.
<LASTSTARTTIME> The situation's most recent start time.
<LAST STOPTIME> The situation's last stop time.
<FIRSTEVENTTIME> The time that the situation first opened an event.
<LASTTRUETIME> The last time the situation evaluated to True.
<LASTFALSETIME> The last time the situation evaluated to False.
<TIMESRECYCLED> Number of times the situation restarted.
<TIMESAUTONOMOUS> Number of times the situation entered autonomous mode.
<DAY> Begin daily metrics.
<DATE> Date description.
<TRUESAMPLES> True sample row count.
<FALSESAMPLES> False sample row count.
<TRUERATIO> Percent of true samples.
<FALSERATIO> Percent of false samples.
<HOURROWS> Hourly sample row count.
<HOURTRUE> Hourly true sample row count.
<HOURFALSE> Hourly false sample row count.
<STATUS> Return status code bracketed by begin and end tag.
Historical data from Tivoli Enterprise Monitoring Agents is displayed in the Tivoli
Enterprise Portal when you select a time span for a table view or other
query-based view. Outside the portal, you can see historical data from an
enterprise monitoring agent or private history data from an enterprise monitoring
agent or system monitor agent by getting a History report from the Agent Service
Interface or by creating a HISTREAD service interface request.
Request input
Table 63. Agent Service Interface <HISTREAD> request.
Tag Description
<HISTREAD> Retrieve history table data
<SQLTABLE> Identify SQL table definition set.
<TABLENAME> Defines table name bracketed by begin and end tags. Maximum
table name consists of 10 characters.
<PVTHIST> Optional. Specify reading private history. No direct agent to
read enterprise short term history
<OUTPUT> Optional. Define output table column selection.
<COLUMN> Optional. Define selected column name bracketed by begin and
end tags.
<FILTER> Optional. Define output data rows filter criteria bracketed by
begin and end tags. See Private Situation <CRITERIA>
specification for details. Use from and to WRITETIME column
to specify history data read range. Use ORIGINNODE column
to select specific MSN history data
<OUTLIMIT> Optional. Define the output record limit bracketed by begin and
end OUTLIMIT tags to safeguard against to much output
volume.
Sample request 1: Get Windows OS agent Process history data using filter and
column selections
<HISTREAD>
<SQLTABLE>
<TABLENAME>NTPROCESS</TABLENAME>
<OUTPUT>
<COLUMN>ORIGINNODE</COLUMN>
<COLUMN>TIMESTAMP</COLUMN>
<COLUMN>INSTCNAME</COLUMN>
<COLUMN>IDPROCESS</COLUMN>
<COLUMN>PCTPRCSTME</COLUMN>
<COLUMN>THREADCNT</COLUMN>
<COLUMN>WRKINGSET</COLUMN>
Report output
Table 64. Agent Service Interface <HISTREAD> request output.
Output tag Description
<HISTREADDATA> Identify output report data set.
<STATUS> Return status code bracketed by begin and end tag
<ROWCOUNT> Output table row count
<ROW> Identify an output row data
<NAME> Define output column name enclosed by begin and end tags.
<DATA> Specify output column data value enclosed by begin and end
tags.
Sample output 1: The Windows OS agent returns Process history data for the
seven specified attributes on April 8 from 10:45 PM to 11:45 PM
<HISTREADDATA>
<SQLTABLE>
<TABLENAME>NTPROCESS</TABLENAME>
<ROWCOUNT>212</ROWCOUNT>
<ROW>
<COLUMN>
<NAME>ORIGINNODE</NAME>
<DATA><![CDATA[Primary:DYANG3:NT]]></DATA>
</COLUMN>
<COLUMN>
<NAME>TIMESTAMP</NAME>
<DATA><![CDATA[1090408224551430]]></DATA>
</COLUMN>
<COLUMN>
<NAME>INSTCNAME</NAME>
<DATA>![CDATA[Idle]]> </DATA>
</COLUMN>
<COLUMN>
<NAME>IDPROCESS</NAME>
<DATA>0</DATA>
</COLUMN>
<COLUMN>
<NAME>PCTPRCSTME</NAME>
<DATA>74</DATA>
</COLUMN>
<COLUMN>
<NAME>THREADCNT</NAME>
<DATA>1</DATA>
</COLUMN>
<COLUMN>
<NAME>WRKINGSET</NAME>
<DATA>16384</DATA>
</COLUMN>
</ROW>
Authorization
The Service Interface Request recognizes the complete configuration load list XML
syntax. The requests that are allowed depend on group permissions:
v If your user ID is a member of the Operation group in the Access Authorization
Group Profile (AAGP), you can use the <CNFGCOMMAND> element to refresh
files using an existing configuration load list, and can issue <CNFGACTION>
Reboot, Reload, and Download requests.
v If your user ID is a member of the Administrative group in the AAGP, you can
submit any valid configuration load list request using the syntax in the
Configuration load list XML specification.
Elements
The elements and their attributes are case-insensitive. For example, you can enter
<CNFGCOMMAND>, <CnfgCommand>, or <cnfgcommand>.
<CNFGCOMMAND>
Specify configuration command request. The following example of a
configuration control request reloads the contents of the current configuration
load list:
<CNFGCOMMAND>
<CNFGACTION>RELOAD</CNFGACTION>
</CNFGCOMMAND>
<CNFGACTION>
Specify the configuration command action:
Reboot
This attribute downloads the configuration load list.
Reload
Reload is used to perform an immediate resend of the current agent
load list, thereby downloading all specified agent artifacts if they have
been updated. See the example under <CnfgCommand>.
Download
Download is used to specify the file to send. See the examples under
<CnfgFile> and <CnfgDisp>.
<CNFGFILE>
Optional. Specific last two segments of file name when <CNFGACTION> is
Download.
File name must exist in the load list. Download file alert.txt
<CNFGCOMMAND>
<CNFGACTION>DOWNLOAD</CNFGACTION>
<CNFGFILE>alert.txt</CNFGFILE>
</CNFGCOMMAND>
<CNFGDISP>
Optional. Specific well-known configuration file disposition as identification of
Centralized Configuration
Use the Centralized Configuration feature to maintain monitoring agent
configuration files in a central location that agents can collect from.
The central configuration server can be a Tivoli Monitoring agent at version 6.2.2 Fix
Pack 2 or later, or it can be any web server, such as WebSphere, IBM HTTP,
Microsoft IIS, or Apache. For security reasons, IBM recommends you choose a web
server.
You can have multiple central configuration servers and logically arrange them as
a hierarchy of central configuration servers.
After Centralized Configuration has been initiated by the agent, the default
behavior is to pull any file updates from the designated central configuration
server every hour. You can also get updates on-demand by entering the load list as
an Agent Service Interface request.
The basic tasks for implementing Centralized Configuration for existing agents are:
1. Decide on a strategy to organize and distribute configuration files from a
central repository and create the configuration files.
2. Configure the central configuration server.
3. Enable the agent to collect the initial configuration load list.
4. Update configuration files as needed on the central configuration server.
The configuration load list contains one or more ConfigServer elements that tell the
agent how to connect to a central configuration server. Central configuration
servers contain a repository of files that are served to the monitoring agents using
HTTP.
The server authenticates requests, examines the configuration article last update
time stamp (set to GMT), and, if the client copy of the requested file is older than
the server copy, the server returns the configuration article contents to the agent.
Otherwise, it returns HTTP status 304 - Object Not Modified. The server returns
other HTTP status if an error is encountered during article processing.
Other keywords can be used to create the granularity required for each
agent to get the correct files.
Tivoli monitoring agents can use existing web servers to collect configuration files.
You can use any web server that the agents can access with HTTP or HTTPS as a
central configuration server.
All monitoring agents (enterprise or system monitor) that run on Windows, Linux
and UNIX platforms contain an HTTP-based Service Interface that can be used as a
central configuration server. Monitoring agents on z/OS and i5 do not provide an
HTTP Service interface, so cannot be used as central configuration servers.
Tip: Consider having each agent collect an AAGP file so that you can
contact the agent directly through its Agent Service Interface to perform
configuration actions with a non-root ID. By connecting directly to an
agent's Service Interface with AD permission, you can provide
credentials to connect to a new central configuration server, put or get
files, or force immediate refreshes of configuration files.
3. On the monitoring agent that functions as the central configuration
server, edit the configuration load list to add a DISP="AAGP"
ConfigFile entry to load the AAGP XML file.
This load list must use credentials ( root;
Administrator) to connect to itself to add the new user ID to
the AAGP. The edited configuration load list looks like this:
<ConfigurationArtifact>
<ConfigServer
Name="CENTRAL-CONFIG-SERVER"
URL="http://linuxhost:1920///linuxhost_lz/linuxhost_lz/"
User="root"
Password="{AES256:keyfile:a}vHBiEqmmvylNPs90Dw1AhQ==" />
<ConfigFile
Server="CENTRAL-CONFIG-SERVER"
Name="AAGP.xml"
Path="/"
Disp="AAGP" />
</ConfigurationArtifact>
4. Save the load list in install_dir/localconfig/lz/lz_cnfglist.xml. This
directory is the default location on Linux systems and can be changed
with the IRA_SERVICE_INTERFACE_CONFIG_LOADLIST
environment variable.
5. Start the Linux OS agent.
The Service Interface for an agent can be used to enter and process configuration
load list requests on demand. See “Agent Service Interface request - Configuration
control” on page 428.
The following configuration load list file names are the defaults, where pc is the
two-character product code:
install_dir\localconfig\pc\pc_cnfglist.xml
install_dir/localconfig/pc/pc_cnfglist.xml
IRA_SERVICE_INTERFACE_CONFIG_LOADLIST=
PCCFGLST.RKANDATV
/QIBM/UserData/IBM/ITM/localconfig/a4/a4_cnfglist.xml
Elements
XML element tags and their attributes are not case-sensitive, but values are
case-sensitive. For example, you can enter <CONFIGSERVER>, <ConfigServer>, or
<configserver>.
<ConfigurationArtifact>
ConfigurationArtifact is the root element that identifies this XML file as a
load list configuration document. Enter <ConfigurationArtifact> at the
beginning of the file and </ConfigurationArtifact> at the end.
Example of a load list file:
<ConfigParm>
Optional. Specifies an agent environment variable override value that
updates the environment settings immediately and takes effect at the next
operation interval or instance.
Interval=
Override or set IRA_SERVICE_INTERFACE_CONFIG_INTERVAL.
Backup=
Override or set IRA_SERVICE_INTERFACE_CONFIG_BACKUP.
NumbTasks=
Override or set IRA_SERVICE_INTERFACE_CONFIG_POOL_SIZE.
MaxWait=
Override or set IRA_SERVICE_INTERFACE_CONFIG_MAX_WAIT.
Tivoli monitoring agents recognize certain keywords in the configuration load list
attributes and substitute them using run time values from the central configuration
client.
See the keyword organization and syntax examples under “Central configuration
server” on page 430.
Enclose environment variables in percent signs (%) when you reference them in a
configuration load list. You might expect this requirement is for Windows only,
because environment variables are delimited with percent signs on that operating
system, but the percent sign delimiters are used to identify environment variables
within the configuration load list on all platforms.
Environment variables in the configuration load list are resolved at the central
configuration server or at the central configuration client, depending on whether a
monitoring agent or a web server is acting as the central configuration server:
v When a monitoring agent is acting as the central configuration server,
environment variables in the configuration load list are resolved using the
environment at the central configuration server.
v When a web server is acting as the central configuration server, environment
variables in the configuration load list are resolved using the environment at the
central configuration client (the monitoring agent making the request).
Chapter 15. Agent-based services 441
To illustrate how variable substitution might be used in the configuration load list,
consider an environment with two monitoring agents acting as central
configuration servers. The environment variable SALES_CNFG_FILES is used to
identify the directory that contains configuration files for use by systems that
belong to the Sales Department of our company. The Primary central configuration
server is a windows OS agent on a server called winhost
IRA_SERVICE_INTERFACE_CONFIG_HOME=C:\IBM\ITM\ConfigFiles
and the configuration for the sales department are in a directory called
C:\IBM\ITM\ConfigFiles\Sales, so we set
SALES_CNFG_FILES=Sales
They locate the configuration files for the sales department in /opt/IBM/ITM/
localconfig/eastcoast/sales, so they set:
SALES_CNFG_FILES=eastcoast/sales
This is the bootstrap configuration load list for the Sales Department:
<ConfigurationArtifact>
<ConfigServer Name="BACKUP-CONFIG-SERVER"
URL="http://linuxhost:1920///linuxhost_lz/linuxhost_lz/"
User="itmuser"
Password="{AES256:keyfile:a}8wNnAEj6uLMTTOeaC+2rfQ==" />
<ConfigServer Name="CENTRAL-CONFIG-SERVER"
URL="http://winhost:1920///primary.winhost_nt/primary.winhost_nt/"
User="itmuser"
Password="{AES256:keyfile:a}8wNnAEj6uLMTTOeaC+2rfQ=="
AltServer="BACKUP-CONFIG-SERVER" />
<ConfigFile Server="CENTRAL-CONFIG-SERVER"
Name="cnfglist.xml"
Path="%SALES_CNFG_FILES%"
Disp="CNFGLIST"
Activate="YES" />
</ConfigurationArtifact>
Because you will be identifying the complete configuration load list anyway, to
initialize Centralized Configuration operations, you only need to tell the agent
In this example, the ConfigServer URL identifies the central configuration server
location and the user name and password to gain access to that server. The
ConfigFile element points to the server named in the ConfigServer element and
identifies the configuration load list file as cnfglist.xml, which is in the path for the
product.
<ConfigurationArtifact>
<ConfigServer
Name="CENTRAL-CONFIG-SERVER"
URL="http://winhost:1920///primary.winhost_nt/primary.winhost_nt/"
User="Administrator"
Password="{AES256:keyfile:a}vHBiEqmmvylNPs90Dw1AhQ==" />
<ConfigFile
Server="CENTRAL-CONFIG-SERVER"
Name="cnfglist.xml"
Path="@PRODUCT@"
Disp="CNFGLIST"
Activate="YES" />
</ConfigurationArtifact>
After creating a bootstrap configuration load list that identifies the correct load list
for the agent, place the file and restart the agent.
For enterprise monitoring agents, the environment variables are set in the agent's
environment file; for system monitor agents, the environment variables are set in
the pc_silent_install.txt response file. For more information about installing the
system monitor agent, see “Monitoring your operating system via a System
Monitor Agent” in the IBM Tivoli Monitoring Installation and Setup Guide.
Upon startup, a monitoring agent first looks for its configuration load list XML file.
If the configuration load list does not exist, the agent reviews its environment file
for the following variables. The agent constructs the initial, or bootstrap, load list
from these environment values to connect to a central configuration server and
download a configuration load list.
IRA_CONFIG_SERVER_URL
Specifies the server URL. For example, http://9.52.111.99.
IRA_CONFIG_SERVER_USERID
Specifies the server user ID. Default: itmuser.
IRA_CONFIG_SERVER_PASSWORD
Specifies the user password either in plain text or AES encrypted password
string.
IRA_CONFIG_SERVER_FILE_PATH
Specifies the path to the configuration load list on the central configuration
The following agent environment variables affect how the agent operates as a
client for Centralized Configuration. Use them to specify a different configuration
load list file from the default, how often to connect to the central configuration
server to check for updates, and whether to download only the configuration files
that have changed since the last time you downloaded or all the files.
IRA_SERVICE_INTERFACE_CONFIG_LOADLIST
Use this variable to override the default configuration load list. Specify the
full path and file name of the configuration load list. The following
configuration load list file names are the defaults, where pc is the
two-character product code:
install_dir\localconfig\pc\pc_cnfglist.xml
install_dir/localconfig/pc/pc_cnfglist.xml
IRA_SERVICE_INTERFACE_CONFIG_LOADLIST=
PCCFGLST.RKANDATV
/QIBM/UserData/IBM/ITM/localconfig/a4/a4_cnfglist.xml
IRA_SERVICE_INTERFACE_CONFIG_INTERVAL
Specifies how often the agent attempts to check with the central
configuration server for updates. Specify the interval in minutes. One day
is 1440 minutes; one week, which is also the maximum, is 10080 minutes.
Default: 60 minutes.
IRA_SERVICE_INTERFACE_CONFIG_BYPASS_TIMESTAMP
When set to N, the agent downloads and replaces only the configuration
files that have a newer UTC time stamp than that of the local version.
Default: N. Setting this parameter to Y instructs the agent to bypass the
timestamp and always download the file after every interval.
As a best practice, synchronize system times across the network to
ensure that any monitoring agents running with their time ahead of the
central configuration server do not miss an update if the file is changed
within the time difference after download.
IRA_SERVICE_INTERFACE_CONFIG_BACKUP
When a new configuration file is downloaded, the agent renames the
existing local file to a backup copy by appending suffix 1 through 5 to the
file name and moving the file to a backup directory. This variable specifies
the number of backup versions to keep. The minimum is 0 for no backup;
the maximum is 5 backups. Default: 2 backups.
IRA_SERVICE_INTERFACE_CONFIG_BACKUP_DIR
Use this environment variable to establish a different backup directory
from the default. These are the default backup directories:
install_dir\localconfig\pc\backup
install_dir/localconfig/pc/backup
RKANDATV DD dataset
/QIBM/UserData/IBM/ITM/localconfig/a4/backup
The following agent configuration parameters affect how the agent operates as a
server for Centralized Configuration:
IRA_SERVICE_INTERFACE_CONFIG_HOME
If an agent is being used as a configuration server, this setting can be used
to override the default central configuration repository location. The
default location used to place files to be served by the central configuration
server is: install_dir/localconfig.
The web server HTTP file root is defined by the web server administrator
and cannot be altered. Relative path specifications such as ../../ to
reference artifacts outside of defined repository location cannot be used. In
addition, the new repository location cannot be the root directory.
IRA_SERVICE_INTERFACE_NAME
Specify the preferred agent service interface name to define a more
functionally recognized name to replace the agent generated default name
in the format of kpcagent, where pc is the two-character product code, such
as kntagent or kmqagent; or pcagent, such as kuxagent02 to identify a
second installed UNIX OS Agent instance on a system.
Default:
system.hostname_pc
hostname_pc
Example: The default agent-ServicePoint for a Windows OS Agent is:
hostname_nt. The URL to connect to a central configuration server on a
Windows OS agent running on host system winhost1 is:
https://winhost1:3661///winhost1_nt/winhost1_nt. If
IRA_SERVICE_INTERFACE_NAME= ConfigServer-A, the URL is
https://winhost1:3661///ConfigServer-A/ConfigServer-A
KDE_TRANSPORT
Use the KDE_TRANSPORT environment variable to specify a different port
from the default 1920 for HTTP or 3661 for HTTPS.
Do not change the default port settings, especially on multifunction UNIX
and Linux systems, because many components might be located on the
Problem determination
These diagnostic options can be set for the agent component. The output is the
ras1 log file.
IRA_DEBUG_SERVICEAPI=Y
Agent component name: Service Interface
IRA_DEBUG_PRIVATE_SITUATION=Y
Agent component name: private situation
IRA_DEBUG_TRANSCON=Y
Agent component name: Transport Conduit
KDH_DEBUG=D
Agent component name: Tivoli Monitoring Service Index HTTP Service.
If you are enabling SNMP alerts from the agent, SNMP v1 & v2c Community
Strings and SNMP v3 Authentication and Privacy Passwords can be stored in
encrypted format in the PCTRAPS.RKANDATV trap configuration file.
On Windows, Linux, and UNIX systems, password and community strings are
encrypted and decrypted using the GSKIT encryption utilities provided by the
Tivoli Management Services infrastructure. On z/OS, GSKit is known as the
Integrated Cryptographic Service Facility, or ICSF. If these strings are stored in
encrypted format on z/OS, the ICSF subsystem must be available on the z/OS
system and the ICSF modules must be added to the z/OS monitoring agent
startup PROC so that the strings can be decrypted for use by the agent.
Procedure
1. Verify that you have at least one IBM cryptographic coprocessor installed and
that the ICSF is installed.
2. Create a KAES256 member in the RKANPARU data set in the z/OS agent
runtime environment. Be sure to use the same encryption key that is used
What to do next
Use the itmpwdsnmp utility to create the encrypted password and community
strings. The utility is available only in the Tivoli Enterprise Monitoring Agent
framework on distributed platforms. The agent framework can be installed from
the Tivoli Monitoring Base DVD or Tivoli Monitoring Agent DVD. Run the
itmpwdsnmp tool in interactive mode on the distributed system to encrypt the
passwords that will be placed in the configuration files. For instructions, see
“SNMP PassKey encryption: itmpwdsnmp” on page 376.
This AAGP.xml file sets the AAGP on the central configuration server. For
our sample setup, the central configuration server will serve that same file
There is no need to include the AAGP for the agent in the bootstrap
CNFGLIST. The agent uses this file to locate the unique configlist that the
agent should use. This CNFGLIST is only in effect for a few seconds. In
our sample, the agent looks in the directory identified by the
@PRODUCT@ keyword for a file called cnfglist.xml. It is best practice to
look for the bootstrap CNFGLIST in the config server to allow agents to
identify their CNFGLIST by changing this file directly on the config server
(rather than changing the mechanism on each agent for beginning central
config operations).
You can enable an agent to use Centralized Configuration by editing the agent
environment variables to specify a default central configuration server, by placing
the configuration load list file on the computer and restarting the agent, or by
submitting a service interface request.
After the initial configuration load list file is established, the monitoring agent uses
that file and no longer attempts to use the environment variables. Deleting the
local configuration load list (on the system monitor agent you also must run a
silent installation) causes the agent to again use the environment variables to
download the bootstrap configuration load list. (See “Bootstrap configuration load
list” on page 442.)
Procedure
1. On the computer where the enterprise monitoring agent is installed, open the
agent environment file from Manage Tivoli Enterprise Monitoring Services or
from the command line:
v Start Manage Tivoli Enterprise Monitoring Services:
Click Start → Programs →IBM Tivoli Monitoring → Manage Tivoli
System monitor agents are started at the end of their silent installation. Without
local configuration files, the agents run but do not run private situations or send
SNMP alerts or EIF events. Using Centralized Configuration, the agent can retrieve
these files and begin using them immediately. The system monitoring agent
installation uses entries in the silent response file to create entries in the agent's
environment file.
For more information about the silent response file, how to configure it, and how
to invoke it, see “Monitoring your operating system via a System Monitor Agent”
in the IBM Tivoli Monitoring Installation and Setup Guide.
Procedure
1. Locate the pc_silent_install.txt response file (such as ux_silent_install.txt) on the
Tivoli Monitoring Agent installation media and make a copy of it.
Example
This example shows how a copy of nt_silent_install.txt from the installation media
might be edited to install a system monitor agent on the local computer and
configure it for Centralized Configuration:
Before
;License Agreement=I agree to use the software only in accordance with
the installed license.
;SETENV_IRA_CONFIG_SERVER_URL=http://configserver.domain.com:1920
;SETENV_IRA_CONFIG_SERVER_USERID=itmuser
;SETENCR_IRA_CONFIG_SERVER_PASSWORD=plaintext_or_encrypted_using_itmpwdsnmp
;SETENV_IRA_CONFIG_SERVER_FILE_PATH=initloadlist/@PRODUCT@
;SETENV_IRA_CONFIG_SERVER_FILE_NAME=cnfglist.xml
After
License Agreement=I agree to use the software only in accordance with
the installed license.
SETENV_IRA_CONFIG_SERVER_URL=http://mysystem.mydomain.ibm.com:1920
SETENV_IRA_CONFIG_SERVER_USERID=itmuser
SETENCR_IRA_CONFIG_SERVER_PASSWORD={AES256:keyfile:a}encryptedpassword
SETENV_IRA_CONFIG_SERVER_FILE_PATH=bootstraploadlist
SETENV_IRA_CONFIG_SERVER_FILE_NAME=cnfglist.xml
You can initiate Centralized Configuration by placing the configuration load list
file in the agent configuration directory and recycling the agent.
Create the configuration load list file using the XML tagging described in
“Configuration load list XML specification” on page 434.
Procedure
1. Access the system locally and place the configuration load list pc_cnfglist.xml in
the agent's install_dir/localconfig/pc directory, where pc is the two-character
product code.
pc_cnfglist.xml
pc_cnfglist.xml
PCCFGLST.RKANDATV
a4_cnfglist.xml
2. Recycle the agent.
Results
During startup, the configuration load list file is read for the central configuration
server connection URL and the files to download from there.
If your environment contains a large number of existing agents that are connected
to a Tivoli Enterprise Monitoring Server, you might prefer to use remote
deployment to distribute the configuration load list to the agents. You can use the
Agent Builderto build non-agent deployment bundles.
Procedure
1. Use Agent Builder to create a non-agent deploy bundle. See the IBM Tivoli
Monitoring Agent Builder User's Guide (http://pic.dhe.ibm.com/infocenter/
tivihelp/v61r1/topic/com.ibm.itm.doc_6.3/builder/agentbuilder_user.htm) for
details.
a. Add the common bootstrap configuration load list confglist.xml file to the
bundle.
b. Create your own copy command that copies the file to the correct location
for the agent that you plan to deploy to. Here is an example of an
installation command for the Linux OS agent:
cp |DEPLOYDIR|/cnfglist.xml |CANDLEHOME|/localconfig/lz/lz_cnfglist.xml
c. Recycle the agent to start using the new configuration load list after it is
deployed.
v Optionally, create a post-installation command that uses the Agent
Management Services watchdog to recycle the agent. Create a command
install_dir\TMAITM6[_x64]\kcapasctrl.exe recycle nt
install_dir/lx8266/lz/bin/pasctrl.sh recycle lz
install_dir/aix526/ux/bin/pasctrl.sh recycle ux
v Non-OS agents still use the watchdog from the OS agent. A
multi-instance DB2 agent on Windows, for example, that is managed by
Agent Management Services requires that you specify the instance name
in the post-installation command. Therefore, including the restart in the
deploy bundle might not be the best method but can be done if standard
instance names are used.
install_dir\tmaitm6\kcapasctrl.exe recycle –o db2inst1 ud
v You could also include a script in the deploy bundle that contains more
advanced logic to recycle agent instances and call that script in a
post-installation command.
Deploy_dir/afterscript.sh
d. Generate the remote deployment bundle.
e. If the agent was not restarted using a post-installation command in the
deploy bundle, recycle the agent to activate the configuration load list.
v See “Starting, stopping, and recycling an agent through the Tivoli
Enterprise Portal” on page 289.
v OS agents can be recycled in the portal client using the AMS Recycle
Agent Instance TakeAction
v The AMS Recycle Agent Instance Take Action command can also be run
using the CLI tacmd executeAction. Here are some examples for the OS
agents:
You can initiate Centralized Configuration using the CLI tacmd putfile to transfer
the configuration load list to the monitoring agent.
Take these steps to push the configuration load list to the monitoring agent where
you want to initiate Centralized Configuration. The IBM Tivoli Monitoring Command
Reference (http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/topic/
com.ibm.itm.doc_6.3fp2/ic/landing_cmdref.htm) describes the tacmds and their
syntax and includes examples.
Procedure
1. Log onto the to the hub monitoring server:
tacmd login –s myhubserver –u myusername –p mypassword –t 1440
where myhubserver is the fully qualified host name of the hub monitoring
server, and myusername and mypassword is a valid user ID for logging onto the
monitoring server operating system.
2. Push the file: tacmd putfile –m Primary:winhost:NT -s C:\config\cnfglist.xml
-d C:\IBM\ITM\localconfig\nt\nt_cnfglist.xml -t text
3. Recycle the agent to activate the configuration load list. See Starting, stopping,
and recycling an agent through the Tivoli Enterprise Portal
v OS agents can also be recycled in the portal client using the AMS Recycle
Agent Instance Take Instance: Open the Agent Management Services
workspace of the OS Agent; right-click the OS agent in the “Agent Runtime
Status” table view and click Take Action - Select; select AMS Recycle Agent
Instance.
v The AMS Recycle Agent Instance Take Action command can also be run
using the CLI tacmd executeAction. Here are some samples for the OS
agents:
Complete these steps to enter the configuration load list as a request in the Agent
Service Interface.
Procedure
1. Open a browser and access the agent's Service Index with the URL,
http://hostname:1920 or https://hostname:3661, where hostname is the
fully-qualified name or IP address of the computer where the monitoring agent
is installed.
2. Click the IBM Tivoli pc Agent Service Interface link for the agent, where pc is
the two-character product code.
3. As prompted, enter the user name and password. The ID must be a member of
the Access Authorization Group Profile's Administrative group on the central
configuration client agent.
4. Select the link to the Service Interface Request.
5. Paste the contents of the configuration load list XML file into the Agent Service
Interface Request text box, then submit the request.
What to do next
You can use the Agent Service Interface to submit the configuration load list as a
service interface request whenever you want to refresh the local configuration
on-demand.
The Service Interface is an API that allows the creation of a custom interface.
Sample HTML files are provided with the agents to demonstrate the function of
the Service Interface. The API can also be accessed programmatically using Java,
Visual Basic, Perl, HTML and other languages. The Tivoli Enterprise Monitoring
Server includes a command line utility called kshsoap that can be used within a
script to submit these service interface requests. You can use kshsoap to initiate
Centralized Configuration.
Procedure
1. Create a file called request.xml with <UUSER> and <UPASS> elements to
specify the credentials that kshsoap requires to connect to the Agent Service
Interface. This ID must be defined on the target systems that you plan to
submit the request to. As well, the ID must be a member of the Administrative
group in the target agent's Access Authorization Group Profile. Example:
<ConfigurationArtifact>
<UUSER>root</UUSER>
<UPASS>{AES256:keyfile:a}ENRUCXLW40LpR0RtGSF97w==</UPASS>
<ConfigServer
Name="CENTRAL-CONFIG-SERVER"
URL="http://winhost:1920///system.winhost_nt/system.winhost_nt/"
User="Administrator"
Password="{AES256:keyfile:a}vHBiEqmmvylNPs90Dw1AhQ==" />
<ConfigFile
Server="CENTRAL-CONFIG-SERVER"
The “Tivoli Data Warehouse solutions” topics in the IBM Tivoli Monitoring
Installation and Setup Guide describe how to install and configure a Tivoli Data
Warehouse and its requisite agents, the warehouse proxy and the summarization
and pruning agent.
The “Historical collection configuration” topics in the Tivoli Enterprise Portal User's
Guide describe how to configure historical data collections for attribute groups,
how to get a report of historical data for a specified time range, how to apply
historical baselines to a chart for trend analysis, and how to model situation
thresholds using historical data.
Important: You can run only one summarization and pruning agent even
if you have multiple monitoring servers that are sharing a single Tivoli
Data Warehouse database. Running multiple summarization and pruning
agents causes database deadlocks and conflicts because the multiple
instances might attempt to summarize or prune the data in the tables
simultaneously.
Converting short-term history files to delimited flat files
If you choose not to use the Tivoli Data Warehouse, then you must
institute roll-off jobs to regularly convert and empty out the history data
files. Roll-off programs are provided. In addition to trimming the history
data files, these scripts produce flat files which can be used with
third-party tools to produce trend analysis reports and graphics. There is
also an environment variable for setting the maximum size of history files.
See “Limiting the growth of short-term history files” on page 500.
Some attribute groups are ineligible for historical data collection
Some agents do not enable collection of history data for all of their
attribute groups. This is because the product development team for that
agent has determined that collecting history data for certain attribute
groups is not appropriate or might have a detrimental effect on
performance. This might be because of the vast amount of data that is
generated. Therefore, for each product, only attribute groups that are
The directory must be an existing directory, you must specify the full path, and
your operating system user ID must have write permission for this directory. If the
directory does not exist, the agent will not collect historical data.
Procedure
v
1. In the Manage Tivoli Enterprise Monitoring Services window, right-click the
monitored application and click Advanced → Edit Variables.
2. In the Override Local Variable Settings window, click Add.
3. Scroll through the variable list and select CTIRA_HIST_DIR
4. In the Value field, replace @LogPath@ with the full path to the directory where
you want the short-term history to be saved.
5. Click OK to see CTIRA_HIST_DIR in the Variable column and the new path
in the Value column; and click OK again to close the window. The value is
recorded in the KpcENV file, such as KNTENV.
6. Recycle the agent to have your changes take effect.
v
1. Change to the <itm_install_dir>/config directory and open pc.ini in a text
editor, where pc is the two-character product code. For example,
/opt/IBM/ITM/config/ux.ini for the UNIX OS agent. For a list of product
codes, see “IBM Tivoli product, platform, and component codes” in the IBM
Tivoli Monitoring Installation and Setup Guide.
2. On a new line, add this environment variable followed by the full path to the
location where you want the short-term history to be saved:
CTIRA_HIST_DIR=
3. Save and close the file.
4. Recycle the agent to have your changes take effect.
When historical data is stored at the agent, the history file for one attribute group
contains data only for that agent and is much smaller than the one stored at the
monitoring server. The most recent 24 hours worth of data comes from short-term
history files. Beyond 24 hours, the data is retrieved from the Tivoli Data
Warehouse. (You can change the break point with the
KFW_REPORT_TERM_BREAK_POINT portal server environment variable.) This
action is transparent to the user; however, requests returning a large a amount of
data can negatively impact the performance of monitoring servers, monitoring
agents, and your network.
If a query goes to the short-term history file and retrieves a large amount of data,
this retrieval can consume a large amount of CPU and memory and users can
experience low system performance while the data is being retrieved. When
processing a large data request, the agent might be prevented from processing
other requests until this one has completed. This is important with many
monitoring agents because the agent can typically process only one view query or
situation at a time.
A best practice that can be applied to the historical collection, to the view query,
or both is to use filters to limit the data before it gets collected or reported. For
historical collections, pre-filtering is done in the Filter tab of the Historical
Collection Configuration editor or the filter option of the CLI tacmd
histcreatecollection command, as described in the IBM Tivoli Monitoring Command
Reference (http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/topic/
com.ibm.itm.doc_6.3fp2/ic/landing_cmdref.htm) and “Creating a historical
collection” in the Tivoli Enterprise Portal User's Guide. For workspace views,
pre-filtering is done in the Query editor by creating another query from a
For optimal performance, best practice is to ensure the short term history file
does not exceed 1 GB.
You specify the collection interval and filter criteria in the History Collection
Configuration window. To find out the disk space requirements for tables in your
IBM Tivoli Monitoring product, see the specific agent's documentation.
While displaying a query-based view, you can set the Time Span interval to obtain
data from previous samplings. Selecting a long time span interval for the report
time span adds to the amount of data being processed, and might have a negative
impact on performance. The program must dedicate more memory and CPU cycles
to process a large volume of report data. In this instance, specify a shorter time
span setting, especially for tables that collect a large amount of data.
If a report rowset is too large, the report request can drop the task and return to
the Tivoli Enterprise Portal with no rows because the agent took too long to
process the request. However, the agent continues to process the report data to
completion, and remains blocked, even though the report data is not viewable.
The historical report data from the z/OS Persistent Data Store might not be
available. This situation occurs because the Persistent Data Store might be not be
available while its maintenance job is running.
Depending upon the reporting requirements, there are two mechanisms that can be
used, exploiting the open interfaces that are included with the warehouse:
1. If the complete database is required, use the Database Replication Facilities of
the Tivoli Data Warehouse RDBMS.
2. Write and schedule SQL extract scripts, similar to ETL Scripts in Tivoli Data
Warehouse V1.x, to extract desired data elements at a scheduled interval from
the Tivoli Data Warehouse and populate a reporting database. This reporting
database can be optimized for use by an external reporting tool, just like data
marts were used in Tivoli Data Warehouse V1.x. These scripts can be SQL
Scripts, shell scripts, or PERL scripts.
See the IBM Redbooks® publication, Introduction to Tivoli Enterprise Data Warehouse
at http://www.redbooks.ibm.com/ for references and additional sample SQL
extract scripts.
The history tables in the Tivoli Data Warehouse database have the same names as
the group names of history tables and columns. For example, Windows NT history
for group name NT_System is collected in a short-term file having the name
WTSYSTEM. Historical data in this file, WTSYSTEM, is stored to the database in a
table named NT_System.
The warehouse proxy uses the complete product attribute name to create DBMS
table and column identifiers. This includes any special characters found in an
attribute name. When the length of an attribute name exceeds the maximum table
or column name length supported by a DBMS product, the warehouse proxy uses
the internal table and column names as defined in the product attribute file.
The warehouse proxy automatically creates an associated index for each data table
in the warehouse database. The index is based on WRITETIME and ORIGINNODE
(whose display name can be “Server_Name,” “System_Name," and so on,
depending on the table) and the TMZDIFF (time zone difference) columns. The
index name is the short name of the table, with an “_IDX” suffix.
All data warehouse table or column names for all major DBMS products are
created by surrounding them with the DBMS-supported quoted identifier
characters. When referencing historical data in the warehouse database, you must
use the double-quote character to ensure correct access to that data. Some database
products, such as Microsoft SQL Server, do not require the use of double quotes.
If you created SQL queries or stored procedures prior to IBM Tivoli Monitoring
V6.2.1 for use with the previous version of the historical data collection program,
these now might need to be modified. The SQL needs to take into account the fact
that some relational database products (such as Oracle) require all table and
column names to be surrounded by double quotation marks to access IBM history
data, some agents might have changed their data characterizations or added new
columns.
The ATTRLIB directory in the warehouse proxy is automatically created for you at
product installation time. On a Windows system, this directory is located in
ITM_dir\tmaitm6\attrlib. On an operating system such as UNIX, this directory is
located in ITM_dir/hd/tables.
The attribute file allows determination of the table or column internal name when
the length of an attribute name exceeds the maximum table or column name
length that a warehouse DBMS product supports. In that condition only, the
attribute file must be in the ATTRLIB directory. If the warehouse proxy is installed
on a separate computer and you have a monitoring agent that is not at the latest
level, you must copy the attribute file of that agent to the ATTRLIB directory
where the warehouse proxy is installed.
If you see an error message stating that an export failed because a particular
product attribute file was missing from this directory, locate the missing product
attribute file and copy it into the ATTRLIB directory.
When changes are detected in the set of collected attributes, such as when a new
version of an agent with added attributes is deployed, the historical program
performs these functions:
v If warehousing is specified in the current historical data collection request, all
collected historical data for the table is exported to the data warehouse. If the
warehousing operation is successful, all short-term history data and meta files
are deleted.
If the operation fails (for example, if the warehouse proxy is not available), the
short-term historical data and meta files are renamed. On the z/OS operating
system environment, if a generic table is used to store the data, the short-term
historical data for a table are deleted regardless of whether the warehousing
operation is successful or not.
– Windows and UNIX operating system environments
On these operating system environments, the history data and meta files are
renamed with the .prv and .prvhdr suffixes respectively.
– IBM i operating system environment
On this operating system environment, the history data and meta files are
renamed with the P and Q suffixes respectively.
If the renamed files already exist, they are deleted prior to the renaming
operation (that is, only one generation of changed short-term history files is
kept).
v If warehousing is NOT specified in the current historical data collection request,
the history data and meta file are renamed as described above. On z/OS, if a
generic table is used to store the data, all short-term history data for a table
together with its meta record are deleted.
To use partitioned tables, the Summarization and Pruning agent and Warehouse
Proxy agent must both be configured with partitioning enabled and the Tivoli Data
Warehouse must allow partitioning.
The migration and required cleanup is handled using scripts generated by the
schema publication tool in migrate mode. The scripts provide the following
functions:
tdw_migrate_setup.sql
This script creates a stored procedure to redefine the source table to a new
partitioned table and creates the control tables required for migration, such
as the WAREHOUSE_MIGRATION_STATUS table.
tdw_migrate_step1.sql
This script invokes the stored procedure created in the setup script. The
stored procedure renames the source table to MIGRATING_<short table
name>, creates the new partitioned table, loads the data from the source
table to the new table, and then renames the source table to DONE_<short
table name>.
You can also migrate tables partitioned using a partitioning scheme different than
the Tivoli Data Warehouse partitioning scheme. Only a table partitioned with the
Tivoli Data Warehouse scheme can be managed by the Summarization and Pruning
agent. If you want to continue to use your user-defined partitioning scheme, use
the KSY_TABLE_FILTER variable to list only the tables you want migrated.
A migrated table's partitions are defined based on the table's retention period and
the forward partitions parameter. The forward partitions parameter is a configuration
parameter defined in the Summarization and Pruning configuration file using the
variable KSY_PARTITIONS_UPWARD. The retention period is the pruning
parameter defined on the attribute group you select through the History
Configuration dialog in the Tivoli Enterprise Portal or through the command line.
For more information about range partitioning, see “Tivoli Data Warehouse range
partitioning” in the IBM Tivoli Monitoring Installation and Setup Guide.
Best practice is to migrate the tables in batches. This practice reduces the amount
of disk space required for migration and the amount of time the Summarization
and Pruning agent and Warehouse Proxy agent need to be offline. A batch of tables
can be migrated within a maintenance window.
Review the “Prerequisites and best practices.” You must ensure you have enough
disk space.
Procedure
1. Configure the Summarization and Pruning agent to partition tables. For
detailed steps, see “Specifying range partitioned tables for the Summarization
and Pruning Agent” in the IBM Tivoli Monitoring Installation and Setup Guide.
2. Stop all Warehouse Proxy agent and Summarization and Pruning agent
instances.
3. Backup the Tivoli Data Warehouse database.
4. Edit the schema publication tool response file.
a. Open the response file:
install_dir/arch/bin/tdwschema.rsp
b. Configure the following variables:
KSY_PRODUCT_SELECT = migrate
KSY_PRODUCT_FILTER = list of products to migrate
An optional filter to indicate that only certain specific products are
included. (If you do not specify a filter, all products in the specified
category are included by default.) Specify the three-letter product codes of
the products you want to include, separated by commas. You can find
these codes by using the tacmd histListProduct command (for more
information, see the IBM Tivoli Monitoring Command Reference).
KSY_TABLE_FILTER = list of tables to migrate
An optional filter to indicate only specific tables. This filter can be used in
addition to the KSY_PRODUCT_FILTER variable. Use the following command
to get the list of tables that are available for a given product. Replace each
space in the attribute group name with an underscore character. For a list
of table names, use the following command:
tacmd histListAttributeGroups -t <productcode>
set CANDLE_HOME=install_dir
CANDLEHOME=/install_dir
export CANDLEHOME
7. Run the schema publication tool script to generate the scripts required for
migration.
install_dir/arch/bin/tdwschema.sh
The following scripts are generated for migration: tdw_migrate_setup.sql,
tdw_migrate_step1.sql, and tdw_migrate_step2.sql.
8. Execute the tdw_migrate_setup.sql script and view the results to ensure it
executed successfully.
db2 -td# -f tdw_migrate_setup.sql
Use the tdw_migrate_setup.sql script only once, even when migrating in
batches. Executing this script more than once breaks the ability of the
migration process to restart if an error occurs. This script contains drop
statements that might fail if the objects do not already exist. Do not consider
these failures as errors, they can be ignored. The expected failures might
return the following messages: DB21034E and SQL0204N.
Results
The tables you specified are now partitioned, and the source tables have been
deleted.
What to do next
Review the “Prerequisites and best practices” on page 475. You must ensure you
have enough disk space.
The schema publication tool can only be executed on a distributed platform, such
as UNIX or Windows. The scripts generated must be executed from a distributed
platform with a DB2 client connected to the remote DB2 z/OS database.
The Tivoli Data Warehouse user must have one or more of the following privileges
in order to execute the tdw_migrate_setup.sql script:
v Ownership and EXECUTE privilege for the packages, DSNADMJS and
DSNADMJF, used in the setup script
v SYSADM authority
v PACKADM authority for the package collection
v Daemon authority
If the BPX.DAEMON is active, the stored procedures loaded into an address
space must be defined to the RACF program control. Otherwise, the following
error is returned: EDC5139I Operation not permitted. For detailed information
about this issue, search for APAR “II13698” in the IBM Support Portal.
The privileges required for migration can be revoked after all the desired
migrations are complete.
You must define the stored procedures to DB2 using the DSNTIJSG sample
installation job, then ensure that all stored procedures are defined to RACF
program control. Additionally, you must define the necessary application
environment in WLM to run these stored procedures, and also specify a WLMENV
value. For more information on defining the stored procedures to DB2, see the DB2
for z/OS Installation and Migration Guide and DB2 for z/OS Administration Guide for
DB2 9 or later, in the DB2 for z/OS Information Center.
Procedure
1. Configure the Summarization and Pruning agent to partition tables. For
detailed steps, see “Specifying range partitioned tables for the Summarization
and Pruning Agent” in the IBM Tivoli Monitoring Installation and Setup Guide.
2. Stop all Warehouse Proxy agent and Summarization and Pruning agent
instances.
3. Backup the Tivoli Data Warehouse database.
4. Catalog the z/OS database using the following commands:
db2 catalog tcpip node <node_Name> remote <DB_server_hostname>
server <port_number> ostype OS390
db2 catalog dcs database <db_name> as <db_name>
db2 catalog db <database_name_on_server> as <alias_on_client_database_name>
at node <node_Name> authentication dcs
5. Edit the schema publication tool response file.
a. Open the response file:
install_dir/arch/bin/tdwschema.rsp
set CANDLE_HOME=install_dir
CANDLEHOME=/install_dir
export CANDLEHOME
7. Ensure the Tivoli Enterprise Portal Server is started.
8. Run the schema publication tool script to generate the scripts required for
migration.
install_dir/arch/bin/tdwschema.sh
The following scripts are generated for migration: tdw_migrate_setup.sql,
tdw_migrate_step1.sql, and tdw_migrate_step2.sql.
9. Execute the tdw_migrate_setup.sql script and view the results to ensure it
executed successfully.
db2 -td# -f tdw_migrate_setup.sql
Use the tdw_migrate_setup.sql script only once, even when migrating in
batches. Executing this script more than once breaks the ability of the
migration process to restart if an error occurs. This script contains drop
statements that might fail if the objects do not already exist. Do not consider
these failures as errors, they can be ignored. The expected failures might
return the following messages: DB21034E and SQL0204N.
10. In the tdw_migrate_step1.sql script update the INSERT INTO
WAREHOUSE_MIGRATION_CONFIG statement with the following
information:
v Specify the user ID and password required to execute the stored migration
procedure. You can specify NULL for the user ID and password in the
following circumstances:
– The operating system is z/OS Version 1 Release 13 or later, and the
authorization ID that is associated with the stored procedure address
space has daemon authority.
– The operating system is z/OS Version 1 Release 13 or later, and the
authorization ID that is associated with the stored procedure address
space does not have daemon authority but is authorized to the
BPX.SRV.userid SURROGAT class profile, where useridis the authorization
ID of the stored procedure. In this case, you must install APAR OA36062.
For more information see the DB2 for z/OS Administration Guide.
v Specify the JCL prefix library where the system LOAD and UNLOAD
utilities are located.
11. Execute the tdw_migrate_step1.sql script and view the results to ensure it
executed successfully.
db2 -tf tdw_migrate_step1.sql
If any errors occur after this script is executed, the errors must be resolved
before running the tdw_migrate_step2.sql script. Continue to re-execute this
script until all errors are resolved.
The following return codes apply:
v -5: Invalid system name specified
v -4: Invalid job class specified
v -3: Prefix library is null
v -2: Table already partitioned
v -1: Invalid parameter passed
v 0: No errors occurred
v 1: Rename source table failed
v 2: Create partitioned table failed
v 3: Create or submit migrate JCL job failed
v 4: Query migrate JCL job status failed
v 5: Fetch migrate JCL job output failed
Results
The tables you specified are now partitioned, and the source tables have been
deleted.
What to do next
If any errors occurred during the migration, review the
WAREHOUSE_MIGRATION_STATUS,
WAREHOUSE_JCLJOB_MIGRATION_STATUS, and
WAREHOUSE_JCLJOB_OUTPUT tables. For detailed information, see the IBM
Tivoli Monitoring Troubleshooting Guide.
Review the “Prerequisites and best practices” on page 475. You must ensure you
have enough disk space.
The Tivoli Data Warehouse user must be directly granted the following system
privileges, the privileges cannot be granted via a role:
v ALTER ANY TABLE
v CREATE ANY TABLE
v DROP ANY TABLE
v LOCK ANY TABLE
v SELECT ANY TABLE
v Execution privileges for the DBMS_REDEFINITION package
To grant authority use the grant execute on DBMS_REDEFINITION TO <Tivoli
Data Warehouse user ID> command.
Procedure
1. Configure the Summarization and Pruning agent to partition tables. For
detailed steps, see “Specifying range partitioned tables for the Summarization
and Pruning Agent” in the IBM Tivoli Monitoring Installation and Setup Guide.
2. Stop all Warehouse Proxy agent and Summarization and Pruning agent
instances.
3. Backup the Tivoli Data Warehouse database.
4. Edit the schema publication tool response file.
a. Open the response file:
install_dir/arch/bin/tdwschema.rsp
b. Configure the following variables:
KSY_PRODUCT_SELECT = migrate
KSY_PRODUCT_FILTER = list of products to migrate
An optional filter to indicate that only certain specific products are
included. (If you do not specify a filter, all products in the specified
category are included by default.) Specify the three-letter product codes of
the products you want to include, separated by commas. You can find
these codes by using the tacmd histListProduct command (for more
information, see the IBM Tivoli Monitoring Command Reference).
KSY_TABLE_FILTER = list of tables to migrate
An optional filter to indicate only specific tables. This filter can be used in
addition to the KSY_PRODUCT_FILTER variable. Use the following command
to get the list of tables that are available for a given product. Replace each
space in the attribute group name with an underscore character. For a list
of table names, use the following command:
tacmd histListAttributeGroups -t <productcode>
KSY_SUMMARIZATION_SELECTION = list of aggregation periods to migrate
An optional filter that can be used in addition to the KSY_PRODUCT_FILTER
and KSY_TABLE_FILTER variables. This variable has an additional option
when the migrate mode is used. The R option allows you to migrate the
detailed tables. Other options are as follows:
R: Migrate detailed tables only
H: Hourly
D: Daily
W: Weekly
M: Monthly
Q: Quarterly
set CANDLE_HOME=install_dir
CANDLEHOME=/install_dir
export CANDLEHOME
7. Run the schema publication tool script to generate the scripts required for
migration.
install_dir/arch/bin/tdwschema.sh
The following scripts are generated for migration: tdw_migrate_setup.sql,
tdw_migrate_step1.sql, and tdw_migrate_step2.sql.
8. Execute the tdw_migrate_setup.sql script and view the results to ensure it
executed successfully.
sqlplus <TDW userid>/<password>@<Oracle SID> @./tdw_migrate_setup.sql
Use the tdw_migrate_setup.sql script only once, even when migrating in
batches. Executing this script more than once breaks the ability of the
migration process to restart if an error occurs. This script contains drop
statements that might fail if the objects do not already exist. Do not consider
these failures as errors, they can be ignored. The expected failures might
return the following messages: DB21034E and SQL0204N.
9. Execute the tdw_migrate_step1.sql script and view the results to ensure it
executed successfully.
sqlplus <TDW userid>/<password>@<Oracle SID> @./tdw_migrate_step1.sql
If any errors occur after this script is executed, the errors must be resolved
before running the tdw_migrate_step2.sql script. Continue to re-execute this
script until all errors are resolved.
If the tdw_migrate_step1.sql script succeeds, a message is provided. For
example:
Partitioning table "AIXTST"."KSY_TABLE_STATISTICS"
Results
The tables you specified are now partitioned, and the source tables have been
deleted.
What to do next
If any errors occurred during the migration, review the error messages from the
execution of the scripts.
The Tivoli Enterprise Portal enables you to set up summarization and pruning for
selected attribute groups in the History Collection Configuration window or from
Names can be different between the detailed data table and summarized
table name due to database name length restrictions.
Summarization and pruning metrics
The following example describes how the Summarization and Pruning
agent calculates metrics that accumulate over time. You can use the results
to manage your resources. In this example, the metric represents cache hits
since last restart of server.
The total number of cache hits in the last hour is given by the Total value.
The Low value represents the lowest number of cache hits in the hour
based on all the detailed data values for the hour. The High value
represents the highest number of cache hits in the hour based on all the
detailed data values for the hour.
With these detailed data values in one hour: 9, 15, 12, 20, 22, delta-based
processing has the following rules:
v If the current value is greater than or equal to the previous value, the
output equals the previous value minus the current value.
v If the current value is less than the previous value, the output equals the
current value.
v Because 15 is greater than 9, the output equals 6.
v Because 12 is less than 15, the output equals 12.
v Because 20 is greater than 12, the output equals 8.
v Because 22 is greater than 20, the output equals 2.
v The TOT_ value is 28, which is the total of outputs.
v The LOW_ value is 2, which is the lowest of outputs.
v The HI_ value is 12, which is the highest of outputs.
Null values in tables and charts of summarized and pruned data
If you see null as the value of a table cell or chart point, it means that no
value was stored in the Tivoli Data Warehouse. This happens when values
that were identified as invalid are reported from a monitoring agent for a
given summarization period. The agent support files might have been
upgraded or some data cannot be computed on the summarized tables (for
instance, counter and delta-based values cannot be calculated if only one
value is present).
Before enabling historical collection think about your business requirement for the
data. There are four common use cases for the historical data. Your needs will vary
for each attribute group, so consider the use cases when configuring historical
collection: problem determination and debugging; reporting; capacity planning and
predictive alerting; and adaptive monitoring.
For performance tuning best practices for the Summarization and Pruning agent,
as well as the other monitoring components, see “Performance tuning” in the IBM
Tivoli Monitoring Installation and Setup Guide.
Each of these use cases has different historical requirements. The following sections
describe each of these use cases and the types of historical collection that will be
desirable.
Problem determination and debugging
These types of metrics are used for problem determination and debugging,
which tends to be relatively short term in nature. Occasionally there is a
need to compare performance from a long time ago, but most of the time
Subject Matter Experts (SMEs) want to go back a few days and evaluate
After the scheduled run time, you should have summary data in the warehouse.
The summarization and pruning agent must be installed, configured, and started
as described in the IBM Tivoli Monitoring Installation and Setup Guide.
Your user ID must have Configure History permission to open the History
Collection Configuration window. If you do not have this permission, you will not
see the menu item or tool for historical configuration.
Procedure
1. If the History Collection Configuration window is not open, click History
Configuration.
2. Select a Monitored Application from the tree.
3. Review the attribute groups in the table. If summarization and pruning has
already been configured for an attribute group, the values will be shown in the
summarization and pruning cells. Collapse the tree, drag the borders, or scroll
the table right to see all the cells.
4. Select one or more attribute groups to configure. You can select multiple groups
with Ctrl+click, or Shift+click to select all groups from the first one selected to
this point. The settings of the first group selected continue to display, regardless
of the settings in any of the other selected groups. This enables you to adjust
the configuration controls once and apply the same settings to all selected
attribute groups. Use the Clear all button if you want to clear all the fields and
start over.
5. In the Summarization area, select the check box for every time period to be
aggregated: Yearly, Quarterly, Monthly, Weekly, Daily, and Hourly.
6. In the Pruning area, select the check box for every time period to be pruned:
Yearly, Quarterly, Monthly, Weekly, Daily, and Hourly. If you also want to keep
the original data samples, select the Detailed data check box. In the
corresponding fields, specify the number of days, months, or years to keep the
data.
7. Click Apply to save the configuration for the attribute groups that were
selected. The summarization and pruning cells for the attribute group are
updated to reflect the new settings.
What to do next
The next time summarization and pruning takes place, the summarization and
pruning agent applies the configuration to the long-term data stored in the data
warehouse. Wait for the next scheduled time period to elapse before expecting to
see any summarized data.
Granular summarization and pruning settings are configured only through the
command-line interface using the tacmd histconfiguregroups command specifying
the -g and -m parameters. Unlike granular summarization and pruning settings,
global summarization and pruning settings can be configured through the
command-line interface or in the Tivoli Enterprise Portal. If your Summarization
and Pruning agent is running in autonomous mode, you cannot configure
summarization and pruning for managed system groups.
The summarization and pruning agent must be installed, configured, and started
as described in the IBM Tivoli Monitoring Installation and Setup Guide.
The managed system groups must be defined with their correlating systems. You
can create managed system groups in the Tivoli Enterprise Portal using the Object
group editor or through the command-line interface. For detailed syntax of the
tacmd createsystemlist command, see the IBM Tivoli Monitoring Command
Reference.
You can assign different summarization and pruning policies to different managed
system groups. For example, one group might retain data for 180 days and the
other group might retain data for 30 days. Another example is, one group
summarizing hourly and the other group summarizing hourly and daily.
A managed system can be part of multiple managed system groups which might
have different summarization and pruning settings. In this case, the multiple
settings are merged, resulting in a union of all summarizations and retention using
the largest found interval. For example:
Group A has hourly and daily summarizations with 10 days and 30 days
retention.
Group B has hourly, daily, and weekly summarizations with 30 days, 60 days,
and 6 months retention.
In this example, for a system that is a member of both groups, the union of the
summarization settings is hourly, daily, and weekly. The retention settings for the
system are 30 days for hourly, 60 days for daily, and 6 months for weekly since
those are the largest setting for each summarization.
If a system does not belong to any managed system groups that have
summarization and pruning settings defined, the global summarization settings are
used. Global summarization is configured through the Tivoli Enterprise Portal or
the command-line interface using the tacmd histconfiguregroups, not specifying
the -g parameter. For more information on configuring global summarization
settings, see “Configuring summarization and pruning for attribute groups” on
page 490 or the IBM Tivoli Monitoring Command Reference.
When you use Tivoli Data Warehouse range partitioning, the following scenarios
apply:
v If there are only global summarization and pruning settings for a table, the
partitions are dropped using the defined retention values.
v If there are any managed system group summarization and pruning settings for
a table, both of the following conditions must be true:
– There are global pruning settings that are defined for the attribute group's
detail or summary table.
– There are pruning settings that are defined for the attribute group's detail or
summary table for all configured managed system groups.
When both conditions are not true, the summarization and pruning agent
outputs a warning message in its log and self monitoring workspace.
Best practice is to define the retention period globally and for each configured
managed system group for the detail data and for all summary tables that might
contain data.
Procedure
v Use the tacmd histconfiguregroups command with the -g and -m parameters to
configure summarization and pruning for managed system groups.
For example, the command tacmd histconfiguregroups -t knt -o NT_Memory_64
-d HD -p H=30d,D=60d -m -g NT_Dev creates a configuration setting for the
agents that belong to the NT_Dev managed system group, with hourly and daily
summarization, and retention of 30 days for the hourly table and 60 days for the
daily table.
v Use the tacmd histviewattributegroup command to view the settings for a
given attribute group.
For example, the command tacmd histviewattributegroup -t knt -o
NT_Memory_64 lists the global settings in effect for that attribute group and all the
managed system groups that have granular settings on that attribute group.
To view only granular settings for a given managed system group, use the -g
parameter.
For example, the command tacmd histviewattributegroup -t knt -o
NT_Memory_64 -g NT_Dev, lists the settings that are specific to the NT_Dev
managed system group.
v Use the tacmd histunconfiguregroups command with the -g and -m parameters
to remove the settings for a specific managed system group.
What to do next
The next time summarization and pruning takes place, the summarization and
pruning agent applies the configuration to the long-term data stored in the data
warehouse. Wait for the next scheduled time period to elapse before expecting to
see any summarized data.
Procedure
1. In Manage Tivoli Enterprise Monitoring Services, right-click Summarization
and Pruning agent.
2. Click on Reconfigure.
3. Click OK in the Warehouse Summarization and Pruning Agent: Advanced
Configuration window.
4. Click OK in the next window.
5. Click Yes in the Warehouse Summarization and Pruning Agent window to
configure the Summarization and Pruning Agent.
6. Enter the Tivoli Data Warehouse database and Tivoli Enterprise Portal server
information in the Sources tab:
a. In the JDBC drivers field, click Add to invoke the file browser window to
select your JDBC driver. Click OK to close the browser and add the JDBC
drivers to the list You can also highlight an entry in the JDBC drivers list
and click Delete to remove a driver. This gives you the ability to collect
JDBC drivers to communicate with your Tivoli Data Warehouse database.
JDBC drivers are installed separately and each database provides a set of
these JDBC drivers.
Note:
v If your Tivoli Data Warehouse database is on an operating system such
as UNIX, find the directory where DB2 is installed and, in the jdbc
drivers directory, select the db2jcc.jar and db2jcc_license_cu.jar files. For
example, <db2_installdir>/java/db2jcc.jar and <db2_installdir>/
java/db2jcc_license_cu.jar.
v If your Tivoli Data Warehouse database is on MS SQL Server 2000 or
2005, install the MS SQL Server 2005 JDBC driver from the Microsoft
SQL Server website. You will need the sqljbc.jar file; see the installation
instructions for your operating systems from Microsoft to locate the file.
v If your Tivoli Data Warehouse database uses Oracle, use the ojdbc14.jar
file. The location on Windows is %ORACLE_HOME%\jdbc\lib; the location
on operating systems such as UNIX is $ORACLE_HOME/jdbc/lib.
b. In the drop down list, select the type of database for your Tivoli Data
Warehouse.
If you want to disable summarization and pruning for your entire enterprise:
1. In Manage Tivoli Enterprise Monitoring Services, right-click the Summarization
and Pruning agent in the Service/Application column.
2. Select Stop.
If you want to turn off summarization and pruning for a particular product or set
of attribute groups in the Historical Collection Configuration window:
Procedure
1. In the Tivoli Enterprise Portal, click the Historical Collection Configuration
button that is located on the toolbar.
2. Select the Product.
3. Select one or more Attribute Groups.
4. Click the Unconfigure Groups button.
Procedure
v Open the event log where the warehouse proxy errors are listed:
– Start the Event Viewer by clicking Start → Programs →
Administrative Tools → Event Viewer, then select Application from the Log
menu. If an error occurs during data roll-off, entries are inserted into the
Windows Application Event Log.
– Open the ITM_dir/logs/*hd*.log file.
– On either platform, errors can also be seen in the WAREHOUSELOG table in
the warehouse database.
v Activate the trace option:
1. In Manage Tivoli Monitoring Services, right-click Warehouse Proxy and
select Advanced Edit Trace Parms.
2. Select the RAS1 filters. The default setting is ERROR.
3. Accept the defaults for the rest of the fields.
4. Click Yes to recycle the service.
v View the trace log containing the error messages:
1. In Manage Tivoli Monitoring Services, right-click Warehouse Proxy and
select Advanced → View Trace Log. The Log Viewer window displays a list
of log files for the warehouse proxy.
2. Select the appropriate log file in Select Log File. All logs are listed in this
window, ordered by most recent file.
3. Click OK.
You must manually create history data directories for all agents that are collecting
historical data on the same computer and then edit each agent configuration file on
the same computer to specify the new path for short-term data collection. This is
required on Windows because all agent logs by default are stored in the same
install_dir\tmaitm6\logs\ directory and each agent creates an agent operations
log file named OPLOG to store short term history data. Thus, the same OPLOG
history file is being shared by all the agents; if more than one agent process
attempts to warehouse history data from the same short term history binary file,
the same data could get transferred to the Tivoli Data Warehouse more than once.
For example, the Windows OS and Active Directory monitoring agents are
installed. Each process will create and store its operations log history data in a file
named C:\IBM\ITM\TMAITM6\logs\OPLOG Now there are at least two processes
attempting to share the same history data file. The data from multiple agents can
be written to the same file, but the warehouse upload process will encounter
problems with this setup. One agent process is not aware that, at any given time,
another agent process might be performing the same warehouse data upload from
the same short-term history file. This can lead to duplicate history data transferred
to the warehouse database.
For each agent that collects historical data on Windows, complete these steps:
Procedure
1. Create a history child directory of install_dir\tmaitm6\logs\.
2. Create a k?? child directory of install_dir\tmaitm6\logs\history where ?? is
the two-character product code. For example, c:\ibm\itm\tmaitm6\logs\
history\k3z would be the path to IBM Tivoli Monitoring Agent for Active
Directory short-term history files. The system user ID for this agent must have
read and write permission for this directory.
3. Open the install_dir\tmaitm6\k??cma.ini agent configuration file (where ?? is
the two-character product code) in a text editor. See your monitoring product
user's guide for the name of the file used for agent configuration.
4. Locate the CTIRA_HIST_DIR=@LogPath@ parameter and append with
\history\k?? (where ?? is the two-character product code). For example,
CTIRA_HIST_DIR=@LogPath@\history\knt specifies c:\ibm\itm\tmaitm6\logs\
history\knt for Windows OS agent historical data collection on this computer.
5. Save the k??cma.ini configuration file.
6. Copy the install_dir\tmaitm6\logs\khdexp.cfg warehouse upload status file
to the \history\k?? directory. If this file is not copied to the new agent history
directory, your existing history data might be warehoused more than once. It is
possible that this file does not exist if the history warehousing option has never
been enabled.
Please note that you might be copying history data files from the tmaitm6\logs
directory that are not managed by the target agent. For example, the directory
might contain Oracle database history data, but you are copying the files to the
new Windows OS agent history directory. The copied files that are not used by
the Windows OS agent will not be needed and can safely be deleted.
8. In Manage Tivoli Enterprise Monitoring Services, right-click the monitoring
agent service and click Reconfigure, click OK twice to accept the settings in the
configuration windows, then Start the agent.
Note: The data warehousing process adds only two columns, TMZDIFF
and WRITETIME, to the Tivoli Data Warehouse database.
Meta description files
A meta description file describes the format of the data in the source files.
Meta description files are generated at the start of the historical data
collection process.
The various operating system environments use different file naming
conventions. Here are the rules for some operating system environments:
v IBM i and HP NonStop Kernel: Description files use the name of the
data file as the base. The last character of the name is 'M'. For example,
for table QMLHB, the history data file name is QMLHB and the
description file name is QMLHBM.
v z/OS: Description records are stored in the PDS facility, along with the
data.
v UNIX and Linux: Uses the *.hdr file naming convention.
v Windows: Uses the *.hdr file naming convention.
Sample *.hdr meta description file
TMZDIFF(int,0,4) WRITETIME(char,4,16)
QM_APAL.ORIGINNODE(char,20,128) QM_APAL.QMNAME(char,148,48)
QM_APAL.APPLID(char,196,12) QM_APAL.APPLTYPE(int,208,4)
QM_APAL.SDATE_TIME(char,212,16)
QM_APAL.HOST_NAME(char,228,48)
QM_APAL.CNTTRANPGM(int,276,4) QM_APAL.MSGSPUT(int,280,4)
QM_APAL.MSGSREAD(int,284,4) QM_APAL.MSGSBROWSD(int,288,4)
QM_APAL.INSIZEAVG(int,292,4) QM_APAL.OUTSIZEAVG(int,296,4)
QM_APAL.AVGMQTIME(int,300,4) QM_APAL.AVGAPPTIME(int,304,4)
QM_APAL.COUNTOFQS(int,308,4) QM_APAL.AVGMQGTIME(int,312,4)
QM_APAL.AVGMQPTIME(int,316,4) QM_APAL.DEFSTATE(int,320,4)
QM_APAL.INT_TIME(int,324,4) QM_APAL.INT_TIMEC(char,328,8)
QM_APAL.CNTTASKID(int,336,4) SAMPLES(int,340,4)
INTERVAL(int,344,4)
For example, an entry can have the form, where int identifies the data as
an integer, 75 is the byte offset in the data file, and 20 is the length of the
field for this attribute in the file:
attribute_name(int,75,20)
Your operating system user ID must have write permission for this directory.
When your configuration includes data roll-off to the Tivoli Data Warehouse, the
size of the short-term history files is controlled by the amount of data being
collected, the frequency of collection, and the frequency of roll-off to the data
warehouse. Yet, it is possible for the warehouse proxy agent or data warehouse to
become unavailable, which means the short-term history files can grow unchecked.
Complete these steps to specify a size limit for the directory where short-term
history files are saved and how often that this check should take place:
Procedure
1. Open the environment file for the agent:
v In the Manage Tivoli Monitoring Services window, right-click the
component and click Advanced → Edit ENV File. (These are the
install_dir\TMAITM6\K<pc>ENV files where <pc> is the two-character product
code, such as C:\IBM\ITM\TMAITM6\KNTENV.)
v Change to the install_dir/config directory and open
<pc>.ini in a text editor, where <pc> is the two-character product code. For
example, /opt/IBM/ITM/config/ux.ini for the UNIX OS agent.
For a list of product codes see “IBM Tivoli product, platform, and component
codes” in the IBM Tivoli Monitoring Installation and Setup Guide.
2. Add two new lines to the file, where 5 is the maximum number of megabytes
that the directory where the short-term history file is located can grow to; and
where 900 (15 minutes) is the number of seconds between evaluation of the
directory size:
KHD_TOTAL_HIST_MAXSIZE =5
KHD_HISTSIZE_EVAL_INTERVAL=900
3. Save and close the file.
4. Recycle the component.
Results
After you set a maximum and the directory limit is reached, no new records are
written to the short-term history files, which causes gaps to occur in the data
collected. However, if the data is warehoused, the warehouse proxy will trim the
short term history files to contain only the last 24 hours of data. This can allow the
agent to write historical data again; thus, the limit can be reached again and the
process repeats. This process can also cause gaps to appear in the data.
You must resolve the cause of the unchecked short-term history file growth before
the saving of data samples to the history files can resume. When data is collected
at the agent you can create a custom SQL query or a situation or both that reports
when this condition occurs.
The conversion procedure empties the history accumulation files and must be
performed periodically so that the history files do not take up needless amounts of
disk space.
Note: For every ATTRIBUTEGROUPNAME that you plan to use with the krarloff
program or itmcmd history, you must first stop historical collection for that
attribute by either using the tacmd histstopcollection or the History Collection
Configuration window in the Tivoli Enterprise Portal.
Corruption of the data can occur if both programs, the historical collection and the
krarloff program, try to access the data at the same time. Stopping the historical
collection ensures that the saving and roll off of the data cannot be done
simultaneously.
Attributes formatting
Some attributes need to be formatted for display purposes. For example, floating
point numbers that specify a certain number of precision digits to be printed to the
left of a decimal point. These display formatting considerations are specified in
product attribute files.
When you use the krarloff rolloff program to roll off historical data into a text file,
any attributes that require format specifiers as indicated in the attribute file are
ignored. Only the raw number is seen in the rolled off history text file. Thus,
instead of displaying 45.99% or 45.99, the number 4599 displays.
502 IBM Tivoli Monitoring: Administrator's Guide
The warehouse proxy inserts data according to the type, length, and data precision
specified in the attribute files. However, the Tivoli Data Warehouse database
displays the correct attribute formatting only for those attributes that use integers
with floating point number formats.
You can use the krarloff rolloff program to covert the history file of the Tivoli
System Monitor Agent into a text file on Linux and UNIX. The krarloff rolloff
program is used because the Tivoli System Monitor Agent does not provide the
command itmcmd history on UNIX and Linux.
Procedure
Run the krarloff rolloff program from the directory in which the
monitoring server or the monitoring agent is run by entering the following
at the command prompt:
krarloff [-h] [-g] [-x] [-d delimiter] [-m metafile] [-r rename-to-file]
[-o output-file] {-s source | source-file name}
Where the [ ] square brackets denote the optional parameters and the { }
curly braces denote a required parameter listed below.
After the conversion is finished, the history file is renamed to *.old. For example;
PVTHIST_LNXCPU becomes PVTHIST_LNXCPU.old.
The following table lists the krarloff rolloff program parameters, their purpose, and
default values.
Table 67. Parameters for the krarloff rolloff program
Parameter Default Value Description
-h off Controls the presence or absence of the header in the
output file. If present, the header is printed as the first
line. The header identifies the attribute column name.
-g off Controls the presence or absence of the product
group_name in the header of the output file. Add the
-g to the invocation line for the krarloff rolloff program
to include a group_name.attribute_name in the header.
-x off Excludes the SAMPLES and INTERVAL attributes in
the output file.
-d tab Delimiter used to separate fields in the output text file.
Valid values are any single character (for example, a
comma).
-m source-file.hdr metafile that describes the format of the data in the
source file. If no metafile is specified on the
command-line, the default file name is used.
-r source-file.old Rename-to-filename parameter used to rename the
source file. If the renaming operation fails, the script
waits two seconds and retries the operation.
-o source-file.nnn Output file name. The name of the file containing the
where nnn is output text file.
Julian day
-s none Required parameter. Source short-term history file that
contains the data that needs to be read. Within the
curly brace, the vertical bar (|) denotes that you can
either use an -s source option, or if a name with no
option is specified, it is considered a source file name.
No defaults are assumed for the source file.
Location of the Windows executable files and historical data collection table
files:
This section discusses the location of Windows programs needed for converting
historical data.
If your agent history data has been configured to be stored at the agent computer
and you want to store your history files on a disk that provides more storage
capacity than the default history data file location provides, this location can be
overridden using the existing environment variable CTIRA_HIST_DIR for your
agent. This can not be done when history data is stored at the Tivoli Enterprise
Monitoring Server.
If you have multiple instances of the same agent running on the same Windows
system, the installer creates a separate directory for the process history files stored
at the agent. The default location for agents running on the Windows operating
system is C:\IBM\ITM\TMAITM6\LOGS. New directories are created under the
TMAITM6\LOGS directory: History\<3 character component code>(KUM, KUD, and
so on)\<specified multi-process instance name>.
For example, if you configure a second instance of the DB2 Monitoring agent
called UDBINST1 on the same Windows system, a directory called
C:\IBM\ITM\TMAITM6\LOGS\History\KUD\UDBINST1 is created to store the
history data. This instance of the DB2 agent environment variable
CTIRA_HIST_DIR is set to this value.
The following section describes the location of Windows historical data table files.
The krarloff rolloff program needs to know the location of these files.
If you run the monitoring server and agents as processes or as services, the
historical data table files are located in the:
v install_dir\cms directory on the monitoring server
v install_dir\tmaitm6\logs directory on the managed systems
For example, if you are collecting data for the system status attributes, these two
files are:
v KA4SYSTS: This is the short-term data that is displayed as output by the IBM i
agent.
v KA4SYSTS.hdr: This is the metafile. The metafile contains a single row of
column names.
The contents of both files can be displayed using WRKLNK /qibm/userdata/ibm/
itm.hist command.
Run the krarloff rolloff program by entering the following at the command
prompt:
call qautomon/krarloff parm (['-h’] ['-g’] ['-x’] ['-d’ 'delimiter’]
['-m’ metafile] ['-r’ rename-source-file-to] ['-o’ output-file]
{'-s’ source-file | source-file )}
Where the [ ] square brackets denote the optional parameters and the { } curly
braces denote a required parameter.
If you run the krarloff rolloff program from an IBM i system in the directory in
which the agent is running, replace qautomonwith the name of the executable for
your agent. For example, the MQ agent uses kmqlib in the command string.
KA4SYSTSH is the file that is displayed as output by the krarloff rolloff program
and that contains the data in delimited flat file format. This file can be transferred
from the IBM i to the workstation by means of a file transfer program (FTP).
In the UNIX environment, you use the itmcmd history script to activate and
customize the conversion procedure used to turn selected Tivoli Monitoring
short-term historical data tables into a form usable by other software products. The
historical data that is collected is in a binary format and must be converted to
ASCII to be used by third party products. Each short-term file is converted
independently. The historical data collected by the Tivoli Enterprise Monitoring
Server can be at the host location of the Tivoli Enterprise Monitoring Server or at
the location of the reporting agent. Conversion can be run at any time, whether or
not the Tivoli Enterprise Monitoring Server or agents are active.
Conversion applies to all history data collected under the current install_dir
associated with a single Tivoli Enterprise Monitoring Server, whether the data was
written by the Tivoli Enterprise Monitoring Server or by a monitoring agent.
Note: Certain parameters are required. Items separated with a | vertical bar
denotes mutual exclusivity (for example, Kb|Mb means enter either Kb or Mb, not
both.) Typically, parameters are entered on a single line at the UNIX command
line.
See the IBM Tivoli Monitoring Command Reference for all of the parameters used
with this command.
See the IBM Tivoli Monitoring: Command Reference for a complete description of the
syntax and options.
After the conversion has taken place, the resulting delimited flat file has the same
name as the input history file with an extension that is a single numerical digit.
For example, if the input history file table name is KOSTABLE, the converted file is
named KOSTABLE.0. The next conversion is named KOSTABLE.1, and so on.
Use itmcmd history to schedule automatic conversions by the UNIX cron facility.
To schedule a basic automatic conversion, enter the following at the command line:
./itmcmd history -A n prod_code
where n is a number from 1-24. This number specifies the number of times per day
the data conversion program runs, rounded up to the nearest divisor of 24. The
product code is also required.
For example, the following command means to run history conversion every three
hours:
itmcmd history -A 7 ux
You can use the itmcmd history script to further customize your history collection
by specifying additional options. For example, you can choose to convert files that
are above a particular size limit that you have set. You can also choose to perform
the history conversion on particular days of the week.
See the Command Reference for a description of all of the history conversion
parameters.
The history files collected using the rules established in the History Configuration
program can be converted to delimited flat files for use in a variety of popular
The history files are kept on the DATA subvolume, under the default
<$VOL>.CCMQDAT. However, the location of the history files is dependent on
where you start the monitoring agent. If you started the monitoring agent using
STRMQA from the CCMQDAT subvolume, the files are stored on CCMQDAT.
You can run the krarloff rolloff program from the DATA subvolume by entering
the following:
Note that CCMQDAT and CCMQEXE are defaults. During the installation process,
you can assign your own names for these files.
Attribute formatting:
Some attributes must be formatted for display purposes. For example, floating
point numbers that specify a certain number of precision digits to be printed to the
left of a decimal point. These display formatting considerations are specified in
product attribute files.
When you use the krarloff rolloff program to roll off historical data into a text file,
any attributes that require format specifiers as indicated in the attribute file are
ignored. Only the raw number is seen in the rolled off history text file. Thus,
instead of displaying 45.99% or 45.99, the number 4599 displays.
The short-term history files can be converted to delimited flat files automatically as
part of your persistent data store maintenance procedures, or they can be
converted manually with the MODIFY command. The delimited flat file serves as
input to applications for data manipulation and report creation. For more
information, see the IBM Tivoli OMEGAMON XE and Tivoli Management Services on
z/OS Common Planning and Configuration (http://pic.dhe.ibm.com/infocenter/
tivihelp/v61r1/topic/com.ibm.omegamon_share.doc_6.3.0.1/zcommonconfig/
zcommonconfig.htm)
When you customized your IBM Tivoli Monitoring environment, you were given
the opportunity to specify the EXTRACT option for maintenance. Specification of
the EXTRACT option ensures that scheduling of the process to convert and archive
information stored in your history data tables is automatic. No further action on
your part is required. As applications write historical data to the history data
tables, the persistent data store detects when a given data set is full, launches the
KPDXTRA process to copy the data set, and notifies the Tivoli Enterprise
Monitoring Server that the data set can be used again to receive historical
information. Additional information about the persistent data store can be found in
IBM Tivoli Management Services on z/OS: Configuring the Tivoli Enterprise Monitoring
Server on z/OS.
Note: The KPDXTRA process currently does not support UTF8 columns.
Because the process is automatic, a brief overview of the use of the KPDXTRA
program is provided here. For full information about the KPDXTRA program,
review the sample JCL distributed with your Tivoli Monitoring product. The
sample JCL is found as part of the sample job the KPDXTRA program contained in
the sample libraries RKANSAM and TKANSAM.
Attribute formatting:
Some attributes must be formatted for display purposes. For example, floating
point numbers that specify a certain number of precision digits to be printed to the
left of a decimal point. These display formatting considerations are specified in
product attribute files.
When you use KPDXTRA to roll off historical data into a text file, any attributes
that require format specifiers as indicated in the attribute file are ignored. Only the
About KPDXTRA:
All data sets are kept in read/write state even if they are not active. This makes
the data sets unavailable if the Tivoli Enterprise Monitoring Server is running.
Thus, jobs cannot be run against the active data sets and the inactive data sets
must be taken offline.
You can remove a data set from the Tivoli Enterprise Monitoring Server by issuing
the following command:
F stcname,KPDCMD DELFILE FILE=DSN:datastorefile
Note that DELFILE drops the file only from the PDS; it does not not delete the file.
The file can be added back into the PDS GROUP by issuing a RESUME command:
F stcname,KPDCMD RESUME FILE=DSN:datastorefile
If you must run a utility program against an active data store, issue a SWITCH
command prior to issuing this command.
The following is a summary of the DD names that must be allocated for the
KPDXTRA program. Refer to the sample JCL in the Sample Libraries distributed
with the product for additional information.
Table 68. DD names required
DD name Description
RKPDOUT KPDXTRA log messages
RKPDLOG PDS messages
RKPDIN Table definition commands file (input to PDS subtask) as set
up by the configuration tool
RKPDIN1 PDS file from which data is to be extracted
RKPDIN2 Optional control file defined as a DUMMY DD statement
KPDXTRA parameters:
The following table specifies the parameters of KPDXTRA, along with their default
values and descriptions.
Table 69. KPDXTRA parameters
Parameter Default Value Description
PREF= none Required parameter. Identifies the high level qualifier
where the output files are written.
These messages can be found in the RKPDOUT sysout logs created by the
execution of the maintenance procedures:
Persistent datastore Extract program KPDXTRA - Version V130.00
Using output file name prefix: CCCHIST.PDSGROUP
The following characters are used to delimit output file tokens:
Column values in data file.............: 0x05
Parenthesized list items in format file: 0x6b
Note: Input control file not found; all persistent data is extracted.
Application
Name Table Name No. of Rows Oldest Row Newest Row
PDSSTATS PDSLOG 431 1997/01/10 1997/02/04
05:51:20 02:17:54
The z/OS historical data files created by the extraction program are located in the
following library structure:
v &hilev.&midlev.&dsnlolev.tablename.D
v &hilev.&midlev.&dsnlolev.tablename.H
where:
v stcname identifies the name of the started task that is running either the Tivoli
Enterprise Monitoring Server or agents.
v cccccccc identifies the group name associated with the persistent data store
allocations. The values for cccccccc can vary based on which products are
installed. The standard group name is GENHIST.
When this command is run, only the tables associated with the group identifier are
extracted. If multiple products are installed, each can be controlled by separate
SWITCH commands.
You can also use the Tivoli Enterprise Portal's advanced automation features to run
the SWITCH command. To do so, define a situation that, when it becomes true,
runs the SWITCH command as the action.
See “Configure the persistent data store” in Configuring the Tivoli Enterprise
Monitoring Server on z/OS for instructions on configuring the persistent datastore.
Analytic engines need data to be available with low latency and high frequency.
You must configure your Warehouse Proxy agent and Tivoli Enterprise Monitoring
Agent to emit comma-separated (CSV) files that can be processed by an analytic
engine.
You must have a connection to the Tivoli Data Warehouse to create CSV files.
The Warehouse Proxy agent receives export requests from agents that are stored in
a memory queue where they can sit for a long time depending on how busy the
Warehouse Proxy agent is. This wait can affect analytics that rely on the data from
the Tivoli Data Warehouse because of a latency between the data collection at the
agent, the data being exported to the Warehouse Proxy agent, and the actual write
to the Tivoli Data Warehouse database.
For quicker access to data, you can now configure the Warehouse Proxy agent to
write to a local CSV file as the data from the agent is received, allowing faster
processing and results in a reduction of the load on the Tivoli Data Warehouse.
Before creating CSV files, ensure the following conditions are met:
v You have sufficient disk space on the file system where the files will be written.
v An external application is set up to consume and delete the files. When the
maximum size threshold is reached, no more CSV files are created. To reduce the
load on storage resources, delete the CSV files when the files are processed by
your analytic engine.
v Monitor the file system to ensure data is being consumed correctly with no time
gap in the data.
Automatic maintenance is not available for the CSV files created. However, the
total size of the written files is monitored, and file creation stops if the total size
exceeds a configured threshold. The evaluation period and maximum size value
are configurable environment variables.
Attention: No provision exists for avoiding duplication of data. The data sent
might fail to be inserted into the Tivoli Data Warehouse due to any number of
reasons. Events such as a timeout or database failure can cause the data to be
resent. The Warehouse Proxy agent has no internal state or knowledge that the
data is a resend, because the new data might have more rows or data added to it
since data collection has occurred on the agent.
File format
The CSV file is created as soon as the data is completely exported by the agent.
Initially, the file is created with a temporary name, and when all the data has been
The data is written in the export order as it is sent by the agent. The data includes
a header line containing the column names for readability purposes, and to
provide descriptive information to the data.
Note: The columns in the CSV file might be a subset of the columns in the Tivoli
Data Warehouse, depending on the level of the agent sending the data.
Note: The Warehouse Proxy agent workspaces are not updated to reflect
these variables.
Monitoring agent and monitoring server environment variables
Use the following environment variables to configure monitoring agents
and monitoring servers that you want to export historical data to the
Warehouse Proxy agent:
KHD_PURE_EVENT_UPLOAD
Optional. The interval in minutes to wait before historical data from
pure events is uploaded to the Warehouse Proxy agent. This interval
overrides the default setting of 30 minutes. The minimum value is 1
minute. There is no maximum value. If the historical data is stored at
the monitoring agent, you must specify this environment variable in
the monitoring agent's environment file. If the historical data is stored
at the monitoring server, you must specify this environment variable in
the monitoring servers's environment file. Default: "30".
If you specify a low interval, such as 1 minute, best practice is set
KHD_HISTRETENTION=0 to minimize CPU and disk usage.
The Managed System Status > History Exports workspace is updated
to reflect the Export Interval Time.
KHD_HISTRETENTION
Optional. Specifies the default retention period in hours for the
short-term history files. This value can be used to reduce the amount
of data that is kept on disk after a successful upload to the warehouse
is performed. Default: "24".
If you configured private history, the value specified for the RETAIN=
parameter in the <HISTORY> element overrides the KHD_HISTRETENTION
value. If you do not specify a value for the RETAIN= parameter, then the
KHD_HISTRETENTION value is used.
Specify KHD_HISTRETENTION=0 to delete the short term binary file after
the export is complete. Deleting the short term binary file prevents
space concerns and also speeds up the process of reading the files.
After the short term binary file is deleted, you will not see short-term
data in the Tivoli Enterprise Portal. If you set KHD_HISTRETENTION=0,
then you must also change the variable KFW_REPORT_TERM_BREAK_POINT
in the portal server environment file to ensure that historical queries in
the portal server work correctly.
To use your monitoring agent historical data for analytics complete the following:
v Ensure the Warehouse Proxy agent environment variables required for analytics
are set.
If you want to include only specific attribute data, see “Warehouse Proxy agent
for analytics” on page 514.
v Optionally, you can enable enterprise historical data collection and private
historical data collection to be flagged for analytics.
For full descriptions of the elements and parameters, see “Private situation XML
specification” on page 335.
In the examples included in this topic, the Warehouse Proxy agent is installed on a
UNIX computer. If your Warehouse Proxy agent is installed on a Windows
computer, edit the KHDENV file.
Private history data is collected and sent to the CSV file every 1
minute
Warehouse Proxy agent configuration
In the file hd.ini set:
KHD_CSV_OUTPUT_ACTIVATE=Y
KHD_CSV_OUTPUT=/wpatest2
Private situation configuration
In the file <ITMHOME>/localconfig/lz/lz_situations.xml set:
<PRIVATECONFIGURATION>
<HISTORY Table="Linux_Disk" Interval="1" Export="1" USE="A">
</HISTORY>
<HISTORY Table="Linux_CPU" Interval="1" Export="1" USE="A">
All historical collections data is inserted into the Tivoli Data Warehouse.
Private history data is sent only to the Tivoli Data Warehouse for
one agent, and sent only to the CSV file for another agent
Warehouse Proxy agent configuration
In the file hd.ini set:
KHD_CSV_OUTPUT_ACTIVATE=Y
KHD_CSV_OUTPUT_TAGGED_ONLY=Y
Private situation configuration on an agent running on HOST1
In the file <ITMHOME>/localconfig/lz/lz_situations.xml set:
<PRIVATECONFIGURATION>
<HISTORY Table="Linux_Disk" Interval="1" Export="15">
</HISTORY>
<HISTORY Table="Linux_CPU" Interval="1" Export="15" >
</HISTORY>
<HISTORY Table="KLZ_CPU" Interval="1" Export="15">
</HISTORY>
<HISTORY Table="Linux_Process" Interval="1" Export="15">
</HISTORY>
<HISTORY Table="KLZ_Disk" Interval="1" Export="15" >
</HISTORY>
</PRIVATECONFIGURATION>
Private situation configuration on an agent running on HOST2
In the file <ITMHOME>/localconfig/lz/lz_situations.xml set:
<PRIVATECONFIGURATION>
<HISTORY Table="Linux_Disk" Interval="1" Export="1" USE="A">
</HISTORY>
</PRIVATECONFIGURATION>
Result Data of agent on HOST1 is sent to the Tivoli Data Warehouse.
Data of agent on HOST2 is sent to the CSV file.
-rw-r--r-- 1 root root 1570 Nov 16 08:48
LNXDISK_1111116085832000_1111116085832007_00017.csv
-rw-r--r-- 1 root root 1570 Nov 16 08:49
LNXDISK_1111116085932000_1111116085932007_00018.csv
-rw-r--r-- 1 root root 1570 Nov 16 08:50
LNXDISK_1111116090032000_1111116090032007_00019.csv
Enterprise history data is sent to the CSV file and the Tivoli Data
Warehouse
Warehouse Proxy agent configuration
In the file hd.ini set:
KHD_CSV_OUTPUT_ACTIVATE=Y
KHD_CSV_OUTPUT=/wpatest2
KHD_CSV_OUTPUT_TAGGED_ONLY=N
To get up and running with reporting, complete the following task in the order
provided:
1. “Ensure that historical reporting is enabled” on page 527.
2. Create and maintain the dimension tables.
3. Connect to the Tivoli Data Warehouse using the database client over ODBC.
You only need to setup this connection once.
4. Import reports by using the report installer.
5. If you installed the OS agent reports, then you can run a prerequisite scan.
A set of predefined reports is provided for the Tivoli Monitoring OS Agents and
other products for monitoring individual, multiple, and enterprise resources.
Tivoli Common Reporting consumers
v The network systems programmer who troubleshoots TCP/IP issues
v The application analyst or documentation manager
v The IT manager or service level advisor who validates service level
agreements
v The capacity planner
v The service manager
v The system administrator
v The storage administrator
Tivoli Common Reporting components
Tivoli Common Reporting consists of several components:
v A data store for storing and organizing report designs, reports, and
supporting resources. The data store is a location within the Tivoli
Common Reporting infrastructure where all report-related files and
reports are managed and maintained.
v A web-based user interface for specifying report parameters and other
report properties, generating formatted reports, and viewing reports.
v A command-line interface for working with objects in the data store and
performing additional administrative functions.
v Report packages, archive files containing reports, documentation, graphics,
and dynamic link libraries.
Note: Tivoli Common Reporting provides enhanced security that enables you to
assign a security string to hypertext links in a report. The Tivoli Common Reporting
User's Guide provides instructions for entering a security set.
Note: If you upgraded Tivoli Common Reporting to Version 3.1 or higher and
you want to migrate reports, including any custom reports or report scheduling,
from the earlier version of Tivoli Common Reporting into the latest version, you
must migrate the reporting data before installing the latest monitoring agent
reports into Tivoli Common Reporting Version 3.1 or higher. For instructions on
how to export report packages from the earlier version of Tivoli Common
Reporting and import the packages into the latest version of Tivoli Common
Reporting, see the “Installing Jazz for Service Management” topic in the Jazz for
Service Management Information Center (http://pic.dhe.ibm.com/infocenter/
tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/install/psc_c_install.html).
v Historical data stored in a database manager product supported by IBM Tivoli
Monitoring. For more information about supported databases, refer to
“Supported databases for the Tivoli Data Warehouse” in the IBM Tivoli
Monitoring Installation and Setup Guide.
v For the IBM Tivoli Monitoring agent reports Cognos package, refer your
monitoring agent user's guide for report details. For more information on the
operating system agent reports, see Operating System Agent Documentation
http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/topic/
com.ibm.itm.doc_6.3fp2/ic/landing_osagents.htm. The documentation contains
the required views for each report. If these views are not present, the report
might not work. In order to ensure that the required views are present, run the
following query against the Tivoli Data Warehouse:
– DB2
select distinct "VIEWNAME" from SYSCAT.VIEWS where "VIEWNAME" like ’%V’
– Oracle
Note: In Tivoli Common Reporting, both BIRT and Cognos report engines can
co-exist.
The report packages for the operating system agents that are provided in IBM
Tivoli Monitoring Version 6.3, can be installed with Tivoli Common Reporting 3.1
or 2.1.1. Each time an OS agent report package is installed it replaces the previous
package if applicable. Best practice is to backup any report data before
upgrading. For more information, see “Working with reports”
(http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/
tcr_original/ttcr_working.html).
Limitations
The limitations of the reports produced by Tivoli Common Reporting are described
in this section.
v The Tivoli Monitoring agent Cognos reports are coded to connect to a data
connection in Tivoli Common Reporting with the name TDW.
v Tivoli Monitoring agent reports run against the Tivoli Data Warehouse. DB2
limits the length of columns to 30 characters. Because the Tivoli Data Warehouse
uses attribute group names as the column headers, attribute names longer than
30 characters in a DB2 Tivoli Data Warehouse are replaced with the internal
column name, abbreviated database name for the attribute (for example,
CPU_UTIL or DISK_UTIL rather than CPU Utilization or Disk Utilization).
v Reports that cover a long time period or a processing-intensive attribute might
cause SQL arithmetic overflow.
v Some of the reports do not support the Tivoli Data Warehouse Summarization
and Pruning agent optional definition of shift hours. Customers can use shift
hour support to flag collected data as being either Peak or Off-Peak periods.
However, some reports include all data collected between the customer-selected
report start and end times, whether that data was collected during Peak or
Off-Peak periods. See “About the Summarization and Pruning agent” on page
485 and “Changing global configuration settings” on page 494.
v If the Summarization and Pruning agent shift hours configuration is changed,
the most recent configuration is used for reporting. If you specify a date range
for an availability report that crosses multiple configurations, the availability
metrics might be incorrect. For example, if you edited the peak hours to add one
hour, the summarization for peak hours and off-peak hours are different before
Reports run against long-term historical data that is stored in the Tivoli Data
Warehouse. Before you can run reports, ensure that you have installed the required
components and configured historical data collection:
Procedure
1. Install and configure the Tivoli Data Warehouse and warehouse agents:
Warehouse Proxy agent and Summarization and Pruning agent, see the IBM
Tivoli Monitoring Installation and Setup Guide (http://pic.dhe.ibm.com/
infocenter/tivihelp/v61r1/topic/com.ibm.itm.doc_6.3fp2/install/
itm_install.htm).
2. Set up historical collection using the Historical Collection Configuration feature
in the Tivoli Enterprise Portal, see “Historical collection configuration”.
For z/OS-based monitoring agents, configure the persistent data store using the
Configuration Tool, see “Configure the persistent data store” in the Configuring
the Tivoli Enterprise Monitoring Server on z/OS and also refer to the IBM Tivoli
OMEGAMON XE and Tivoli Management Services on z/OS Common Planning and
Configuration (http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/topic/
com.ibm.omegamon_share.doc_6.3.0.1/zcommonconfig/zcommonconfig.htm).
3. Optionally, enable access to summarized data in the Tivoli Data Warehouse.
The use of summarized data in reports can simplify analysis of displayed
reports and improve the performance of generating the reports.
What to do next
After starting the Tivoli Data Warehouse, the warehouse agents, and data
collection, allow enough time for the Tivoli Data Warehouse to save historical data
for your requested report time period or the appropriate amount of data for a
summarized report. For example, if you want a monthly report, you need at least a
month's worth of stored data.
Warning: When your site changes either the IBM Tivoli Monitoring
data model or the operating system agent reports, your updated
data model and reports are no longer supported. In addition, these
updates can be lost when you apply maintenance to Tivoli
Monitoring or move to a subsequent release.
TIME_DIMENSION table
Includes years of time dimensional data and granularity to a
specified number of minutes. Each row of this table is a unique
minute key with various dimensions related to it, such as hour,
weekday, day of month, and quarter.
MONTH_LOOKUP table
Globalizes the month names for Time Dimension.
WEEKDAY_LOOKUP table
Globalizes the weekday names for Time Dimension.
Resource dimension tables
The resource dimension tables are MANAGEDSYSTEM,
MANAGEDSYSTEMLIST, and MANAGEDSYSTEMLISTMEMBERS.
The OS Agents Report Prerequisites Scanner report refers to these tables as
the IBM Tivoli Monitoring Shared Dimensions.
The following descriptions apply:
MANAGEDSYSTEMLIST table
Contains the name, product, and description (which is blank by
default and can be customized) for the managed system group on
the monitoring server.
MANAGEDSYSTEMLISTMEMBERS table
Contains the managed systems that are a member of a given
managed system group as defined in the MANAGEDSYSTEMLIST
table.
In order to build the resource dimension table, configure historical data collection
for one or more of the following attribute groups, depending on the operating
system you are getting reports for:
You can configure historical data collection in the Tivoli Enterprise Portal or in the
Command Line Interface. The following example shows how a local historical
collection for NT Computer Information was created and distributed from the CLI:
tacmd login -s MyComputer -u MyUser -p MyPassword
tacmd tepslogin -s localhost -u sysadmin
tacmd histconfiguregroups -t knt -o "NT Computer Information" -m -d YQMWDH
-p Y=2y,Q=2y,M=1y,W=1y,D=6m,H=14d,R=7d
tacmd histcreatecollection -t knt -o "NT Computer Information"
-a "ComputerInformation" -c 15m -i 15m -l TEMA -e
"Needed for resource dimension table for TCR."
tacmd histstartcollection -n TEMS_NAME -t "knt" -o "NT Computer Information"
Warning: When your site changes either the IBM Tivoli Monitoring data model or
the operating system agent reports, your updated data model and reports are no
longer supported. In addition, these updates might be lost when you apply
maintenance to Tivoli Monitoring or move to a subsequent release.
This task configures the Summarization and Pruning agent to create and maintain
the dimension tables. If the tables already exist, the Summarization and Pruning
agent ensures the tables contain all the needed columns and then adds any missing
columns. If a table already exists, but the index does not exist, the Summarization
and Pruning agent will not create the missing index. If you have already
customized your table data, your customized data is preserved.
Procedure
1. Edit the Summarization and Pruning agent environment variable file.
Results
The dimension tables have been created and are now maintained by the
Summarization and Pruning agent.
The Summarization and Pruning agent only adds new systems to the
MANAGEDSYSTEM table. This means if you have customized data, it is
preserved.
What to do next
Verify the contents of the tables and ensure they have data for the upcoming
month. The Summarization and Pruning agent maintains data one month ahead of
the current month.
You can view the Summarization and Pruning agent Configuration workspace for
an overview of your configurations. Any errors encountered are also reported in
this workspace. For detailed information about this workspace, see the IBM Tivoli
Warehouse Summarization and Pruning Agent Reference.
You can create reports and queries based on your managed system groups.
The following time dimension tables are created by this task: TIME_DIMENSION,
MONTH_LOOKUP, and WEEKDAY_LOOKUP. The following resource dimension
tables are also created by this task: MANAGEDSYSTEM, MANAGEDSYSTEMLIST,
MANAGEDSYSTEMLISTMEMBERS.
You can use this task to create both the time dimension tables and the resource
dimension tables, or you can create just the time dimension tables, or just the
resource dimension tables. Each set of tables can be created using a different
connection to the Tivoli Data Warehouse.
For additional information on running the schema publication tool see “Generating
SQL for data warehouse tables” in the IBM Tivoli Monitoring Installation and Setup
Guide.
Procedure
1. If you want to create the resource dimension tables used by the warehouse, you
must edit the response file.
install_dir/arch/bin/tdwschema.rsp
Configure the following environment variables:
KSY_PRODUCT_SELECT = updated
KSY_SQL_OUTPUT_FILE_PATH = optional file path for SQL output
Save and close the file.
2. If you want to create the time dimension tables used for reporting, you must
edit the Summarization and Pruning agent environment variable file and set
KSY_TRAM_ENABLE=Y.
Note: Scripts to create the time dimension tables will not be generated if
KSY_TRAM_ENABLE=Y and you also use the KSY_TABLE_FILTER variable in
the tdwschema.rsp file but do not include the time dimension tables and
resource dimension tables in the list of tables to filter by.
3. Ensure the Tivoli Enterprise Portal Server is started.
4. Run the schema publication tool script:
install_dir/arch/bin/tdwschema.sh
The SQL files for the products specified in the response file are generated and
written to the directory indicated by the KSY_SQL_OUTPUT_FILE_PATH
keyword, or to the current working directory, if no output directory is
specified.
5. Connect to the Tivoli Data Warehouse with the authorized user ID and execute
the following scripts in the order listed.
To create the resource dimension tables and any other attribute group tables,
execute the following SQL scripts in the order listed with the Tivoli Data
Warehouse user ID:
tdw_schema_table.sql
tdw_schema_index.sql
tdw_schema_view.sql
tdw_schema_function.sql
tdw_schema_insert.sql
To create the time dimension tables execute the following SQL scripts in the
order that is listed while connected to the Tivoli Data Warehouse database with
the user ID authorized to create tables with the IBM_TRAM schema:
Note:
If using Oracle or Microsoft SQL Server, run the scripts as the TRAM user
IBM_TRAM.
If using DB2, run the scripts as a user that has privileges to create tables with
the IBM_TRAM schema.
tdw_tram_table.sql
tdw_tram_index.sql
tdw_tram_function.sql
tdw_tram_insert.sql
Results
What to do next
If you received errors while executing the tdw_schema_insert.sql script, see the
IBM Tivoli Monitoring Troubleshooting Guide.
You will need the database scripts included in the extracted reports package under
the db_scripts directory.
If reports are distributed with an installer, the following manual procedures can be
handled automatically by the report installer. See your agent-specific user's guide
for information on automated TRAM creation.
When installing multiple report packages, the following steps need only be
completed once. When installing multiple report packages the same
TIME_DIMENSION tables are used. If you want to reset granularity or begin and
end times, you can repeat the procedure.
Procedure
v IBM DB2
1. Copy the database scripts (.db2 files) from the reports package to a location
where they can be run against the Tivoli Data Warehouse. The scripts are in
the db_scripts branch of the directory where the reports package was
extracted to.
2. Log in as db2admin. Your user ID must have administrator access to create
the IBM_TRAM schema.
3. Connect to the database that you want to create the dimension tables for.
This is your Tivoli Data Warehouse.
db2 connect to WAREHOUS
4. If you have an older version of the database scripts already installed clean
up the database:
db2 -tf clean.db2
5. Create the schema and tables:
db2 -tf create_schema_IBM_TRAM.db2
After the command completes successfully, several tables are shown under
IBM_TRAM: TIME_DIMENSION, MONTH_LOOKUP, WEEKDAY_LOOKUP,
ComputerSystem, BusinessService, SiteInfo, and so on.
6. Create the stored procedure for generating the time dimension:
db2 -td@ -vf gen_time_dim_granularity_min.db2
Tip: When populating the time dimension use the following guidelines:
– To view yearly data, you must provide the first day of the year, as seen in
the preceding example.
– Specify the end date far enough into the future so that new incoming data
can map to and be displayed correctly in the reports.
– Best practice is to use a value of 60-minute granularity.
v Microsoft SQL Server
1. Copy the database scripts (.sql files) from the reports package to a location
where they can be run against the Tivoli Data Warehouse. The scripts are in
the db_scripts branch of the directory where the reports package was
extracted.
2. Customize the provided scripts by changing the default database name in the
use statement (replace USE IBM_TRAM) if it is different from the default. If
the name of your Tivoli Data Warehouse is "warehouse," the statement is USE
warehouse:
a. If you have an older version of the database scripts already installed,
clean up the database using the clean.sql command..
b. Run the createSchema.sql command.
c. Run the createProcedure.sql command.
d. Run the populateTimeDimension.sql command. Also, modify the
boundary parameters for the time dimension and granularity, for
example,
@startDate = ’2010-01-01 00:00:00’,
@endDate = ’2012-12-31 00:00:00’,
@granularity = 60,
If Monday must be the first day of the week, add the fourth parameter
equal to 1; otherwise, release three parameters.
@weekday = 7
3. If you have an older version of the database scripts already installed, clean
up the database.
sqlcmd -i clean.sql [-U username -P password] [-S hostname]
4. Run the scripts at the MS SQL command line in this order:
sqlcmd -i createSchema.sql [-U username -P password] [-S host]
sqlcmd -i createProcedure.sql [-U username -P password] [-S host]
sqlcmd -i populateTimeDimension.sql [-U username -P password] [-S host]
v Oracle manual installation
where TCR_PASS is the password for the new user, USER_TBSPC is the default
user tablespaces name (must exist), and TEMPORARY_TBSPC is the default
temporary tablespaces name (must exist)
5. Create the IBM_TRAM tables (the script must be called by the IBM_TRAM
user created in the previous step):
@MY_PATH\create_schema.sql USER_TBSPC
Results
Troubleshooting
What to do next
You must first configure historical data collection. For more information, see
“Configuring historical data collection before you begin” on page 529.
If your site runs the Tivoli Data Warehouse, each time you install one or more
monitoring agents, you must update the warehouse's ManagedSystem table.
Important: The following scripts use hardcoded user schemas. If you use a
different schema, you must replace every instance of the hardcoded schema with
the user you specified.
Procedure
v IBM DB2
After the command completes successfully, a new table is shown under the
ITMUSER schema: ManagedSystem.
Note: If the table "ITMUSER.ManagedSystem" has already been created the
following message is displayed when executing the gen_resources.db2 script
and can be ignored: DB21034E The command was processed as an SQL
statement because it was not a valid Command Line Processor command.
During SQL processing it returned: SQL0601N The name of the object to
be created is identical to the existing name "ITMUSER.MANAGEDSYSTEM"
of type "TABLE". SQLSTATE=42710"
5. Create the stored procedure to populate the ManagedSystem table:
db2 -td@ -vf populate_resources.db2
6. To populate ManagedSystem table, call the stored procedure:
db2 "call ITMUSER.POPULATE_OSAGENTS()"
Note: If you specified a different user from the default, replace ITMUSER with
the user specified during your warehouse configuration.
v Microsoft SQL Server
1. Customize the provided scripts:
a. In create_table.sql, change the default database name in the use
statement (replace USE WAREHOUS) if it is different from the default.
b. In create_procedure.sql, change the default database name in the use
statement (replace USE WAREHOUS) if it is different from the default.
c. In populate_agents.sql, change the default database name in the use
statement (replace USE WAREHOUS) if it is different from the default.
2. Run the scripts at the MS SQL command line in this order:
sqlcmd -i create_table.sql [-U myusername -P mypassword] [-H myhost])
sqlcmd -i create_procedure.sql [-U myusername -P mypassword] [-H myhost])
sqlcmd -i populate_agents.sql [-U myusername -P mypassword] [-H my_host])
v Oracle manual installation
1. Start a SQL *Plus session if it is not already running.
2. Run this command (path with no spaces) and provide all the information
that the script requires:
@MY_PATH\setup_populate_agents.sql
v Oracle batch installation
1. Start a SQL *Plus session if it is not already running.
2. Create the ITMUSER.ManagedSystem table. The script must be called by the
Tivoli Data Warehouse user, which is ITMUSER by default. If you used a
different user name, modify the script for the correct name.
Results
What to do next
The report installer supports Tivoli Common Reporting versions 2.1 and later.
Set the PATH environment variable to include the bin directory of Java Runtime
Environment (JRE) 1.5 or later before using the report installer.
See your agent-specific user's guide for additional installation steps and possible
troubleshooting items for your agent.
Use the following procedure to import reports that are bundled by using the report
installer. This procedure can be used on the 6.2.3 or later versions of the OS agents
and the TivoliPerformance Analyzer reports.
For additional Tivoli Common Reporting information, see the “Installing Tivoli
Common Reporting” topic in the Jazz for Service Management Information Center
(http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/
install/tcr_t_install.html).
Procedure
v Using the GUI:
1. From the \osreports directory on the product CD, run the command
appropriate for your operating system:
setup_platform.exe
setup_platform.bin
The installer window opens.
2. Choose your language and click OK.
3. On the Welcome page click Next.
Results
Agent reports are now installed on your Tivoli Common Reporting server.
What to do next
You can now use the reports to display monitoring data gathered by the
monitoring agents. To learn more on how to run, administer, and edit reports in
Tivoli Common Reporting, see the “Working with reports” (http://
pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/
tcr_original/ttcr_working.html) topics.
If your reports are included with the report installer, see “Importing reports by
using the report installer” on page 541.
If your reports are not included with the report installer, see “Importing reports
through the Dashboard Application Services Hub” on page 545.
For detailed report installation information, see the “Installing Tivoli Common
Reporting” topic in the Jazz for Service Management Information Center
(http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/
install/tcr_t_install.html).
For DB2 on z/OS, you must establish a connection and grant the required
privileges. Run the following commands from the DB2_install_dir/version/bnd
directory:
db2 bind @ddcsmvs.lst SQLERROR CONTINUE BLOCKING ALL GRANT PUBLIC
db2 grant select on SYSIBM.SYSVIEWS to USER1
The OS Agents Report Prerequisites Scanner report returns data on the following
areas:
v Prerequisites for Tivoli Common Reporting Shared Dimensions
v Prerequisites for IBM Tivoli Monitoring Shared Dimensions
v Prerequisites by report
If your system is configured correctly, the time dimensions will report as satisfied.
If a report set returns as unsatisfied, you can dismiss this if it pertains to a report
set you do not wish to collect.
Limitation: When using reporting in your national language, some text strings
display in only English.
Procedure
1. From the Tivoli Common Reporting Navigator tree, select Public Folders → IBM
Tivoli Monitoring OS Agents Reports → Prerequisites Validation → OS Agents
Report Prerequisites Scanner report.
2. Select between the two available report types:
v Show all sections: This option shows all sections, including failing
(unsatisfied prerequisites) and success (satisfied prerequisites).
v Show failing sections only: This option shows only sections with failing
(unsatisfied prerequisites).
3. Review the returned report information. Take any actions needed to resolve any
unsatisfied prerequisites. Read the returned information in the Legend tables
and look in the Status and Details columns for summary information.
What to do next
When viewing your report, in the Details column, you can click on to view the
Table Details report for additional information.
Note: The Table Details report can only be accessed from clicking the icon in the
Details column. If you try to run the report directly from Public Folders → IBM
Tivoli Monitoring OS Agents Reports → Prerequisites Validation → Table Details,
you will receive an error.
Procedure
v IBM DB2
1. Make sure you have deployed a DB2 database client on the computer where
the Cognos-based Tivoli Common Reporting engine is installed. The client
should be of the same version as the database that the Tivoli Data Warehouse
is using.
If a DB2 server is installed where the Cognos-based
Tivoli Common Reporting engine is installed, the DB2 client files are already
Results
The monitoring agent report models are based on IBM Cognos. You must have
Tivoli Common Reporting V3.1 (with Cognos engine) installed and running on the
computer on which you install the reports. You must also have created and
populated the dimensions tables as instructed in “Creating and populating the
time dimensions tables” on page 536 and “Creating and populating the resource
dimension table” on page 539, and connected to the data warehouse as described
in “Connecting to the Tivoli Data Warehouse using the database client over ODBC”
on page 544.
Restriction: This import method can be used for Cognos reports only.
You must obtain a report package you want to work with. You can download
packages from the IBM Integrated Service Management Library
(http://www.ibm.com/software/brandcatalog/ismlibrary), or you can create one
by using the Content Administrator interface. All the packages you want to import
Procedure
1. Launch the Dashboard Application Services Hub administrative console and
log in.
2. Go to Common Reporting.
3. In the Work with reports window on the right, click Administration from the
Launch drop-down list.
4. Go to Configuration tab, and open the Content Administration section.
5. Create a new package import by clicking Import, which opens a New
Import wizard.
6. Follow the wizard to import a new package.
Results
OS Agent Reports are now installed on your Tivoli Common Reporting server.
What to do next
You can now use the reports to display monitoring data gathered by the OS
Monitoring Agents. To learn more on how to run, administer, and edit Cognos
reports in Tivoli Common Reporting, see the “Working with reports”
(http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/
tcr_original/ttcr_working.html) topics.
For additional reporting information, see the operating system agent user's
reference at Operating System Agent Documentation http://pic.dhe.ibm.com/
infocenter/tivihelp/v61r1/topic/com.ibm.itm.doc_6.3fp2/ic/landing_osagents.htm.
If you encounter any problems installing the report package, see the IBM Tivoli
Monitoring Troubleshooting Guide.
A report package is a .zip file containing all of the data required for defining one or
more reports, including the required designs and resources and the hierarchy of
report sets to contain the reports. The monitoring agent reports are included as .zip
files on the agent image in the REPORTS directory. For example, on a Windows
computer, if the image drive is labelled D:, reports are in directories such as:
D:\REPORTS\kqb. See the agent reporting chapter or Product reporting guide for
the location of the reports.
The -import command flag for the trcmd command imports BIRT and Cognos
report packages and report designs. The type of a package is recognized
automatically. This command can be used for single-box installation and on the
reporting engine. It is not supported for other scenarios.
For more information, see trcmd -import in the Tivoli Common Reporting
Information Center.
Procedure
1. Use this syntax to import a report package:
trcmd -import -bulk pkgFile [-reportSetBase rsBase] [-resourceBase resourceBase]
[-designBase designBase] [-help]
This example imports a BIRT package named avail_skills.zip with its resource
directory imported from C:\download:trcmd -import -bulk
C:\download\sth\report\avail_skills.zip -reportSetBase myReportSetBase
-resourceBase myResourceBase -designBase myDesignBase -user tipadmin
-password admin
2. Use this syntax to import a report design and also create a new report
associated with the design:
trcmd -import -design designPath [-resourceDir resourcePath] -reportSetBase
rsBase
Usage notes:
v During Cognos reports import, the -resourceBase, -designBase, and
-resourceDir parameters are ignored.
v You can import a single Cognos report from an .xml file using the -design
parameter.
Results
The Navigation tree shows an item for the reports and items for subsets of the
reports.
What to do next
Changing the data source in a report will change the data sources for all reports.
You do not need to repeat the change for all reports.
After you have installed Tivoli Common Reporting and imported your first set of
reports, you or a user with Administrator authority must copy JDBC drivers from
the local or remote database manager that you are using to run the Tivoli Data
Procedure
1. Locate the JDBC driver files:
IBM DB2 db2jcc.jar and db2jcc.license_cu.jar
C:\Program Files\IBM\SQLLIB\java
db2_installdir/java
For example, the default DB2 on the workstation Version 9 installation
directory is /usr/opt/db2_09_01 on AIX and /opt/IBM/db2/V9.1 on
Linux and Solaris.
The JDBC drivers are typically found in this default DB2 installation
path or in the java directory of whatever alternate path you specified
for DB2 installation.
You can also download the IBM DB2 Driver for JDBC and SQLJ from
the IBM website.
Microsoft SQL Server sqljdbc.jar
Download the Microsoft SQL Server JDBC Driver from the Microsoft
website. The SQL Server 2005 JAR file name and location after
installation is mssql2005installdir/sqljdbc_1.1/enu/sqljdbc.jar.
Oracle oraclethin.jar
Obtain the JDBC Type 4 driver from the Oracle website. The Oracle
JDBC driver JAR file name and location after installation is
oracleinstalldir/jdbc/lib/oraclethin.jar.
2. Copy the JDBC driver to your Tivoli Common Reporting installation directory:
v tcr_install_dirTCR_component_dir\lib\birt-runtime-2_2_2\ReportEngine\
plugins\org.eclipse.birt.report.data.oda.jdbc_2.2.2.r22x_v20071206\
drivers
v For a DB2 data source, copy the DB2 JDBC drivers and the license JAR file to
the same location. You can copy db2jcc.jar and th db2jcc_licence_cu.jar
file on the DB2 server system from the db2_installdir/java location (for
example, C:\Program Files\IBM\SQLLIB\java).
3. Run the trcmd -modify command to configure the data source. See the
trcmd-modify command topic in the Tivoli Common Reporting Information
Center for complete instructions.
What to do next
For additional information, refer to the JDBC driver section of the IBM Tivoli
Common Reporting: Development and Style Guide on IBM developerWorks Tivoli
Common Reporting community.
For more information about Tivoli Data Warehouse connectivity issues, refer to
“Part 5. Setting up data warehousing” in IBM Tivoli Monitoring Installation and
Setup Guide (http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/topic/
com.ibm.itm.doc_6.3fp2/install/itm_install.htm).
See OMEGAMON XE and Tivoli Management Services on z/OS: Reports for Tivoli
Common Reporting for information about how to increase the default heap size.
7. In the Actions column, click the run icon for the report you want to launch,
and then select the type of report format: HTML (the default), PDF, Microsoft
Word, Microsoft Excel, or Adobe Postscript.
When you select a report from Tivoli Common Reporting, you are presented
with a Report Parameters window that prompts you for information that will
be used to generate the report. The title of the parameters window indicates the
type of report that will be generated. For a description of the types of reports,
see the agent user's guide or product reporting guide for the agent or product
with which you are working.
A Report Parameters window contains some fields common to all reports (for
example, timeframe). Other fields are specific to the agent running the reports.
For most reports, you select a timeframe, resources, the summarization level of
the data, and the attributes to graph, or click to accept all displayed
defaults.
8. Click Run to generate a report matching your parameter definitions.
An hourglass is displayed while Tivoli Common Reporting gathers report data and
creates formatted output. After processing finishes, the report is displayed in the
Dashboard Application Services Hub.
What to do next
If no report is generated or you see a message indicating that the requested data is
unavailable, see the IBM Tivoli Common Reporting User's Guide for information
about defining a data source.
If you are viewing an HTML or PDF report, you can also click any embedded links
to open drill-through reports. Clicking a drill-through embedded link causes the
report to link back to itself with the newly passed parameters or to a secondary
(drill-down or summarized) report. Examples of drill-through links include clicking
on a bar or line chart or on a table heading.
You can also use the migrate-import and migrate-export scripts to switch from a
32-bit Tivoli Enterprise Portal Server to a 64-bit Tivoli Enterprise Portal Server on
the same operating system.
Tivoli Enterprise Portal customizations are stored at the portal server in the TEPS
database. This includes user IDs, Navigator views, custom queries, custom
workspaces, and local terminal scripts. It does not store situations, policies, and
managed system groups.
During an installation upgrade to a new version of the portal server, the TEPS
database is updated with any new or changed predefined Navigator views, queries
and workspaces. Custom Navigator views, queries, and workspaces that you
created are not affected.
The TEPS database replication is required for moving from a test environment to a
production environment. You can also use the procedure for backing up the
database as a precautionary measure before applying a fix pack or upgrading to a
new version.
Before migrating the Tivoli Enterprise Portal Server, make sure your environment
fulfills these requirements:
v The portal servers on the source and target computers must be configured to
connect to the same hub monitoring server.
v The portal servers on the source and target computers must be at Version 6.2.1
or later and, ideally, both have been installed from the same Tivoli Monitoring
Base DVD.
v The portal servers on the source and target computers must have been installed
the same way:
The command line interface has tacmds for exporting and importing specific IBM
Tivoli Monitoring objects. See the IBM Tivoli Monitoring Command Reference for a
description of each of these commands and their syntax.
tacmd exportworkspaces
tacmd importworkspaces
Selectively copy workspaces from one portal server to another.
tacmd exportQueries
tacmd importQueries
Export custom queries to an XML file; then import them into a portal
server.
tacmd bulkExportSit
tacmd bulkImportSit
Export all Tivoli Monitoring enterprise situations from one hub monitoring
server and importing into another.
tacmd bulkExportPcy
tacmd bulkImportPcy
Export all Tivoli Monitoring policies from one hub monitoring server and
importing into another.
tacmd exportNavigator
tacmd importNavigator
Export custom Navigator views and their assigned workspaces, queries,
and situation associations to an XML file; then import them into a portal
server.
tacmd exportSitAssociations
tacmd importSitAssociations
Export all the situation associations for a Navigator view or a particular
Navigator item to an XML file; then import them into a portal server.
tacmd exportSysAssignments
tacmd importSysAssignments
Export all managed system assignments for a Navigator view or a
particular Navigator item to an XML file; then import them into a portal
server.
The portal server can be running or stopped when you initiate the migrate-export
script. If the server is stopped, the script starts it temporarily in a limited mode to
On the computer where the source Tivoli Enterprise Portal Server is installed, take
these steps to create a copy of the TEPS database
Procedure
v
1. Open a command prompt window: Start→ Run, enter CMD.
2. Change to the install_dir\CNPS directory.
3. Enter: migrate-export
The migrate-export script generates a file named saveexport.sql in the
install_dir\CNPS\sqllib subdirectory. It contains all the Tivoli Enterprise Portal
Server data.
v
1. On the source system, open a terminal window.
2. Change to the bin subdirectory of your IBM Tivoli Monitoring installation,
such as: cd /opt/IBM/ITM/bin
3. Enter: ./itmcmd execute cq "runscript.sh migrate-export.sh" Be sure to
use the " double-quote symbol and not ' single-quote.
The migrate-export script generates a file named saveexport.sql in the
install_dir/$platform/cq/sqllib subdirectory. It contains all the Tivoli
Enterprise Portal Server data.
Some of the tables included in the import script are applicable only to the
CandleNet Portal Server, the predecessor to Tivoli Enterprise Portal Server. Unless
you are not importing a Tivoli Enterprise Portal Server database, the
migrate-import log file will contain SQL errors about an undefined name, such as
SQLExecDirect rc=-1: SQL_ERROR SQLSTATE: 42S02, ERR: -204, MSG: [IBM][CLI
Driver][DB2/LINUX] SQL0204N "ITMUSER.TAGGROBJ" is an undefined name.
SQLSTATE=42704 RC = -1 (also ITMUSER.TMANOBJS, ITMUSER.TMANTMPL,
ITMUSER.TTMPLSIT, ITMUSER.TTMPLSTA, ITMUSER.TSTUSERA). Ignore these errors.
Chapter 18. Replicating the Tivoli Enterprise Portal Server database 553
About this task
On the Windows computer where the target portal server is installed, take these
steps to import the TEPS database that was copied from another Window
computer using migrate-export.
Procedure
1. Stop the portal server on the target system.
2. On the source system, open a command prompt: Click Start → Run, and enter
CMD.
3. Copy file saveexport.sql that was generated by the migrate-export.bat script
from the source system to install_dir\CNPS\sqllib on the destination system,
where <mapped drive on destination system> is the disk drive on the source
system where this file resides. Example:
copy <mapped drive on destination system>:\IBM\ITM\CNPS\sqllib
\saveexport.sql c:\ibm\itm\cnps\sqllib
If a drive is not already defined, you must map a drive to the source system
from the destination system with the net use command.
4. On the target system, change to the install_dir\CNPS directory and enter:
migrate-import. Running the migrate-import process stops the portal server if
it is currently running.
5. If you are using the migrate-import function to move the TEPS database from
one release to another, perform this task after migrating the database to add
application support:
a. Open <install_dir>\CNPS\kfwalone in a text editor.
b. Set KFW_MIGRATE_FORCE=Y, then save and close the file.
c. Invoke this script to apply the current portal server application support to
the newly migrated TEPS database: <install_dir>\CNPS\
buildpresentation.bat
6. Restart the portal server.
On the Linux or UNIX computer where the target portal server is installed, take
these steps to import the TEPS database that was copied from a Window computer
using migrate-export.
Procedure
1. Stop the portal server on the target system.
2. On the source system, open a command prompt: Click Start → Run, and enter
CMD.
On the Windows computer where the target portal server is installed, take these
steps to import the TEPS database that was copied from a Linux or UNIX
computer using migrate-export.
Procedure
1. Stop the portal server on the target system.
2. Copy file saveexport.sql that was generated by the migrate-export script from
the source Linux or UNIX system ( /opt/IBM/ITM/$platform/cq/sqllib) to
install_dir\CNPS\sqllib on the target system.
3. On the target system, change to the install_dir\CNPS directory and enter:
migrate-import. Running the migrate-import process stops the portal server if
it is currently running.
Chapter 18. Replicating the Tivoli Enterprise Portal Server database 555
4. If you are using the migrate-import function to move the TEPS database from
one release to another, perform this task after migrating the database to add
application support:
a. Open <install_dir>\CNPS\kfwalone in a text editor.
b. Set KFW_MIGRATE_FORCE=Y, then save and close the file.
c. Invoke this script to apply the current portal server application support to
the newly migrated TEPS database: <install_dir>\CNPS\
buildpresentation.bat
5. Restart the portal server.
6. Restart the Tivoli Enterprise Portal Server.
On the Linux or UNIX computer where the target portal server is installed, take
these steps to import the TEPS database that was copied from another Linux or
UNIX computer using migrate-export.
Procedure
1. Stop the portal server on the target system.
2. Copy file saveexport.sql that was generated by the migrate-export script from
the source Linux or UNIX system install_dir/$platform/cq/sqllib directory
to the same directory on the target system, where install_dir is the installation
directory on the destination system, such as /opt/IBM/ITM/, and $platform is
the operating system, such as li6243 for Intel Linux or ls3263 for zSeries Linux.
3. Open a terminal window on the target system.
4. Change to the bin subdirectory of the Tivoli Monitoring installation:
Install_dir/bin. For example,
cd /opt/IBM/ITM/bin
5. In the terminal window, enter the following command.
./itmcmd execute cq "runscript.sh migrate-import.sh"
Be sure to use the " double-quote symbol and not ' single-quote. The script
processes a file named saveexport.sql in the IBM/ITM/$platform/cq/sqllib
subdirectory. Depending on the contents of the saveexport.sql file, this process
can completely replace the existing portal server data.
6. If you are using the migrate-import function to move the TEPS database from
one release to another, perform this task after migrating the database to add
application support:
a. Open Install_dir/cq/bin/lnxnocmsenv in a text editor.
b. Set KFW_MIGRATE_FORCE=Y, then save and close the file.
Chapter 18. Replicating the Tivoli Enterprise Portal Server database 557
558 IBM Tivoli Monitoring: Administrator's Guide
Appendix A. IBM Tivoli Monitoring Web Services for the SOAP
server
This appendix describes the IBM Tivoli Monitoring Web Services feature of the
SOAP server. The IBM Tivoli Monitoring Web Services solution provides you with
an industry-standard open interface into IBM Tivoli Monitoring solutions. This
open interface provides easy access to Tivoli performance and availability data,
allowing you to use this information for advanced automation and integration
capabilities.
Predefined SOAP methods let you perform many functions within the monitored
environment. You can begin to use the SOAP methods immediately. You can also
use these SOAP methods as templates in creating your own advanced methods.
SOAP works with any programming or scripting language, any object model and
any Internet wire protocol. Tivoli SOAP methods can be invoked by PERL,
Javascript, VBSCRIPT, JSCRIPT, C++, Java, and through a browser.
Note: Web Services does not support situation creation. Use the Tivoli Enterprise
Portal Situation editor or the CLI tacmd createSit function for situation creation.
The SOAP server can query only agent and managed system attributes.
Important: Prior to using IBM's solution, you must have a basic understanding of
SOAP, of Extensible Markup Language (XML) and XML Namespaces, and of the
Web Services Description Language (WSDL).
The instructions in this chapter assume that you have a basic understanding of
SOAP, XML and XML Namespaces, and the Web Services Description Language
(WSDL). These steps are required to configure SOAP:
v Define the hubs with which your SOAP Server communicates.
v Create users and grant them access.
v Verify that you have successfully configured SOAP.
© Copyright IBM Corp. 2005, 2014 559
Note: You cannot make SOAP requests to earlier version SOAP servers.
Defining hubs
The procedure below describes how you can use the Manage Tivoli Enterprise
Monitoring Services to activate the SOAP server and define the hubs with which
the SOAP server communicates.
Procedure
1. On the computer where the hub monitoring server is installed, start Manage
Tivoli Enterprise Monitoring Services:
a. Click Start → Programs → IBM Tivoli Monitoring → Manage
Tivoli Enterprise Monitoring Services.
b. or Change directory to install_dir/bin and enter:
./itmcmd manage
To use the command-line interface, see “Defining hubs on Linux and
UNIX using the CLI” on page 561.
2. Right-click Tivoli Enterprise Monitoring Server and click Reconfigure.
3. Select or clear the Security: Validate User field.
4. Open Manage Tivoli Enterprise Monitoring Services.
5. Right-click Tivoli Enterprise Monitoring Server.
6. Click Advanced → Configure SOAP Server Hubs.
7. Click Add Hub. The Hub Specification window is displayed.
8. Select the communications protocol to be used with the from the Protocol
menu.
9. Specify an alias name in the Alias field (for example: HUB2). Alias names can
be a minimum of 3 characters and a maximum of 8 characters.
10. Perform one of the following steps:
a. If you are using TCP/IP or TCP/IP Pipe communications, complete the
following fields:
Table 70. TCP/IP Fields in Hub Specification Dialog
Field Description
Hostname or IP Address The host name or TCP/IP address of the
host computer.
Port The TCP/IP listening port for the host
computer.
Procedure
1. On the host of the hub monitoring server on which you want to configure Web
Services, change to the install_dir/bin directory and enter the following
command:
./itmcmd config -S -t tems_name
2. Accept the default values, which should reflect the choices made during the
last configuration, until you see the following prompt:
*************************
*************************
Hubs
## CMS_Name
1 ip.pipe:TEMS_NAME[port_#]
1)Add, 2)Remove ##, 3)Modify Hub ##, 4)UserAccess ##, 4)Cancel, 5)Save/exit:
3. To add a hub with which the local hub can communicate:
a. Type 1 and press Enter.
b. Respond to the following prompts as shown in :
Network Protocol [ip, sna, ip.pipe, or ip.spipe] (Default is: ip):
CMS Name (Default is: local_host):
Port Number (Default is: 1918):
Alias (Default is: SOAP):
Appendix A. IBM Tivoli Monitoring Web Services for the SOAP server 561
Table 72. SOAP hub configuration values (continued)
Configuration Value
Alias An alias for the hub. Alias names can be a minimum of 3 characters
and a maximum of 8 characters. The alias for the local hub must
always be SOAP, but you must create a new alias for additional hubs
(for example, HUB2).
After you enter the alias, the list of hubs is displayed with the new hub added.
For example,
Hubs
## CMS_Name
1 ip.pipe:chihuahua[1918]
2 ip:maple[1918]
1)Add, 2)Remove ##, 3)Modify Hub ##, 4)UserAccess ##, 5)Cancel, 6)Save/exit:
You can continue to add hubs, or you can proceed to define user access for the
hubs you have already defined.
Adding users
Define users on each hub and specify access rights for each user (query or update)
by following the procedure below.
Complete the following procedure to define users and specify access rights:
Procedure
1. Select the server (click anywhere within the server tree displayed), if required.
2. Under Add User Data, type the user name. User IDs must be identical to those
specified for monitoring server logon validation. Access is restricted to only
that monitoring server to which a user has access.
Note: If you do not supply a user ID, all users are given permission to update
data.
3. Click the type of user access: Query or Update.
4. Click Add User. The server tree is updated, showing the user and type of
access.
5. To delete a user: Select the user name from the tree and click Delete Item.
6. To delete a hub: Click anywhere within the hub's tree and click Clear Tree.
The query permission prevents the user from performing the create, update,
and delete operations, and also the tacmd commands for remote deploy and
execution of commands, such as executeaction and executecommand.
The update permission grants permission to run all SOAP operation and
applies to all tacmd commands that send requests to the hub monitoring server,
except for the tacmd getFile and tacmd putFile commands. Permission to run
the tacmd getFile and tacmd putFile commands is controlled by the
KT1_TEMS_SECURE environment variable of the hub monitoring server. For more
details on how to enable permission to run these two commands, see the IBM
Tivoli Monitoring Command Reference.
Use the following steps to define SOAP hubs on UNIX or Linux using Manage
Tivoli Enterprise Monitoring Services:
Procedure
1. Change to the install_dir/bin directory and start Manage Tivoli Enterprise
Monitoring Services by entering the following command:
./itmcmd manage
Appendix A. IBM Tivoli Monitoring Web Services for the SOAP server 563
Tuning SOAP transaction performance on AIX systems
SOAP transaction performance can be modified on AIX by deciding whether or not
to allow delayed acknowledgments. Tune the performance by following the
procedure below.
The default behavior on AIX systems for Transmission Control Protocol (TCP)
connections is to allow delayed acknowledgments (Ack packets) by up to 200 ms,
and is controlled by the tcp_nodelayack network option. This delay allows the
packet to be combined with a response and it minimizes system overhead. If you
set tcp_nodelayack to 1, the acknowledgment is immediately returned to the
sender. With this setting, slightly more system overhead is generated but results in
much higher network transfer performance when the sender is waiting for
acknowledgment from the receiver. To find out more about the tcp_nodelayack
option, refer to the IBM System p® and AIX Information Center.
Procedure
Access a user account that has root privileges and issue the following command:
no -p -o tcp_nodelayack=1
Results
This is a dynamic change that takes effect immediately. The -p flag makes the
change persistent, so that it is still in effect the next time you start the operating
system.
For information on how to configure the hub monitoring server to validate SOAP
users, see the IBM Tivoli Monitoring Installation and Setup Guide. If you also want to
authenticate SOAP users who are sending CT_EMail or CT_Export SOAP requests,
you must enable the SOAP_IS_SECURE environment variable on the hub monitoring
server.
Procedure
1. On the computer where the hub monitoring server is installed, open the
KBBENV or ms.ini file:
564 IBM Tivoli Monitoring: Administrator's Guide
Use Manage Tivoli Enterprise Monitoring Services (Start → Programs →
IBM Tivoli Monitoring → Manage Tivoli Enterprise Monitoring Services)
to edit environment files. Right-click the component you want to
modify and click Advanced → Edit ENV File. You must recycle the
component to implement the changes.
In this step you verify that SOAP has been correctly configured by starting the
SOAP client and making a request using the command-line utility kshsoap.
Procedure
1. Verify that the monitoring server that you used to enable SOAP is running. If
not, start it.
2. Open a command window.
3. Change to the install_dir\cms directory or
The install_dir/TBD.
4. In the current directory, create an ASCII text file named SOAPREQ.txt that
contains the following SOAP request:
<CT_Get><object>ManagedSystem</object></CT_Get>
SOAPREQ.txt is the name of the file that contains the SOAP request and
URLS.txt is the name of the file that contains the URLs.
Results
The kshsoap utility processes the SOAPREQ.txt file and displays the output of the
SOAP request in the command window. The SOAP request is sent to each URL
listed in URLS.txt, and the SOAP response from each URL displays in the DOS
window.
Appendix A. IBM Tivoli Monitoring Web Services for the SOAP server 565
Using IBM Tivoli Monitoring web services
Numerous SOAP methods are included with IBM Tivoli Monitoring web services.
These methods allow you to dynamically query and control IBM Tivoli Monitoring
environments.
You can also use this product to test a request to ensure it works correctly. You can
then create a policy that submits multiple requests for processing. In addition, you
can generate daily operation summaries.
You can store retrieved data in the Tivoli Data Warehouse, as described in the
historical data collection guide.
Note: IBM Tivoli Monitoring web Services provides XML data rows. Use IBM's
SOAP methods in combination with your own scripts to display the data in charts
and tables.
User IDs
At installation and configuration time, you are asked to supply user IDs for those
who need access to monitoring server data. If no user IDs are supplied, all users
are given permission to update data.
User IDs must be identical to those specified for monitoring server logon
validation. Access is restricted to only that monitoring server to which a user has
access.
You can also make changes at a later time to add or to remove users' access to
monitoring server data. See the IBM Tivoli Monitoring: Installation and Setup Guide
for details.
When you use the SOAP client in conjunction with Internet Explorer to issue
SOAP requests, you can modify, if needed, the tags or the text. In contrast, the
command-line utility simply displays the output of the request at the command
line.
After installing the Tivoli Monitoring Web Services SOAP client, perform these
actions:
Procedure
1. Start Internet Explorer version 5 or later, or Mozilla Firefox . Be sure to enable
the Access data sources across domains option in Internet Explorer's security
settings.
2. In the Address field, type the URL for the SOAP client, where localhost can be
used literally when accessing the SOAP server running on the same system or
changed to the proper host name or network address of a SOAP server running
on a different system:
http://localhost:1920///cms/soap/kshsoap.htm
Note: You can also route requests to a remote hub by replacing soap in the
Address field with the alias name of the hub you want to access
(HUB_localhost in the example below). The alias must have been previously
defined to the SOAP server (for information about defining hub aliases, see the
installation documentation). For example: http://localhost:1920///cms/
HUB_localhost/kshsoap.htm
The SOAP client HTML page is displayed.
3. Select a SOAP method from the list in the first field. After you select a method,
the other fields are updated automatically.
4. Modify, if needed, the tags or the text in the “Edit Payload (XML)” area.
5. Click Make SOAP Request. The output of the request displays in the Your
SOAP Response Payload area.
What to do next
When issuing a CT_Get request against a particular agent type, the monitoring
server where the SOAP server is running must be configured and have the
application support for that agent type. For example, when issuing a CT_Get
request for a z/OS agent connected to an z/OS monitoring server, the monitoring
server running the SOAP server must be configured and have the application
support for that z/OS agent.
Complete these steps to create a SOAP request file and a SOAP URL receiver file
and send the request.
Appendix A. IBM Tivoli Monitoring Web Services for the SOAP server 567
Procedure
v
1. On the Tivoli Enterprise Monitoring Server system where the SOAP server is
installed, change to the install_dir\cms directory.
2. Create a text file named SOAPREQ.txtand type the following SOAP request:
<CT_Get><object>ManagedSystem</object></CT_Get>
Results
The kshsoap utility processes the SOAPREQ file and displays the URL destination
and request. It sends the SOAP request to each URL listed in the URLS file, then
displays the URL and the response message received.
The SOAP requests are stored in a text file. For details, see the “Specifying an
action” and “Action Settings” topics in the Tivoli Enterprise Portal User's Guide.
where:
CT_Execute is the name of the SOAP method that allows you to run a SOAP
request that is stored in a file.
SOAPREQ is the name of the file you created that contains the CT_EMail
SOAP request
For example, SOAPREQ might contain:
SOAP methods
Use the predefined SOAP methods to compose requests for invocation by PERL,
Javascript, VBSCRIPT, JSCRIPT, C++, Java, and through a browser. With each
method is a list of supported tags and usage examples. Each SOAP method
provided by IBM and its supported tags is described here.
CT_Acknowledge
Example:
Appendix A. IBM Tivoli Monitoring Web Services for the SOAP server 569
<CT_Acknowledge>
<hub>z/OSPROD</hub>
<name>situation_from_CT</name>
<source>CT_supported_system</source>
<data>Jack is taking care of this failure</data>
<item>subsystem</item>
<userid>sysadmin</userid>
<password>xxxxxxxx</password>
<type>pure</type>
<expire>60</expire>
</CT_Acknowledge>
CT_Activate
Example:
<CT_Activate>
<hub>z/OSPROD</hub>
<name>name_of_situation_or_policy</name>
<type> situation</type>
<userid>sysadmin</userid>
<password>xxxxxxxx</password>
</CT_Activate>
CT_Alert
Example:
<CT_Alert>
<hub>z/OSPROD</hub>
<name>situation_from_XXX</name>
<source>XXX_supported_system</source>
<data><NT_Logical_Disk.Disk_Name>
C:</NT_Logical_Disk.Disk_Name></data>
<item>subsystem</item>
<userid>sysadmin</userid>
<password>xxxxxxxx</password>
</CT_Alert>
Note: When you specify object.attribute in the data tag, leave out any
non-alphanumber characters other than the underscore (_). For example,
NT_System.%_Total_Processor_Time is entered as
NT_System.Total_Processor_Time.
CT_Deactivate
Appendix A. IBM Tivoli Monitoring Web Services for the SOAP server 571
Example:
<CT_Deactivate>
<hub>z/OSPROD</hub>
<name>name_of_situation_or_policy</name>
<type>situation</type>
<userid>sysadmin</userid>
<password>xxxxxxxx</password>
</CT_Deactivate>
CT_EMail
Send the output from another CT SOAP method, such as CT_Get, using e-mail
through an SMTP server to a defined e-mail address (not available on z/OS).
<server>
The smtp server name/network address is required.
<sender>
Sender's e-mail address is required.
<receiver>
Receiver's e-mail address is required.
<subject>
Optional. E-mail subject.
<message>
Optional. E-mail message.
<attachmenttitle>
Optional. Title of an attachment.
<request>
When specifying a second-level request, such as CT_Get, each sub-request
must be included within a <request> </request> tag.
Example:
<CT_EMail>
<server>smtp.server</server>
<sender>myemail@something.com </sender>
<receiver>youremail@whatever.com </receiver>
<subject>Here’s your data.</subject>
<message>Table data supplied as attachment below. It is
presented in csv format to be used by MS/Excel.</message>
<attachmenttitle>tabledata.csv</attachmenttitle>
<request id="XMLID">
<CT_Get>
<object>NT_Process </object>
<target>TlPrimary:DCSQLSERVER:NT</target>
With the additional security, the user ID and password are requested by CT_EMail
in order to be authorized. If a CT_Get is specified the same credentials are used to
issue the CT_Get.
CT_Execute
Example:
<CT_Execute>
<filename>execute1.xml</filename>
</CT_Execute>
CT_Export
Send the output from another CT SOAP method, such as CT_Get, to a defined file
(not available on z/OS).
<filename>
The name of the file to contain the exported data. This is required.
Note: When inserting the file name tag into a quoted string literal of
certain programming languages, such as C++, back slashes must be
doubled.
To the <filename> tag, you can add an optional date/time stamp variable.
The variable is enclosed in dollar signs ($) and can contain a combination
of yy/mm/dd/hh/mm/ss (for year/month/day/hours/minutes/seconds).
Appendix A. IBM Tivoli Monitoring Web Services for the SOAP server 573
The date/time stamp attributes can be specified in any order, except mm
must be preceded by yy or hh to identify it as either month (after year) or
minutes (after hours). For example:
<filename>g:\exchange\excel\ntprocess$yymmdd$.htm</filename>
<warehouse/>
Specifies that data is to be exported to the Tivoli Enterprise Portal data
warehouse through ODBC. <filename> and <warehouse/> are mutually
exclusive, but one must be supplied.
<request>
When specifying a second-level request, such as CT_Get, each sub-request
must be included within a <request> </request> tag.
Example:
<CT_Export>
<filename>g:\exchange\excel\ntprocess$yymmddhhmmss$.htm</filename>
<request>
<attach>prefix.xsl</attach>
</request>
<request id="XMLID">
<CT_Get>
<object>NT_Process</object>
<target>Primary:DCSQLSE RVER:NT</target>
<userid>sysadmin</userid>
<password>xxxxxxxx</password>
</CT_Get>
</request>
<request>
<attach>suffix.xsl</attach>
</request>
</CT_Export>
With the additional security, the user ID and password are requested by CT_Export
in order to be authorized. If a CT_Get is specified the same credentials are used to
issue the CT_Get.
CT_Get
Receive a group of XML objects or individual XML objects from any IBM Tivoli
Monitoring platform agent. You can use this to obtain real time data.
Important: When issuing a CT_Get request against a particular agent type, the
monitoring server where the SOAP server is running must be configured and
seeded for that agent type.
<object>
The name of the object to be retrieved. Required (by default, retrieves all
the public elements of an object).
<userid>
The user ID to access the hub monitoring server. "nnn.nnn.nnn.nnn" is
inserted if not provided.
<password>
The password to access the hub monitoring server. Required for
monitoring server/hub logon validation.
<target>
Name of the agent.
Example:
<CT_Get>
<hub>z/OSPROD</hub>
<object>NT_System</object>
<target>Primary:DCSQLSERVER:NT</target>
<userid>sysadmin</userid>
Appendix A. IBM Tivoli Monitoring Web Services for the SOAP server 575
<password></password>
<history>Y</history>
<attribute>Server_Name</attribute>
<attribute>Processor_Queue_Length</attribute>
<afilter>Write_Time;GT;1020804</afilter>
<afilter>Write_Time;LT;1020805</afilter>
</CT_Get>
Note: When you specify an attribute in the attribute tags, leave out any
non-alphanumeric characters other than the underscore (_). For example,
%_Total_User_Time is entered as Total_User_Time.
CT_Redirect
Reroute a SOAP request to another registered SOAP method outside of the domain
of the IBM Tivoli Monitoring platform.
<request endpoint=" ">
The <request endpoint= " "> value must specify the target of the redirected
SOAP request. The entire XML supplied as the value of the request
element is sent to that endpoint. When CT_Redirect is specified within a
second- level request, such as, CT_Export, the <endpoint=" "> attribute is
specified only within the CT_Redirect method. This is required.
Example:
<CT_Redirect>
<request endpoint= \"http://services.xmethods.net:80/soap/servlet/rpcrouter\">
<SOAP-ENV:Envelope xmlns:SOAP-ENV=\"http://schemas.xmlsoap.org/soap/envelope/\">
<SOAP-ENV:Body>
<ns1:getTemp xmlns:ns1=\"urn:xmethods-Temperature\"SOAP-ENV:
encodingStyle=\"http://schemas.xmlsoap.org/soap/encoding/\">
<zipcode>93117</zipcode>
</ns1:getTemp>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
</request>
</CT_Redirect>
CT_Reset
Send an event reset (close event) to the IBM Tivoli Monitoring platform.
<name>
The name of the situation. This is required.
<source>
The source of the event (agent name or monitoring server name). The reset
applies to all the active sources of the named alert if the source is not
supplied.
<item>
Display item.
<userid>
Optional. The user ID to access the hub monitoring server.
"nnn.nnn.nnn.nnn" is inserted if not provided.
<password>
Optional. The password to access the hub monitoring server. Required for
monitoring server/hub logon validation.
Example:
<CT_Reset>
<hub>z/OSPROD</hub>
<name>situation_from_CT</name>
<source>CT_supported_system</source>
<item>subsystem</item>
<userid>sysadmin</userid>
<password>xxxxxxxx</password>
</CT_Reset>
Note: Sampled events can be closed only if the situation has been stopped or
deleted. Use the <type> tag if CT_Reset will be closing a pure event.
CT_Resurface
Example:
<CT_Resurface>
<hub>z/OSPROD</hub>
<name>situation_from_CT</name>
<source>CT_supported_system</source>
<item>subsystem</item>
<userid>sysadmin</userid>
<password>xxxxxxxx</password>
</CT_Resurface>
Appendix A. IBM Tivoli Monitoring Web Services for the SOAP server 577
CT_WTO
Example:
<CT_WTO>
<hub>z/OSPROD</hub>
<data>This is Universal Message</data>
<category>Critical Messages</category>
<severity>High Severity</severity>
<userid>sysadmin</userid>
<password>xxxxxxxx</password>
</CT_WTO>
The <CT_Get> and <CT_Redirect> tags are used as described in “SOAP methods”
on page 569. The <attach> tag is used to load a file. The file must be located in the
<install_dir>\cms\html directory on Windows or <install_dir>/tables/
HUB_Name/HTML on Linux and UNIX. You cannot use relative paths in the <attach>
tag. The <insert> tag allows you to load the imbedded text into the retrieved
(output) data stream at a point corresponding to its position in the XML request.
The following example shows how a second-level request might be used. This
XML creates the file tabledata.htm, which is written with the data from
prefix.xls. Next, embedded data is entered by using the <insert> tag and a
request using the <CT_Get> command is made. Note that this request has an ID
value of "NTDATA", which will result in the data tag <XML id=”NTDATA”>
Appendix A. IBM Tivoli Monitoring Web Services for the SOAP server 579
<PARMS> </PARMS>
<TABLE name="KNT.WTSYSTEM">
<OBJECT>NT_System</OBJECT>
<DATA>
<ROW>
<Server_Name>Primary:ESADA:NT</Server_Name>
<Timestamp >1011127123323391</Timestamp>
<User_Name>SYSTEM</User_Name>
<Operating_System_Type>Windows_NT</Operating_System_Type>
<Operating_System_Version>4.0</Operating_System_Version>
<Network_Address>10.21.2.154</Network_Address>
<Number_of_Processors dt:dt="number">1</Number_of_Processors>
<Processor_Type dt:dt="number">586</Processor_Type>
<Page_Size dt:dt="number">4096</Page_Size>
<_Total_Privileged_Time dt:dt="number">1</_Total_Privileged_Time>
<_Total_Processor_Time dt:dt="number">7</_Total_Processor_Time>
<_Total_User_Time dt:dt="number">6</_Total_User_Time>
<Context_Switches_Sec dt:dt="number">1745</Context_Switches_Sec>
<File_Control_Bytes_Sec dt:dt="number">4500</File_Control_Bytes_Sec>
<File_Control_Operations_Sec dt:dt="number">98
</File_Control_Operations_Sec>
<File_Data_Operations_Sec dt:dt="number">28
</File_Data_Operations_Sec>
<File_Read_Bytes_Sec dt:dt="number">800</File_Read_Bytes_Sec>
<File_Read_Operations_Sec dt:dt="number">27
</File_Read_Operations_Sec>
<File_Write_Bytes_Sec dt:dt="number">9772</File_Write_Bytes_Sec>
<File_Write_Operations_Sec dt:dt="number">1
</File_Write_Operations_Sec>
<Processor_Queue_Length dt:dt="number">0</Processor_Queue_Length>
<System_Calls_Sec dt:dt="number">2368</System_Calls_Sec>
<System_Up_Time dt:dt="number">956388</System_Up_Time>
<Total_Interrupts_Sec dt:dt="number">1076</Total_Interrupts_Sec>
</ROW>
</DATA>
</TABLE>
</SOAP-CHK:Success>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Note: These scenarios do not describe the actual code that was used to develop
them. To produce the charts and tables shown in these examples, you must
develop your own scripts.
You might want to add an <insert> tag into CT_EMail. This tag contains
instructions for the preferred format for the summaries. Management can view
these summaries at their desktops using Internet Explorer. Summaries provide an
efficient and speedy look at problems that might have occurred during the night.
In addition to the general features, you might add to tables and charts:
In addition to the general features you might add to tables and charts. This type of
request might contain these features:
v The chart can be plotted over multiple segments, making it easier to view and
print.
v Clicking the attribute name in the legend box might display that attribute in the
Y-axis and show its threshold value.
v The threshold value, when changed, can be used as the new threshold value.
The graphics that follow depict sample Daily Business Operation summaries.
The graphics that follow show sample charts/reports generated for this type of
request.
Appendix A. IBM Tivoli Monitoring Web Services for the SOAP server 581
Figure 34. Data snapshot table
The graphics that follow show a sample Telnet session, a Universal Message
console showing messages received, and a sample message log.
To accomplish this task, use the CT_Acknowledge SOAP method. This method
enables you to control events in the IBM Tivoli Monitoring environment based
upon information obtained and detected by IBM's automation solutions.
Report contents
You can design a report to contain both a table and a chart view. You might want
to add a Table/Chart button that allows you to toggle between the chart and the
table view.
Appendix A. IBM Tivoli Monitoring Web Services for the SOAP server 583
Table view features
Tables can have specific features. For example, you can design tables that allow
you to:
v View the flyover text containing the name and value of the attribute plotted by
placing your mouse over each plotted item
v Modify the table by filtering the attributes that display
v Remove attributes from a table by clicking the X button next to the attribute
name
Note: The IBM Tivoli Monitoring dashboard data provider is used instead of the
charting web service when you display monitoring data in IBM Dashboard
Application Services Hub.
Single sign-on must be enabled for users of the Tivoli Integrated Portal console and
Tivoli Enterprise Portal Server. The users who display charts containing data from
the charting web service must have a Tivoli Enterprise Portal user ID that is
assigned the monitoring application whose data is displayed in the chart.
Complete these steps on the computer where the Tivoli Enterprise Portal Server is
installed and running to enable the Tivoli Monitoring Charting Web Service.
Procedure
1. Copy the kfwtipewas.properties file to the portal server directory:
From install_dir\CNPS\SQLLIB\ to install_dir\CNPS.
From install_dir/platform/cq/sqllib/ to
install_dir/platform/cq/.
2. Reconfigure the Tivoli Enterprise Portal Server.
What to do next
As a Tivoli Enterprise Portal user you are entitled to see certain workspaces that
belong to a particular monitored application based on your permissions. If you are
entitled to see, say, Linux workspaces, then those workspace queries are available
in the Tivoli Integrated Portal for charting.
If you want to use HTTPS to secure communication between the charting web
service, see “Tivoli Business Service Manager and Tivoli Enterprise Portal Server
integration over SSL” in the IBM Tivoli Monitoring Installation and Setup Guide.
The TMS DLA identifies all distributed and z/OS managed systems registered to
the Tivoli Management Services.
When the tmsdla script is launched, the TMS DLA gathers information by
querying the hub monitoring server for all managed systems and mapping them to
Common Data Model resources based on the agent product code and managed
system name format. The queries specified in the XML input file provided by each
product are run and the results saved to a single output file.
See the agent-specific user guide’s to determine if the agent supplies an input XML
file for the TMS DLA and possible mapping information between the agent’s
monitored resources and Common Data Model resources.
The monitoring servers and the Tivoli Enterprise Portal Server must be running for
these queries. Also, any managed systems that are not online will be ignored.
Run the following TMS DLA script from the command line on the computer where
the portal server is installed:
Procedure
v To make a create-type IDML book, enter the following command:
install_dir\CNPS\tmsdla.bat
The TMS DLA generates the XML output file to the same directory on the portal
server. The name of this file follows the standard Discovery Library file name
format. To use this information in CCMDB, TADDM, or TBSM you must transfer
the XML file to the Discovery Library File Store and then use the Discovery
Library Bulk Loader.
The TMS DLA also creates an output file with the .xml.original extension which
contains the TMS DLA output before any relationships are removed. Removed
relationships are written to tmsdla.log. See “OS agent dependency” on page 589
for examples of scenarios where relationships might be removed from the TMS
DLA XML output file.
Usage
where:
-? | -h Displays the syntax help information.
-d Specify the template directory location.
-f Specify the resulting output file name.
-l Discovers logical views.
-m Specify the list of managed systems.
The list is double quote delimited and follows this syntax:
"os_msys1, os_apptype1, [msys1, apptype1] ~ [os_msys2, os_apptype2,
[msys2, apptype2]] ~ .. ~ [os_msysN, os_apptypeN, [msysN, apptypeN]]"
-o Force processing of offline managed systems.
-p Specify the portal server's port number if it is not the default value of 1920.
The port number is included in the output book and used by TADDM or
TBSM to generate the URL to launch to the Tivoli Enterprise Portal.
-r Generate a refresh-type output XML file. After you import a refresh-type
output file into TADDM, the objects for any managed systems that are
offline, such as for maintenance operations, and their monitored resources
are removed from the TADDM database. The same is true when you
import a refresh-type output file into TBSM or CCMDB. If you do not
specify this option, a create-type output XML file is generated that only
contains online managed systems and the resources that they are
monitoring. When you import a create-type output XML file into TADDM,
TBSM, or CCMDB, managed systems and monitored resources are added
or updated but no deletions occur.
-s Suppress generation of the .original file from cleanup process.
-t Specify the number of threads to use.
-w Specify the number of seconds to wait for query to be serviced by agent
before timing out. Use this option if monitoring agents might not be able
to service queries in a reasonable time due to a heavy load on the queried
system. Default value: 120 seconds.
OS agent dependency
The Tivoli Management Services Discovery Library Adapter (TMS DLA) requires
operating system (OS) agents to monitor the same systems as application agents
that provide DLA templates.
Some application agents (such as the DB2 agent) rely on the OS agents to create
the elements in the DLA book that describe the computer system and operating
systems that the agents are running on. In their DLA templates, the application
agents reference the computer system and operating system elements that will be
created by the OS agents using a relationship element. For example, a Db2System
runsOn a ComputerSystem, where runsOn is the relationship type, Db2System is
the source element, and ComputerSystem is the target element.
If either the source or target of a relationship do not exist in the DLA book, the
book will not load successfully into Tivoli Application Dependency Discovery
Manager (TADDM) or Tivoli Business Service Manager (TBSM). Therefore, the
DLA removes a relationship from an DLA book if the source or target of a
relationship do not exist in the book. This allows the DLA books to load
successfully. However, if a relationship is removed, the DLA book will not contain
the information to map the affected resource (such as a database system) to a
computer system or operating system in TADDM or TBSM.
Appendix C. Using the Tivoli Management Services Discovery Library Adapter 589
The DLA creates two XML files each time the tmsdla command is run:
v A book with the .xml extension
v A book with the .xml.original extension
The file with the .xml.original extension contains the contents of the DLA book
before any relationships are removed. Removed relationships are written in
tmsdla.log.
The TMS DLA does not populate computer systems with data from private
network interfaces configured according to Internet Engineering Task Force (IETF)
RFC 1918 and IETF RFC 4193. For details about RFCs, see the RCF Index
(http://tools.ietf.org/rfc/index). This behavior prevents the incorrect merging of
computer systems when multiple private networks use overlapping address
ranges.
To enable discovery of computer systems with private network interfaces, edit the
IP address filters in the XML template files that control the TMS DLA behavior.
Procedure
1. Back up the template files before editing.
v The template files are stored in $ITM_HOME/arch/cq/
tmsdla on the Tivoli Enterprise Portal Server.
v The template files are stored in %ITM_HOME%\CNPS\tmsdla on the
Tivoli Enterprise Portal Server.
2. A template for each monitoring agent provides discovery data.
a. Check each of the template files to determine whether it has one or more
<tmsdla:filter> sections. For example, the template file names for the
operating system agents are:
knt_tmsdla.xml for the Windows OS agent
kux_tmsdla.xml for the UNIX OS agent
klz_tmsdla.xml for the Linux OS agent
b. Update the multiple <tmsdla:filter> sections in each of the template files
to contain only the filters for loopback addresses (127.0.0.1 for IPv4 and ::1
for IPv6), as shown in the following example:
<tmsdla:filters>
<tmsdla:filter name="IF_IP_ADDR" exclude="127\.0\.0\.1"/>
<tmsdla:filter name="IF_IP_ADDR" exclude="::1"/>
</tmsdla:filters>
Appendix C. Using the Tivoli Management Services Discovery Library Adapter 591
592 IBM Tivoli Monitoring: Administrator's Guide
Appendix D. Using the z/OS Tivoli Management Services
Discovery Library Adapter
The z/OS Tivoli Management Services Discovery Library Adapter (zTMS DLA),
available as of V6.2.2 Fix Pack 7 or later and IBM Tivoli Monitoring V6.2.3 Fix Pack
1 or later, scans the IBM Tivoli Monitoring environment and discovers resources
monitored by the OMEGAMON agents.
The zTMS DLA identifies resources only on z/OS operating systems. To discover
resources on distributed systems, you must also run the Tivoli Monitoring Services
Discovery Library Adapter.
The zTMS DLA creates the following Common Data Model (CDM) objects:
v sys.zOS.Sysplex
v sys.zOS.SysplexGroup
v sys.zOS.ZSeriesComputerSystem
v sys.zOS.ZOS
v sys.zOS.CICSRegion
v sys.zOS.DB2Subsystem
v sys.zOS.IMSSubsystem
v sys.zOS.MQSubsystem
v sys.zOS.AddressSpace
Important: To reconcile with the zTMS DLA book, the version of the z/OS DLA
required is V3.1, with PTF UA61720. The IDML book generated by the zTMS DLA
does not contain all required attributes for the various z/OS CDM objects. Before
importing the zTMS DLA book into a consuming application, you must first run
the z/OS DLA on all the systems monitored by the IBM Tivoli Monitoring
OMEGAMON agents and import the resulting z/OS DLA books into the
consuming application. Then you can import the zTMS DLA book, and all objects
will be reconciled with existing objects found in the z/OS DLA books. If the zTMS
DLA book is imported without having imported the z/OS DLA books first, objects
might be displayed in the TBSM UI as NO_LABEL_SUPPLIED.
User scenarios
1. On z/OS LPARS, execute the z/OS DLA on all z/OS LPARs of interest.
2. On the Tivoli Enterprise Portal Server, execute the zTMS DLA on portal servers
with z/OS agents.
3. If you are using TBSM, complete the following steps:
a. On the TBSM data server, import z/OS DLA books into TBSM by using the
TBSM discovery library toolkit.
Run the following DLA script from the command line on the computer where the
Tivoli Enterprise Portal Server is installed:
Procedure
v To make an IDML book, enter the following command:
install_dir\CNPS\ztmsdla.exe
Results
The DLA generates the XML output file in the directory identified above. The
name of this file begins with the string ZTMSDISC100-B and follows the standard
Discovery Library file name format, for example: ZTMSDISC100-
B.<hostname>.<timestamp>.refresh.xml.
To import this book into TADDM or TBSM, you must transfer the XML file to the
Discovery Library File Store and then use the Discovery Library Bulk Loader.
Usage
where:
/? Displays the syntax help information.
/b Opens a browser to view the output file of the Discovery Library Adapter
(on Windows only).
/d Creates a diagnostic file during the discovery process. You can use this file
for debugging. The file is located in the same directory as the DLA IDML
book. The file name is the same as the DLA IDML book, with an extension
of .log at the end of the file name, for example: ZTMSDISC100-
B.<hostname>.<timestamp>.refresh.log.
/o orgname
Sets the Organization GlobalName value. If this argument is not specified,
the GlobalName defaults to <defaultOrg>.
Known limitations
Appendix D. Using the z/OS Tivoli Management Services Discovery Library Adapter 595
596 IBM Tivoli Monitoring: Administrator's Guide
Appendix E. MIB SNMP agent event descriptions
Tivoli monitoring agents emit three types of SNMP alerts to convey agent
operational status, sampled situation events, and pure situation events. The alert
types are defined in the canbase.mib and cansyssg.mib files, which are available on
the IBM Tivoli Monitoring- and IBM Tivoli Monitoring Agents installation media.
Agent situation state SNMP traps are sent using enterprise 1.3.6.1.4.1.1667.1.3
(Candle-BASE-MIB::candle-Alert-MIB).
agentStatusEvent
agentSitSampledEvent
A sampled situation event was detected. This trap was generated by the Tivoli
Autonomous Agent SNMP Event Exporter in response to a situation threshold
being exceeded at the time of the data sampling.
Specific trap: 21
Access: read-only
Status: mandatory
Table 74. SNMP trap variables for agentSitSampledEvent
Attribute Description OID
agentSit- This is the product application name, 1.3.6.1.4.1.1667.1.2.1.10.1.1
Application from 1 to 8 bytes.
agentSit-Table This is the name of the product 1.3.6.1.4.1.1667.1.2.1.10.1.2
application table (attribute group), from
1 to 12 bytes.
agentSit-Name The situation name, up to 32 bytes, 1.3.6.1.4.1.1667.1.2.1.10.1.3
identifies the name and nature of the
status event.
agentSit- The name of the managed system where 1.3.6.1.4.1.1667.1.2.1.10.1.4
OriginNode the situation was evaluated, up to 32
bytes.
agentSitPureEvent
A pure situation event was detected. This trap was generated by the Tivoli
Autonomous Agent SNMP Event Exporter in response to a situation threshold
being exceeded. The variables in a pure event trap are identical to those for a
sampled event trap except there is no agentSit-SampleInterval because pure events
are not sampled; rather the arrival of unsolicited data from the monitored attribute
group causes the situation to become true. A situation created with an attribute
group for a system log, for example, opens a pure event when a log entry arrives.
Specific trap: 22
Access: read-only
Status: mandatory
Table 75. SNMP trap variables for agentSitPureEvent
Attribute Description OID
agentSit- This is the product application name, 1.3.6.1.4.1.1667.1.2.1.10.1.1
Application from 1 to 8 bytes.
agentSit-Table This is the name of the product 1.3.6.1.4.1.1667.1.2.1.10.1.2
application table (attribute group), from
1 to 12 bytes.
agentSit-Name The situation name, up to 32 bytes, 1.3.6.1.4.1.1667.1.2.1.10.1.3
identifies the name and nature of the
status event.
agentSit- The name of the managed system where 1.3.6.1.4.1.1667.1.2.1.10.1.4
OriginNode the situation was evaluated, up to 32
bytes.
When an agent runs autonomously, audit trail records for all events and true
sampled application data rows are written to the operations log. The agent
leverages the existing Agent Operation Log facility and outputs audit trail records
to it. The Agent Operation Log can be viewed on the Tivoli Enterprise Portal while
the agent is online.
v On distributed systems, the agent creates the Operation Log file automatically in
the agent installation directory, names it ComputerName_product.LG0 for the
current running log file, and renames the previous log file
ComputerName_product.LG1 (the backup file).
v On z/OS systems, the agent writes the Agent Operation log records to a SYSOUT
class, saving portions of records in memory cache.
The agent operations log also shows the activity of private situations.
This is the result of a table view of the Agent Operations Log filtered to include
only the agent autonomy messages: == KRAIRA005
Message Global
Server Name Number Timestamp Managed System Type
Primary:East:NT KRAIRA005 02/16/2009 Situation NT_Process_CPU_Critical for KNT.WTPROCESS
12:35:42 reset
Primary:East:NT KRAIRA005 02/16/2009 Situation NT_Process_CPU_Critical for KNT.WTPROCESS
12:34:43 triggered (03) Process_Name [_Total] value <kdsmain>
Primary:East:NT KRAIRA005 02/16/2009 Situation NT_Process_CPU_Critical for KNT.WTPROCESS
12:34:42 triggered (02) Priority_Base [0] value <8>
For information about accessing and using the publications, select IBM Tivoli
Monitoring → Using the publications in the Contents pane of the IBM Tivoli
Monitoring and OMEGAMON XE Information Center at http://pic.dhe.ibm.com/
infocenter/tivihelp/v61r1/index.jsp.
To find a list of new and changed publications, click the New in this release topic
on the IBM Tivoli Monitoring welcome page. To find publications from the
previous version of a product, click Previous versions under the name of the
product in the Contents pane.
The following publications provide information about using the base agents.
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 OS agent documentation is delivered in the following locations:
Agent Installation and Configuration Guide
Available in the Information Center:
– IBM i OS Agent Installation and Configuration Guide, SC27-5653
– Linux OS Agent Installation and Configuration Guide, SC27-5652
– UNIX OS Agent Installation and Configuration Guide, SC27-5651
– Windows OS Agent Installation and Configuration Guide, SC27-5650
Agent Reference
Available on Service Management Connect
Agent Troubleshooting Guide
Available on Service Management Connect
Infrastructure Management Dashboards for Servers Reference
Available on Service Management Connect
v Warehouse agent documentation is delivered in the following locations:
Agent Installation and Configuration Guide
Available in the Information Center:
– Warehouse Proxy Agent Installation and Configuration Guide, SC27-5655
– Warehouse Summarization and Pruning Agent Installation and
Configuration Guide, SC27-5654
Related publications
For information about related products and publications select OMEGAMON XE
shared publications or other entries in the Contents pane of the IBM Tivoli
Monitoring and OMEGAMON XE Information Center.
You can access the IBM Tivoli Monitoring and OMEGAMON XE Information
Center at http://pic.dhe.ibm.com/infocenter/tivihelp/v61r1/index.jsp .
You can also access other information centers at IBM Tivoli Documentation Central
(https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/
wiki/Tivoli%20Documentation%20Central).
The IBM Support Assistant saves you the time it takes to search the product,
support, and educational resources. The IBM Support Assistant helps you gather
support information when you need to open a problem management record
(PMR), which you can then use to track the problem.
The product-specific plug-in modules provide you with the following resources:
v Support links
v Education links
v Ability to submit problem management reports
For more information, and to download the IBM Support Assistant, see
http://www.ibm.com/software/support/isa. After you download and install the
IBM Support Assistant, follow these steps to install the plug-in for your Tivoli
product:
1. Start the IBM Support Assistant application.
2. Select Updater on the Welcome page.
3. Select New Properties and Tools or select the New Plug-ins tab (depending on
the version of IBM Support Assistant installed).
4. Under Tivoli, select your product, and then click Install. Be sure to read the
license and description.
Obtaining fixes
A product fix might be available to resolve your problem. To determine which
fixes are available for your Tivoli software product, follow these steps:
1. Go to the IBM Software Support website at http://www.ibm.com/software/
support.
2. Under Select a brand and/or product, select Tivoli.
If you click Go, the Search within all of Tivoli support section is displayed. If
you don't click Go, you see the Select a product section.
3. Select your product and click Go.
4. Under Download, click the name of a fix to read its description and, optionally,
to download it.
If there is no Download heading for your product, supply a search term, error
code, or APAR number in the field provided under Search Support (this
product), and click Search.
For more information about the types of fixes that are available, see the IBM
Software Support Handbook at http://www14.software.ibm.com/webapp/set2/sas/
f/handbook/home.html.
Before contacting IBM Software Support, your company must have an active IBM
software maintenance contract, and you must be authorized to submit problems to
IBM. The type of software maintenance contract that you need depends on the
type of product you have:
v For IBM distributed software products (including, but not limited to, Tivoli,
Lotus®, and Rational® products, as well as DB2 and WebSphere products that
run on Windows or UNIX operating systems), enroll in Passport Advantage® in
one of the following ways:
Online
Go to the Passport Advantage website at http://www-306.ibm.com/
software/howtobuy/passportadvantage/pao_customers.htm .
By telephone
For the telephone number to call in your country, go to the IBM
Software Support website at http://techsupport.services.ibm.com/
guides/contacts.html and click the name of your geographic region.
v For customers with Subscription and Support (S & S) contracts, go to the
Software Service Request website at https://techsupport.services.ibm.com/ssr/
login.
v For customers with Linux, iSeries, pSeries, zSeries, and other support
agreements, go to the IBM Support Line website at http://www.ibm.com/
services/us/index.wss/so/its/a1000030/dt006.
v For IBM eServer™ software products (including, but not limited to, DB2 and
WebSphere products that run in zSeries, pSeries, and iSeries environments), you
can purchase a software maintenance agreement by working directly with an
IBM sales representative or an IBM Business Partner. For more information
about support for eServer software products, go to the IBM Technical Support
Advantage website at http://www.ibm.com/servers/eserver/techsupport.html.
If you are not sure what type of software maintenance contract you need, call
1-800-IBMSERV (1-800-426-7378) in the United States. From other countries, go to
the contacts page of the IBM Software Support Handbook on the web at
http://www14.software.ibm.com/webapp/set2/sas/f/handbook/home.html and
click the name of your geographic region for telephone numbers of people who
provide support for your location.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law :
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
2Z4A/101
11400 Burnet Road
Austin, TX 78758 U.S.A.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
All IBM prices shown are IBM's suggested retail prices, are current and are subject
to change without notice. Dealer prices may vary.
This information is for planning purposes only. The information herein is subject to
change before the products described become available.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows: © (your company name) (year). 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 be displayed.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks 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.
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 Oracle and/or its affiliates.
Notices 615
Offering uses cookies to collect personally identifiable information, specific
information about this offering’s use of cookies is set forth below.
Depending upon the configurations deployed, this Software Offering may use
session cookies that collect each user’s user name for purposes of session
management, authentication, and single sign-on configuration. These cookies
cannot be disabled.
If the configurations deployed for this Software Offering provide you as customer
the ability to collect personally identifiable information from end users via cookies
and other technologies, you should seek your own legal advice about any laws
applicable to such data collection, including any requirements for notice and
consent.
For more information about the use of various technologies, including cookies, for
these purposes, See IBM’s Privacy Policy at http://www.ibm.com/privacy and
IBM’s Online Privacy Statement at http://www.ibm.com/privacy/details the
section entitled “Cookies, Web Beacons and Other Technologies” and the “IBM
Software Products and Software-as-a-Service Privacy Statement” at
http://www.ibm.com/software/info/product-privacy.
Index 619
IBM Tivoli Monitoring Web Services 559 KD8_VM_IMPORT_ID 68 load balancing
adding users 562 keep 16 See HTTP server for load balancing
introduction 559 key database, creating 241 login daemon 294
predefined SOAP methods 569 keywords for configuration load list 441 logon
report contents 583 KFW_AUTHORIZATION_ controlling number of attempts 83
sample CT_Get SOAP request 579 MAX_INVALID_LOGIN 83 logon error messages 559
second-level requests 578 KFW_MCS_XML_FILES 273 LTPA keys 123
SOAP description and URLs 559 KFWENV file 79
SOAP requests as system KHD_HISTSIZE_EVAL_INTERVAL 501,
commands 568
starting the client 566
502
KHD_TOTAL_HIST_MAXSIZE 501, 502
M
Manage Tivoli Enterprise Monitoring
user IDs 566 KMS_EVAL_REFLEX_AT_TEMS 85
Services 96
verifying configuration 565 KMS_OMTEC_
defining SOAP hubs 560
IFS directory 506 GLOBALIZATION_LOC 259
global parameters 69
import KPDXTRA 510
managed system
portal server database 553 DDNAMES to be allocated 511
add through the portal 287
portal server database from and to a parameters 511
apply a patch through the portal 290
Linux or UNIX system 556 KPDXTRA attribute 510
description 7
importing LTPA keys 123 KPDXTRA program
managed system groups
Infrastructure Management about 511
configure summarization and
Dashboards 29 messages 512
pruning 492
initiating Centralized Configuration 451 krarloff 502
Managed System Groups
initiating Centralized Configuration by krarloff rolloff attribute 509
security 179
placing the file 454 krarloff rolloff program
managed systems
install 19 converting files on HP NSK 509
configure through the portal 288
installing 19 HP NonStop Kernel Systems
MANAGEDSYSTEMLIST 530
Integrated Cryptographic Service historical data conversion 508
MANAGEDSYSTEMLISTMEMBERS 530
Facility 78, 79 IBM i 506
manual conversion 508
Integrated Service Management on HP NSK 508
map
Library 608 on Linux or UNIX 507
customizable column 284
Integrated Solutions Console on Windows 504
customizable columns 284
See TEPS/e administration console on z/OS 509
maximum directory size 502
integration parameter 266 Windows
MCS Attribute Service 273
Internet Explorer historical data conversion 504
meta description files 499
Options - Security 16 z/OS
MIB for SNMP alerts and agent emits
ior URL 72 historical data conversion 509
agentSitPureEvent 377, 597
ISA 609 kshsoap 567
agentSitSampledEvent 377, 597
ITM Audit log 245 KSY_Summarization_Config_DV 539
agentStatusEvent 377, 597
ITM Connector 280 KSY_TRAM_ENABLE 530
Microsoft Management Console 134
itmc_kdy.properties 292 KSY_TRAM_PASSWORD 530
ADSI Edit snap-in for 144
itmcmd history 507, 508 KSY_TRAM_TD_GRANULARITY 530
migrate
itmcmd history, running on a UNIX KSY_TRAM_TD_INITIAL_LOAD 530
authentication 126
system 508 KSY_TRAM_USER 530
migrate-export script 552
itmpwdsnmp command 376 kwgcap.xsd 317
migrate-import 553, 554, 555
from Linux or UNIX to Linux or
UNIX 556
J L migrate-import script 553
Java 19 launch application 25 MKTIME 339
in an emulation environment 74 LDAP 121 monitoring
JRE on Windows for Java Web configure an external server 115 Agent Management Services 315
Start 19 disable portal server monitoring agent 287
Java Runtime Environment 15 authentication 125 analytics 518
for GSKit 240 new users 125 apply a patch through the portal 290
Java Web Start portal server configration 112 assign through the portal 287
download the desktop client 21 portal server configuration 108 connect to a different monitoring
using to download the desktop SSL for portal server 119 server 294
client 18 ldapsearch 96 recycling 289
Java Web Start client 10 sample command (no TLS/SSL) 98 starting 289
JRE 19 sample command with SSL 98 stopping 289
enabling tracing for 20 ldapsearch command-line options 97 monitoring agents
Lightweight Directory Access Protocol See also enterprise monitoring agents
Active Directory, Microsoft 129 Centralized Configuration to
K Linux 285, 563
Linux or UNIX
maintain 429
clearing the Deployment Status
KASENV file 87
historical data conversion 507 table 292
KBBENV file 84
Linux OS lz_situations.xml 353 configure through the portal 288
kcacap.xsd 317
Linux_IP_Addres 539 managing with the portal client 287
Index 621
queries (continued) self-describing agents (continued) SOAP server (continued)
of k<pc>.atr in the Agent Service suspending 305 adding users 562
Interface 411 terminal errors 302 configuration 559
self-signed certificate 242 defining hubs 560
Service Management Connect 607, 609 security 564
R short-term history
data conversion programs 499
verifying configuration 565
SOAP_IS_SECURE 564
reconfigure
limiting file size 501 Software Support 609
browser client 122
short-term history file 502 contacting 611
recycling a monitoring agent 289
shortcut for launching desktop client 22 receiving weekly updates 610
Redbooks 608, 609
Simple Object Access Protocol (SOAP) SP800-131a 230
REGEX 340
client requests 559 specify browser 25
Regular expression 339, 340
single sign-on 102, 122 SSL 213
release information 1
roadmap for portal server and LDAP between portal server and LDAP
remove agent 291
registry 104 server 119
replicate the portal server 551
unavailable with monitoring server between the hub monitoring server
prerequisites 551
authentication 129, 147 and the LDAP server 210
report installer 541
sitconfig.sh command 263 CA certificate request, creating 241
reports
situation CA certificate, receiving 242
See IBM Cognos reports
SOAP requests 568 certificate management for
RoleAdministrator 187, 189
sound parameter 72 Netcool/OMNIbus 400
rule check utility tool 266
situation description 257 EIF events 397
Runtime 19
situation event 272 key database, creating 241
situation events password, saving to stash file 243
map 255 public-private key pair, creating 241
S situation overrides XML 360 self-signed certificate, using 242
SA IO REXX application 582 situations setting up asymmetric
sample autonomous agent behavior 327 encryption 207
data mart duper process 85 stash file 243
SQL script 470 event integration with OMNIbus 277 with the Authorization Policy
sampled situation 264 private Server 214
schedule See private situations with the dashboard data
history data conversion 508 status in Agent Service Interface 409 provider 211
Schema Publication Tool SMC 607, 609 SSL between the portal server and LDAP
create Tivoli Common Reporting SNMP server 113
dimension tables 532 encrypting passkeys 376 SSO 122
script MIB agent event types 377, 597 starting a monitoring agent 289
terminal maximum 73 Situation element 371 stash file 243
security TrapAttrGroup xml element 370 StatTrap element 374
See also Access Authorization Group SNMP alerts 365 stopping a monitoring agent 289
Profile configuration 365 store data to database 502
Access Control Lists 179 from agents with subnodes 329 summarization and pruning 463, 491
Authorization Policy Server 179 sample OMNIbus rules 379 configuration 485
FIPS 226 sample trap configuration file 365 data availability 490
Managed System Groups 179 trap XML specification 367 description 485
portal server for LDAP and SSO 99 SNMP element 367 disable 497
role-based 179 SNMP traps global configuration 494
SP800-131a 230 configuring the OMNIbus Summarization and Pruning agent
security settings 16 Multi-threaded Trapd probe 377 reporting table automation 530
self-describing agent SOAP 559, 564 Tivoli Common Reporting
SDA-enabled agents 310 browser startup 567 limitations 526
self-describing agents 295, 300 server 563 Summarization and Pruning
auto refresh 306 SOAP client requests 559 sy_situations.xml 357
disabling at the agent 309 SOAP method support assistant 609
disabling at the remote monitoring CT_Acknowledge 569, 583 Support Assistant 609
server 308 CT_Activate 570 synchronizing situation events
enabling at the agent 309 CT_Alert 570, 582 IBM Tivoli Enterprise Console 262
enabling at the remote monitoring CT_Deactivate 571 synchronizing TEC events 255
server 308 CT_EMail 572 sysadmin 89
environment variables 312 CT_Execute 573 SYSADMIN 174
errors that can be tried again 302 CT_Export 573 system administrator 11
install errors 302 CT_Get 575, 579 system monitor agents
install options 304 CT_Redirect 576 Agent Management Services on 331
monitoring server event flow 298 CT_Reset 576 initiating Centralized
resuming 305 CT_Resurface 577 Configuration 452
seeding 306 CT_WTO 578
STATUS codes 302 SOAP server 580
Index 623
user administration (continued)
Users and User Groups window 163
X
validating user access 175 XML
workspace administration mode 174 See also local configuration files
user authentication 92, 94, 95, 96 AGENTINFO 413
automation server 128 AGENTSTAT 424
new LDAP users 125 ATTRLIST 415
portal server 99 CNFGLIST 434
road map for single sign-on using EVENTDEST 383
LDAP 104 EVENTMAP 383
single sign-on 102 HISTREAD 426
via Active Directory 129 LISTSUBNODE 414
user groups 171 private history 335
adding 172 private situations 335
removing 174 PVTCONTROL 422
reviewing and editing 173 READATTR 415
viewing memberships 171 REPORT 412, 417
user ID 121 SITSUMMARY 412, 423
enable authentication 89 situation_name (exported) 347
IBM Tivoli Monitoring Web TABLESIT 421
Services 566 THRESHOLDS 360
Windows Users Group 17 TRAPCNFG 365, 367
user IDs 168 UTF-8 encoding 330
adding a user ID 168 z/OS
default user 171 UTF-8 encoded XML 330
removing a user ID 170
viewing and editing a user ID 169
user security Z
configuring for a hub monitoring z/OS
server on Linux or UNIX 95 agent autonomy 323, 458
configuring for a hub monitoring data conversion using
server on Windows 94 KPDXTRA 510
user validation 92 Integrated Cryptographic Service
See user authentication Facility 78, 79
user.language 74 LDAP not supported on hub 89
user.region 75 location of historical data files 513
Users Group privileges 17 manual archiving procedure 513
UTF-8 encoded XML 330 private history and PDS 358
RACF or ACF/2 for user
validation 175
W SNMP alerts in PCTRAPS 365
warehouse proxy
ATTRLIB directory 473
warehouse proxy agent
error logging 497
Warehouse Proxy agent
analytics 514
parameters 514
WAREHOUSEID 472
Web services
configure 563
Web Services 559
defining hubs 560
Web Start 22
what is new 1, 2
window
Edit Tivoli Enterprise Portal Parm 69
Windows
location of executable files 505
location of historical data table
files 506
Users group 17
Windows OS nt_situations.xml 355
Windows systems AT command 505
workspace
history parameter 72
Printed in USA
SC22-5446-02