Tivoli IBM Tivoli Universal Agent


Version 6.1.0

User’s Guide

SC32-9459-00
 Tivoli IBM Tivoli Universal Agent
®


Version 6.1.0

User’s Guide

SC32-9459-00
 Note
Before using this information and the product it supports, read the information Appendix J, “Notices,” on page 233.

Second Edition (November 2005)

This edition applies to version 6, release 1, modification 0 of IBM Tivoli Monitoring (product number 5724-C04) and
to all subsequent releases and modifications until otherwise indicated in new editions.
© Copyright International Business Machines Corporation 2003, 2005. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . vii Chapter 3. Creating an application . . . 15
Introduction to the IBM Tivoli Universal Agent
Tables . . . . . . . . . . . . . . . ix application . . . . . . . . . . . . . . 15
Creating an IBM Tivoli Universal Agent application 15
Constructing a data definition metafile . . . . . 15
About this guide . . . . . . . . . . . xi
Naming metafiles . . . . . . . . . . . 17
Who should read this guide . . . . . . .
. xi .
Creating help for applications, attribute groups,
Publications . . . . . . . . . . . .
. xi .
and attributes. . . . . . . . . . . . . 17
IBM Tivoli Monitoring library . . . . .
. xi .
Storing metafiles. . . . . . . . . . . . 18
Accessing terminology online . . . . . . . xii
Validating data definitions . . . . . . . . . 18
Accessing publications online . . . . . . . xii
Running the validation program . . . . . . 19
Ordering publications. . . . . . . . . . xiii
Sample validation output . . . . . . . . . 19
Accessibility . . . . . . . . . . . . . . xiii
Activating metafiles . . . . . . . . . . . 19
Tivoli technical training . . . . . . . . . . xiii
Activating metafiles with console commands . . 19
Support information . . . . . . . . . . . xiii
Activating metafiles with Take Action commands 20
Conventions used in this guide . . . . . . . xiii
Activating metafiles with a configuration file . . 21
Typeface conventions . . . . . . . . . . xiv
Creating a metafile server . . . . . . . . . 22
Tivoli command syntax . . . . . . . . . xiv
Designating a metafile server . . . . . . . 23
Storing server metafiles . . . . . . . . . 23
Chapter 1. Understanding the IBM Tivoli Determining server and client roles on the same
Universal Agent . . . . . . . . . . . 1 host . . . . . . . . . . . . . . . . 23
Introducing the IBM Tivoli Universal Agent . . . . 1 Synchronization of metafile server and client . . 23
Understanding how the IBM Tivoli Universal Agent Overriding the central metafile definition . . . 24
works . . . . . . . . . . . . . . . . 1 Versioning of metafiles . . . . . . . . . . 24
Defining data to the IBM Tivoli Universal Agent . . 3 Incrementing version and modification numbers 24
Providing data to the IBM Tivoli Universal Agent . . 3 Reversioning of managed systems, workspaces,
Working with the data . . . . . . . . . . . 4 and attribute groups . . . . . . . . . . 24
A simple monitoring scenario . . . . . . . . . 4 Changes that do not affect modification or
Selecting the data provider . . . . . . . . 5 version number . . . . . . . . . . . . 25
Preparing the data source . . . . . . . . . 5 Changes that affect modification number (minor
Defining the IBM Tivoli Universal Agent changes) . . . . . . . . . . . . . . 25
application . . . . . . . . . . . . . . 5 Changes that affect version number (major
Viewing attribute data from FTPLOGFILE . . . 6 changes) . . . . . . . . . . . . . . 25
Creating an automation policy . . . . . . . 6 Resetting version numbers . . . . . . . . 26
IBM Tivoli Universal Agent SNMP applications . . 27
Chapter 2. Getting started . . . . . . . 9 Metafile names . . . . . . . . . . . . 27
Introduction . . . . . . . . . . . . . . 9 Location of SNMP metafiles . . . . . . . . 27
Setting up the IBM Tivoli Universal Agent . . . 9 Importing SNMP metafiles . . . . . . . . 28
Selecting a data provider . . . . . . . . . . 9 Versioning of applications . . . . . . . . 28
Selecting the data you want to monitor . . . . 9 Viewing application metafiles . . . . . . . 28
Understanding the location of your data . . . . 10 Creating custom SNMP applications . . . . . 29
Determining the data provider . . . . . . . 10
Determining the required number of IBM Tivoli Chapter 4. About data providers . . . . 33
Universal Agents . . . . . . . . . . . . 11 About data providers . . . . . . . . . . . 33
Determining how many IBM Tivoli Universal Types of data providers . . . . . . . . . 33
Agents I can run on the same host . . . . . . 11 Running multiple instances of a data provider . . 33
Determining how many data providers I can start API Server Data Provider . . . . . . . . . . 37
with one IBM Tivoli Universal Agent . . . . . 11 Invoking the APIs . . . . . . . . . . . 37
Starting the IBM Tivoli Universal Agent and its data The API client package . . . . . . . . . 37
providers . . . . . . . . . . . . . . . 12 Calling programs . . . . . . . . . . . 38
Specifying data providers . . . . . . . . . 12 API console commands . . . . . . . . . 38
Specifying startup parameters on Windows Specifying the host of the API Server Data
operating systems . . . . . . . . . . . 12 Provider . . . . . . . . . . . . . . 39
Specifying startup parameters on UNIX operating Specifying the listening port for the API Server
systems . . . . . . . . . . . . . . . 12 Data Provider . . . . . . . . . . . . 39

© Copyright IBM Corp. 2003, 2005 iii

 Managed system names of API Data Provider Timing out . . . . . . . . . . . . . 93
applications . . . . . . . . . . . . . 39 Sending action commands to socket clients . . . 93
File Data Provider . . . . . . . . . . . . 40 End of input . . . . . . . . . . . . . 94
Location of File Data Provider . . . . . . . 40 Character code translation . . . . . . . . 94
Managed system names of File Data Provider Use of character format for numeric data . . . 95
applications . . . . . . . . . . . . . 40 Managed system names of Socket Data Provider
File sampling frequency . . . . . . . . . 40 applications . . . . . . . . . . . . . 95
Special file extracting routines . . . . . . . 41 TCP outage detection . . . . . . . . . . 96
Multiple record input . . . . . . . . . . 41 Delay of TCP disconnection notification . . . . 96
Globalized file monitoring . . . . . . . . 41 Data acknowledgment . . . . . . . . . . 97
Dynamic file name support . . . . . . . . 42 Limitations of the Socket Data Provider . . . . 97
Pre-allocated file space . . . . . . . . . 44
Additional file monitoring options . . . . . . 44 Chapter 5. Monitoring applications . . . 99
HTTP Data Provider . . . . . . . . . . . 45 Monitoring IBM Tivoli Universal Agent data . . . 99
Starting the HTTP Data Provider . . . . . . 45 IBM Tivoli Universal Agent managed systems . . . 99
Managed system names of HTTP Data Provider Managed system names . . . . . . . . . 99
applications . . . . . . . . . . . . . 45 Truncation of managed system names . . . . 100
Monitoring a URL . . . . . . . . . . . 45 Managed system version numbers . . . . . 100
URL attributes . . . . . . . . . . . . 47 Managed system version changes . . . . . 100
ODBC Data Provider . . . . . . . . . . . 50 Application workspaces . . . . . . . . . . 101
Starting the ODBC Data Provider . . . . . . 50 Physical . . . . . . . . . . . . . . 101
Sample ODBC metafiles . . . . . . . . . 50 Logical . . . . . . . . . . . . . . 102
Parameters and statements . . . . . . . . 51 Application names . . . . . . . . . . 102
Automatic generation of ODBC metafiles . . . 53 Workspace names . . . . . . . . . . . 102
Post Data Provider . . . . . . . . . . . . 54 Customizing workspace contents . . . . . . 102
Default configuration . . . . . . . . . . 54 Accessing help for applications, attribute
Message categories . . . . . . . . . . . 55 groups, and attributes . . . . . . . . . 102
Acknowledgment stamp . . . . . . . . . 55 UAGENT workspaces . . . . . . . . . . 103
Customizing the Post Data Provider with UAGENT managed system names . . . . . 103
metafiles . . . . . . . . . . . . . . 55 DPLOG workspace . . . . . . . . . . 103
Customizing the Post Data Provider runtime ACTION workspace . . . . . . . . . . 104
specifications . . . . . . . . . . . . . 56 IBM Tivoli Universal Agent situations . . . . . 105
Post Data Provider supplied data . . . . . . 57 About predefined situations . . . . . . . 105
The KUMPSEND program . . . . . . . . 57 Using situations . . . . . . . . . . . 106
Sending data to the Post Data Provider . . . . 58 Attribute and attribute group names . . . . 106
Script Data Provider . . . . . . . . . . . 59 Creating situations with attributes from different
Script metafiles . . . . . . . . . . . . 59 groups . . . . . . . . . . . . . . 106
Using the Script Data Provider . . . . . . . 59 Distributing situations to managed systems . . 106
Scripts directory . . . . . . . . . . . . 61 Monitoring interval and time-to-live value . . 107
Managed system names of Script Data Provider Historical data collection . . . . . . . . . 107
applications . . . . . . . . . . . . . 61
Script authentication . . . . . . . . . . 62
Chapter 6. Introducing the SNMP
Sample script metafile . . . . . . . . . . 62
SNMP Data Provider . . . . . . . . . . . 64 emitter . . . . . . . . . . . . . . 109
Managed system names of SNMP Data Provider Understanding the SNMP emitter . . . . . . 109
applications . . . . . . . . . . . . . 64 SNMP emitter environment variables . . . . 110
Features of the SNMP Data Provider . . . . . 65 Installing and integrating the SNMP emitter . . . 110
Specifying community names . . . . . . . 65 Installing the SNMP emitter . . . . . . . 110
Assigning network symbolic names . . . . . 67 Integrating the SNMP emitter into third-party
SNMP-MANAGER application . . . . . . . 67 solutions . . . . . . . . . . . . . . 110
Sending SNMP traps to the data provider . . . 68 Using the SNMP emitter and its data . . . . . 111
Starting the SNMP Data Provider . . . . . . 68 Establishing SNMP emitter parameters . . . . 111
Stopping the SNMP Data Provider . . . . . 69 Using SNMP emitter data . . . . . . . . 113
Monitoring SNMP applications . . . . . . . 69
Socket Data Provider . . . . . . . . . . . 88 Appendix A. Data definition control
Contacting the Socket Data Provider . . . . . 88 statements . . . . . . . . . . . . 115
Changing the default listening port . . . . . 89 Introduction . . . . . . . . . . . . . . 115
Host name and TCP/IP address translation. . . 89 SNMP statement . . . . . . . . . . . . 116
Multiple host machines . . . . . . . . . 89 Description . . . . . . . . . . . . . 116
Associating data sources with metafiles . . . . 89 Syntax . . . . . . . . . . . . . . . 116
Formatting a socket buffer for transmission . . . 93 Parameter . . . . . . . . . . . . . 116

iv IBM Tivoli Universal Agent: User’s Guide

APPL statement . . . . . . . . . . . . 117 Derived attribute functions . . . . . . . . 161
Description . . . . . . . . . . . . . 117 Filtering attributes . . . . . . . . . . . . 162
Syntax . . . . . . . . . . . . . . . 117 Syntax . . . . . . . . . . . . . . . 162
Parameters . . . . . . . . . . . . . 117 Description . . . . . . . . . . . . . 162
NAME statement . . . . . . . . . . . . 119 Sequencing attribute definitions . . . . . . . 164
Description . . . . . . . . . . . . . 119 Syntax . . . . . . . . . . . . . . . 164
Syntax . . . . . . . . . . . . . . . 119 Description . . . . . . . . . . . . . 164
Parameters . . . . . . . . . . . . . 119 SNMP attributes . . . . . . . . . . . . 166
Additional features . . . . . . . . . . 122 About attributes and attribute groups . . . . 166
INTERNAL statement . . . . . . . . . . 123 MANAGED-NODES attribute group . . . . 169
Description . . . . . . . . . . . . . 123 MIBNODATA attribute group . . . . . . . 171
Syntax . . . . . . . . . . . . . . . 123 MIBSTATUS attribute group . . . . . . . 172
Parameters . . . . . . . . . . . . . 123 NETSUMMARY attribute group . . . . . . 173
SOURCE statement . . . . . . . . . . . 126 NETWORK attribute group . . . . . . . . 175
Description . . . . . . . . . . . . . 126 ROUTER attribute group . . . . . . . . 177
Syntax . . . . . . . . . . . . . . . 126 TRAP attribute group . . . . . . . . . 178
Parameters . . . . . . . . . . . . . 126
RECORDSET statement . . . . . . . . . . 135 Appendix C. Console commands . . . 181
Description . . . . . . . . . . . . . 135 Using console commands . . . . . . . . . 181
Syntax . . . . . . . . . . . . . . . 135 Invoking the console command interface on
Parameters . . . . . . . . . . . . . 135 Windows operating systems . . . . . . . 181
Missing attribute delimiters . . . . . . . 137 Invoking the console command interface on
CONFIRM statement . . . . . . . . . . . 139 UNIX operating systems. . . . . . . . . 181
Description . . . . . . . . . . . . . 139 Specifying metafile and application names in
Syntax . . . . . . . . . . . . . . . 139 commands . . . . . . . . . . . . . 182
Parameters . . . . . . . . . . . . . 139 Multi-interface systems . . . . . . . . . 182
SQL statement . . . . . . . . . . . . . 140 Sending console commands to an alternate IBM
Description . . . . . . . . . . . . . 140 Tivoli Universal Agent instance . . . . . . 182
Syntax . . . . . . . . . . . . . . . 140 DELETE . . . . . . . . . . . . . . . 184
Parameters . . . . . . . . . . . . . 140 Syntax . . . . . . . . . . . . . . . 184
SUMMARY statement . . . . . . . . . . 141 Parameters . . . . . . . . . . . . . 184
Description . . . . . . . . . . . . . 141 Usage . . . . . . . . . . . . . . . 184
Syntax . . . . . . . . . . . . . . . 141 GENERATE . . . . . . . . . . . . . . 185
Parameters . . . . . . . . . . . . . 141 Syntax . . . . . . . . . . . . . . . 185
Example 1 . . . . . . . . . . . . . 142 Parameters . . . . . . . . . . . . . 185
Example 2 . . . . . . . . . . . . . 143 Examples . . . . . . . . . . . . . . 185
Example 3 . . . . . . . . . . . . . 144 Usage . . . . . . . . . . . . . . . 186
Total counts for a summarizing Interval . . . 144 IMPORT . . . . . . . . . . . . . . . 188
Example 4 . . . . . . . . . . . . . 144 Syntax . . . . . . . . . . . . . . . 188
Creating new attributes . . . . . . . . . 145 Parameters . . . . . . . . . . . . . 188
Example 5 . . . . . . . . . . . . . 145 LIST . . . . . . . . . . . . . . . . 189
ATTRIBUTES statement . . . . . . . . . . 146 Syntax . . . . . . . . . . . . . . . 189
Syntax . . . . . . . . . . . . . . . 146 Parameters . . . . . . . . . . . . . 189
Parameters . . . . . . . . . . . . . 146 Output . . . . . . . . . . . . . . 189
Metafile examples . . . . . . . . . . . . 149 LOADCOMM . . . . . . . . . . . . . 190
Metafile example 1 . . . . . . . . . . 149 Syntax . . . . . . . . . . . . . . . 190
Metafile example 2 . . . . . . . . . . 149 Parameters . . . . . . . . . . . . . 190
LOADLIST . . . . . . . . . . . . . . 191
Appendix B. Attribute definitions . . . 151 Syntax . . . . . . . . . . . . . . . 191
Defining attributes . . . . . . . . . . . 151 Parameters . . . . . . . . . . . . . 191
Description . . . . . . . . . . . . . 151 LOADNAME . . . . . . . . . . . . . 192
Syntax . . . . . . . . . . . . . . . 151 Syntax . . . . . . . . . . . . . . . 192
Parameters . . . . . . . . . . . . . 151 Parameters . . . . . . . . . . . . . 192
Exploring attribute characteristics . . . . . . 158 MNL ADD NODE . . . . . . . . . . . . 193
Duplication of attributes . . . . . . . . . 158 Syntax . . . . . . . . . . . . . . . 193
Invisible attributes . . . . . . . . . . . 158 Parameters . . . . . . . . . . . . . 193
Left truncation of display attributes . . . . . 159 MNL REMOVE NODE . . . . . . . . . . 194
Enumeration support . . . . . . . . . . 159 Syntax . . . . . . . . . . . . . . . 194
Deriving attributes . . . . . . . . . . . 160 Parameters . . . . . . . . . . . . . 194
Derived attributes as real numbers . . . . . 160 REFRESH . . . . . . . . . . . . . . 195
Derived attribute string concatenation . . . . 161 Syntax . . . . . . . . . . . . . . . 195

Contents v
 Parameters . . . . . . . . . . . . . 195 Setting the working directory . . . . . . . 210
Usage . . . . . . . . . . . . . . . 195 IBM Tivoli Universal Agent and data provider
SET. . . . . . . . . . . . . . . . . 196 environment variables . . . . . . . . . . 210
Syntax . . . . . . . . . . . . . . . 196
Parameters . . . . . . . . . . . . . 196 Appendix F. Migration . . . . . . . . 221
SHOW . . . . . . . . . . . . . . . 197 Migrating to version 6.1.0 of the IBM Tivoli
Syntax . . . . . . . . . . . . . . . 197 Universal Agent . . . . . . . . . . . . 221
Parameters . . . . . . . . . . . . . 197 Migration process . . . . . . . . . . . 221
Messages . . . . . . . . . . . . . . 197
SHUTDOWN . . . . . . . . . . . . . 198
Appendix G. Starting data providers
Syntax . . . . . . . . . . . . . . . 198
Parameters . . . . . . . . . . . . . 198 as separate processes . . . . . . . 223
TRAPCNFG . . . . . . . . . . . . . . 199 Starting data providers . . . . . . . . . . 223
Syntax . . . . . . . . . . . . . . . 199 Startup programs . . . . . . . . . . . 223
Parameters . . . . . . . . . . . . . 199 Execution environment . . . . . . . . . 223
UNPACK . . . . . . . . . . . . . . . 200 Connecting to the IBM Tivoli Universal Agent 224
Syntax . . . . . . . . . . . . . . . 200 Starting sequence . . . . . . . . . . . 225
Parameters . . . . . . . . . . . . . 200 Stopping data providers . . . . . . . . . . 226
VALIDATE . . . . . . . . . . . . . . 201 The SHUTDOWN command . . . . . . . 226
Syntax . . . . . . . . . . . . . . . 201 Termination delays . . . . . . . . . . 226
Parameters . . . . . . . . . . . . . 201 Managed system offline . . . . . . . . . 226

Appendix D. SNMP trap configuration 203 Appendix H. Accessibility . . . . . . 227

The SNMP trap configuration trapcnfg file . . . 203 Navigating the interface using the keyboard . . . 227
Location of configuration file . . . . . . . 203 Magnifying what is displayed on the screen . . . 227
Using the HP OpenView trapd.conf file . . . 203
Types of records . . . . . . . . . . . 203 Appendix I. Support information . . . 229
Defaults for the trapcnfg file . . . . . . . . 206 Searching knowledge bases . . . . . . . . . 229
Supported categories . . . . . . . . . . 206 Searching the information center . . . . . . 229
Supported statuses . . . . . . . . . . 206 Searching the Internet . . . . . . . . . 229
Supported source IDs . . . . . . . . . 207 Obtaining fixes . . . . . . . . . . . . . 229
Modifying the trapcnfg file . . . . . . . . . 207 Receiving weekly support updates . . . . . . 230
Modifying default definitions . . . . . . . 207 Contacting IBM Software Support . . . . . . 230
TRAPCNFG console command . . . . . . 208 Determining the business impact . . . . . . 231
Describing problems and gathering information 232
Appendix E. Environment variables 209 Submitting problems . . . . . . . . . . 232
Setting environment variables . . . . . . . . 209
Name and location of environment variables file 209 Appendix J. Notices . . . . . . . . 233
Editing environment variables on Windows Trademarks . . . . . . . . . . . . . . 234
operating systems . . . . . . . . . . . 209
Editing environment variables on UNIX Index . . . . . . . . . . . . . . . 237
operating systems . . . . . . . . . . . 210

vi IBM Tivoli Universal Agent: User’s Guide

Figures
1. How the IBM Tivoli Universal Agent works . . . . . . . . . . . . . . . . . . . . . . . 3
2. NTLOG.MDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Create a data definition metafile to define the attributes that you want to monitor. In the metafile, name the
application and attribute data groups to which the attributes belong. Identify the sources of the data, specify
what type of data you are monitoring, and define the help text fro your application, attribute groups, and
attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4. Activating metafiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5. Example of a data provider configuration file . . . . . . . . . . . . . . . . . . . . . . 22
6. Custom SNMP application metafile . . . . . . . . . . . . . . . . . . . . . . . . . 31
7. Relationship between data sources, metafiles, and data providers . . . . . . . . . . . . . . . 33
8. Implementation of API Server Data Provider . . . . . . . . . . . . . . . . . . . . . . 38
9. KUMPOST data definition metafile . . . . . . . . . . . . . . . . . . . . . . . . . 54
10. Specification of write access in mib-2 variable definition . . . . . . . . . . . . . . . . . . 86
11. Socket Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
12. KUMPCON GENERATE example . . . . . . . . . . . . . . . . . . . . . . . . . . 186
13. Examples of configuration record types 2 and 3 . . . . . . . . . . . . . . . . . . . . . 205

© Copyright IBM Corp. 2003, 2005 vii

viii IBM Tivoli Universal Agent: User’s Guide
Tables
1. IBM Tivoli Universal Agent data providers . . . . . . . . . . . . . . . . . . . . . . . 2
2. Preferred data providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3. Default location of metafiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4. Version numbering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5. URL attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6. URL objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
7. MAS attributes for the Post Data Provider . . . . . . . . . . . . . . . . . . . . . . . 54
8. Post Data Provider message categories . . . . . . . . . . . . . . . . . . . . . . . . 55
9. Post Data Provider environment variables . . . . . . . . . . . . . . . . . . . . . . . 56
10. Generated environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . 60
11. Managed system name formats . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
12. MANAGED-NODES workspace columns . . . . . . . . . . . . . . . . . . . . . . . 73
13. MIBNODATA workspace columns . . . . . . . . . . . . . . . . . . . . . . . . . . 73
14. MIBSTATUS workspace columns . . . . . . . . . . . . . . . . . . . . . . . . . . 74
15. NETSUMMARY workspace columns . . . . . . . . . . . . . . . . . . . . . . . . . 74
16. NETWORK workspace columns. . . . . . . . . . . . . . . . . . . . . . . . . . . 75
17. ROUTER workspace columns . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
18. TRAP workspace columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
19. Product-provided situations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
20. DPLOG workspace columns . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
21. Log categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
22. ACTION workspace columns . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
23. Default values for event data . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
24. Descriptions of derived attribute functions . . . . . . . . . . . . . . . . . . . . . . . 161
25. Filter function characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
26. Translation table for ASN.1 to IBM Tivoli Monitoring types . . . . . . . . . . . . . . . . . 167
27. Summary of console commands . . . . . . . . . . . . . . . . . . . . . . . . . . 183
28. Categories supported by the SNMP Data Provider . . . . . . . . . . . . . . . . . . . . 206
29. Severities supported by the SNMP Data Provider . . . . . . . . . . . . . . . . . . . . 206
30. Statuses supported by the SNMP Data Provider . . . . . . . . . . . . . . . . . . . . . 206
31. Source IDs supported by the SNMP Data Provider . . . . . . . . . . . . . . . . . . . . 207
32. Name and location of variables file by operating system . . . . . . . . . . . . . . . . . . 209
33. IBM Tivoli Universal Agent environment variables . . . . . . . . . . . . . . . . . . . . 210
34. Starting data providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

© Copyright IBM Corp. 2003, 2005 ix

x IBM Tivoli Universal Agent: User’s Guide
About this guide
The IBM® Tivoli® Universal Agent User’s Guide introduces you to the IBM Tivoli
Universal Agent, an agent of IBM Tivoli Monitoring. The IBM Tivoli Universal
Agent enables you to use the monitoring and automation capabilities of IBM Tivoli
Monitoring to monitor any type of data you collect.

Who should read this guide

This guide is designed for those responsible for setting up the IBM Tivoli Universal
Agent and its data providers, for preparing and defining the data to send to the
IBM Tivoli Universal Agent, for creating programs or scripts to collect data, or for
monitoring IBM Tivoli Universal Agent data using the Tivoli Enterprise Portal.

This guide is intended to provide the information you need to use the IBM Tivoli
Universal Agent and IBM Tivoli Monitoring to monitor user-defined data. It is
designed to complement the Tivoli Enterprise Portal online help provided with the
IBM Tivoli Universal Agent and Tivoli Enterprise Portal, and the topics covered in
the Tivoli Enterprise Portal Administrator’s Guide.

Publications
This section lists publications in the IBM Tivoli Universal Agent library. It also
describes how to access Tivoli publications online and how to order Tivoli
publications.

IBM Tivoli Monitoring library

The following documents provide information about the IBM Tivoli Monitoring
product:
v Introducing IBM Tivoli Monitoring, GI11-4071
Introduces the components of IBM Tivoli Monitoring and also compares
concepts and function of IBM Tivoli Monitoring to Tivoli Distributed
Monitoring.
v IBM Tivoli Monitoring: Upgrading from Tivoli Distributed Monitoring, GC32-9462
Provides information on how to upgrade from Tivoli Distributed Monitoring.
v IBM Tivoli Monitoring Installation and Setup Guide, GC32-9407
Provides information about installing and setting up IBM Tivoli Monitoring and
upgrading from OMEGAMON V350 or V360.
v IBM Tivoli Monitoring User’s Guide, SC32-9409
Complements the Tivoli Enterprise Portal online help. The guide provides
hands-on lessons and detailed instructions for all Tivoli Enterprise Portal
features.
v IBM Tivoli Monitoring Administrator’s Guide, SC32-9408
Describes the support tasks and functions required for the Tivoli Enterprise
Portal Server and clients, including Tivoli Enterprise Portal user administration.
v Configuring IBM Tivoli Enterprise Monitoring Server on z/OS, SC32-9463
Describes how to configure and customize the Tivoli Enterprise Monitoring
Server running on z/OS.
v IBM Tivoli Monitoring Problem Determination Guide, GC32-9458

© Copyright IBM Corp. 2003, 2005 xi

 Provides information and messages to assist users with troubleshooting
problems with the software.
v Exploring IBM Tivoli Monitoring, SC32-1803
Provides a series of exercises that help users explore IBM Tivoli Monitoring.
After completing the activities in this workbook, you will have installed and
configured your environment, explored both the graphical and command-line
interfaces of the product, used several of the new features in this release of IBM
Tivoli Monitoring (such as creating a monitor based on a custom script), and
worked with several monitoring agents.
v IBM Tivoli Universal Agent User’s Guide, SC32-9459
Introduces you to the IBM Tivoli Universal Agent, an agent of IBM Tivoli
Monitoring. The IBM Tivoli Universal Agent enables you to use the monitoring
and automation capabilities of IBM Tivoli Monitoring to monitor any type of
data you collect.
v IBM Tivoli Universal Agent API and Command Programming Reference Guide,
SC32-9461
Explains the procedures for implementing the IBM Tivoli Universal Agent APIs
and provides descriptions, syntax, and return status codes for the API calls and
command-line interface commands.
v IBM Tivoli Monitoring: IBM Tivoli Monitoring 5.x Endpoint Agent User’s Guide
The IBM Tivoli Monitoring 5.x Endpoint Agent extends the capabilities of IBM
Tivoli Monitoring V5.1.2. It enables data collected by deployed IBM Tivoli
Monitoring V5.1.2 endpoints to be displayed in the Tivoli Enterprise Portal and
stored in Tivoli Data Warehouse.

Accessing terminology online

The Tivoli Software Glossary includes definitions for many of the technical terms
related to Tivoli software. The Tivoli Software Glossary is available at the following
Tivoli software library Web site:

http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm

The IBM Terminology Web site consolidates the terminology from IBM product
libraries in one convenient location. You can access the Terminology Web site at the
following Web address:

http://www.ibm.com/ibm/terminology

Accessing publications online

IBM posts publications for this and all other Tivoli products, as they become
available and whenever they are updated, to the Tivoli software information center
Web site. Some products also include publications on a documentation CD. The
format of the publications is PDF, HTML, or both. Access the Tivoli software
information center by first going to the Tivoli software library at the following Web
address:

http://www.ibm.com/software/tivoli/library/

Click the Tivoli product manuals link. In the Tivoli Technical Product Documents
Alphabetical Listing window, click M to access all of the IBM Tivoli Monitoring
product manuals.

xii IBM Tivoli Universal Agent: User’s Guide

 Note: If you print PDF documents on other than letter-sized paper, set the option
in the File → Print window that allows Adobe Reader to print letter-sized
pages on your local paper.

The IBM Software Support Web site provides the latest information about known
product limitations and workarounds in the form of technotes for your product.
You can view this information at the following Web site:

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

Ordering publications
You can order many Tivoli publications online at the following Web site:

http://www.elink.ibmlink.ibm.com/public/applications/
publications/cgibin/pbi.cgi

You can also order by telephone by calling one of these numbers:

v In the United States: 800-879-2755
v In Canada: 800-426-4968

In other countries, contact your software account representative to order Tivoli

publications.

Accessibility
Accessibility features help users with a physical disability, such as restricted
mobility or limited vision, to use software products successfully. With this product,
you can use assistive technologies to hear and navigate the interface. You can also
use the keyboard instead of the mouse to operate most features of the graphical
user interface.

For additional information, see the Accessibility Appendix in the user’s guide for
this product.

Tivoli technical training

For Tivoli technical training information, refer to the following IBM Tivoli
Education Web site:

http://www.ibm.com/software/tivoli/education/

Support information
Appendix I, “Support information,” on page 229 describes the following options
for obtaining support for IBM products:
v “Searching knowledge bases” on page 229
v “Obtaining fixes” on page 229
v “Contacting IBM Software Support” on page 230

Conventions used in this guide

This guide uses several conventions for special terms and actions.

About this guide xiii

 Typeface conventions
This guide uses the following typeface conventions:
Bold
v Lowercase commands and mixed case commands that are otherwise
difficult to distinguish from surrounding text
v Interface controls (check boxes, push buttons, radio buttons, spin
buttons, fields, folders, icons, list boxes, items inside list boxes,
multicolumn lists, containers, menu choices, menu names, tabs, property
sheets), labels (such as Tip:, and Operating system considerations:)
v Keywords and parameters in text
Italic
v Words defined in text
v Emphasis of words (for example, ″Use the word that to introduce a
restrictive clause.″)
v New terms in text (except in a definition list)
v Variables and values you must provide
Monospace
v Code and other examples
v File names, programming keywords, and other elements that are difficult
to distinguish from surrounding text
v Message text and prompts addressed to the user
v Text that the user must type
v Values for arguments or command options

Tivoli command syntax

The following special characters define Tivoli command syntax:
[] Identifies elements that are optional. Required elements do not have
brackets around them.
... Indicates that you can specify multiple values for the previous element.
Separate multiple values by a space, unless otherwise directed by
command information.
If the ellipsis for an element follows a closing bracket, use the syntax
within the brackets to specify multiple values. For example, to specify two
administrators for the option [–a admin]..., use –a admin1 –a admin2.
If the ellipsis for an element is within the brackets, use the syntax of the
last element to specify multiple values. For example, to specify two hosts
for the option [–h host...], use –h host1 host2.
| Indicates mutually exclusive information. You can use the element on
either the left or right of the vertical bar.
{} Delimits a set of mutually exclusive elements when a command requires
one of them. Brackets ([ ]) are around elements that are optional.

In addition to the special characters, Tivoli command syntax uses the typeface
conventions described in “Typeface conventions.” The following examples illustrate
the typeface conventions used in Tivoli command syntax:
v wcrtpr [–a admin]... [–s region] [–m resource]... name

xiv IBM Tivoli Universal Agent: User’s Guide

 The name argument is the only required element for the wcrtpr command. The
brackets around the options indicate they are optional. The ellipsis after the –a
admin option means that you can specify multiple administrators multiple times.
The ellipsis after the –m resource option means that you can specify multiple
resources multiple times.
v wchkdb [–o outfile] [–u] [–x] {–f infile | –i | object...}
The –f, –i, and object elements are mutually exclusive. Braces that surround
elements indicate that you are including a required element. If you specify the
object argument, you can specify more than one object.

About this guide xv

xvi IBM Tivoli Universal Agent: User’s Guide
Chapter 1. Understanding the IBM Tivoli Universal Agent
This chapter provides a high-level introduction to the IBM Tivoli Universal Agent.
It also presents a simple scenario illustrating the steps required to implement
monitoring with the IBM Tivoli Universal Agent using a File Data Provider.

Introducing the IBM Tivoli Universal Agent

The IBM Tivoli Universal Agent is a generic agent of IBM Tivoli Monitoring. You
can configure the IBM Tivoli Universal Agent to monitor any data you collect. You
can view the data in real-time and historical workspaces on the Tivoli Enterprise
Portal and manage with Tivoli Enterprise Portal monitoring situations and
automation policies, the same as data from other Tivoli Enterprise Monitoring
Agents.

The IBM Tivoli Universal Agent extends the performance and availability
management capabilities of IBM Tivoli Monitoring to applications and operating
systems not otherwise covered by other IBM Tivoli Monitoring agents. It gives you
a single point of management for all your enterprise resources and protects your
investment in applications and resources.

The IBM Tivoli Universal Agent provides the following:

v Integrates data from virtually any operating system and any source. For
example, custom applications, databases, systems, subsystems, and networks
v Monitors only the data attributes that interest you
v Responds quickly to changing monitoring and management scenarios
v Gives you control of attributes and surfacing of data

Understanding how the IBM Tivoli Universal Agent works

The IBM Tivoli Universal Agent gets its data from interfaces called data providers.
Although data providers run as threads inside the IBM Tivoli Universal Agent
process, it is still useful to view them as autonomous entities. Data providers
enable you to supply data to the IBM Tivoli Universal Agent in whatever way is
most convenient or practical for a particular monitoring scenario. For example, you
can supply data through a sequential file, TCP/IP socket program, API calls, shell
script, SNMP traps, or console commands.

You create data definitions that describe the source and structure of the data
supplied by the data providers. You store the data definitions in metafiles. The data
providers relay the monitoring data and the metafile statements to the IBM Tivoli
Universal Agent, which then sends the monitoring data to the Tivoli Enterprise
Monitoring Server. The IBM Tivoli Universal Agent uses the metafile statements to
dynamically generate and upload application definition files, that represent the
definitions you supplied in the metafile, to the Tivoli Enterprise Monitoring Server
and the Tivoli Enterprise Portal. By dynamically generating application definition
files, the IBM Tivoli Universal Agent allows you to create your own monitoring
solutions that function just like regular IBM Tivoli Monitoring agents.

The IBM Tivoli Universal Agent also provides the following:

v Monitors and reports the status of data providers

© Copyright IBM Corp. 2003, 2005 1

 v Accepts and processes requests from data providers
v Accepts Tivoli Enterprise Portal requests for information for workspaces and
event monitoring
v Manages version control of data definitions
v Distributes automation requests to data providers

Table 1 lists the data providers currently available with the IBM Tivoli Universal
Agent. Figure 1 on page 3 illustrates the relationship between data providers, IBM
Tivoli Universal Agents, the Tivoli Enterprise Monitoring Server, and the Tivoli
Enterprise Portal.
Table 1. IBM Tivoli Universal Agent data providers
Type Description
API Server Enables you to collect data from resources on remote
machines where the IBM Tivoli Universal Agent API
client software is supported. See “API Server Data
Provider” on page 37 for additional information.
API, Socket, File, Script (ASFS) Consolidates four types of data providers into one
package, which is started as a single thread to save
resource usage. This is the default data provider
when you install the IBM Tivoli Universal Agent.
File Monitors sequential files, such as system or message
logs. Provides the most direct, simplest method of
collecting data. See “File Data Provider” on page 40
for additional information.
HTTP Allows monitoring of Internet URLs for availability
and response time. You can specify URLs to monitor
in a startup configuration file or within Tivoli
Enterprise Portal situations. See “HTTP Data
Provider” on page 45 for additional information.
ODBC Allows data collection from ODBC-compliant
databases using SQL Select statements and stored
procedures. See “ODBC Data Provider” on page 50
for additional information.
Post TCP/IP socket application with predefined data.
Enables you to send ad hoc notifications such as
messages, alerts, and status. See “Post Data Provider”
on page 54 for additional information.
Script Allows data collection from any script or program
that sends results to standard output. See “Script
Data Provider” on page 59 for additional information.
SNMP Provides the functionality of an SNMP manager,
including network discovery, trap monitoring, and
MIB data collection. See “SNMP Data Provider” on
page 64 for additional information.
Socket Listens on a TCP/IP socket for data sent using
program-to-program communication. Enables you to
collect data from remote devices or machines for
which no IBM Tivoli Universal Agent API support is
available. See “Socket Data Provider” on page 88 for
additional information.

2 IBM Tivoli Universal Agent: User’s Guide

 Data
Source
B

network
Data
Source
A

File Data
Provider Socket Data
Provider

Universal
Agent
API Data
Provider

Data network
Source
C Data
Source
D

Figure 1. How the IBM Tivoli Universal Agent works. In this illustration, Data Source A is a
log file, monitored by a File Data Provider. Data Source B is a program on a remote host that
supplies data through a TCP/IP socket to the Socket Data Provider. Data Source C uses the
IBM Tivoli Universal Agent APIs to send data to the API Server Data Provider, as does Data
Source D on a remote host.

Defining data to the IBM Tivoli Universal Agent

Tell the IBM Tivoli Universal Agent what data you want it to monitor by creating
an IBM Tivoli Universal Agent application. An IBM Tivoli Universal Agent
application consists of one or more attribute groups, each group consisting of one
or more attributes. Define the application in a data definition file, called a metafile,
which is imported by the IBM Tivoli Universal Agent.

Providing data to the IBM Tivoli Universal Agent

You can supply data to the IBM Tivoli Universal Agent in whatever way is most
convenient and suitable for your needs and environment.

Chapter 1. Understanding the IBM Tivoli Universal Agent 3

 For example, if the data you want to monitor is already in a sequential file, and
you decide to use a File Data Provider, you only need to create a metafile that
describes the layout of the sequential file. If you want to use a File Data Provider,
but your data is not already in a sequential file, you can write a script or program
that preprocesses the raw data and writes it as a series of records to a sequential
file that the File Data Provider can then monitor using a metafile.

However, if you decide to use either an API Server or a Socket Data Provider to
monitor your data, you can create a program to issue IBM Tivoli Universal Agent
API calls to forward data directly to the API Server Data Provider, or create a
program that sends the data over a socket to the Socket Data Provider.

Working with the data

After the IBM Tivoli Universal Agent imports the metafile and starts collecting
data, you can do the following:
View real-time and historical data on demand
When the Tivoli Enterprise Monitoring Server imports your data and data
definitions, you can view real-time or historical workspaces for each group
of attributes you define. You can customize the workspaces and export the
workspace data to other applications for manipulation and presentation.
See “Application workspaces” on page 101 for additional information.
Set event alerts
You can use the attributes you define to create Tivoli Enterprise Portal
situations that alert you to actual or potential problems that threaten
availability or performance of your applications and resources. You can
even create complex situations that combine IBM Tivoli Universal Agent
situations with situations you monitor with other Tivoli Enterprise
Monitoring Agents. See “IBM Tivoli Universal Agent situations” on page
105 for additional information.
Program automatic responses to events
You can create policies that respond automatically to critical events by
executing system commands or complex activity programs.
Monitor the status of data providers from the Tivoli Enterprise Portal
The IBM Tivoli Universal Agent provides workspaces that let you monitor
the status and operation of its data providers and the automated actions
they support. See“UAGENT workspaces” on page 103 for additional
information.

You can monitor applications on non-supported environments, such as OpenVMS

or Tandem, provided that the IBM Tivoli Universal Agent is not required to run on
these operating systems. For example, SNMP solutions do not require the IBM
Tivoli Universal Agent to run on the operating system where the SNMP Agent
resides. If an SNMP MIB is not available, then a TCP/IP socket client script or
program could be developed on the operating system to collect and send data
across the network to the Socket Data Provider.

A simple monitoring scenario

This simple scenario illustrates the steps required to implement monitoring with
the IBM Tivoli Universal Agent:
1. Selecting the appropriate data provider
2. Preparing the data source

4 IBM Tivoli Universal Agent: User’s Guide

 3. Defining the IBM Tivoli Universal Agent application
4. Create monitoring situations and policies using IBM Tivoli Universal Agent
application attributes

Selecting the data provider

You want to monitor FTP activity on your Windows® server, NTSRV1. In addition,
you want to prevent users from making uploads to the server that consume large
amounts of disk space.

Because you can configure the Windows FTP Service to create a log file, you
decide that the simplest solution would be to use the File Data Provider.

Preparing the data source

You configure the Windows FTP Service to create a log file, specifying its name
and characteristics. You decide to have the system automatically open a new log
file every month, so the name of the first file is IN0204.LOG.

Or use the file name pattern feature as described in “Dynamic file name support”
on page 42 to change the name of the data source in the SOURCE statement of
your data definition metafile every month as the name of the log file changes.

Defining the IBM Tivoli Universal Agent application

Define an FTP Log monitoring application by creating the metafile NTLOG.MDL
as shown in the following example:
//Appl NTLOG
//NAME FTPLOGFILE E
//SOURCE FILE C:\WINNT\SYSTEM32\LOGFILES\IN204.LOG Tail
//ATTRIBUTES ’,’
ClientAddr D 32
ClientName D 32
Date D 16
Time D 16
Service D 32
ServerName D 32
ServerAddr D 32
ElapsedTime C 100000
BytesReceived C 100000
BytesSent C 100000
SrvStatusCode C 100000
NTStatusCode C 100000
OperationName D 64
ObjectName D 256

Figure 2. NTLOG.MDL

In the metafile, you name the application NTLOG and specify the source of the
attribute data as a file named IN0204.LOG, located in C:\WINNT\SYSTEM32\LOGFILES.
You define one attribute group, named FTPLOGFILE, and specify the monitoring
method as E, for event. You supply the names and characteristics of the 14
attributes you want to monitor. See Chapter 3, “Creating an application,” on page
15 and Appendix A, “Data definition control statements,” on page 115 for
information about creating metafiles.

Place the metafile in the IBM Tivoli Universal Agent metafiles directory on
NTSRV1. Now you are ready to start the IBM Tivoli Universal Agent.

Chapter 1. Understanding the IBM Tivoli Universal Agent 5

 Note: Because the File Data Provider is automatically included in the consolidated
ASFS Data Provider, which is the installation default, you do not need to
reconfigure the data providers that are activated during the IBM Tivoli
Universal Agent startup.

When the IBM Tivoli Universal Agent is running, you can import the
NTLOG.MDL metafile. Importing a metafile is the process of activating a metafile
application inside a running IBM Tivoli Universal Agent. To accomplish this task,
you can either use the IBM Tivoli Universal Agent provided Import console
command or the Tivoli Enterprise Portal Take Action, Control Import window. See
“Activating metafiles” on page 19 for information about loading metafiles. See the
IBM Tivoli Monitoring Installation and Setup Guide for instructions for starting
and stopping a Tivoli Enterprise Monitoring Agent.

Viewing attribute data from FTPLOGFILE

When your metafile is imported and collecting new file records that are appended
at the bottom of the IN0204.LOG, you can start viewing the data in the Tivoli
Enterprise Portal navigator.

The Navigator provides a physical view of your monitored network, organized by

operating system, system type, monitoring agents, and the attribute groups from
which the agents can collect information.

One of the managed systems that is displayed in the navigator has the name
NTSRV1:NTLOG00, reflecting the application you defined in the APPL statement in
the metafile. You also see a physical mapping of the system within the Tivoli
Enterprise Portal navigator with the name NTLOG00. See “IBM Tivoli Universal
Agent managed systems” on page 99 and Chapter 5, “Monitoring applications,” on
page 99 for information on the naming of managed systems, Customer
workspaces, and attributes. When you open this item representing the application,
you see a workspace entry named FTPLOGFILE, representing the attribute group.
Click the item to access the workspace. The columns of the workspace correspond
to the attributes you defined in the metafile. See “Application workspaces” on
page 101 for information on viewing workspaces.

Creating an automation policy

Now that you have defined the NT log attributes in your IBM Tivoli Universal
Agent metafile application, you can use those attributes to create a monitoring
situation that trips when a file being uploaded is 10 MB or more.

Using the Tivoli Enterprise Portal Situation editor, you use the attribute
BytesReceived to create the following situation, which you distribute to NTSRV1:
NTLFTPLOGFILE00.BytesReceived *GE 10,000,000

Now, whenever a user tries to upload a file of 10MB or more, this situation fires.

Next you create a policy named FTPLimit, which waits for the situation to fire and
then
1. Sends a message to the user uploading the file (ClientName) that the file
exceeds FTP limits and that the Service is being terminated.
2. Performs the action ″Net stop ″FTP Publishing Service″ to stop the FTP Service.
3. Notifies the operator on the Tivoli Enterprise Portal that the FTP Publishing
Service has been stopped.
4. Restarts the Service if the operator does not take action within 5 minutes.

6 IBM Tivoli Universal Agent: User’s Guide

See the Tivoli Enterprise Portal Administrator’s Guide and the Tivoli Enterprise Portal
online help for instructions on creating situations and policies.

Chapter 1. Understanding the IBM Tivoli Universal Agent 7

8 IBM Tivoli Universal Agent: User’s Guide
Chapter 2. Getting started
This chapter describes how to set up the IBM Tivoli Universal Agent. It addresses
questions about which type of data provider to use and how many IBM Tivoli
Universal Agents to install. It also discusses setting environment variables to suit
your monitoring scenarios and provides instructions for starting and stopping the
IBM Tivoli Universal Agent and its data providers. Subsequent chapters address
defining your data to the IBM Tivoli Universal Agent by creating IBM Tivoli
Universal Agent applications and monitoring your data on the Tivoli Enterprise
Portal.

Introduction
Implementing the IBM Tivoli Universal Agent involves the following three
procedures:
v Setting up and configuring the IBM Tivoli Universal Agent
v Defining IBM Tivoli Universal Agent applications
v Monitoring data on the Tivoli Enterprise Portal

Setting up the IBM Tivoli Universal Agent

Setting up the IBM Tivoli Universal Agent involves the following steps:
v Selecting the types of data providers you want to use
v Deciding how many IBM Tivoli Universal Agents you want to install
v Setting environment variables

Selecting a data provider

The decision about which type of data provider to use to monitor your data rests
primarily upon the following considerations:
v Type of data you want to monitor
v Location of the data you want to monitor

Selecting the data you want to monitor

If your data is available in a sequential file on an operating system supported by
the IBM Tivoli Universal Agent, the File Data Provider offers the simplest, most
direct means of monitoring your data.

Even if your data is not already in a sequential file, you can create an extraction
program to export the data from the native source to a sequential file, or to modify
your application to redirect data to a sequential file, and still use a File Data
Provider solution.

If your data cannot be easily exported to a sequential file, or the data source is on
an operating system that the IBM Tivoli Universal Agent does not support, you
can use the Socket Data Provider or API Data Provider. If you are monitoring
SNMP traps or the status of SNMP-enabled resources, you can use the SNMP Data
Provider.

© Copyright IBM Corp. 2003, 2005 9

 Understanding the location of your data
The possibility of using the File Data Provider or the choice between the API
Server or Socket Data Provider can depend upon the operating system where your
data source resides.

The File Data Provider must reside on the same operating system as the file it
monitors, or be capable of logically mapping to the file across the network as if the
file were local. Even when data resides in a sequential file, you cannot use a File
Data Provider to monitor it if it is located on an operating system that the IBM
Tivoli Universal Agent does not support.

To use the IBM Tivoli Universal Agent APIs, you need to install the IBM Tivoli
Universal Agent API dynamic link library for the operating system you plan to
develop on. This run-time library, which is part of what is called the API client
package, is not available on all operating systems. Your operating system must
have a TCP/IP stack with a socket interface if you want to use the Socket Data
Provider.

Determining the data provider

Since the IBM Tivoli Universal Agent APIs encapsulate many of the details of
dealing with TCP/IP sockets, it is easier to use the API Server Data Provider than
the Socket Data Provider. If you have a choice between the Socket and the API
Server Data Provider, choose the API Server Data Provider. But if your data resides
on a operating system not supported by the API client package, such as z/OS®,
then the Socket Data Provider is the right choice. The following table provides
information for selecting your data provider:
Table 2. Preferred data providers
Data source Preferred data provider
Log files File
Ad hoc notifications such as messages, Post
alerts, and status information
Application internals (supported API client API Server
operating system)
Application internals (nonsupported API Socket
client operating system) using TCP/IP
Any combination of the following: API, Socket, File, Script (ASFS)
v Log files
v Application internals (supported API
client operating system)
v Application internals (nonsupported API
client operating system)
v Stdout messages produced by a script or
program
Internet or Intranet URLs HTTP
Relational Databases ODBC
SNMP MIB data SNMP
Stdout messages produced by a script or Script
program

10 IBM Tivoli Universal Agent: User’s Guide

Determining the required number of IBM Tivoli Universal Agents
You can run more than one IBM Tivoli Universal Agent. The source of your data,
the type of data provider you are going to use to monitor it, and site-specific
considerations such as network traffic and departmental control help you
determine the appropriate number of IBM Tivoli Universal Agents to run.

A File Data Provider must start on a system where your files are available locally.
Therefore, if you want to monitor application log files on 20 different machines,
you need to install 20 IBM Tivoli Universal Agents. You need to install one on each
host unless the remote files are available through networking software such as NFS
or Samba.

The Script Data Provider must execute on a system where the script is running
because the stdout messages produced by the script are piped on the local system
to the Script Data Provider.

The Post, Socket, API Server, HTTP, ODBC, and SNMP Data Providers are
distributed data providers. That is, they do not have to start in the same location
as their data sources. So if you plan to monitor data that is not accessible from a
file, you can start just one IBM Tivoli Universal Agent, which can receive data sent
from any system in your enterprise. You can use more than one IBM Tivoli
Universal Agent to limit network traffic or allow different IBM Tivoli Universal
Agents to monitor data about resources managed by different departments.

Determining how many IBM Tivoli Universal Agents I can run

on the same host
You can run more than one IBM Tivoli Universal Agent on a given host. However,
this is usually not necessary because one IBM Tivoli Universal Agent can monitor
data from multiple sources. For example, with the ASFS Data Provider a single
IBM Tivoli Universal Agent can monitor multiple files, multiple API clients,
multiple scripts, and multiple socket clients.

For additional information, see “Running multiple instances of a data provider” on

page 33

Determining how many data providers I can start with one IBM
Tivoli Universal Agent
When you start the IBM Tivoli Universal Agent, by default it starts the ASFS Data
Provider. You can override the default startup configuration by specifying any or
all of the data providers as arguments of the startup command. For startup
command and arguments, consult the installation guide for your operating system.
You can also change the default startup using the environment variable
KUMA_STARTUP_DP.

KUMA_STARTUP_DP uses the same arguments as the startup command,

separated by commas. For example:
KUMA_STARTUP_DP=POST,SNMP

would only start the Post and SNMP Data Providers.

Chapter 2. Getting started 11

Starting the IBM Tivoli Universal Agent and its data providers
On UNIX® and Windows operating systems, you start the IBM Tivoli Universal
Agent using Manage Tivoli Enterprise Monitoring Services. UNIX operating
systems also offer a command-line interface for configuring, starting, and stopping
the IBM Tivoli Universal Agent.

By default, when you start the IBM Tivoli Universal Agent, the consolidated
(ASFS) Data Provider is activated. Specify different or additional data providers to
activate when you start the IBM Tivoli Universal Agent by changing the
environment variable, KUMA_STARTUP_DP.

Specifying data providers

Specify which of the following data providers you want to start when you start the
IBM Tivoli Universal Agent by setting KUMA_STARTUP_DP to specify one or
more of the following arguments.
ASFS Starts the consolidated data provider
APIS Starts the API Server Data Provider
FILE Starts the File Data Provider
HTTP Starts the HTTP Data Provider
ODBC
Starts the ODBC Data Provider
POST Starts the Post Data Provider
SCRP Starts the Script Data Provider
SNMP
Starts the SNMP Data Provider
SOCK Starts the Socket Data Provider

For example, if you specify the following, the consolidated API, Socket, File, and
Script Data Providers and SNMP Data Provider are activated when you start the
IBM Tivoli Universal Agent.
KUMA_STARTUP_DP=ASFS,SNMP

Specifying startup parameters on Windows operating systems

To manually override the data providers listed in KUMA_STARTUP_DP, perform
the following steps to specify startup parameters on Windows operating systems:
1. From the Start button, select Programs → Tivoli OMEGAMON® XE → Manage
Tivoli Enterprise Monitoring Services.
2. In the Manage Tivoli Enterprise Monitoring Services window, right-click the
IBM Tivoli Universal Agent, then select Change Startup Parms from the
pop-up menu.
3. Type the parameters in the entry field, separated by commas, then click OK.

The startup parameters you specify using this window are not persistent; they do
not remain in effect when the agent is restarted.

Specifying startup parameters on UNIX operating systems

If you want to start one or more data providers manually, instead of through
KUMA_STARTUP_DP environment variable, you must start the IBM Tivoli

12 IBM Tivoli Universal Agent: User’s Guide

Universal Agent from a command line and specify the data providers you want to
start as parameters in the itmcmd agent command string. For example:
itmcmd agent -o SNMP,FILE start um

If you are manually starting the HTTP Data Provider on a previously configured
alternate instance of the IBM Tivoli Universal Agent named Test, enter the
following command string:
itmcmd agent -o HTTP -p Test start um

Chapter 2. Getting started 13

14 IBM Tivoli Universal Agent: User’s Guide
Chapter 3. Creating an application
This chapter describes how to create an IBM Tivoli Universal Agent application
which defines the data that you want to manage. It covers how to do the
following:
v Construct a data definition metafile
v Validate your metafile
v Import the metafile to the IBM Tivoli Universal Agent
v Create a metafile server

This chapter also explains how version numbers are assigned to metafiles and how
the version numbers of metafiles affect the naming of managed systems,
workspaces, and attributes on the Tivoli Enterprise Portal.

Introduction to the IBM Tivoli Universal Agent application

An IBM Tivoli Universal Agent application defines the data you want to manage to
IBM Tivoli Monitoring. Each IBM Tivoli Universal Agent application consists of a
data definition specification, or metafile, for one or more groups of data attributes.

From the standpoint of IBM Tivoli Monitoring, an application is anything you

define it to be in your metafile. For example, you can create a metafile with an
application name of HOSTRESOURCES. This metafile can have three attribute
groups, representing network, system, and applications resources.

Note: You do not need to create applications if you are using the SNMP Data
Provider. IBM Tivoli Monitoring creates them for you from standard MIBs or
from any MIB that you supply.

Creating an IBM Tivoli Universal Agent application

You create an application by constructing a metafile that specifies the following
information:
v Name of the application
v Name of each of the attribute groups that comprise the application
v Source or sources of the data in each attribute group
v Names and characteristics of the individual attributes

The key to creating useful IBM Tivoli Universal Agent applications is placing
related attributes into groups and placing related groups of attributes into
individual IBM Tivoli Universal Agent applications.

Constructing a data definition metafile

A metafile is a plain text file. It contains the following control statements in the
order shown (if present):
SNMP
For SNMP Data Providers only, introduces the data definition for IBM
Tivoli Monitoring provided SNMP MIB applications. SNMP TEXT
introduces the data definition for user-defined SNMP applications.

© Copyright IBM Corp. 2003, 2005 15

 APPL Specifies the name that IBM Tivoli Monitoring uses for the application.
NAME
Defines the name of an attribute group, the type of data being collected,
and the period for which the data is valid.
INTERNAL
Provides for data redirection between attribute groups as a way to perform
additional processing.
SOURCE
Defines the location of the data you are collecting.
RECORDSET
For File Data Providers only, defines the set of records from which the data
provider extracts data.
CONFIRM
For Socket Data Providers only, specifies the requirements for data
acknowledgment.
SQL For ODBC Data Providers only, defines the Select statement or stored
procedure to use for collecting relational data.
SUMMARY
Defines the requirements for gathering the frequency of data input during
monitoring.
ATTRIBUTES
Introduces the attribute definitions and specifies the attribute delimiters in
the data string. Below the ATTRIBUTES control statement, list the
individual attribute definition statements.

You can use any text editor to create a metafile. Appendix A, “Data definition
control statements,” on page 115 contains the definitions and syntax of the metafile
statements. If a metafile contains any non-English text, you must save the metafile
as UTF-8. Other file encodings, such as UTF-16 or UTF-32, are not supported.
Examples of non-English text in a metafile are help text, delimiter characters, and
captions.

16 IBM Tivoli Universal Agent: User’s Guide

 //APPL

//NAME

//SOURCE

TCPIOQ.MDL
Figure 3. Create a data definition metafile to define the attributes that you want to monitor. In
the metafile, name the application and attribute data groups to which the attributes belong.
Identify the sources of the data, specify what type of data you are monitoring, and define the
help text fro your application, attribute groups, and attributes.

The following example illustrates a small metafile named TCPIOQ.MDL, which

defines a socket application named UXnet:
//APPL UXnet @sample application for socket DP
//NAME TCPioQ E @attribute group for sample DP application
//SOURCE SOCK UNIX1
//SOURCE SOCK UNIX2
//ATTRIBUTES
LocalApplAddress D 24 @address of local application
TargetApplAddress D 24 @address of target application
SendQueueSize C 999999 @TCP/IP send queue size
RecvQueueSize C 999999 @TCP/IP receive queue size

Naming metafiles
By convention, IBM Tivoli Universal Agent metafiles end with an .mdl extension,
but there are no restrictions on the names of metafiles. You can use any name
supported by the operating system on which the file resides. It is good practice to
give the file the same name as the application.

Creating help for applications, attribute groups, and attributes

In your metafile you can define help for the application, each of its attribute
groups, and each attribute in a group. The help you define for each attribute group
displays in the Situation editor when you select an Attribute group. The help you
define for each attribute displays as you mouseover the table column headings that
represent each attribute.

Chapter 3. Creating an application 17

 For the SNMP Data Provider, help is created automatically from the descriptions of
attributes in the MIB. See the previous example for help definitions in a metafile
and Appendix A, “Data definition control statements,” on page 115 for information
about the @helptext parameter.

Storing metafiles
By default, the IBM Tivoli Universal Agent looks for metafiles in the directory
indicated in Table 3.
Table 3. Default location of metafiles
Operating system Location
Windows IBM\ITM\TMAITM6\metafiles
UNIX <install_dir>/$ARCH/um/metafiles

You can change the location using the variable KUMP_META_PATH. For example,
if you want to store all of your metafiles in a special directory that is outside the
IBM Tivoli Monitoring installation directory structure, use the KUMP_META_PATH
environment variable to redirect the metafile search from the default directory to
an alternate location.

Note: The local KUMP_META_PATH specification does not override the

KUMP_META_PATH specification for the metafile server. See “Creating a
metafile server” on page 22 for information on the optional metafile server
facility.

If you are using an IBM Tivoli Universal Agent console command against a
metafile and the metafile is not in the default metafiles directory, you can specify
the fully qualified metafile name. For example, if you use the console command
VALIDATE to syntax check a metafile, you can enter the following on the
command line:
kumpcon validate c:\ua\test\my_metafile.mdl

If you have many metafiles, you can create subdirectories in the directory
designated by KUMP_META_PATH. When you use a console command that refers
to a metafile in one of the subdirectories, you can use a relative path when you
specify the metafile name. For example:
kumpcon validate .\subdirectory_name\mymetafile.mdl

Backing up metafiles
Always regularly back up your metafiles since they represent an important part of
your enterprise management system. Although many metafiles are simple, some
are as complex as small programs if you utilize the various metafile language
features. In these cases, it is not easy to recreate a metafile if it is deleted by
mistake. Treat metafiles as an important corporate asset, back them up, and protect
them from alteration or loss as you would any other source code in your
enterprise.

Validating data definitions

IBM Tivoli Monitoring supports a console command VALIDATE, which invokes
the same data validation subroutine that the IBM Tivoli Universal Agent uses at
runtime. It is useful to run the validation program against a newly developed or
modified metafile so that you can quickly identify and correct syntactical and
specification errors before you activate it.

18 IBM Tivoli Universal Agent: User’s Guide

 VALIDATE reads the metafile and produces detailed validation messages. It also
creates a data specification report showing the exact application definition in effect.
The report has the same file name as the metafile, with the extension rpt. For
example, if you run the program on the metafile tcpioq.mdl,a file named
tcpioq.rpt is created.

Running the validation program

To run the metafile validation program, from any console interface enter:
kumpcon validate metafile_name

Note: For UNIX operating systems, you cannot run the kumpcon program directly.
Instead, use the um_console shell script, which allows you to run the
metafile validation program. See “Invoking the console command interface
on UNIX operating systems” on page 181 for more information on the
um_console script.

Sample validation output

The following example shows the validation output for an application named
UXnet, defined in the metafile named TCPIOQ.MDL:
Application Name: UXnet; Definition Metafile Name:
C:\IBM\OMEGAMON\TMAITM6\METAFILES\TCPIOQ.MDL
Attribute Group: TCPioQ
Type: Event data Total number of SOURCEs: 2
SOURCE is SOCKET UNIX1
Total Attributes: 4
Attribute delimiter is Space Character
LocalApplAddress Display Type Size 24 Delimiter is Space Character
TargetApplAddress Display Type Size 24 Delimiter is Space Character
SendQueueSize Counter Type Size 4 Delimiter is Space Character
RecvQueueSize Counter Type Size 2 Delimiter is Space Character
SOURCE is SOCKET UNIX2
Total Attributes: 4
Attribute delimiter is Space Character
LocalApplAddress Display Type Size 24 Delimiter is Space Character
TargetApplAddress Display Type Size 24 Delimiter is Space Character
SendQueueSize Counter Type Size 4 Delimiter is Space Character
RecvQueueSize Counter Type Size 4 Delimiter is Space Character
Total Attribute Groups: 1

Activating metafiles
To manage application data correctly, the IBM Tivoli Universal Agent must activate
the appropriate metafiles. You can activate metafiles in any of the following three
ways:
v Dynamically through a console command
v Dynamically through a Take Action command in the Tivoli Enterprise Portal
v Through a configuration file update and an IBM Tivoli Universal Agent restart

When deciding which method to use to activate a metafile, attempt to strike a

balance between flexibility, ease of use, maintainability, and the reduction of errors
caused by implicit actions and defaults.

Activating metafiles with console commands

You can activate metafiles dynamically using the IMPORT and REFRESH
commands. See Appendix C, “Console commands,” on page 181 for information on
the IBM Tivoli Universal Agent command-line interface. You would use this

Chapter 3. Creating an application 19

 method if you have created a new metafile and want to import it, or you have
modified an active metafile and you want to refresh it, without having to restart
the IBM Tivoli Universal Agent.

At startup, the IBM Tivoli Universal Agent checks to see if any metafiles are
specified in the KUMPCNFG configuration file. If so, the IBM Tivoli Universal
Agent loads the appropriate metafiles from the path names specified in
KUMPCNFG, or if fully qualified names were not specified, from the metafiles
directory. You can also use the IMPORT and REFRESH console commands to
import new and revised metafiles at any time.

Universal
Agent

KUMPCNFG Candlehome/... IMPORT Command

//APPL
//NAME
//SOURCE
//ATTRIBUTES

TCPIOQ.MDL

Figure 4. Activating metafiles

Activating metafiles with Take Action commands

You can activate metafiles dynamically using the Take Action Control Import and
Control Refresh commands. Use the Take Action method if you do not want to
restart the IBM Tivoli Universal Agent after creating a new metafile and want to
import it, or if after modifying an active metafile you want to refresh the metafile.
You must have the Tivoli Enterprise Portal client session active if you plan to use
this method.

Perform the following steps to select the IBM Tivoli Universal Agent Take Action
commands from the Tivoli Enterprise Portal:
1. From any location in the Tivoli Enterprise Portal navigator tree under
Universal Data Provider, select a leaf in the navigator tree.
2. Right-click on the leaf and select Take Action... → Select.... The Take Action
window is displayed.

20 IBM Tivoli Universal Agent: User’s Guide

 3. From the Take Action window, select an action from the Name: drop-down list.
The Edit Argument Values window is displayed.

As an example, if you are going to import the TCPIOQ.MDL file, choose

Control Import from the Name: drop-down list. From the Edit Argument
Values window, enter TCPIOQ.MDL for the Value.
4. Type the name of the metafile that you want to activate in the Value field of
the Edit Argument Values window.
5. Click OK.
6. From the Destination Systems section of the Take Action window, select a
destination system for the action.

Note: Always distribute the Take Action command to the destination system
whose data provider type matches the data provider type of the metafile
that you import.
7. Click OK. The Action Status window is displayed and indicates whether the
action was successful.

Activating metafiles with a configuration file

KUMPCNFG is a plain text file which contains the names of the metafiles that an
IBM Tivoli Universal Agent should load at start-up time. You would use this
method when you want the IBM Tivoli Universal Agent to automatically load
specific metafiles at start-up time.

Guidelines for updating configuration files

Observe the following guidelines when updating a configuration file to include a
new metafile:
v The name of the configuration file must be KUMPCNFG. On systems where files
are case-sensitive, you must specify the name in all uppercase characters.

Chapter 3. Creating an application 21

 v If you are running an alternate instance of the IBM Tivoli Universal Agent, the
name of the configuration file is KUMPCNFG_&instanceName. For example,
KUMPCNFG_TEST.
v You can enter one or more metafile names in a single configuration file record,
separated by a space or you can specify one metafile per file record. Specifying
one metafile per file record simplifies updating of the configuration file.
v Except when strictly necessary, use only unqualified metafile names in the
configuration file.
v Any configuration file record that starts with an asterisk (*) is treated as a
comment and ignored. In Figure 5 for example, only the metafiles mymeta,
appl1.mdl, appl2, and CustInq.txt are loaded by the IBM Tivoli Universal Agent.
v If you directly edit KUMPCNFG, your changes do not take effect until the next
IBM Tivoli Universal Agent restart.

Location of the configuration file

The IBM Tivoli Universal Agent uses the value specified for the
KUMP_INIT_CONFIG_PATH environment variable as the location of its configuration
file. If no value is specified for KUMP_INIT_CONFIG_PATH, the IBM Tivoli Universal
Agent uses its default working directory or the directory specified by
KUM_WORK_PATH. See “Setting the working directory” on page 210 for more
details on the default working directory and the KUM_WORK_PATH variable.

Note: The path specification is case-sensitive for some operating systems.

mymeta appl1.mdl appl2

CustInq.txt
*Payroll

Figure 5. Example of a data provider configuration file

Sharing configuration files

Multiple IBM Tivoli Universal Agent and data provider threads can share a
KUMPCNFG file. The same KUMPCNFG file can contain Socket Data Provider
metafiles, File Data Provider metafiles, SNMP Data Provider metafiles, ODBC Data
Provider metafiles and Script Data Provider metafiles.

Every data provider loads all the metafiles specified in KUMPCNFG, but each data
provider only begins monitoring metafiles belonging to its defined data type and
ignores the others. For example, a File Data Provider does not start to monitor
in-bound socket connections, and an API Server Data Provider does not spawn
threads for monitoring log files. Similarly, the SNMP Data Provider only loads
SNMP MIB metafiles, and non-SNMP Data Providers only load non-SNMP
metafiles. Consequently, aside from the extra storage allocated to each data
provider for the internal data definition control blocks, there is no danger of
management conflicts among data providers. If you start the API, Socket, File, and
Script (ASFS) Data Providers, all applicable monitoring for each data provider type
starts at the same time.

Creating a metafile server

In an enterprise, the same metafile applications can be supported by several IBM
Tivoli Universal Agents at various locations. To ensure consistent definitions
through the enterprise and to reduce the complexity of managing and maintaining
multiple IBM Tivoli Universal Agents, store metafiles in a single location. It is also
a good practice to regularly back up your metafiles since they represent an
important part of your enterprise management system.

22 IBM Tivoli Universal Agent: User’s Guide

 The centralized metafile server facility enables you to designate one or more IBM
Tivoli Universal Agents as a metafile server. Client IBM Tivoli Universal Agents
can retrieve the metafiles they require from the designated server at run time
rather than maintaining local copies.

For example, the Engineering department might designate an IBM Tivoli Universal
Agent running on system ENG1 as the metafile server. The Finance department
selects system FIN4 as the metafile server. All the IBM Tivoli Universal Agents in
the Engineering department download required metafiles from the IBM Tivoli
Universal Agent on ENG1, while all the IBM Tivoli Universal Agents in the
Finance department retrieve necessary metafiles from the IBM Tivoli Universal
Agent on FIN4. You can set up other IBM Tivoli Universal Agents to use the
metafile server running on MIS9.

Designating a metafile server

You use the environment variable KUMP_META_SERVER to specify the name of the
host of the IBM Tivoli Universal Agent that you want to use as the server:
KUMP_META_SERVER=hostname

The presence of the environment variable indicates to the IBM Tivoli Universal
Agent that it should use a centralized metafile server. If this environment variable
is not set, the IBM Tivoli Universal Agent operates in standalone mode and looks
for its required metafiles locally. If the host name specified by kump_meta_server
cannot be resolved to a TCP/IP address, the metafile server feature is disabled and
the data provider loads metafiles from the local metafile location.

Storing server metafiles

You must store the metafiles for the server in the IBM Tivoli Universal Agent
default working directory or in the location identified by the KUMP_META_PATH or
KUM_WORK_PATH environment variables. See “Activating metafiles” on page 19 for
information on KUMP_META_PATH and “Setting the working directory” on page 210
for information on KUM_WORK_PATH.

Determining server and client roles on the same host

When an IBM Tivoli Universal Agent starts up and discovers that
KUMP_META_SERVER is set to the name of its own host, it makes the following
determination:
v If it is the first IBM Tivoli Universal Agent initialized on this system, it
immediately takes the role of metafile server.
v If it is not the first IBM Tivoli Universal Agent initialized on this system, it
assumes that the metafile server has already started and it takes the role of
metafile client, as would any IBM Tivoli Universal Agent started elsewhere in
the enterprise.

Synchronization of metafile server and client

If an IBM Tivoli Universal Agent determines at startup that KUMP_META_SERVER is
not set to the name of its own host, it assumes the role of client and immediately
attempts to establish a connection to the designated metafile server.

If the connection is successful, the IBM Tivoli Universal Agent sets up the
necessary internal management structure and continues startup processing. If the
connection is unsuccessful, either because of network problems or because the IBM

Chapter 3. Creating an application 23

 Tivoli Universal Agent metafile server has not started, it schedules periodic
connection retries and completes initialization.

Communication between metafile client and server can be disrupted during normal
operation for a variety of system or network reasons. If communication is
disrupted, the client automatically falls back to standalone mode and schedules
periodic retries until the connection to the server is re-established. Log messages
are issued that clearly identify the status of the metafile service. You can monitor
the messages in the DPLOG workspaces. See “UAGENT workspaces” on page 103
for additional information.

Overriding the central metafile definition

If you need to override a data definition metafile while you are testing an
application upgrade or editing the specifications, make the new application
metafile available locally to the IBM Tivoli Universal Agent. The IBM Tivoli
Universal Agent always checks for the existence of a local copy of the required
metafile before attempting to download it from the metafile server.

Versioning of metafiles
Versioning of metafiles makes it possible for you to identify the level of your
metafile. It also allows you to run different versions of a metafile on different
machines. For example, you might want to install a new version of an operating
system on your test system and monitor data that the older version of the
operating system does not provide. You can modify your metafile to monitor the
new system statistics and run the new version on the test system while still using
the older version on your other machines.

Incrementing version and modification numbers

Metafiles are assigned both version and modification numbers. When you first
import a metafile into the IBM Tivoli Universal Agent, it is assigned a version
number of 0 and a modification number of 0. Subsequently, each time you change
the metafile and refresh it on the IBM Tivoli Universal Agent, either the version
number (major changes) or the modification number (minor changes) is
incremented by one, depending upon the type of change you make.

Reversioning of managed systems, workspaces, and attribute

groups
The IBM Tivoli Universal Agent appends the version number of the metafile to the
name of managed systems, managed system lists, and attribute groups. When the
version number of a metafile changes, the managed systems, managed system lists,
and attribute groups based on the previous version number go offline and new
ones with the new version number come online. See Table 4 on page 25 and
Chapter 5, “Monitoring applications,” on page 99 for additional information. The
managed system name change means that a new Tivoli Enterprise Portal Navigator
tree entry is inserted for the new metafile application version, and report
workspaces are positioned below the entry.

Version numbers changes are considered major because you cannot simply restart
situations distributed to a previous version of a managed system. You must create
new situations or modify the old ones to use the new attribute group names, then
distribute the situations to the new versions of the managed systems or the
managed system list. You also need to update any existing policies to reference the
new version number.

24 IBM Tivoli Universal Agent: User’s Guide

 Modifications are considered to be minor changes because if you attempt to make
changes that affect only the modification number, you do not need to make
changes to your existing situations, managed objects, and automation policies.
Table 4. Version numbering
Name Version 00 Version 01
managed system ENG1:UL300 ENG1:UL301
managed system list *CUSTOM_UL300 *CUSTOM_UL301
attribute group SYSLOG00 SYSLOG01

Changes that do not affect modification or version number

You can make the following changes without changing the modification or version
number of the metafile:
v TTL value
v A change to the SOURCE statement
v Data type from P, S, or K to any of P, S, or K
v Delimiter specified in the ATTRIBUTE statement
v A change to the RECORDSET statement
v A change to the CONFIRM statement
v A change to an attribute FILTER parameters
v A change to the SQL statement

Changes that affect modification number (minor changes)

The following changes cause the modification number to be incremented:
v Adding a new attribute to the end of the attribute list for an attribute group
v Adding a new attribute group at the end of the metafile
v Adding, removing, or changing help text
v Atomizing an existing attribute
v Adding, removing, or changing Scale or Precision values
v Adding, removing, or changing Caption values
v Adding, removing, or changing Warehouse or Aggregation parameters
v Adding, removing, or changing HistoricalTimestamp or PrimaryKey options

Changes that affect version number (major changes)

The following changes cause the version number to be incremented:
v Renaming or deleting an existing attribute
v Changing the type of an attribute
v Changing the length of an attribute
v Changing the name of an attribute group
v Adding a new attribute anywhere other than the end of a list of existing
attributes
v Changing the order of attributes
v Changing a data type from E to P, S, or K
v Changing a data type from P, S, or K to E
v Adding a new attribute group anywhere other than the end of a metafile

Chapter 3. Creating an application 25

 Resetting version numbers
The following cleanup scripts are provided to allow you to reset the version
number of your metafiles back to the original 00 versions:
v For Windows operating systems, um_cleanup.bat
v For UNIX operating systems, um_cleanup

These scripts do not affect the actual metafiles. The next time the metafiles are
imported or activated, their applications come back online, but all versions will be
0.

Before you run either of these scripts, you must shut down the IBM Tivoli
Universal Agent and manually delete the existing IBM Tivoli Universal Agent
managed systems from the Tivoli Enterprise Portal Managed System Status
workspace.

After you run the cleanup script, you must recycle the Tivoli Enterprise Monitoring
Server and the Tivoli Enterprise Monitoring Server and then restart the IBM Tivoli
Universal Agent to activate the new 00 version suffixes.

Manually deleting managed systems

Perform the following steps to delete the existing managed systems:
1. Stop the IBM Tivoli Universal Agent so all its managed systems go offline.
2. From the Tivoli Enterprise Portal client Physical Navigator view, right-click on
Enterprise and select Workspace → Managed System Status. The Managed
System Status workspace is displayed.
3. Highlight all the IBM Tivoli Universal Agent managed systems.
4. Right-click and select Remove managed system. The Apply pending updates
icon is highlighted in the Tivoli Enterprise Portal client.
5. Select the Apply pending updates icon to collapse the Navigator tree. When
you re-expand the Navigator tree, yourIBM Tivoli Universal Agent managed
systems no longer appear in the tree.
6. Restart the IBM Tivoli Universal Agent. Your applications appear in the
Navigator tree with the 00 version suffixes.

Running the cleanup program

You run the cleanup script up to three times, depending on whether your Tivoli
Enterprise Monitoring Server and Tivoli Enterprise Portal Server are installed on
the same system as your IBM Tivoli Universal Agent.

Note: The Tivoli Enterprise Portal Server uses the CNPS directory name and the
Tivoli Enterprise Monitoring Server uses the CMS directory name.

To run the cleanup script, enter the following in a command window on the
appropriate system:
um_cleanup home_directory component [work_directory]

where:
home_directory The base directory where your IBM Tivoli
components are installed. For example, IBM\ITM
component One of three values:

26 IBM Tivoli Universal Agent: User’s Guide

 UA
CMS
CNPS

Note: Capitalize each of these values. For example,

use UA and do not use Ua or ua.
work_directory Only required if the work directory is not the
default IBM\ITM\TMAITM6\work (on Windows)
or <install_dir>/$ARCH/um/work (on UNIX)

IBM Tivoli Universal Agent SNMP applications

This section discusses the IBM Tivoli Universal Agent SNMP application metafiles
that IBM Tivoli Monitoring provides and how to use them to create your own
customized SNMP applications. The following details are unique to SNMP
metafiles:
v You do not create metafiles for SNMP MIB applications as you do for
applications used with other data providers. IBM Tivoli Monitoring creates
SNMP metafiles for you by converting MIBs into metafiles.
v SNMP metafiles are encrypted by default.
v SNMP metafiles are stored in a separate subdirectory under \metafiles.
v You can unpack the IBM Tivoli Monitoring provided SNMP metafiles and create
modified versions called custom SNMP applications. Custom SNMP application
metafiles are stored in a separate directory.

IBM Tivoli Monitoring provides metafiles for over several hundred

industry-standard MIBs and it can create a metafile for any MIB you request or
supply. To request a new SNMP metafile for a MIB, open a Problem Management
Record with IBM Customer Support and attach the MIB that you want to convert.

In addition to supporting MIB applications, the SNMP Data Provider automatically

activates a special application, SNMP-MANAGER, which you can use for network
management, monitoring SNMP traps, and checking the status of MIB data
collection.

Metafile names
SNMP metafile names take the form:
vendorname__enterprise.mdl

where:
vendorname
Specifies the RFC number for IETF standard MIBs or a vendor name for a
vendor-specific MIB.
enterprise
Specifies the MIB enterprise name. For example, the metafile for the
industry standard mib-2 is RFC1213_mib-2.mdl, and the one for Cisco’s
interface MIB is Cisco_linterfaces.mdl.

Location of SNMP metafiles

On Windows operating systems, non-SNMP Data Provider metafiles are located in
the following directory:
IBM\ITM\TMAITM6\metafiles

Chapter 3. Creating an application 27

 SNMP metafiles are located in the following subdirectories. You are not required to
store the provided SNMP metafiles or your customized metafiles in these
specialized subdirectories, but you can use them to organize your SNMP metafiles.
Converted vendor MIB metafiles provided by IBM Tivoli Monitoring
IBM\Omegamon\TMAITM6\metafiles\SNMP\vendor
Converted RFC* industry standard MIB metafiles provided by IBM Tivoli
Monitoring
IBM\Omegamon\TMAITM6\metafiles\SNMP\standard
Custom SNMP metafiles
IBM\Omegamon\TMAITM6\metafiles\CUSTOMIZED
trapcnfg_* metafiles
IBM\Omegamon\TMAITM6\metafiles\TRAPCNFG

On UNIX operating systems, non-SNMP Data Provider metafiles are located in the
following directory:
<install_dir>/$BINARCH/um/metafiles

SNMP metafiles are located in the following subdirectories. You are not required to
store the provided SNMP metafiles or your customized metafiles in these
specialized subdirectories, but you can use them to organize your SNMP metafiles.
Converted vendor MIB metafiles provided by IBM Tivoli Monitoring
<install_dir>/$BINARCH/um/metafiles/SNMP/vendor
Converted RFC* industry standard MIB metafiles provided by IBM Tivoli
Monitoring
<install_dir>/$BINARCH/um/metafiles/SNMP/standard
Custom SNMP metafiles
<install_dir>/$BINARCH/um/metafiles/CUSTOMIZED
trapcnfg_* metafiles
<install_dir>/$BINARCH/um/metafiles/TRAPCNFG

Importing SNMP metafiles

Use the IMPORT console command, the Take Action Control Import dialog, or
direct updating of the KUMPCNFG initialization file to import the metafiles
defining SNMP applications to the IBM Tivoli Universal Agent.

Versioning of applications
The initial version number of all SNMP applications is 00. The version number of
an application, and therefore the version numbers of all managed systems,
workspaces, and attribute groups based on it, is incremented each time you load
an updated definition (metafile) of the application.

Viewing application metafiles

MIB metafiles are not readable unless you process them through the UNPACK
console command:
kumpcon unpack metafile_name

This command produces a metafile_name.txt file in the same directory as the .mdl
file.

You can also use the VALIDATE console command to view MIB metafile contents
in an unencrypted format:

28 IBM Tivoli Universal Agent: User’s Guide

 kumpcon validate metafile_name

When you run the validate command, it produces a report file ending in .rpt
which contains, among other things, information about the attributes. See
Chapter 3, “Creating an application,” on page 15 for additional information on the
validate command.

Creating custom SNMP applications

In the metafiles that IBM Tivoli Monitoring creates from MIBs, a new attribute
group is created for each new group of scalar variables encountered and for each
new conceptual table. However, only a few attributes in a group can be of interest
for a particular network management scenario. Or you can crosscheck and
correlate attribute values from different attribute groups or even different MIBs,
which means that you have to open several reports to view and analyze a problem
situation. Since you can only create situations that use attributes from the same
attribute group, if you want to use attributes from different groups in your
situation, you must create other situations and embed them.

You can get around these limitations by constructing your own SNMP MIB-based
applications, derived from the ones that IBM Tivoli Monitoring provides. In these
custom applications you can use attributes from different groups and even from
different MIBs.

The following sections outline the steps you perform to create your own
applications.

Step 1: Unpack the SNMP metafiles

Run the console command UNPACK on each metafile that contains attributes you
want to include in your application and examine its output text file. For example,
the command
kumpcon unpack metafiles\SNMP\standard\RFC1213_mib-2.mdl

unencrypts the industry standard RFC1213_mib-2.mdl metafile and produces a .txt

file named RFC1213_mib-2.txt.

To prevent you from entering the additional directory levels, you can set the
environment variable, KUMP_META_PATH, to the directory where the SNMP MIB
metafile is located. Using the following example, you would enter the following
two commands in a Windows DOS prompt:
C:\IBM\ITM\TMAITM6>set KUMP_META_PATH=C:\IBM\Omeagamon\TMAITM6
\metafiles\SNMP\standard
C:\IBM\ITM\TMAITM6>kumpcon unpack RFC1213_mib-2.mdl

Step 2: Identify the scalar SNMP MIB variables of interest

Scan the attributes shown in the text file to identify all the scalar variables of
interest. Scalar SNMP MIB variables are variable definitions with OIDs ending in
zero. For example:
SysName D 255 1.3.6.1.2.1.1.5.0
ipInReceives C 999999 1.3.6.1.2.1.4.3.0
udpInDatagrams C 999999 1.3.6.1.2.1.7.1.0

Note the form of the attributes or copy them to the metafile in which you are
going to define the custom SNMP application. You can place all scalar attributes
into one or more attribute groups.

Chapter 3. Creating an application 29

 Tabular SNMP MIB variables have OIDs that do not end in zero. If you are
interested in tabular data you must define each MIB attribute table as its own
attribute group. You do not need to copy all the attributes in a MIB table into the
new attribute group; you can choose only those attributes in the table that are of
interest to you. However, you cannot mix scalar and tabular MIB attributes in an
attribute group.

Step 3: Construct a custom SNMP application metafile

Review metafile requirements, syntax, and restrictions. Take care to choose a
unique name for the application. You must make the first three characters of the
application name unique among all IBM Tivoli Universal Agents connected to a
particular Tivoli Enterprise Monitoring Server.

Group the selected attributes into one or more attribute groups as appropriate to
your own management scenarios. Remember that you cannot use attributes from
different groups in a single situation, but you can assign attributes to more than
one attribute group.

Two additional rules apply to SNMP metafiles:

v The metafile must include //SNMP TEXT as the first statement.
v In each attribute group, the first two attributes must be:
Agent_Info D 128 0.0
Agent_Name D 64 KEY 0.0

Refer to Figure 6 on page 31 to see an example of a sample custom SNMP metafile.

Step 4: Validate the metafile

Run the console command VALIDATE. Review the output report for any warning
or error messages and modify the metafile as necessary.

Step 5: Import the metafile to the IBM Tivoli Universal Agent

Make the metafile available to the IBM Tivoli Universal Agent either by executing
the console IMPORT command, using the Take Action Control Import dialog, or
including the metafile name in the IBM Tivoli Universal Agent configuration file,
KUMPCNFG, and then recycling the IBM Tivoli Universal Agent. The following is
an example of a custom SNMP application metafile:

30 IBM Tivoli Universal Agent: User’s Guide

//SNMP TEXT
//APPL SNMPEXAMPLE
//NAME TcpipNodeMonitor k 3600
//ATTRIBUTES’;’
Agent_Info D 128 0.0
Agent_Name D 64 KEY 0.0
sysName D 255 1.3.6.1.2.1.1.5.0
sysDescr D 255 1.3.6.1.2.1.1.1.0
sysServices C 127 1.3.6.1.2.1.1.7.0
ipInReceives C 999999 1.3.6.1.2.1.4.8.0
ipInDiscards C 999999 1.3.6.1.2.1.4.9.0
ipInDelivers C 999999 1.3.6.1.2.1.4.10.0
ipInDeliverPercent (ipInDelivers %ipInReceives)
ipInDiscardPercent (ipInDiscards %ipInReceives)
ipInAddrErrors # 999999 1.3.6.1.2.1.7.1.0
ipOutRequests C 999999 1.3.6.1.2.1.4.10.0
ipOutDiscards C 999999 1.3.6.1.2.1.4.11.0
ipOutDiscardPercent (ipOutDiscards %ipOutRequests)
udpInDatagrams ? 999999 1.3.6.1.2.1.7.1.0
udpOutDatagrams ? 999999 1.3.6.1.2.1.7.4.0
tcpActiveOpens # 999999 1.3.6.1.2.1.6.5.0
tcpPassiveOpens # 999999 1.3.6.1.2.1.6.6.0
tcpAttemptFails C 999999 1.3.6.1.2.1.6.7.0
tcpCurrEstab C 999999 1.3.6.1.2.1.6.9.0
tcpInSeqs % 999999 1.3.6.1.2.1.6.10.0
tcpOutSeqs % 999999 1.3.6.1.2.1.6.11.0
tcpRetransSeqs C 999999 1.3.6.1.2.1.6.12.0

Figure 6. Custom SNMP application metafile

Chapter 3. Creating an application 31

32 IBM Tivoli Universal Agent: User’s Guide
Chapter 4. About data providers
This chapter discusses the characteristics of data providers you need to consider
when you create metafiles to define IBM Tivoli Universal Agent applications or
develop programs to send data to the IBM Tivoli Universal Agent.

About data providers

Data providers are the interfaces of the IBM Tivoli Universal Agent. They enable
you to supply data in whatever way is most convenient or practical for your
particular monitoring scenario. Data providers allow you to do the following:
v Load and validate data definition metafiles.
v Collect data from data sources, such as log files, client programs, URLs, scripts,
relational tables, or SNMP agents.
v Pass the collected data, and the information about the data definition metafiles,
to the IBM Tivoli Universal Agent.
A given data provider can support multiple IBM Tivoli Universal Agent
applications concurrently.

Although it is useful from a conceptual standpoint to view data providers as

separate entities, they run as threads within the overall IBM Tivoli Universal Agent
process.Figure 7 illustrates the relationship between data providers and data
sources, metafiles, and the IBM Tivoli Universal Agent.

Types of data providers

The IBM Tivoli Universal Agent supports the File, API Server, Socket, Post, HTTP,
SNMP, Script, and ODBC Data Providers. This chapter describes these data
providers and their characteristics.

Data
Source
A

Universal
Data Data Provider Agent
Source
C

//APPLA //APPLB
//NAME //NAME
Data //SOURCE //SOURCE
Source //ATTRIBUTES //ATTRIBUTES
B

Figure 7. Relationship between data sources, metafiles, and data providers

Running multiple instances of a data provider

You can run multiple instances of a particular data provider type on a single
system. To distinguish the data providers, the IBM Tivoli Universal Agent prefixes
an instance name parameter to the managed system name.

© Copyright IBM Corp. 2003, 2005 33

 Advantages
Running multiple data providers of the same type on the same system offers the
following advantages:
v Runs a test and production IBM Tivoli Universal Agent on the same system. The
test IBM Tivoli Universal Agent could be used to verify new maintenance, as
well as environment variable and metafile changes before migrating the changes
to the production IBM Tivoli Universal Agent.
v Creates specialized IBM Tivoli Universal Agents for logical grouping purposes.
For example, to monitor discrete portions of your network.
v Balances workloads, if the volume of data being collected is overloading a single
IBM Tivoli Universal Agent.
v Connects multiple IBM Tivoli Universal Agents to different Tivoli Enterprise
Monitoring Servers.

Instance names
For each data provider that comes online, a primary, or non-instance, copy of IBM
Tivoli Universal Agent generates a managed system name of the form:
hostnameDPTYPEdp:UAGENT00. To run multiple instances of the same data
provider type on the same system, the resulting IBM Tivoli Universal Agent
generated managed system name uses an instance name parameter as a prefix to
guarantee uniqueness.

The naming conventions include:

Heartbeat Probe instname:hostname:UA
Data Provider instname_hostnameDPTYPEdp:UAGENT00
Application instname_hostname:applicationVV

The instance name is suffixed to all configuration and run-time files in the IBM
Tivoli Universal Agent work directory. For example, KUMPCNFG_TEST,
KUMATBLS_INST1 or KUMPURLS_PROD.

The configuration and run-time files for the primary IBM Tivoli Universal Agent
remain as before, without a suffix. The primary IBM Tivoli Universal Agent does
not have an instance name prefix in its managed system names, nor does it have
an instance name suffix in its configuration files.

There can only be one primary copy of IBM Tivoli Universal Agent configured and
active at a time. However, multiple additional copies, each with a unique instance
name, can run concurrently with or without the primary IBM Tivoli Universal
Agent active.

Running multiple data providers of the same type

Perform the following steps to create a new non-primary instance of IBM Tivoli
Universal Agent:
1. Right-click IBM Tivoli Universal Agent in the Manage Tivoli Enterprise
Monitoring Services window.
2. Select Create Instance.
The Create Instance panel displays.
3. Type a short instance name. Use the three-to-six character range.

34 IBM Tivoli Universal Agent: User’s Guide

Multiple instance configuration on UNIX operating systems
For information on configuring multiple instances of IBM Tivoli Universal Agent
on UNIX operating systems, see the IBM Tivoli Monitoring Installation and Setup
Guide.

A note on truncation
Manage Tivoli Enterprise Monitoring Services offers a context menu-driven
window where you can use an instance name of 1-20 characters. However, IBM
Tivoli Universal Agent limits an entire managed system name (instance prefix +
host name + application name + version suffix) to 32 characters. To preserve the
integrity of the managed system name, the instance name prefix gets truncated
from the left. For example, if the instance name ABCDEFGHIJKLMNOP is used
and the resulting managed system name is 35 characters, the actual registered
managed system appears as:
DEFGHIJKLMNOP_hostname:appnameVV

Therefore, choose short instance names to avoid managed system name truncation.

Sending a console command to an alternate instance

To make a program or console connection to an alternate IBM Tivoli Universal
Agent instance, you must specify the KUMP_DPCONSOLE_PORT environment
variable. To target the correct IBM Tivoli Universal Agent, use the UAGENT
DPLOG report. It provides the port numbers of the Socket and API listeners, and
the Console port for kumpcon commands. If the Data Provider Console port
number is no longer visible because it has scrolled off of the DPLOG report, you
can also find the port number by searching for "DP console port" in the IBM Tivoli
Universal Agent RAS1 log for that instance.

By default, the target IBM Tivoli Universal Agent is the primary and uses console
port 7700. To prevent you from issuing commands against the wrong IBM Tivoli
Universal Agent when a non-primary IBM Tivoli Universal Agent is accessed
through the console interface, the prompt for the target data provider displays the
Instance Name next to each data provider.

The Take Action interface does not have this ambiguity problem. When
distributing an action such as URL Add or Manage Start, the list of available
managed system names includes the Instance Name prefix.

Running multiple instances of SNMP Data Providers

Even with multiple instance support, you cannot run two full-function SNMP Data
Providers on the same system. Only one process can acquire the reserved SNMP
trap listening port 162. This is an SNMP restriction, not a IBM Tivoli Universal
Agent restriction. Assuming there is not another non-IBM Tivoli Universal Agent
SNMP Manager or trap listener already active, the first IBM Tivoli Universal Agent
that activates the SNMP Data Provider acquires port 162. Any subsequent IBM
Tivoli Universal Agent that activates the SNMP Data Provider fails to open the
trap listening port, but is able to perform other SNMP Data Provider functions,
such as collecting MIB data. The failure to acquire the trap listening port is logged
in the UA RAS1 log and in the SNMP Data Provider UAGENT DPLOG report.

Note: If you use an alternate instance of the IBM Tivoli Universal Agent as your
SNMP trap receiver, copy or rename the trapcnfg file in the work directory
so that it has the instance name suffix. For example, if your alternate
instance is called ″SNMP″, then copy trapcnfg to trapcnfg_SNMP.

Chapter 4. About data providers 35

 Conflicts between duplicate applications
Do not run the exact same application in two different IBM Tivoli Universal Agent
instances. Through the use of suffixed configuration files, it is relatively easy to
maintain a different set of IBM Tivoli Universal Agent applications for the multiple
IBM Tivoli Universal Agents you run. However, nothing prevents you from
activating the exact same application in two different IBM Tivoli Universal Agents.
For example, you can monitor the same log file and the same URLs. In some cases,
this is merely wasteful and inefficient. In other cases, duplicate monitoring could
cause problems, particularly if you run different versions of the same-named
application.

36 IBM Tivoli Universal Agent: User’s Guide

API Server Data Provider
The Application Programming Interface Server (APIS) Data Provider supports API
client functions. The data provider and the IBM Tivoli Universal Agent APIs enable
you to easily develop scripts and C/C++ programs that send data to the IBM
Tivoli Universal Agent. They also support a command-line interface which
implements a subset of the API functions.

See the IBM Tivoli Universal Agent API and Command Programming Reference Guide
for complete information on the IBM Tivoli Universal Agent APIs and supported
commands.

Invoking the APIs

You can invoke the IBM Tivoli Universal Agent APIs in the following ways:
v Program function calls
You can develop or modify C/C++ programs that invoke the API functions
directly as subroutines.
v Script file calls
You can develop or modify script or batch files that call the API command-line
interface programs.
v Manual commands
You can enter API commands directly from a system console. This method is
particularly useful because it allows you to send data or create events whenever
the need arises. For example, Customer Support might receive an urgent call
from a critical customer site. The customer service representative could enter an
API command with accompanying text. The command would cause a situation
to become true and the on-duty action team to be notified.

The API client package

The data provider API client package consists of the following:
v A library containing the binary executable files of the API functions
v A C header file
v A set of command-line interface programs

The client package was developed in standard C language and requires only a
common C runtime environment and TCP/IP with a socket interface. It does not
create added programming complexity or dependency for the calling program.

Chapter 4. About data providers 37

 API
Runtime
API Dynamic
Console Commands Library

API API Server

Data Source Runtime Data Provider
Dynamic
Library
Transport Network

API
Data Source Runtime
Dynamic
Library

Figure 8. Implementation of API Server Data Provider

Calling programs
C/C++ calling programs instrumented with the IBM Tivoli Universal Agent APIs
rely upon API services provided by the runtime dynamic library. The programs
can reside locally with the API Server Data Provider or they can start at a remote
location. These calling programs are commonly referred to as API clients because
they depend on the API client package and they follow a client-server paradigm in
their connections to the API Server Data Provider. You can also think of API clients
as data collectors because their primary purpose is to perform some type of data
collection and send the collected data to the API Server Data Provider.

The IBM Tivoli Universal Agent API and Command Programming Reference Guide
contains the minimum program requirements and procedures for implementing the
API functions and provides descriptions, syntax, and return status codes for the
API calls, as well as a sample API client program.

API console commands

The API console commands are console interface programs that call the API
functions. They use the same API runtime dynamic library as the API functions, so
you can invoke them either from the console of the local system or from the
console of a remote system.

The IBM Tivoli Universal Agent API and Command Programming Reference Guide
contains descriptions of the console commands.

38 IBM Tivoli Universal Agent: User’s Guide

Specifying the host of the API Server Data Provider
The default mode of the API client assumes that the APIS Data Provider resides on
the same system. If the APIS Data Provider is running on a remote system, you
must set the environment variable KUMP_API_DPAPI_HOST to the host name of the
APIS Data Provider.

Specifying the listening port for the API Server Data Provider
The default listening port for the APIS Data Provider is 7600. If this port is already
in use, or you would prefer that a different port be used, you can set the
environment variable KUMP_API_DPAPI_PORT to the preferred port. If you set this
variable for the APIS Data Provider, or if this variable was automatically
reassigned as a result of starting an alternate instance of the IBM Tivoli Universal
Agent, you must set the same variable on the API client side. You can check the
APIS Data Provider UAGENT DPLOG report to verify the correct listening port
number.

Managed system names of API Data Provider applications

The managed system name of an API metafile application has the following
format:

Hostname:ApplNameVV

where:
Hostname
The host where the API client program is running.

Note: This host is different from the host where the IBM Tivoli Universal
Agent is running if the API client is connecting from a remote
system.
ApplName
The name value specified to the API metafile application.
VV The two-digit version suffix.

You can customize the Hostname portion of the managed system name with the
dp_SetSourceName API. See the IBM Tivoli Universal Agent API and Command
Programming Reference Guide for additional information.

Note: The managed system for an API metafile application does not come online
in the Tivoli Enterprise Portal Navigator until the API client program has
connected to the APIS Data Provider.

Chapter 4. About data providers 39

File Data Provider
The File Data Provider monitors data residing in a sequential text file. It offers the
simplest, most direct way of using the IBM Tivoli Universal Agent to monitor data
with IBM Tivoli Monitoring.

Location of File Data Provider

File Data Providers must reside on the same host as the files they monitor, or the
files must be displayed to the data provider to be residing on the local system. The
operating system can remove the “remoteness” of a file from the running data
provider by implementing a network file system or mapping a remote system
resource to a local device.

If the File Data Provider is monitoring a file on a remote system through the use of
logical drive mapping, the userid/account associated with the IBM Tivoli Universal
Agent must have sufficient authority to open and read the file on the remote
system. In some cases this can require, for example, reconfiguring the IBM Tivoli
Universal Agent Windows service with something other than the default
"LocalSystem" account. The Windows Control Panel Services applet allows you to
configure a different account for a particular service. In this scenario, you could
change the IBM Tivoli Universal Agent account from "LocalSystem" to an
Administrator ID that is authorized on your LAN to access files on the remote
system.

Managed system names of File Data Provider applications

If the file specified on the metafile //SOURCE FILE statement is accessible when
the metafile is activated, a managed system name with the following format comes
on-line:LocalHostname:ApplNameVV

where:
LocalHostname
The host where the IBM Tivoli Universal Agent is running.
ApplName
The name value specified on the metafile //APPL statement. See “APPL
statement” on page 117 for additional information.
VV The two-digit version suffix. See “Versioning of metafiles” on page 24 for
additional information.

You can customize the LocalHostname portion of the managed system name with
the ManagedSystemName parameter on the metafile //SOURCE statement. See
“SOURCE statement” on page 126 for additional information.

File sampling frequency

The File Data Provider samples a monitored file periodically for new records. The
sampling frequency is determined as follows:
v For event type data, the File Data Provider samples data every 15 seconds or at
the rate, in seconds, specified by the KUMP_DP_EVENT environment variable.
v For polled, sampled, and keyed data, the sampling frequency is derived from
the time-to-live (TTL) value specified in the data definition metafile, divided by
the sample factor. The default TTL is 300 seconds and the default sample factor
is 5. You can control the sampling frequency for polled and sampled data using

40 IBM Tivoli Universal Agent: User’s Guide

 the KUMP_DP_SAMPLE_FACTOR environment variable and the TTL. If you do not
define an override, the File Data Provider samples data every 60 seconds (300
divided by 5).

The maximum default sample frequency is 5 minutes (300 seconds). You can
override this default using the KUMP_DP_SAMPLE_FACTOR variable. For example, if a
metafile specifies the TTL as 3600 seconds, the sampling frequency is 3600 divided
by 5, or 720 seconds. The sample frequency actually enforced is 300, the default
maximum. However, if you specify the KUMP_DP_SAMPLE_FACTOR as 10, the sample
frequency is 360. The maximum override takes place only if no user specification is
defined.

The File Data Provider also enforces a minimum sampling frequency. The
minimum default sampling frequency of 30 seconds is substituted if the TTL
divided by the sampling factor results in a sampling frequency of less than 1
second. For example, in the case of a TTL equal to 180 and a
KUMP_DP_SAMPLE_FACTOR equal to 360, the file is actually sampled every 30 seconds.
If the specified frequency is overridden, a metafile definition validation warning
message is issued which identifies the minimum sample interval in effect.

Special file extracting routines

Many operating systems, networks, and applications maintain useful information
in files suitable for monitoring by a File Data Provider. However, if your data is
not already in a sequential file, you can create an extraction program to export the
data from the native source to a sequential file so the File Data Provider has access
to it.

For example, the Windows Event Log cannot be read easily as a sequential file.
However, you can develop an extractor program using the Win32 Event Log APIs
to access Event Log records. The program would obtain the records through the
appropriate APIs, then write the records to a sequential file monitored by the File
Data Provider.

Multiple record input

The File Data Provider supports multiple record input in cases where multiple
physical file records comprise one logical record. For example, the data for the first
two attributes in an attribute group can reside in one file record, the data for the
third and fourth attributes in a second record, and the data for a fifth attribute in a
third record. Or you can concatenate the data in five records and treat it as a single
attribute for the purposes of monitoring.

You can define record sets consisting of a fixed number of records, or of a variable
number of records identified by a delimiter pattern. See “RECORDSET statement”
on page 135 for details.

Globalized file monitoring

You can use the File Data Provider to monitor files in any language or character
encoding. When doing so, be aware of the following:
v If the language and code page of the file data that you are monitoring is not the
default language and code page of the system where the IBM Tivoli Universal
Agent is running, you must specify the CODEPAGE and LOCALE keyword
parameters on the metafile //SOURCE statement. These two parameters tell the

Chapter 4. About data providers 41

 File Data Provider what character encoding to use when processing the file data.
See “SOURCE statement” on page 126 for additional information on using this
metafile statement.
v If the monitored file is located in a non-English directory system, you must type
the path name and file name in the metafile in the appropriate language.
However, you must save the metafile as a UTF-8 file. The IBM Tivoli Universal
Agent is only able to open and read metafiles that are in ASCII or UTF-8
encoding.

Dynamic file name support

The //SOURCE statement defines a fixed monitoring application file. An
application program often creates its output file based on specific criteria such as
day, week, or month naming conventions or on files reaching their defined size
and rolling over to a new file. In cases like these, you can specify a monitoring file
name pattern in the //SOURCE statement as
//SOURCE FILE file-name-pattern-spec

instead of the actual file name. The File Data Provider inspects all files in the
designated path location, seeking files that match the defined pattern. The File
Data Provider always manages the most current matching file, based on whichever
matching file has the highest number or date/time value. The appropriate file is
determined by file name, instead of by file creation or modification date. The
pound sign (#) sign defines the position of the numeric character within the file
name.

Note: The file name and pattern are case-sensitive on a case-sensitive operating
system.

See “SOURCE statement” on page 126 for additional information.

The following examples illustrate file name pattern specification:

{########}.abc Matches numeric file names of length 8 and the file
extension .abc, such as 10252005.abc or
10262005.abc. File 10262005.abc is monitored
because 10262005 is greater than 10252005.
{########}.* Matches numeric file names of length 8 and
ignores the file extension. Examples include
20051025.log, 20051101.log, and 10252005.abc. File
20051101.log is monitored because 20051101 is the
largest number.
{######??}.abc Matches numeric file names of length 8 and
ignores the last two positions in the file name.
Examples include 02110100.abc, 02110101.abc, and
02110202.abc. File 02110202.abc is monitored.
IN{######}.log Matches file names starting with IN followed by
six numerals and the file extension .log. Examples
include IN021001.log, IN021002.log, and
IN021004.log. File IN021004.log is monitored.
PS{###}FTP.txt Matches file names starting with PS followed by
three numerals, followed by FTP, and the extension
.txt. Examples include PS001FTP.txt, PS005FTP.txt,
and PS010FTP.txt. File PS010FTP.txt is monitored.

42 IBM Tivoli Universal Agent: User’s Guide

Follow these guidelines to establish file name patterns:
v Use an asterisk (*) to ignore file extensions. Only the first part of the file name is
checked and the second part, which must be present, is ignored.
v If a specific file extension is defined, then only files with the same extension are
considered.
v Use braces {} to enclose the numeric part of the file name pattern.
v Use a pound sign to indicate each numeric element of a file name.
v Use a question mark to exclude each element of the naming convention that
does not serve as search criteria in determining the appropriate file name.
v Use a dollar sign ($) to represent either any character or no character.
v The total number of pound signs and question marks enclosed in braces is
significant. It must match the portion of file name exactly. For example, the
pattern AA{####} instructs IBM Tivoli Universal Agent to look for file AA0001.
File names, such as AA001 or AA00001, are not considered.
v The exact file name pattern, the constant and the numeric parts, must match the
file name exactly. For example, the pattern AA{###} instructs IBM Tivoli
Universal Agent to check file AA101. File names, such as XAA101, AA222X and
AA55555, are not considered.
v If you want to match on file names that have or do not have a character in a
certain position, for example, Log and LogA, specify Log{$}.

To precisely specify a file name consisting of date components (year, month, and
day), use the capital letters Y, M, and D. This naming convention enables IBM
Tivoli Universal Agent to determine the candidate file without errors. Y, M, and D
must be displayed within braces; otherwise they are treated as literals.

Examples include:
{YYYYMMDD}.log Specifies candidate files with names such as
20050930.log or 20051015.log.
{MMDDYY}.log Specifies files with names such as 101105.log or
110105.log.
{DDMMYYYY}.log Specifies possible files with names such as
01092005.log. or 15082005.log.
MY{YYDDD}.log Specifies files with names such as MY05202.log,
MY05010.log or MY04350.log.

The File Data Provider periodically checks for new files that match the defined file
pattern in the target path location. When a newer file that matches the pattern is
detected, the File Data Provider automatically switches application monitoring to
the new file. The File Data Provider searches for the best matching file when:
v The File Data Provider first starts up.
v The currently managed file no longer exists due to possible renaming or
deleting.
v The existing file contents have changed due to possible rewriting.
v The check interval expired. The default interval is 10 minutes. You can change
the interval to a longer or shorter interval value by specifying the environment
variable
KUMP_DP_FILE_SWITCH_CHECK_INTERVAL=seconds

The File Data Provider issues a DPLOG message notifying you that the active
monitored file has switched from the current file to the new file.
Chapter 4. About data providers 43
 Some applications use a pair of related log files that switch between being active
and inactive. In many cases, the inactive one is cleared out and the active one
gradually increases in size until the next switch occurs. You can use the pattern
matching feature for the File Data Provider to monitor a pair of files based on
relative file size.
//SOURCE FILE file-name-pattern-spec tail CompareBySize

The CompareBySize keyword means that of the two files that match the pattern
criteria, the bigger file will be monitored. The CompareBySize feature only works if
there are two or fewer files in the directory that match the pattern criteria. If there
are more than two matching files, the default name-based pattern matching is in
effect. This restriction was implemented to prevent the scenario where multiple
matching files are changing in size at irregular rates, which could lead to frequent
file switching. Do not use CompareBySize with two files that are both being
updated at the same time because of the possibility of frequent file switches. Either
case causes monitoring to restart at the beginning of the file. Use CompareBySize
when there are two matching files, but only one is being updated at any given
time.

Pre-allocated file space

An application program can pre-allocate a file with a specific size and manage the
file records in this pre-allocated file space based on a special algorithm. The
Microsoft® Internet Information Server log is an example of this type of file.

The common technique of tailing a file by examining the end-of-file file record
pointer location for newly added records becomes ineffective because the
end-of-file pointer location does not change. The file size remains unchanged until
the application program allocates the next file space increment. Using the common
file I/O function to read a file record also proves problematic because it always
returns a valid file record pointer until reaching the pre-allocated file size.

The keyword tailbyrecord specified on the //SOURCE statement

//SOURCE FILE file-name tailbyrecord

instructs the File Data Provider to use a special method in handling the managed
file. The File Data Provider tracks physical file records in a pre-allocated file and
examines the record contents for validity. In this case, the File Data Provider is
monitoring a file’s logical EOF instead of its physical EOF for newly added file
records.

Note: You can specify the tailbyrecord keyword for all files including “non”
pre-allocated file space files. However, this is less efficient than the standard
approach of simply monitoring the file location pointers.

See “SOURCE statement” on page 126 for additional information.

Additional file monitoring options

For most situations, simple tail monitoring of new records appended to the end of
a file is sufficient. However, if there is a need to employ other forms of tail
monitoring, the File Data Provider supports the TailRestart, TailRestartFromTop,
and TailByCount options. See “SOURCE statement” on page 126 for additional
information on these options.

44 IBM Tivoli Universal Agent: User’s Guide

HTTP Data Provider
The IBM Tivoli Universal Agent HTTP Data Provider allows you to monitor the
availability and response time of selected URLs. The HTTP Data Provider runs as a
separate data provider. You can specify URLs to monitor in the startup
configuration file, within situations, or through the Take Action option.

Starting the HTTP Data Provider

Start the HTTP Data Provider using the same method you would use to start other
data providers. In the following example, the KUMA_STARTUP_DP parameter
starts the HTTP Data Provider.
KUMA_STARTUP_DP=HTTP

In the next example, the KUMA_STARTUP_DP parameter starts the HTTP Data
Provider in conjunction with the ASFS and SNMP Data Providers.
KUMA_STARTUP_DP=ASFS,SNMP,HTTP

Managed system names of HTTP Data Provider applications

When HTTP monitoring becomes active, it is represented by two managed
systems. One for the INTERNET application with the following managed system
name:
host-name:INTERNET00

and one for the HTTP Data Provider with the following name:
host-nameHTTPdp:UAGENT00

Note: You cannot create metafiles for the HTTP Data Provider. Therefore, you
cannot use any applications other than INTERNET with this data provider.

Monitoring a URL
Start monitoring any URL in one of three ways:
v Include the target URLs in the data provider startup URL initialization file
KUMPURLS.
v Create IBM Tivoli Monitoring situations based on the INTERNET table.
v Use the URL Add Take Action option.

URL initialization file

KUMPURLS lists initial monitoring URLs and must reside in the product
installation WORK directory. If this file does not exist or is empty, then you can
only start URL monitoring by using IBM Tivoli Monitoring situations or through
Take Action. The default URL sampling interval is 300 seconds for URLs defined in
this file. An example of KUMPURLS follows.
*****************************************************
** List of initial monitoring URLs. **
*****************************************************
www.tivoli.com
http://www.etrade.com/cgi-bin/gx.cgi/AppLogic%2bHome
http://moneycentral.msn.com/investor/home.asp

Note: The http:// prefix is optional.

IBM Tivoli Monitoring situations

You can construct situations using the URL attribute in the INTERNET table for
monitoring any target URL. If the URL is not already monitored as a result of its

Chapter 4. About data providers 45

 presence in the KUMPURLS file, then monitoring for it begins. If it already exists
in KUMPURLS, the situation is still valid, but a second monitoring instance for the
URL is not created. The only required attribute when creating a situation to
monitor a URL is the URL name itself. It must begin with the http:// prefix.

The Test_Yahoo situation interval defines the URL monitoring sample frequency. If
the Test_Yahoo situation interval is less than 60 seconds, it is reset in the Managed
URLs table to 60 because that is the minimum sampling interval allowed for URLs.
Stopping the situation stops the specific target URL monitoring.

If multiple URLs are monitored as a result of IBM Tivoli Monitoring situations and
those situations are activated all at the same time, then you might see User ID
values of _Z_INT36863000 substituted for one or more of your situation-started
URLs. The _Z_INT36863000 substitution results from the Tivoli Enterprise
Monitoring Server ″DUPER″ feature which optimizes the activation of multiple
situations that have the same sampling interval. If this User ID substitution has
occurred for a URL and you are attempting to remove the URL through the URL
Remove window, specify _Z_INT36863000 in the window. To avoid situation name
substitution, you must disable the Tivoli Enterprise Monitoring Server DUPER
feature. You can accomplish this by specifying the CMS_DUPER=N environment
variable in your Tivoli Enterprise Monitoring Server KBBENV file.

Take Action
You can also specify URLs to monitor through a Take Action option called URL
Add. When this option is selected, a window allowing you to specify the following
parameter displays:
URL A required parameter representing the URL itself. You can type this
parameter with or without the http:// prefix. If this parameter is not filled
in, the Alias Name defaults to blank, the Status Interval defaults to 300
seconds, the User ID defaults to TAKE_ACTION, and the Cache Percentage
defaults to 0%.
URLaliasName
An optional parameter that you can specify to associate a more meaningful
name to a URL.
StatusInterval
An optional parameter representing the elapsed time in seconds between
samples, the sampling interval. If you are monitoring multiple URLs, you
can specify a different status interval for each URL.
ID An optional parameter representing the user who started monitoring the
URL. The following rules apply for the User ID:
v For URLs monitored as a result of a IBM Tivoli Monitoring situation, the
User ID is the situation name.
v For URLs specified in KUMPURLS, the default User ID is INITCNFG.
v For URLs specified in this Take Action window, the default User ID is
TAKE_ACTION. However, you can also specify a different User ID
value. The User ID in this context is also referred to as the URL owner.
ObjCache%
An optional parameter that you can use to refine response time
measurements. If you know roughly what percentage of your Web pages
are cached, then specify that value for ObjCache%. The HTTP Data
Provider factors the cache percentage into its calculations of URL response
time. For example, if you specify 50% for ObjCache% and there are 20

46 IBM Tivoli Universal Agent: User’s Guide

 objects embedded in the Web page, then only 10 of the objects are
downloaded, reducing the response time value.

After you fill in the information and close the window, assign the URL Add action
to the destination managed system associated with the IBM Tivoli Universal Agent
INTERNET application. Monitoring begins immediately for the new URL.
Availability and response time data for the URL becomes viewable in Tivoli
Enterprise Portal client as soon as the new URL’s Status Interval time period has
elapsed. The URL is also added to the KUMPURLS configuration file so that it
continues to be monitored across IBM Tivoli Universal Agent restarts.

A corresponding Take Action option, called URL Remove, permits immediate

stopping of monitoring for a particular URL. The removed URL is also deleted
from the KUMPURLS configuration file. The URL Remove window only requests
the URL and User ID values. The User ID value must match what you specified
for the URL when monitoring began or the Remove action fails. After filling in the
information and closing the window, assign the URL Remove action to the
destination managed system associated with the IBM Tivoli Universal Agent
INTERNET application.

URL attributes
The IBM Tivoli Universal Agent HTTP Data Provider automatically registers the
INTERNET application. This application contains the Managed URLs and URL
Objects table definitions that are displayed in the INTERNET reports.

Managed URLs
The Managed URLs table includes the following attributes, which are available to
IBM Tivoli Monitoring situations using URL monitoring:
Table 5. URL attributes
Attribute name Type Size Description
Average Response Time Integer Long The average observed managed URL
response time in milliseconds.
Current® Response Time Integer Long The current observed managed URL
response time in milliseconds.
HTTP Version Character 8 The HTTP version (HTTP 1.0 or 1.1)
of the Web server for the target URL
Web site.
ISP_Name Character 64 The name of the Internet Service
Provider (ISP).
Maximum Response Time Integer Long The maximum observed managed
URL response time in milliseconds.
Page Objects Integer Long The total number of additional
objects associated with the
monitored page.
Page Size Integer Long The page size, in bytes, of the
received URL page.
Page Title UTF-8 256 The page title of the received URL
page.
Server Type Character 64 The type of Web server used at the
target URL Web site.
Status Character 64 The current managed URL status
(OK or status description).

Chapter 4. About data providers 47

 Table 5. URL attributes (continued)
Attribute name Type Size Description
Status Interval Integer Long The elapsed time, in seconds,
between status checks for the target
URL.
Status Timestamp Character 32 The time when the current managed
URL status was last taken.
Total Object Size Integer Long The total number of bytes
downloaded for the associated page
objects.
Total Samples Taken Integer Long The total number of samples taken
for this URL since monitoring began.
URL UTF-8 512 The target managed URL. You must
use the format, http://.
URL Alias UTF-8 32 The user-specified alias for the URL.
User Name UTF-8 32 The user ID that initiated
monitoring for the target URL.

The calculations which are performed to determine attribute values such as

Average Response Time and Maximum Response Time are based upon the concept
of a ″sample set″. If a URL has been monitored for days, thousands of sampling
statistics can have been obtained for it. However, only the most recent statistics are
needed in reporting, for example, Average Response Time. In fact, including
response time measurements from days or hours before could end up skewing the
average. Therefore, the HTTP Data Provider maintains a table, known as a sample
set, of the most recently obtained samples and uses only those values to calculate
response time statistics.

The sample set size is determined by a URL’s Status Interval value. A small Status
Interval leads to a big sample set, and a large Status Interval leads to a small
sample set. Sample sets can range anywhere from 3 to 15 (3 if the Status Interval is
5 minutes, and 15 if the Status Interval is 1 minute), but they are always based on
the last 15 minutes of sampling data.

You can specify the ISP name in a text file called ISP.ID located in the IBM Tivoli
Universal Agent product installation WORK directory. If the file does not exist, a
default ISP value of ″LAN″ is used.

URL objects
The second INTERNET table, URL Objects, includes the following attributes:
Table 6. URL objects
Attribute name Type Size Description
Object Name UTF-8 512 The name of the page object within
target URL.
Object Size Integer Long The size of page object within target
URL.
URL UTF-8 512 The target managed URL You must
use the format, http://.

The URL Objects table contains a separate URL entry for each embedded object,
such as the .eps and .eps files that might be used in the Web site listed in the
48 IBM Tivoli Universal Agent: User’s Guide
Managed URLs report. When you need to monitor the response time and
availability of specific objects within a Web site, review the contents of the URL
Objects table.

Chapter 4. About data providers 49

ODBC Data Provider
Open Database Connectivity (ODBC) is a standard application programming
interface for accessing data in relational data sources. The IBM Tivoli Universal
Agent ODBC Data Provider allows you to collect data from ODBC-compliant
databases using SQL Select statements and stored procedures supported by the
particular ODBC source that is being monitored.

The ODBC Data Provider runs as separate data provider. It is only available on
Windows operating systems. You specify the ODBC data source, tables, and SQL
Select information through parameters and statements in IBM Tivoli Universal
Agent metafiles. The tables and columns in the ODBC data source become
attribute groups and attributes in the associated metafile. Any valid SQL Select
statement or stored procedure that retrieves column data from one or more tables
or views can be specified in an ODBC metafile.

ODBC allows you to collect data from a remote data source without having to
install any additional software on the remote system. The ODBC driver software
handles all of the network connectivity issues. As a result, the ODBC Data
Provider can run on one box while it’s simultaneously collecting data from
multiple remote database systems in your network. Any ODBC data source that
you can configure on the Windows operating systems where the ODBC Data
Provider is running is eligible for monitoring.

Starting the ODBC Data Provider

The ODBC Data Provider is started in the same way as other IBM Tivoli Universal
Agent data providers. In the following example, the KUMA_STARTUP_DP
environment variable specifies to start the ODBC Data Provider along with the
ASFS Data Provider:KUMA_STARTUP_DP=ASFS,ODBC

Sample ODBC metafiles

The following two examples illustrate the parameters and statements specific to
ODBC metafiles:

Example 1
//APPL NWIND
//NAME EMPLOYEES K 300 Interval=60
//SOURCE ODBC nwind
//SQL select * from employees
//ATTRIBUTES
EmployeeID N 8 KEY ATOMIC
LastName D 32
FirstName D 32
Title D 32
TitleOfCourtesy D 16
BirthDate D 24
HireDate D 24
Address D 32
City D 32
Region D 32
PostalCode D 32
Country D 32
HomePhone D 32
Extension D 16
Notes D 128
ReportsTo N 4

50 IBM Tivoli Universal Agent: User’s Guide

 Modes of collecting table data
You can collect ODBC table data in interval-driven or demand-driven mode. The
default is demand-driven, which signifies that data is only collected if a situation
request or report request is issued for the table. This example uses interval-driven
collection, indicated by the Interval=60 parameter on the //NAME statement,
which means that data is collected for this table every 60 seconds. If the
Interval=nn parameter is omitted, demand-driven collection is in effect.

Parameters and statements

//NAME statement
The //NAME statement also specifies ″K 300″, indicating that this is a keyed table
and its data has a TimeToLive value of 300 seconds. Use a keyed table for ODBC
metafiles for the following reasons:
v Prevent the same retrieved rows from being added multiple times whenever the
SQL Select statement is started.
v Most ODBC tables have one or more indexed columns which logically
correspond to KEY attributes in the IBM Tivoli Universal Agent metafile

//SOURCE statement
The //SOURCE statement supports an ″ODBC″ parameter to specify that it is an
ODBC metafile. This is a required parameter for all ODBC metafiles. The presence
of this parameter means that other data providers bypass loading the metafile and
only the ODBC Data Provider loads and activates it. Following the ″ODBC″
parameter, you must include the ODBC data source name, ″nwind″ in this
example. It is the same name that you configured in the ODBC Data Sources
applet. You must configure this data source because it is not automatically
configured by the ODBC Data Provider. If the data source is not accessible across
the network or if the ODBC Data Provider cannot connect to it because of missing
or incorrect userid/password credentials, the associated managed system does not
come online. If the data source name contains any embedded blanks, it must be
surrounded by single quotation marks.

//SQL statement
Each ODBC metafile requires a valid //SQL statement for every //NAME
statement. You can use an SQL Select statement or a stored procedure name. In the
example above, all columns and rows are being selected from the Employees table
in the Microsoft Access Northwind database, which has been configured as
″nwind″. This metafile specifies that every 60 seconds, the ″select * from
employees″ SQL statement is started against the nwind database.

//ATTRIBUTES statement
In ODBC metafiles, the attributes listed under the //ATTRIBUTES statement must
match column names defined in the ODBC table that is being accessed. You do not
need to include an attribute for every column in the table. You also do not need to
list the attributes in the same sequence as the columns are displayed in the ODBC
table. However, the attributes that you do include must have a matching column
name. This is not case sensitive. You cannot rename an attribute in the metafile so
that it no longer matches its corresponding column. You are free to add derived
attributes and other IBM Tivoli Universal Agent specific attributes, such as a
LocalTimeStamp.

Chapter 4. About data providers 51

 Usage notes
v In ODBC metafiles, the attribute delimiter is not used because each column
value is retrieved separately. Therefore, it does not matter what you specify for
the delimiter value on the //ATTRIBUTES statement.
v Use the IBM Tivoli Universal Agent refresh command without changing the
version number of the ODBC metafile application to dynamically implement
changes to the //SOURCE and //SQL statements.
v Although this example uses the ODBC data source name, nwind, as the
application name on the //APPL statement, it is not a requirement that the two
names match.

Example 2
Here is another example to illustrate additional features of ODBC metafiles:

//APPL CNPS
//NAME spt_server_info K 300 AddTimeStamp
//SOURCE ODBC cnps user=sa pswd= maxrows=50
//SQL select * from spt_server_info where attribute_id > 2
//ATTRIBUTES
attribute_id N 8 KEY ATOMIC
attribute_name D 64
attribute_value D 64
*
//NAME sp_helpdb K 300
//SOURCE ODBC cnps user=sa pswd=
//SQL proc=sp_helpdb master
//ATTRIBUTES
name D 32 KEY ATOMIC
db_size D 32
owner D 32
dbid C 999999
created D 20
status D 64

//NAME statement
The absence of the Interval= parameter indicates that these two tables use
demand-driven data collection. The spt_server_info table includes an
″AddTimeStamp″ parameter, which inserts a LocalTimeStamp column in the
spt_server_info report.

//SOURCE statement
The SQL Server ″cnps″ data source requires a userid/password combination to
connect. So both of these //SOURCE statements include ″user=″ and ″pswd=″
parameters. The ″sa″ userid does not have an associated password, so the ″pswd=″
parameter value is left blank.

By default, a maximum of 100 rows are returned for each ODBC table in a
metafile. To increase or decrease this value for a particular table, you can include a
maxrows=nn override on the //SOURCE statement. You can globally change the
default with the KUMP_ODBC_MAX_ROWS environment variable. The maxrows=50
specified for the spt_server_info table means that if more than 50 rows are
returned from the Select statement, only the first 50 rows is used for reporting and
situation evaluation.

52 IBM Tivoli Universal Agent: User’s Guide

 //SQL statement
The first //SQL statement in Example 2 shows how you can include a Where
clause to filter which rows to return. Use Where clause filtering in your ODBC
metafiles when possible. This clause is more efficient because fewer rows are
retrieved. Issue qualified SQL Select statements that only retrieve the rows you
want to evaluate in your situations.

The sp_helpdb table in Example 2 illustrates the use of stored procedures. Instead
of a Select statement, the //SQL statement can specify the name of a stored
procedure, which must be preceded by the ″proc=″ keyword. If there are any input
parameters to the stored procedure, they must be blank-separated tokens after the
stored procedure name. In this example, ″master″ is the only parameter being
supplied to the sp_helpdb procedure.

The two metafile examples above assume a one-to-one relationship between IBM
Tivoli Universal Agent attribute groups and SQL tables, but this is not a
requirement. SQL joins are supported. An //SQL statement could select columns
from 10 different tables and store the retrieved values in attributes belonging to a
single IBM Tivoli Universal Agent attribute group. The only requirement is that the
retrieved columns have matching attribute names; however, the columns do not all
have to come from the same table.

Automatic generation of ODBC metafiles

To save the effort of manually creating ODBC metafiles, it is possible to
automatically generate a complete, syntactically correct ODBC metafile from a
given data source name. See the description of the GENERATE command in
“GENERATE” on page 185.

Chapter 4. About data providers 53

Post Data Provider
The Post Data Provider offers a convenient means of sending ad hoc notifications
such as messages, alerts, and status information to IBM Tivoli Monitoring. You can
customize the Post Data Provider to fill a specific use. For example, with a
minimum of additional programming an application can use a TCP/IP socket to
send processing status to IBM Tivoli Monitoring. A customer service representative
can start a basic command script file and send inquiry messages to a Help Desk.
System operators can quickly invoke a console command when they observe
abnormal events to notify the network control center.

The Post Data Provider is implemented as a TCP/IP socket application with a

predefined metafile. It listens on both TCP and UDP protocol ports 7575 or any
port specified by the environment variable KUMP_POST_DP_PORT. Any program can
quickly open a socket and send messages, alerts, or status to a Post Data Provider
on demand. You can also develop simple Java™ applications that help you send ad
hoc messages or use the command-line interface program KUMPSEND provided with
the IBM Tivoli Universal Agent. The KUMPSEND program does accept non-English
message text input.

Default configuration
The default characteristics of the Post Data Provider are defined in the data
definition metafile KUMPOST shown in Figure 9 on page 54.

The name of the application defined by KUMPOST is MAS (Messages, Alerts,

Status) and the name of the attribute group is dpPost. The application collects
polled data with a time-to-live of one hour. There are five attributes in the group,
delimited by semicolons (;). The values for the first three attribute values are
automatically supplied by the Post Data Provider. The attribute values for
Post_Text and Post_Category are obtained from an application or from a console
command using the KUMPSEND program.
Table 7. MAS attributes for the Post Data Provider
Attribute Definition
Post_Time The time when the message was received.
Post_Origin The host name that sent the message.
Post_Ack_Stamp A unique identifier generated for each
received message.
Post_Text The text of the message sent to the Post
Data Provider.
Post_Category One of the ten predefined Post Data
Provider message categories.

//APPL MAS
//NAME dpPost S 3600
//ATTRIBUTES ’;’
Post_Time T 16
Post_Origin D 32
Post_Ack_Stamp D 26
Post_Text U 512
Post_Category D 16

Figure 9. KUMPOST data definition metafile

54 IBM Tivoli Universal Agent: User’s Guide

Message categories
There are ten predefined post message categories, shown in Table 8. The meaning
of each category is determined by your data and local usage guidelines.
Table 8. Post Data Provider message categories
Category Description
I Information
O Operation
P Application
S System
N Network
A Alerts
C Critical
W Warning
R Reset
D Detail

Acknowledgment stamp
The Post Data Provider generates an acknowledgment stamp to uniquely identify
each message received from an application. The stamp is returned to the sending
application only if the application is connected to the Post Data Provider by a
connection-oriented TCP socket. For UDP sockets, the stamp is internally
associated with the received message, but it is not returned. Using the
acknowledgment stamp, you can quickly track and identify all Post Data Provider
messages while in the system.

The stamp
AAAAAAAATTTTTTTTTTTTCSSSSS

is comprised of four parts where:

AAAAAAAA is the origin of the message
TTTTTTTTTTTT is the local time of message arrival
C is the message category
SSSSS is the message one complement check sum

Customizing the Post Data Provider with metafiles

Like all other IBM Tivoli Universal Agent applications, you can modify the MAS
application through a metafile. However, the following restrictions apply to the MAS
application.
v The name of the metafile must be KUMPOST.
v The attribute delimiter, if specified, must be a single delimiter.
v The first three attributes must be specified exactly as shown in Figure 9 on page
54. Their names, data types, specifications, and order cannot be changed.

You can specify an application name, attribute group name, data type, and
time-to-live that are most appropriate to your site and you can define additional
attributes after the mandatory first three. However, the KUMPSEND program works

Chapter 4. About data providers 55

 only with the five default attributes. If you define additional attributes you must
develop your own program to format and send the added values to the data
provider. See “The KUMPSEND program” on page 57 for additional information.

Customizing the Post Data Provider runtime specifications

You can configure a number of the run time specifications for the Post Data
Provider using environment variables. Table 9 lists these variables and gives
descriptions of their function.
Table 9. Post Data Provider environment variables
Environment variable Description
KUMP_POST_DP_PORT Overrides the default Post Data Provider
listening port
KUMP_POST_APPL_NAME Overrides the application name defined in
the KUMPOST metafile
KUMP_POST_GROUP_NAME Overrides the name of the attribute group
defined in the KUMPOST metafile
KUMP_POST_APPL_TTL Overrides the time-to-live value of the
attribute group
KUMP_POST_CATEGORY Redefines default post categories or adds
new ones.

For example, you can find that the Post Data Provider satisfies most of your
requirements. However, you would like the name of the data provider managed
system to reflect your specific area of interest. You can override the application and
attribute group names using the variables KUMP_POST_APPL_NAME and
KUMP_POST_GROUP_NAME:
KUMP_POST_APPL_NAME=SYSTEM

KUMP_POST_GROUP_NAME=HelpDesk

The names of the managed system and the Application workspace entry now
become sourcename:SYSTEM00 and SYSTEM00, and the name of the report becomes
HelpDesk for easy identification and grouping of alerts and messages. See
Chapter 5, “Monitoring applications,” on page 99 for information on naming of
managed systems and workspaces.

You might also start another Post Data Provider with a different set of
specifications:
KUMP_POST_APPL_TTL=7200
KUMP_POST_APPL_NAME=BOB
KUMP_POST_GROUP_NAME=GENERAL

The associated Customer report, named BOBGENERAL, contains common inquiries

and messages to Bob, but they are deleted automatically after two hours (7200
seconds).

You can also add to, redefine, or remove the default category definitions. A
maximum of 16 message categories is possible. For example:
KUMP_POST_CATEGORY=(X=Experimental)

adds the category X to the Post Data Provider.

KUMP_POST_CATEGORY=(P=Programming)

56 IBM Tivoli Universal Agent: User’s Guide

 redefines category P from Application to Programming.
KUMP_POST_CATEGORY=(D=)

removes category D.
KUMP_POST_CATEGORY=(X=Experimental,P=Programming,D=)

specifies all three of the previous definitions in one statement.

Any predefined category that is not explicitly redefined or removed remains

unchanged.

Post Data Provider supplied data

The data transferred between the sending program and the Post Data Provider are
the values for the attributes defined by the KUMPOST metafile. The values for the
first three attributes—Post_Time, Post_Origin, and Post_Ack_Stamp—are supplied
by the Post Data Provider. A program needs to send values for only the remaining
attributes. In the case of the default metafile, sending attribute values for only
Post_Text and Post_Category.

For example, the data stream received by a Post Data Provider sent by an irate
user to the help desk might consist of only an inquiry, listed as critical:
Please help! System has been down for over an hour and I can’t do any work;c

The KUMPSEND program

The KUMPSEND program provides a command-line interface to the Post Data
Provider. This program works in conjunction with the five predefined attributes. If
you add more attributes to the application or you alter the sequence of attributes,
you must develop a new companion program for interacting with the Post Data
Provider through command line.

The KUMPSEND program receives requests by examining keyword oriented input

parameters. The syntax for the KUMPSEND command is:

kumpsend msg=”text” [cat=category] [dp=dp_hostname]

[port=dp_listening_port] [ack=Y|N]

where:
msg The message sent to the data provider, enclosed in double
quotation marks (““). Globalized input is accepted in this
parameter.
cat The category of the message. The default categories are shown in
Table 8 on page 55.
dp The host name of the data provider. The default is the local host.
port The port on which the target data provider is listening. The default
is 7575.
ack Indicates that an acknowledgment is required from the data
provider. The default is N.

For example, to send the information status message, “Hello World! I am ready
to go.” to the Post Data Provider at ENG1 without requesting an
acknowledgment, enter:
KUMPSEND msg="Hello World! I am ready to go." dp=ENG1

Chapter 4. About data providers 57

 To send an alert message to and request acknowledgment from the Post Data
Provider on host atlantis, enter:

KUMPSEND msg="Router NY-TC1 packet discard rate exceeds

threshold" dp=atlantis cat=a ack=yes

Enter a question mark (?) with the command to get help for keywords. For
example,
KUMPSEND ?

Sending data to the Post Data Provider

Communication between the sending program and the Post Data Provider is
straightforward.

Using a UDP socket

The sending program opens a UDP socket and sends the attribute value string to
the Post Data Provider. Do not expect a reply.

Using a TCP socket

The sending program does the following:
1. Opens a TCP socket and binds it to any local port.
2. Establishes a TCP session by connecting the TCP socket to the Post Data
Provider.
3. Sends the attribute value string to the data provider.
4. Waits to receive an acknowledgment stamp from the data provider.
5. Closes the TCP socket.

58 IBM Tivoli Universal Agent: User’s Guide

Script Data Provider
The Script Data Provider facilitates the collection of monitoring data by running a
script or program at regular intervals and parsing the script output to look for
errors, anomalies and threshold conditions by making it easy to specify the
following in a metafile:
v The script name to run
v The interval to run the script on
v The parameter list
v An optional set of environment variables to be placed in the script environment
prior to execution

The Script Data Provider is the final S in the consolidated ASFS Data Provider. If
you activate the ASFS Data Provider, which is the IBM Tivoli Universal Agent
installation default, you can import and use script metafiles.

Script metafiles
A script metafile requires a //SOURCE statement for every //NAME statement.
The //SOURCE statement must point to a path location on the local system where
a script file can be found. You must enclose the path name or script name in single
quotation marks if it contains embedded blanks.

Note: The script can reside on a network drive mapped to the local system as long
as the drive is accessible to the IBM Tivoli Universal Agent process and
drive access permissions have been granted.

Scripts of any type are eligible for monitoring provided that the appropriate script
interpreter is accessible to the Script Data Provider. Some examples of scripts
are:VBScript, shell script, Perl script, bat file, JavaScript™, and Rexx script. If
needed, the script interpreter command name must precede the script name on the
//SOURCE statement. For example:
//SOURCE SCRIPT c:\tools\perl.exe myscript.pl “arg1 arg2”

A script interpreter is not always necessary, as in the following examples,

//SOURCE SCRIPT sh.exe "-c myscript.sh arg1 arg2"
//SOURCE SCRIPT myprog.exe "arg1 arg2"
//SOURCE SCRIPT myscript.sh "arg1 arg2"

If you do not include the script interpreter command name, the system interprets
and reports the first value on the SOURCE line as the script.

Although it is called the Script Data Provider, you can specify in the script metafile
any program that writes messages to stdout. Additionally, you must provide the
full path name if the path to the script interpreter is not known to the calling IBM
Tivoli Universal Agent process. Although it is called the Script Data Provider, you
can specify any program that outputs messages to stdout in the script metafile.

Using the Script Data Provider

The Script Data Provider receives attribute data from the called scripts use of
stdout and stderr. Scripts launched by the Script Data Provider do not require any
Universal Agent awareness. They simply execute a command that sends data to
stdout, and the calling Script Data Provider thread reads stdout by virtue of
having redirected stdout before the script process was launched. The same is true

Chapter 4. About data providers 59

 of any messages sent by the script to stderr. When the Script Data Provider has
received the stdout or stderr values, it parses them into attribute values just as if
the data came from a socket, file, SNMP agent, or any of the other IBM Tivoli
Universal Agent input mechanisms.

You must place any arguments passed to the script inside double quotation marks
after the script name on the //SOURCE statement. You must be able to run the
script as an independent command. It cannot have dependencies on a larger
framework or subsystem that would prevent the script from being called from a
command line.

Because many scripts need environment variables set to run properly, the Script
Data Provider supports an envfile=<xxxx> parameter on the //SOURCE SCRIPT
statement. This envfile must contain a series of variable=<value>statements, one
per line. You must enclose the path to the envfile in single quotation marks if it
contains embedded blanks. Whenever a script is about to be launched, the Script
Data Provider sets every environment variable specified in the envfile and passes
that environment to the called script process. If the envfile size or last modification
date changes, indicating that the envfile has been updated, the contents of the file
are re-processed. Otherwise, the same environment variable settings will be in
effect for each script invocation.

To remain compatible with scripts or programs used for IBM Tivoli Distributed
Monitoring, certain environment variables are generated if they are not already
within a specified environment file. Not all values that IBM Tivoli Distributed
Monitoring uses are generated. The following table provides the generated value
name and default value:
Table 10. Generated environment variables
Value name Default value
MONITOR_ID The hash of the script to run, the arguments, and
the PROFILE_OID and ENDPOINT_OID
environment values if present in the
environment.
PROBE_ID The hash of the script to run, the arguments, and
the PROFILE_OID and ENDPOINT_OID
environment values if present in the
environment. Same as MONITOR_ID.
HOSTNAME The host name of the monitored system.
INTERP The supported values are: aix4-r1, solaris2,
linux-ix86, and hpux10.
MONITOR The script or program to run.
PROBE_ARG The argument string.
PROBE The script or program to run. Same as
MONITOR.
PREV_VALUE The last output from the script or program.
LASTSTAMP The timestamp when the last output was
obtained.

The Script Data Provider supports both interval-driven and demand-driven data
collection. If the INTERVAL=<nn>parameter is present on the metafile //NAME
statement, the script is launched whenever <nn> number of seconds has elapsed. If
the INTERVAL parameter is omitted, demand-driven data collection is in effect,

60 IBM Tivoli Universal Agent: User’s Guide

 which means the script does not execute unless either a situation interval occurs
for the application table associated with the metafile //SOURCE statement, or a
Tivoli Enterprise Portal workspace open or refresh occurs for the application table.

Scripts directory
When you install the IBM Tivoli Universal Agent, a scripts directory is created a
the same level as the metafiles and work directories. Store all of your script files in
this scripts directory so that you do not need to provide the scripts fully qualified
path name on the //SOURCE SCRIPT statement. When the Script Data Provider
processes a metafile that contains an unqualified script file, it automatically
searches for the file in the scripts directory.

Managed system names of Script Data Provider applications

If the script specified on the metafile //SOURCE SCRIPT statement is accessible
when the metafile is activated, a managed system name with the following format
comes on-line:
LocalHostname:ApplNameVV

where:
LocalHostname
The host where the IBM Tivoli Universal Agent is running,
ApplName
The name value specified on the metafile //APPL statement. See “APPL
statement” on page 117 for additional information.
VV The two-digit version suffix. See “Versioning of metafiles” on page 24

If the script file is not accessible at startup, the corresponding managed system
does not come online. Similarly, if the script file is renamed or deleted after
startup, its managed system goes offline. In both cases, the Script Data Provider
enters a wait/retry loop to periodically check whether the script has become
available. When that occurs, the managed system is brought online.

Like the File and Socket Data Providers, the Script Data Provider supports the
ManagedSystemName=xxxxxx parameter on the //SOURCE statement, which
allows the LocalHostname portion of the managed system name to be customized.
The ManagedSystemName parameter enables multiple related scripts that all have
the same attribute layout to be grouped under one //NAME statement, for
example:
//APPL MyAppl
//NAME AttrData K 300 AddTimeStamp Interval=60
//SOURCE SCRIPT c:\wmi\resmodel1.vbs “arg1” ManagedSystemName=ResModel1
//SOURCE SCRIPT c:\wmi\resmodel2.vbs “arg1” ManagedSystemName=ResModel2
//SOURCE SCRIPT c:\wmi\resmodel3.vbs “arg1” ManagedSystemName=ResModel3
//ATTRIBUTES ’;’
Attr1 R 512 Key @Attr1 help text

If this metafile were activated and all three scripts were accessible to the Script
Data Provider, the following three managed systems would be registered with the
Tivoli Enterprise Monitoring Server and inserted in the Tivoli Enterprise Portal
navigator:
ResModel1:MyAppl00, ResModel2:MyAppl00, ResModel3:MyAppl00

The local host name value is replaced by the ManagedSystemName=xxxxxx value.

The ManagedSystemName parameter offers the following benefits:

Chapter 4. About data providers 61

 v Reduces the number of situations that you must define. If each of the three
resource models above had its own //NAME statement, it would mean three
separate situations. But with this format, a single situation could be defined and
distributed to the three managed systems.
v You do not need to create multiple //NAME and //ATTRIBUTES definition
statements for different instances of the same input data, allowing a metafile to
be more concise.

Script authentication
A common script requirement is that a specially authorized user ID must run the
script to give the script access to protected resources. By default, every launched
script inherits the user ID of the IBM Tivoli Universal Agent process. On Windows
operating systems, the Windows Service "LocalSystem" account user ID is used. On
UNIX operating systems, the user ID that started IBM Tivoli Universal Agent is
used. If a script requires special authentication, you must supply a User= and
Pswd= parameter on the //SOURCE statement. If present, these values are used
by the Script Data Provider as the authorization credentials when launching the
script. The user indicated must be defined to the system and have execute
authority on the script that is going to run. If not present, you receive an error and
the script is launched with the user ID associated with the IBM Tivoli Universal
Agent process.

Another strategy for authenticating scripts is to configure the IBM Tivoli Universal
Agent so that its owning user ID has the necessary authority to run all scripts. On
Windows operating systems, reconfigure the IBM Tivoli Universal Agent service
through the Control Panel → Administrative Tools → Services applet. Change
"LocalSystem" to an actual user ID in the local domain. Similarly, on UNIX
operating systems, start the IBM Tivoli Universal Agent with a user ID that has the
required script run-time authority.

Sample script metafile

The following is a sample metafile that illustrates the Script Data Provider metafile
syntax:
//APPL MyAppl
//NAME AttrData K 300 AddTimeStamp Interval=60
//SOURCE SCRIPT listdrives.vbs “arg1 arg2” envfile=env.dat
//ATTRIBUTES ’;’
Attr1 D 128 KEY @Attr1 help text -FILTER={MATCH(0,#)}
Attr2 C 2147483647 @Attr2 help text
Attr3 C 2147483647 @Attr3 help text
DerivedAttr (Attr2 / Attr3) @DerivedAttr help text
//NAME Errors S 300 AddTimeStamp
//ATTRIBUTES
Message D 256 @Error message help text

The unqualified name, listdrives.vbs, means that the listdrives.vbs script file is
located in the IBM Tivoli Universal Agent scripts directory.

Filtering unwanted script output

Many scripts send special data rows to stdout, such as column headings and
copyright statements, that you normally would not want to see in the Tivoli
Enterprise Portal workspace. To filter out these data rows, you can use the -FILTER
parameter in your script metafile, for example:

62 IBM Tivoli Universal Agent: User’s Guide

//APPL Disk
//Name FreeSpace K 300 AddTimeStamp Interval=120
//Source Script cscript.exe listfreespace.vbs "/S myHost" Interval=60
//Attributes
DriveLetter D 4 KEY DLM=’:’ -FILTER={SCAN(0,Micr) OR SCAN(0,Copy)}
FreeSpace D 32

This sample script metafile invokes the Windows Script Host program, cscript.exe,
which commonly writes the following two header statements at the top of its
stdout:
v Microsoft (R) Windows Script Host Version 5.6
v Copyright (C) Microsoft Corporation 1996-2001. All rights reserved

To prevent these two data rows from appearing in the Tivoli Enterprise Portal
workspace, the first attribute in the script metafile includes a -FILTER parameter
that scans for the first 4 characters of those two data rows.

Note: Only the first 4 characters are specified because the DriveLetter attribute has
a maximum size of 4.
See “Filtering attributes” on page 162 for additional information on the FILTER
parameter.

Key attributes
If a script runs at regular intervals and generates the same basic data rows, the
Tivoli Enterprise Portal workspace shows these rows accumulating at each data
collection interval unless you designate one or more attributes as KEY in the script
metafile. Additionally, you must mark the attribute group with a ‘K’ to indicate
that it is a KEY table. For script metafiles, use KEY tables to prevent the same
retrieved rows from being added multiple times whenever the script executes.

When the Script Data Provider collects a new data row for an attribute group, it
checks if there are any KEY attributes and, if so, if they have the same values as a
previously collected data row. If that is the case, the new collected data row
replaces the previous row with the matching KEY values. The use of KEY
attributes provides a data correlation capability. To implement a script metafile
with KEY attributes, first analyze sample script output to determine if there are
any values which can logically be treated as indexes or keys.

Adding a LocalTimeStamp column

Include the AddTimeStamp parameter on the script metafile //NAME statement if
your script does not include the time when it executed as part of its stdout. This
parameter causes a LocalTimeStamp column to be automatically inserted in the
workspace. The LocalTimeStamp value is filled in by the Script Data Provider with
the local time when the script finished executing.

Chapter 4. About data providers 63

SNMP Data Provider
The SNMP Data Provider brings the functionality of Simple Network Management
Protocol (SNMP) management capability to IBM Tivoli Monitoring, allowing you to
integrate network management with systems and applications management. This
functionality includes network discovery, trap monitoring, SNMP queries, and
SET™ operations.

Through the SNMP Data Provider, the IBM Tivoli Universal Agent can monitor
any industry standard MIB or any MIB you supply. IBM Tivoli Monitoring creates
IBM Tivoli Universal Agent applications for you by converting the MIBs into data
definition metafiles. You can then monitor any MIB variable as an attribute. You
can also create your own customized SNMP applications to monitor multiple
attribute tables and multiple MIBs.

Through the SNMP Data Provider, the IBM Tivoli Universal Agent can monitor
any variable in an SNMP Management Information Base (MIB) as an IBM Tivoli
Monitoring attribute. This allows you to:
v View real time and historical workspaces showing values for all your MIB
variables on Tivoli Enterprise Portal.
v Create situations to monitor for and alert you to exception conditions.
v Create policies to automate responses to network alerts.

In addition, the SNMP Data Provider can:

v Automatically discover your TCP/IP network topology and dynamically post
changes as they occur.
v Collect enterprise MIB data.
v Monitor any SNMP traps sent to the data provider.
v Perform SNMP SET operations.
v Manage and configure any SNMP-enabled devices in your enterprise.
v Collect historical statistics from your SNMP-enabled devices

Managed system names of SNMP Data Provider applications

As a rule, SNMP Data Provider applications follow the same managed system
naming standard as other data provider applications:
<Hostname>:<ApplNameVV>

For example, for the MIB-2 metafile application, the corresponding managed
system name is <Hostname>:MIB-200.

The exceptions to this format are the managed system names for the NETWORK
and MANAGED-NODES, or hotlist, workspaces. See “NETWORK workspace” on
page 75 for additional information.Table 11 summarizes the formats for managed
systems.
Table 11. Managed system name formats
Managed system name Used for viewing...
host name:SNMP-MANAGERVV NETSUMMARY, ROUTER, TRAP, MIBSTATUS,
and MIBNODATA workspaces
hotListName:SNMP-MANAGERVV MANAGED-NODES workspaces
networkName:SNMP-MANAGERVV NETWORK workspaces

64 IBM Tivoli Universal Agent: User’s Guide

 Table 11. Managed system name formats (continued)
Managed system name Used for viewing...
hostname:mibApplicationNameVV a particular MIB application

The same managed system names are used when you distribute a situation. For
example, if you create a situation which includes attributes from the
MANAGED-NODES group, you must distribute it to hotListName:SNMP-
MANAGERVV. If you create a situation which includes attributes from the
NETWORK group, you must distribute it to networkName:SNMP-MANAGERVV.

Features of the SNMP Data Provider

The SNMP Data Provider is a full function SNMP manager capable of discovering
your network, querying SNMP agents, monitoring SNMP traps, and controlling
SNMP agents through SET operations. IBM Tivoli Universal Agent applications
with one to one mapping of MIB variables to IBM Tivoli Monitoring attributes
mean you can manage and control SNMP data just like any other data using the
capabilities of IBM Tivoli Monitoring.

Network discovery and management

An IBM Tivoli Universal Agent-defined application, SNMP-MANAGER, enables
you to discover your TCP/IP network topology, monitor SNMP traps sent to the
data provider, and manage and configure any SNMP-enabled devices in your
enterprise.

User-customizable applications
You do not create metafiles for SNMP applications as you do applications created
for use with other data providers. IBM Tivoli Monitoring creates them for you by
converting MIBs into metafiles. You can use the metafiles IBM Tivoli Monitoring
provides as the basis for customized applications. Include only the attributes you
are interested in and create your own attribute groupings, so you can track and
analyze problems in a single workspace window and create situations without
embedding.

Customized managed nodes lists (Hot Lists)

Managed node lists enable you to divide your enterprise network into small, easily
manageable segments, for which you can view workspaces, create monitoring
situations, and set up automation policies.

Flexible community name specification

The SNMP Data Provider accommodates variations in community names with a
community name table that can be updated or modified dynamically.

Symbolic name support

With its symbolic name table, the SNMP Data Provider enables you to use familiar
names instead of network addresses.

Specifying community names

The SNMP Data Provider performs two operations which require community
names:
v Network discovery
v MIB data collection

Chapter 4. About data providers 65

 The data provider allows you considerable flexibility in how you specify the
community names for these operations. The simplest methods of specifying
community names are:
v If you want to use the default, but the default is not public, use the environment
variable KUMP_SNMP_NET_COMMUNITY to specify the name that you want
to use as the default.
v If a specific community name should be used for a particular network address,
specify that name in the KUMSCOMM file.

Resolution of community names

During network discovery, the SNMP Data Provider attempts to collect mib-2
(RFC1213) data from devices. If no specific community name is indicated in the
KUMSCOMM file for a particular host or device, the data provider uses the default
specified by KUMP_SNMP_NET_COMMUNITY. If no default is specified, the
default public is used.

During the MIB data collection, the data provider resolves the community name in
the following order:
v If a community name is specified in the &AgentData field for the Take Action →
Monitor Start operation the specified name is used. See “Managed system names
of SNMP Data Provider applications” on page 64) for additional information.
v If no community name is specified for &AgentData, but a name is specified in
the KUMSCOMM file for the particular host or device, that name is used.
v If no name is specified in either the &AgentData field or the KUMSCOMM file,
the data provider uses the default specified by
KUMP_SNMP_NET_COMMUNITY.
v If no default is specified, the default public is used.

Specifying a default community name

To specify a different default community name for the SNMP Data Provider to use,
set the environment variable KUMP_SNMP_NET_COMMUNITY to the preferred
name:
KUMP_SNMP_NET_COMMUNITY=default_name

Specify the community name exactly as assigned because it is case-sensitive.

Specifying non-default community names

The community name table is a text file named KUMSCOMM, which resides in the
IBM Tivoli Universal Agent work directory. In this table, list all the network
resources you want to manage that do not accept the default community name
along with the name that they do accept.

The format for entries is:

agent_name/address community_name

For example:
alpha tiger
beta.tivoli.com osprey
10.10.32.1 yellowtail

The SNMP Data Provider reads the community name table at startup. But you can
add, change, or delete entries at any time, then activate the table using the console
command LOADCOMM:
kumpcon loadcomm

66 IBM Tivoli Universal Agent: User’s Guide

 This command is also available from the Take Action interface.

Assigning network symbolic names

The SNMP Data Provider enables you to refer to networks by their symbolic
names. The data provider supports symbolic names through a file named
KUMSNAME. After you have defined the symbolic names, they are used to refer
to the networks in all reports, and you can use them whenever you are required to
specify the network name or address.

Editing the symbolic name file

The KUMSNAME file resides in the working directory. The working directory is
the directory where the IBM Tivoli Universal Agent configuration files are located,
as indicated by the KUM_WORK_PATH environment variable. On Windows
operating systems, a separate subdirectory, named \work, is created for you at
installation and the variable KUM_WORK_PATH is preset to specify
IBM\Omegamon\TMAITM6\work as the working directory. On UNIX operating systems,
a separate subdirectory, named /work, is created for you and the variable
KUM_WORK_PATH preset to specify <install_dir>/$BINARCH/um/work directory,
where $BINARCH is the operating system and version.

To specify symbolic names for your networks, create a list of dotted decimal IP
network addresses, followed by their symbolic names:
10.10.18.0 LA-TEST

198.210.36.0 Chicago-DEV

10.10.32.0 Chicago-FIN

Observe the following conventions when you create the list of names:
v The trailing zero of the network address is optional
v The symbolic network name must be unique
v The names can contain only alphanumeric characters, dashes, and underscores

Activating the file

The SNMP Data Provider always reads the symbolic name file at startup. However,
you can add, delete, or change entries at any time, then activate the edited file
using the console command LOADNAME:
KUMPCON LOADNAME

This command is also available from the Take Action interface.

SNMP-MANAGER application
The SNMP-MANAGER application is comprised of the following seven attribute
groups:
v MANAGED-NODES
v MIBNODATA
v MIBSTATUS
v NETSUMMARY
v NETWORK
v ROUTER
v TRAP

Chapter 4. About data providers 67

 The attributes in these groups are discussed in “SNMP attributes” on page 166.
The workspaces based on these groups are discussed in “SNMP-MANAGER
workspaces” on page 72.

Sending SNMP traps to the data provider

The SNMP-MANAGER TRAP workspace contains information on traps received
by the data provider. You must configure your SNMP agents to send traps to the
host name where the IBM Tivoli Universal Agent SNMP Data Provider is running
to receive data in this workspace. When the trap data is being collected, you can
define situations against the SNMP-MANAGER TRAP table and specify reflex
actions and other forms of automation in response to these received alerts.

For more information

The SNMP Data Provider uses a configuration file named trapcnfg to render trap
information in a more easily readable form and to assign categories, severities,
status, and source IDs to traps. You can modify this file or use a different
configuration file. See Appendix D, “SNMP trap configuration,” on page 203 for
more information.

Starting the SNMP Data Provider

The SNMP Data Provider runs as a thread of the IBM Tivoli Universal Agent. You
start the data provider when you start the IBM Tivoli Universal Agent, either
manually or automatically.

Starting the SNMP Data Provider automatically

Use the KUMA_STARTUP_DP environment variable if you want the SNMP Data
Provider or any other data provider to start automatically when you start the IBM
Tivoli Universal Agent. By default, this environment variable is set to ASFS.
Therefore, to start the SNMP Data Provider, you must modify the
KUMA_STARTUP_DP environment variable.

On Windows operating systems, you directly update the environment variable in

the KUMENV file. During the command line installation on UNIX operating
systems, you indirectly update KUMA_STARTUP_DP by invoking the itmcmd
config shell script. This script prompts you for the data providers that you wish to
configure and takes the value you supply and updates the KUMA_STARTUP_DP
environment variable.

Starting the SNMP Data Provider manually on Windows

operating systems
Use the KUMA_STARTUP_DP environment variable to control which data
providers are activated. For example, KUMA_STARTUP_DP=ASFS,SNMP. However, if you
need to manually override your configured data providers and start the SNMP
Data Provider instead, use the Manage Tivoli Availability Services window on your
Windows operating system. Use the following steps to manually start the SNMP
data provider.

Note: Your configured data providers do not currently include SNMP.

1. If necessary, stop the IBM Tivoli Universal Agent.
2. Right-click the IBM Tivoli Universal Agent, then select Change Startup Parms
from the pop-up menu.
3. Type SNMP in the field.
4. Click OK.

68 IBM Tivoli Universal Agent: User’s Guide

 Starting the SNMP Data Provider manually on UNIX operating
systems
On UNIX operating systems, if you want to start the data provider manually
instead of using the data providers that you previously configured with the
itmcmd config shell script, you must start the IBM Tivoli Universal Agent from a
command line and specify SNMP as a parameter in the start command string. For
example:
itmcmd agent -o SNMP start um

This command starts the SNMP Data Provider even if a different data provider or
a set of data providers have been previously configured.

Stopping the SNMP Data Provider

The SNMP Data Provider is stopped automatically when you stop the IBM Tivoli
Universal Agent.

The console SHUTDOWN command

To stop the SNMP Data Provider without stopping the IBM Tivoli Universal Agent,
use the console SHUTDOWN command:
KUMPCON SHUTDOWN

If more than one data provider is running, the program prompts you to specify
which type you want to stop. The IBM Tivoli Universal Agent stops when all its
data providers are stopped through the console interface. This command is also
available from the Take Action interface.

Monitoring SNMP applications

This section discusses how to monitor your SNMP data using the Tivoli Enterprise
Portal. The Tivoli Enterprise Portal presents a set of workspaces for every SNMP
MIB application you monitor. Each workspace corresponds to an attribute group
defined in the application metafile, and each of the columns in the workspace
corresponds to an attribute in that group. See “IBM Tivoli Universal Agent SNMP
applications” on page 27 for information on SNMP applications.

In addition, IBM Tivoli Monitoring supplies a special application,

SNMP-MANAGER, which provides workspaces on your network topology and
any SNMP traps received by the SNMP Data Provider. The SNMP-MANAGER
workspaces are discussed in “SNMP-MANAGER workspaces” on page 72. The
SNMP-MANAGER attributes are discussed in “SNMP attributes” on page 166.

You can create and monitor hot lists that contain only specific devices or agents
that are critical to you. See “Using managed node lists (Hot Lists)” on page 79 for
additional information.

You can use the attributes defined in each application to create situations that alert
you to problems with monitored devices or to received traps or exception
conditions. See “Creating situations with SNMP application attributes” on page 83
for details specific to creating situations that you want to use with the SNMP Data
Provider.

Initiating MIB data collection

For your MIB workspaces to display data and for your situations to evaluate data,
you must initiate data collection by telling the SNMP Data Provider from which

Chapter 4. About data providers 69

 SNMP hosts to collect data, what community names to use, and how often to
sample for data. You do this using the Monitor Start option of the Take Action
feature.

Note: The data collection interval in effect is the shortest interval entered for all
Take Action data collection requests and IBM Tivoli Monitoring situation
sampling intervals for a particular attribute group. This is because a
common execution thread serves all requests for the group. The attribute
data is collected only once and shared by all outstanding requests.

Starting data collection: Use the following steps to use the Take Action feature to
start collecting MIB data:
1. Select the Navigator item associated with the application or system on which
you want to start the command.
2. Right-click the Navigator item or a row in a table view.
3. Select Take Action from the pop-up menu.
4. Select Monitor Start from the Name list.
The Edit Argument Values window is displayed.
5. In the Edit Argument Values window:
v For AgentData, specify the host names or dotted decimal addresses of the
SNMP agents you want to monitor and, optionally, a community name.
If you do not specify a community name, the default is used. See “Specifying
community names” on page 65 for information on specifying community
names.
If you do specify a community name, enclose the pair of host name or IP
address and community name in braces. For example:
Mars, Venus, {Jupiter viewx}, Pluto, {198.210.57.37 co98x}
As you can see in this example, with one Take Action request you can
specify a series of SNMP agents to query and you can use combinations of
host name, IP addresses, and community names.
If you want to poll an agent using a port other than 161, the default port,
indicate the target port within brackets immediately following the host name
or dotted decimal address.

Tip: To collect data for all SNMP agents within a given network, specify the
network portion of the IP address instead of the host address. For
example, if your network is a class C network and you specify
198.210.57, the data provider starts data collection for all appropriate
SNMP agents on hosts in the 198.210.57 network. If you have specified
a symbolic name for the network, you can use that name instead. See
“Assigning network symbolic names” on page 67 for additional
information.
To use this form of specification, the network must already have been
discovered by the data provider. The network address is ignored if it
has not been discovered or you have turned off network discovery
(KUMP_SNMP_NET_DISCOVERY=NO).
v For Interval, specify the interval, in seconds, at which you want the SNMP
Data Provider to poll the SNMP agent.
v For attrGroup (optional), specify the name of the attribute group for which
you want to collect data.
If you do not specify a particular attribute group, collection takes place for
all attribute groups in the selected MIB application.

70 IBM Tivoli Universal Agent: User’s Guide

6. Supply the SNMP agents, sampling interval, and attribute group.
7. Click OK.
8. For Destination Systems, select the system names that contain the MIB
application you want to monitor, then click OK.
You receive a message box confirming that data collection has been started for
the selected managed systems.
After you have initiated data collection, you do not need to start it again each
time you start the SNMP Data Provider. The data provider maintains
information about monitored SNMP agents in the KUMSMIBI configuration file
so that data collection will persist across restarts. To stop data collection, you
must issue a Take Action → Monitor Stop command.

Stopping data collection: To stop collecting data:

1. Select the Navigator item associated with the application or system on which
you want to start the command.
2. Right-click the Navigator item or a row in a table view.
3. Select Take Action from the pop-up menu.
4. Select Monitor Stop from the Name list.
The Edit Argument Values window is displayed.
5. In the Edit Argument Values window:
v For AgentData, type a comma-delimited list of the host names or IP
addresses of the SNMP agents for which you want to stop data collection.
For example,
Mars, Venus, Jupiter, Pluto
v If you want to discontinue polling of an agent using a port other than 161,
the default port, indicate the target port within brackets immediately
following the host name or dotted decimal address.

Tip: To stop collecting data for all SNMP agents within a given network, you
can specify the network portion of the IP address instead of the host
address. For example, if your network is a class C network and you
specify 198.210.57, the SNMP Data Provider stops data collection for all
appropriate SNMP agents on hosts in the 198.210.57 network. If you
have specified a symbolic name for the network, you can use that name
instead See “Assigning network symbolic names” on page 67 for
additional information.
v For attrGroup (optional), specify the name of the attribute for which you
want to stop data collection.
If you do not specify a particular attribute group, collection is stopped for all
attribute groups in the selected MIB application.
6. Click OK.
7. In the Take Action window, select the system or systems whose name contains
the MIB application you want to stop monitoring, then click OK.
You will receive a confirmation message box indicating that data collection has
been stopped for the selected managed systems.
You can browse the SNMP-MANAGER MIBSTATUS workspace at any time to
see a list of the applications and attribute groups for which data is being
collected on a particular host.

SNMP MIB data collection from non-standard ports: Certain vendor SNMP
agents can feature special requirements, such as using ports other than the default

Chapter 4. About data providers 71

 monitoring port of 161. You can specify alternate port assignments through
bracket-delimited port values to target an SNMP agent on a non-standard port. For
example, to indicate that the SNMP Data Provider should poll an agent on port
333 on a host called goby, specify:
goby[333]

in the AgentData field of the Monitor Start window. The bracket-deliimited port
specification also works in the AgentData field of the Monitor Stop Take Action
window, as well as in the TargetAgentAddr field of the SNMP Set window.

Automatic MIB data collection for discovered network resources: As network

nodes are discovered and added to a managed node list, or hot list, the IBM Tivoli
Universal Agent SNMP Manager can automatically start data collection of the
corresponding MIBs. You must satisfy the following conditions to allow automatic
MIB collection.

The automatic MIB collection applies to managed node list resources. You can
manually add these resources to the list, or automatically add during the discovery
process by IBM Tivoli Universal Agent.

You must pre-load the corresponding vendor MIBs. The MIB metafiles, vendor or
standard RFCs, are loaded to collect data. Only the required MIB metafiles are
included in the IBM Tivoli Universal Agent startup initialization file KUMPCNFG
to control the amount of data collection.

MIB data collection environment variables: The environment variable

KUMP_SNMP_AUTOSTART_MIB_COLLECTION controls automatic MIB data
collection. The default is Yes.

When a network resource is added to or activated from the managed node list, the
SNMP Manager first retrieves the resource’s identity and determines the
manufacturer’s enterprise OID. The IBM Tivoli Universal Agent then checks all
loaded MIB metafiles that belong under the vendor enterprise OID tree. Data
collections are automatically started for this node for all attribute groups of all
applicable MIB metafiles.

MIB II data collection environment variables: All SNMP agents support RFC 1213
MIB II attributes. Therefore, these attributes can be collected for all agents
regardless of their enterprise OID. You can control MIB II automatic data collection
by setting the environment variable
KUMP_SNMP_AUTOSTART_COLLECTION_MIB2. The default is No, which
means no MIB II agent data is automatically collected.

Viewing SNMP Data Provider workspaces

SNMP-MANAGER workspaces
The SNMP-MANAGER application provides seven workspaces which present
information about your networks, SNMP traps received, the MIBs and attributes
for which you are currently collecting data, any devices that you have identified in
a “hot list”, and all Tivoli Enterprise Monitoring Agent throughout your enterprise:
v MANAGED-NODES
v MIBNODATA
v MIBSTATUS
v NETSUMMARY
v NETWORK

72 IBM Tivoli Universal Agent: User’s Guide

v ROUTER
v TRAP

The following sections give descriptions of these workspaces. See “Using managed
node lists (Hot Lists)” on page 79 for more information on hot lists. See “SNMP
attributes” on page 166 for full descriptions of the SNMP-MANAGER attributes.

Accessing the SNMP-MANAGER workspaces: To access the SNMP-MANAGER

workspaces:
1. Double-click the SNMP-MANAGER item in the Physical view of the
Navigation tree.
The SNMP-MANAGER workspace items is displayed below the
SNMP-MANAGER item.
2. Select the item representing the workspace you want to view.
The default workspace is displayed.

MANAGED-NODES workspace: This workspace contains information about the

nodes you identified in your Hot List, as specified in the KUMSLIST configuration
file. It enables you to monitor information about the nodes you identified in your
managed node list.

Collected data for a MANAGED-NODES workspace is only displayed under

managed systems of the form: hotListName:SNMP-MANAGERVV. See Table 11 on
page 64 for Manage System Name formats.
Table 12. MANAGED-NODES workspace columns
Column Description
Address The IP address of the managed node host.
Current Response Time ms The current network response time for SNMP or ICMP
requests for the managed node as viewed by the
SNMP-MANAGER.
Name The host name of the managed node. If the node address
cannot be resolved through DNS, then the dotted decimal
IP address is shown.
Node Description The description of the node characteristics as defined by a
network administrator or device manufacturer.
Node Status The current operating status of the managed node.
Node Type The type of managed node. For example, general IP node,
application host, or gateway.
Status TimeStamp The date and time the node status was last checked.

MIBNODATA workspace: This workspace identifies the MIB tables to which

monitoring agents do not return data. If a workspace is consistently empty for a
particular attribute group in one of your SNMP MIB metafiles, you can check the
MIBNODATA workspace to see whether it is normal and expected for the attribute
group in question to return no data.
Table 13. MIBNODATA workspace columns
Column Description
Agent Name The monitoring agent name or address.
Enterprise Module The data collection MIB enterprise name.

Chapter 4. About data providers 73

 Table 13. MIBNODATA workspace columns (continued)
Column Description
No Data Tables A list of Enterprise tables for which the agent returns no
data.

MIBSTATUS workspace: This workspace enables you to tell at any point what
SNMP MIBs and attribute groups you are collecting data for and from which
SNMP agents. It also shows the currently active monitor interval and the last time
the data sample was collected.

Anytime you perform a Take Action → Monitor Start or a Take Action → Monitor
Stop, the information is updated in this workspace.
Table 14. MIBSTATUS workspace columns
Column Description
Attribute Group The name of the attribute group for which data is being
collected.
Enterprise The enterprise name of the MIB on which the monitored
application is based.
Monitor Agent Info A list target SNMP agent nodes and their corresponding
SNMP community name.
Monitor Interval The currently active data collection interval. This is the
shortest interval of all outstanding data collection requests.
Last Sample Timestamp The timestamp of the MIB attribute data set that is currently
available.

NETSUMMARY workspace: The NETSUMMARY workspace provides high level

information about the networks in your enterprise, such as number of active and
inactive nodes.

Table 15 lists the columns in the workspace and their descriptions.

Table 15. NETSUMMARY workspace columns
Column Description
Active Nodes The total number of network nodes in the network
that are currently active.
CurrRespTime ms The current network response time for SNMP and
ICMP requests as viewed by the SNMP-MANAGER
in milliseconds. If the environment variable
kump_snmp_net_discover_enterprise is set to No,
you will see a 0 in this column.
Inactive Nodes The total number of nodes in your network that are
currently inactive. If the environment variable
kump_snmp_net_discover_enterprise is set to No,
you will see a 0 in this column.
Managed Indicates whether or not nodes within your network
are actively managed. Use the NETWORK Detail
report to see details for the managed network.

74 IBM Tivoli Universal Agent: User’s Guide

Table 15. NETSUMMARY workspace columns (continued)
Column Description
MaxRespTime ms The maximum network response time for all SNMP
or ICMP requests as viewed by the
SNMP-MANAGER in milliseconds. If the
environment variable
kump_snmp_net_discover_enterprise is set to No,
you will see a 0 in this column.
MinRespTime ms The minimum network response time for all SNMP
and ICMP requests as viewed by the
SNMP-MANAGER in milliseconds. If the
environment variable
kump_snmp_net_discover_enterprise is set to No,
you will see a 0 in this column.
Network Address The address of the discovered network.
Network Mask The address mask of the discovered network.
Network Routers A list of the routers attached to the network.

NETWORK workspace: The NETWORK workspace presents detailed information

for individual networks in your enterprise. By default, only your local network,
where the SNMP Data Provider is running, is discovered and managed initially.
You can disable the default by setting
KUMP_SNMP_MANAGE_LOCAL_NETWORK=N in the IBM Tivoli Universal
Agent environment variable file. To discover and manage other networks
throughout your enterprise, you must start network discovery as explained in
“Network discovery” on page 78.

The managed system names take the following forms if you define the network
name in the KUMSNAME configuration file:
ip_address:SNMP-MANAGERnn

or
netname:SNMP-MANAGERnn

When you select a managed system, the detailed workspace you see has
information particular to that network.

Table 16 lists the columns in the NETWORK workspace and their descriptions.
Table 16. NETWORK workspace columns
Column Descriptions
Address The Internet network address of a node within a
managed network.
Description The description of the node characteristics as defined
by a network administrator or device manufacturer.
This attribute value corresponds to the RFC 1213
System Group sysDescr MIB variable specification.
Location The node location information as defined by a
network administrator. This attribute value
corresponds to the RFC 1213 System Group
sysLocation MIB variable specification.

Chapter 4. About data providers 75

 Table 16. NETWORK workspace columns (continued)
Column Descriptions
Name The host name of the network node. If the address of
a router cannot be resolved through DNS, then the
dotted decimal IP address is shown.
SNMP-Enabled Indicates whether or not an SNMP agent is active on
the network node.
Status The current operational status of the network node.
The possible node statuses are:
On-line The node has been contacted and is
operational.
Inactive The node is not operational and it is
not responding to SNMP Get
requests or ping requests.
Type The network type, as defined by the Internet
standard RFC 1213 System group sysServices MIB
variable specification.

ROUTER workspace: The ROUTER workspace contains information pertaining to

the routers in your discovered networks, such as current status and the number of
subnetworks defined to the router.

Table 17 lists the columns in the ROUTER workspace and their descriptions.
Table 17. ROUTER workspace columns
Column Description
Destination Networks A list of network addresses known to this router.
Route Count The total number of routable subnetworks defined to
this router.
Router Address The IP address of the discovered router.
Router Description A description of the router characteristics, as defined
by device manufacturer. This value corresponds to
the RFC 1213 System Group sysDescr MIB variable
specification.
Router Name The host name of a discovered router. If the address
of a router cannot be resolved through DNS, then the
dotted decimal IP address is shown.
Router Status The current status of the discovered router. The
possible statuses are:
Verify the SNMP Data Provider is in the
process of verifying router status.
On-line the router is active and operational
Off-line the router is not operational
Passive the router is a daemon and it is not
actively participating in network
operation

76 IBM Tivoli Universal Agent: User’s Guide

TRAP workspace: The TRAP workspace contains information about SNMP traps
reported to the SNMP Data Provider. You must configure your SNMP agents to
send traps to the host name where the SNMP Data Provider is running to receive
data in this workspace.

The SNMP Data Provider uses a configuration file named trapcnfg to render trap
information in a more easily readable form and to assign categories, severities,
status, and source IDs to traps. You can modify this file or use a different
configuration file. See Appendix D, “SNMP trap configuration,” on page 203 for
more information. Table 18 lists the columns in the TRAP workspace.
Table 18. TRAP workspace columns
Column Description
Alert Name The trap name as specified in the definition in the trap
configuration file.
Category The trap category as specified in the definition in the trap
configuration file.
Description The trap description as specified in the definition in the trap
configuration file. The maximum description length is 256
characters.
Enterprise Name The trap Enterprise name as specified in the trap configuration
file and looked up through the trap object identifier.
Generic Trap The generic trap number extracted from the received trap.
Possible values are:
0 ColdStart
1 WarmStart
2 LinkDown
3 LinkUp
4 Authentication Failure
5 EGPNeighborLoss
Object ID The SNMP object identifier that uniquely identifies the trap in
the MIB. The object ID is extracted from the received trap.
Severity The trap severity as specified in the definition in the trap
configuration file.
Source Name The host name or IP address of the SNMP agent that sent the
trap.
Source Status The status of the agent that originated the trap after sending it
as specified in the trap definition in the trap configuration file.
Source Type The type of the agent that originated the trap as specified in
the trap definition in the trap configuration file.
Specific Trap The enterprise-specific trap number extracted from the
received trap. Applies only when Generic_Trap = 6.
Time Stamp The date and time when the trap occurred. The timestamp
format is, CYYMMDDHHMMSSmmm.
Value List The variable binding (VarBind) data received in the trap
protocol data unit (PDU). The VarBind elements are converted
to their IBM Tivoli Monitoring attribute names if the
corresponding MIB metafile is loaded. Otherwise, they are
shown as Object ID.

Chapter 4. About data providers 77

 Network discovery
To begin discovery of networks other than your local network, use the Take Action
option, Manage Start. After you have initiated network monitoring, you do not
need to start it again each time you start the SNMP Data Provider. The data
provider maintains a persistent state between restarts. To stop network monitoring,
you must issue a Take Action → Manage Stop command. To exclude a particular
network from discovery, use the Take Action → Manage Exclude option.

Initiating network discovery: To initiate discovery:

1. Select the Navigator item associated with the application or system on which
you want to start the command.
2. Right-click the Navigator item or a row in a table view.
3. Select Take Action from the pop-up menu.
4. Select Manage Start from the Name list.
The Edit Argument Values window is displayed.
5. Type then network address in the SNMP field.
6. Type the frequency, in seconds, at which you want the network data updated.
7. Click OK.
8. Select the hostname:SNMP-MANAGERnn node, where hostname is the name of
the host where the SNMP Data Provider is running.
9. Click OK.
You receive a confirmation notification for the managed system with the
selected network address. After you recieve the confirmation, the Navigator
update pending indicator is displayed in the Tivoli Enterprise Portal because a
new managed system has been inserted into the Universal Data Provider
section of the Navigator. You can see the new managed system name by
collapsing and then expanding the Navigator tree. The managed system name
includes the network address of the network for which you started collection.
After you open your NETWORK workspace, you can see the data being
collected for the nodes in that network. If you have specified a network name
for the network, the managed system name includes that name instead of the
IP address.

Stopping network discovery: To end collection of network data, use the Take
Action option, Manage Stop. By default, the local network where IBM Tivoli
Universal Agent is running will always be managed whenever the SNMP Data
Provider is active. Management of this network can be manually stopped by
issuing the Take Action → Manage Stop command, but you must issue this
command after each IBM Tivoli Universal Agent restart.

To automatically disable management of the local network, use the environment

variable KUMP_SNMP_MANAGE_LOCAL_NETWORK which can be set to ’N’ in
the configuration file, as follows:
KUMP_SNMP_MANAGE_LOCAL_NETWORK=N

Note: If this environment variable is not present, local network management is the
default setting.

To stop discovery:
1. Select the Navigator item associated with the application or system on which
you want to start the command.
2. Right-click the Navigator item or a row in a table view.

78 IBM Tivoli Universal Agent: User’s Guide

3. Select Take Action from the pop-up menu.
4. Select Manage Stop from the Name list.
The Edit Argument Values window is displayed.
5. Type the network address in the SNMP field.
6. Select the hostname:SNMP-MANAGERnn node, where hostname is the name of
the host of the data provider or data providers you want to collect the data,
then click OK.
You receive a confirmation notification for the managed system with the
selected network address.

Excluding a network from discovery: You can exclude certain networks from
discovery, perhaps because they are backup networks or because you do not want
to burden them with network discovery inquiries. In this case, use Take Action
option Manage Exclude to exclude a particular network.

Note: Networks that are accessed through dial-up serial line interfaces such as ppp
or slip are automatically excluded. If you want to manage these networks,
you must manually issue Take Action → Monitor Start requests for them.
When a network is being actively managed, it will not be excluded.

To exclude a network:
1. Select the Navigator item associated with the application or system on which
you want to start the command.
2. Right-click the Navigator item or a row in a table view.
3. Select Take Action from the pop-up menu.
4. Select Manage Exclude from the Name list.
The Edit Argument Values window is displayed.
5. Type then network address in the SNMP field.
6. In the Yes/No field, type Yes to exclude the selected network or No to reset a
previously excluded network.
7. In the Destination Systems list, select the SNMP-MANANGER managed
system, then click OK.
You receive a confirmation notification for the managed system with the
selected network address. If the network is actively managed at the time you
make this request, you see that its managed system goes offline in the Tivoli
Enterprise Portal Navigator tree.

Using managed node lists (Hot Lists)

An average size network can contain hundreds or thousands of devices. This can
easily create problems of manageability and usability. One way to address these
problems is to compartmentalize management into small, well-understood pieces,
managing separately those devices critical to a particular application, a specific use,
a geographical location, or a part of the network backbone.

The SNMP-MANAGER application enables you to define and manage sets of

critical devices through managed node lists, or hot lists. For example, you can
define one list that contains everything critical to your Web services: firewall
devices, firewall server, Web server, and alternate server. You can define another
list that contains all the routers essential to keeping a particular office operational,
and a third that contains the servers that keep a distributed application on-line.

From your managed node list, you can view workspaces, define situations,
perform reflex actions, and run automation policies, just as you can for any other

Chapter 4. About data providers 79

 managed system. An example is to define a situation that looks for a Node_Status
attribut value of ″Off-line″ for any device on the list. The benefit of a managed
node list is that you can monitor basic on-line or off-line status for a set of servers
or other critical devices in your environment in a simple and low-overhead
fashion. A managed node list issues a ping at 30 second intervals to every device
in the list. If the device does not respond to the ping request, then the Node_Status
attribute is set to Off-line . Otherwise, it s set to On-line .

Creating a managed node list: A managed node list is a text file containing a list
name definition (optional) and a list of device and host names:
LISTNAME=TivoliWeb
www.tivoli.com
mercury[4500]
us07 ishtar
List name definition
The defined list name becomes part of the managed system name for the
node list. For example, the list name for the example above would be
TivoliWeb:SNMP-MANAGER00. If no list name is defined, the name of the
managed node list file is used. A managed system name cannot be longer
than 32 characters, so if your list name is longer than 17 characters, it will
be truncated from the right.
If the list name is displayed, the list name definition must take the
following form:
LISTNAME=listname

The list name specification does not need to be the first record of the
managed node list definition. However, if the list name is defined more
than once in the definition, the last specification is used as the name of the
managed node list.
Device and host names:
There is no limit to the number of network devices and hosts that can be
included in a managed node list. However, including too many entries
defeats the purpose of having a targeted list of critical devices and it
increases the overall workload.
One or more network devices can be specified in each record. To monitor
only a specific application running on a network node, specify the
application port enclosed in square brackets, as in the example above
mercury[4500].

Location of managed node list file: You must store the managed node list file in
the working directory. This is the directory in which the IBM Tivoli Universal
Agent configuration files are located as specified in the KUM_WORK_PATH
environment variable. On Windows operating systems, the default directory is
IBM\ITM\TMAITM6\work.

Activating a managed node list: You activate a managed node list using the
console command LOADLIST:
kumpcon loadlist managed_node_list_filename

or with the Take Action → Control LoadList command. The IBM Tivoli Universal
Agent keeps track of managed node lists by putting their file names in a file
named KUMSLIST. At startup, the IBM Tivoli Universal Agent reads KUMSLIST
and activates all the lists in it, so you have to activate each list only once.

80 IBM Tivoli Universal Agent: User’s Guide

Modifying a managed node list: To modify a managed node list, edit it, then
activate it using the LOADLIST command. The command checks to determine
whether a list of the same name is already active. If so, the running list is
deactivated and the new list becomes active.

Deactivating a managed node list: You can deactivate a managed node list by
editing KUMSLIST, which resides in the working directory. The SNMP Data
Provider checks KUMSLIST only at startup. To deactivate a managed node list
dynamically, create a file which has the same list name but contains no device
names, and then upload that file with the LOADLIST command.

Automatic grouping of resources by criteria: To ease the creation and

maintenance of network resource lists, the IBM Tivoli Universal Agent
SNMP-MANAGER application enables you to manage network resources by
certain criteria, such as a particular business function and its corresponding
resources.

For example, a managed node list could contain the identities of all network
resources belonging to a department, a financial application system, a geographical
location, or a group of network servers that support business operations. There can
be as many managed node lists defined as are required to manage the network
effectively.

In the managed node list file, instead of entering an itemized list of network
resources, you can define a resource filter. You are only allowed one resource filter
per managed node list file. Using the filter, IBM Tivoli Universal Agent
automatically includes discovered network resources in the managed node list.

The following filters are valid:

NAME [*]string[*] – Filter on network resource names that match or include the
defined character string.
*string Match names that end with the character string.
String* Match names that begin with the character string.
*string* Scan names that contain the character string.

DESC string - Scan for the defined character string in agent’s SNMP MIB II
SysDescr attribute reply.

TYPE type – Look for network resources of the defined type. Valid types are:

A – Applications

B – Bridges

G – Gateways

H – Hosts

R – Routers

EOID oid-string – Select the network resource of the defined enterprise OID from
the agent’s SNMP MIB II sysObjectID attribute reply.

The following four examples illustrate the managed node list filter usage.

Chapter 4. About data providers 81

 v NetWare managed node list includes all devices in which the sysDescr attribute
reply contains Novell.
LISTNAME=NetWare
FILTER=(DESC Novell)
v NewYorkOffice managed node list includes all network nodes with a host name
starting with NY.
LISTNAME=NewYorkOffice
FILTER=(NAME NY*l)
v NetCorporate managed node list contains all discovered network routers,
bridges, and gateways.
LISTNAME=NetCorporate
FILTER=(TYPE RBG)
v CISCO managed node list contains all CISCO routers and switches.
LISTNAME=CISCO
FILTER=(EOID 1.3.6.1.4.1.9.2)

Whenever the SNMP-MANAGER application discovers a new network device, it

checks every active managed node list filter. A device that satisfies a filter is
automatically added to the corresponding managed node list. Since the
SNMP-MANAGER examines all filters, a discovered device could get added to
multiple managed node lists.

The discovered network resources and the managed node list contents persist
across IBM Tivoli Universal Agent SNMP Data Provider restarts. You can use the
managed node list filter for a short period of time, to build the list of matching
network device names, and then remove or comment out the filter definition and
use the managed node list “as is”.

You can dynamically manipulate the managed node list contents with Take Action
requests. The Take Action request MNL Add Node adds a network resource to the
managed node list. The MNL Remove Node Take Action request removes a
network resource from the list.

The SNMP Manager tracks removed devices. A removed network resource is not
added back to the list during the discovery process. However, you can re-add the
removed network resource by using a MNL Add Node Take Action request.

Using the Universal Message Console (Hot Console)

By default, the IBM Tivoli Universal Agent sends the following information to the
Universal Message Console (UMC):
v SNMP traps with a severity of 2 or greater. Severity 2 is a Warning.
v Change in status of network nodes. Status includes on-line to off-line, off-line to
on-line.

Note: This is valid only for networks that are being managed, that is, the locally
connected network and any networks for which you have issued a Take
Action Manage Start request.
v Change in status of any host or device in a Managed Node list.

You can change which traps are forwarded, or turn off reporting altogether.

82 IBM Tivoli Universal Agent: User’s Guide

Specifying which traps to forward: Use the variable
kump_snmp_trap_console_sev to specify which traps are forwarded to the UMC.
All traps at the specified severity or above are forwarded. The default severity is 2:
KUMP_SNMP_TRAP_CONSOLE_SEV=2

Disabling UMC reporting: To turn off reporting to the UMC altogether, set the
variable kum_umc to No:
KUM_UMC=No

Creating situations with SNMP application attributes

You can create situations using any attribute you see in a workspace. You can
include actions in your situation that you want to start on the host where the
SNMP Data Provider is located and can embed in policies.

Special purpose attribute, Agent_Name: Each MIB attribute group has a special
purpose KEY attribute, named Agent_Name. Since you can specify more than one
host from which you want to collect MIB data, you can receive multiple rows of
the same attribute data, but each row coming from a different SNMP agent host.
The Agent_Name attribute is used to identify the originating host name for a
particular row of data. Agent_Name is useful in cases where you have initiated
data collection for multiple hosts, but want your situation evaluated for one
particular host.

For example, if you initiate MIB data collection and specify a network address to
collect data for all the hosts in a network, but you want your situation to only
evaluate data from host athens, include:
*SCAN MIB-2IFTABLE.Agent_Name *EQ athens

in your situation predicate.

In addition to being a KEY attribute, Agent_Name is also an ATOMIC attribute.

You can define Agent_Name as a Display Item in the Situation Editor. This allows
you to see which particular agent host caused a situation to raise.

See Appendix B, “Attribute definitions,” on page 151 for a description of KEY

attribute.

The Tivoli Enterprise Portal presents a set of workspaces for every MIB application
you monitor. Each workspace corresponds to an attribute group. In the workspaces
you see information from SNMP agents for which you have initiated data
collection. The Agent_Name column identifies the particular host that the row of
data pertains to.

Distributing situations: You can distribute situations to an SNMP Data Provider

managed system or to an SNMP managed system list. For example, for each
application you import into the SNMP Data Provider, you get a managed system
list named *CUSTOM_aaavv, where aaa is the application name and vv is the
version number for the application. Use a managed system list only if you are
running more than one SNMP Data Provider and you want to distribute a
situation to all of them. For performance reasons, use specific managed system
names whenever possible.

Specifying situation monitoring intervals: The situation monitor interval

specifies how often the Tivoli Enterprise Monitoring Server evaluates data for your
situation. It has no direct relationship to the sampling interval you specify when
you use Take Action → Monitor Start. The sampling interval specifies how often

Chapter 4. About data providers 83

 the SNMP Data Provider polls SNMP agents for MIB data. The data sampled from
the agents is queued for later evaluation by situations and is the data you see in
MIB application workspaces.

All SNMP application attribute groups have a time to live (TTL) of 3600 seconds (1
hour). This means that MIB data remains available for workspaces and situation
evaluation for one hour from the time at which it was received from SNMP agents.
Your situation interval must be less than 1 hour, or it never becomes true. See the
IBM Tivoli Universal Agent User’s Guide for more information on TTL.

Predefined SNMP situations: The SNMP Data Provider offers a set of predefined
situations that address some of the most common network exception conditions.
You can use these situations to begin exception monitoring almost immediately or
as templates for creating your own situations.

Table 19 on page 84 provides the names, descriptions, logic, and comparison values
for the product-provided situations.
Table 19. Product-provided situations
Name Description, Logic, and Values
MB2_interfaceDown A network interface is down
MIB-2IFTABLE00.ifOperStatus *EQ 2
MB2_interfaceInError Either the number of inbound packets that contained
errors which prevented them from being deliverable to
a higher-layer protocol was 20 or more, or the number
of inbound packets which were chosen to be discarded
even though no errors had been detected was 100 or
more.
MIB-2IFTABLE00.ifInErrors *GE 20 OR
MIB-2IFTABLE00.ifInDiscards *GE 100
MB2_interfaceOutError Either the number of outbound packets that could not
be transmitted because of errors is 20 or more or the
number of outbound packets which were chosen to be
discarded is 100 or more
MIB-2IFTABLE00.ifOutErrors *GE 20 OR
MIB-2IFTABLE00.ifOutDiscards *GE 100
MB2_ipInError This situation monitors three types of inbound IP
datagrams errors:
v The number of input datagrams discarded due to
errors in their IP headers is 5 or more.
v The number of locally-addressed datagrams received
successfully but discarded because of an unknown or
unsupported protocol 20 or more
v The number of input IP datagrams for which no
problems were encountered to prevent their
continued processing, but which were discarded, is
20 or more
MIB-2IP00.ipInHdrErrors *GE 5 OR
MIB-2IP00.ipInUnknownProtos *GE 20 OR
MIB-2IP00.ipInDiscards *GE 20

84 IBM Tivoli Universal Agent: User’s Guide

Table 19. Product-provided situations (continued)
Name Description, Logic, and Values
MB2_ipOutError Either the number of output IP datagrams for which no
problem was encountered to prevent their transmission
to their destination, but which were discarded is 20 or
more, or the number of IP datagrams discarded
because no route could be found to transmit them to
their destination is 20 or more
MIB-2IP00.ipOutDiscards *GE 20 OR
MIB-2IP00.ipOutNoRoutes *GE 20
MB2_ipFragmentationError The number of IP datagrams that have been discarded
because they needed to be fragmented at this entity,
but could not be, is 10 or more
MIB-2IP00.ipFragFails *GE 10
MB2_icmpError Either the number of ICMP messages which the entity
received but determined to have ICMP-specific errors is
20 or more, or the number of ICMP messages which
this entity did not send due to problems discovered
within ICMP (such as a lack of buffers) is 20 or more
MIB-2ICMP00.icmpInErrors *GE 20 OR
MIB-2ICMP00.icmpOutErrors *GE 20
MB2_tcpError The total number of segments received in error is 10 or
more
MIB-2TCPCONNTABLE00.tcpInErrs *GE 10
MB2_udpError The number of received UDP datagrams that could not
be delivered for reasons other than the lack of an
application at the destination port is 10 or more
MIB-2UDP00.udpInErrors *GE 10
MB2_egpError Either the number of EGP messages received that
proved to be in error is 10 or more, or the number of
locally generated EGP messages not sent due to
resource limitations within an EGP entity is 10 or more
MIB-2EGP00.egpInErrors *GE 10 OR
MIB-2EGP00.egpOutErrors *GE 10
MB2_egpNeighError Either the number of EGP messages received from this
EGP peer that proved to be in error is 10 or more, or
the number of locally generated EGP messages not sent
to this EGP peer due to resource limitations within an
EGP entity is 10 or more
MIB-2EGP00.egpNeighInErrs *GE 10 OR
MIB-2EGP00.egpNeighOutErrs *GE 10
MB2_snmpOperationViolations Either the total number of SNMP messages delivered to
the SNMP protocol entity which used a SNMP
community name not known to said entity has
exceeded 10, or the total number of SNMP Messages
delivered to the SNMP protocol entity which
represented an SNMP operation which was not allowed
by the SNMP community named in the message has
exceeded 10
MIB-2SNMP00.snmpInBadCommunityNames *GE 10
OR
MIB-2SNMP00.snmpInBadCommunityUses *GE 10

Chapter 4. About data providers 85

 Table 19. Product-provided situations (continued)
Name Description, Logic, and Values
NETWORK_not_responding A network is not responding within a reasonable
amount of time
*VALUE SNMP-
MANAGERNETSUMMARY00.Max_Resptime_ms *GT
500
ROUTER_status_offline A router is off-line
*SCAN SNMP-MANAGERROUTER00.Router_Status
*EQ Off-line
TRAP_category_errors An SNMP trap was received with the category “error”
*SCAN SNMP-MANAGERTRAP00.Category *EQ ‘Error
Events’
TRAP_severity_errors An SNMP trap was received with the severity “error:”
*SCAN SNMP-MANAGERTRAP00.Severity *EQ
Critical OR *SCAN SNMP-
MANAGERTRAP00.Category *EQ ‘Major Error’
HOTLIST_offline A managed node list item shows the status “off-line”
*SCAN SNMP-MANAGERMANAGED-
NODES00.Node_Status *EQ Off-line

SNMP SET operations

An SNMP SET operation is a way of changing the value of a MIB variable. The
IBM Tivoli Universal Agent enables you to perform SET operations using the Take
Action option.

Requirements: A SET operation requires the following information:

v The host name of the targeted SNMP agent
v The read-write community name that the SNMP agent accepts
v The name of the MIB variable that you want to change
v The new value

For the SET operation to succeed, the SNMP metafile that defines the MIB variable
must be currently activated, the MIB definition of the variable must allow write
access, and the SNMP agent must be programmed to handle SET operations on
that variable. The ACCESS read-write statement for the ipForwarding MIB variable
in the following figure is an example of an MIB definition of a variable allowing
write access.

Figure 10. Specification of write access in mib-2 variable definition

ipForwarding OBJECT-TYPE
SYNTAX INTEGER {
forwarding (1), -- acting as a gateway
not-forwarding (2) -- NOT acting as a gateway
}
ACCESS read-write
STATUS mandatory
DESCRIPTION
"The indication of whether this entity is acting
as an IP gateway in respect to the forwarding of
datagrams received by, but not addressed to, this
entity. IP gateways forward datagrams. IP hosts

86 IBM Tivoli Universal Agent: User’s Guide

 do not (except those source-routed via the host).

Note that for some managed nodes, this object may

take on only a subset of the values possible.
Accordingly, it s appropriate for an agent to
return a 'badValue' response if a management
station attempts to change this object to an
inappropriate value."
::= {ip 1}

Performing a SET operation: To perform a SET operation:

1. Select the Navigator item associated with the application or system on which
you want to start the command.
2. Right-click the Navigator item or a row in a table view.
3. Select Take Action from the pop-up menu.
4. Select SNMP SET from the Name list.
The Edit Argument Values window is displayed.
5. Fill in the fields as follows:
TargetAgentAddr
The name or address of the host of the SNMP agent whose variable
you want to modify. If you want to target an agent using a port other
than 161, the default port, indicate the target port within brackets
immediately following the host name or dotted decimal address.
Community
The community name that the agent accepts for write operations This
name is usually different than the community name used for read
operations.
AttributeName
The name of the attribute you want to modify. The value for
AttributeName is case-sensitive and you must specify it exactly as it is
displayed in the metafile.
SetToValue
The new value for the attribute.

Tip: To determine the exact spelling and case for the attribute, run the console
command KUMPCON VALIDATE against the MIB to create an output
report file. In the report file you will see the exact name used by the IBM
Tivoli Universal Agent for the attribute.
6. Click OK to return to the Take Action window.
7. Select the managed system corresponding to the MIB application in which the
variable is displayed.

Note: Remember that you can always check the UAGENT ACTION workspace
for detailed information on any Take Action command you issue.
8. Click OK.

Chapter 4. About data providers 87

Socket Data Provider
The Socket Data Provider enables the IBM Tivoli Universal Agent to manage data
on operating systems where it cannot be installed by implementing
program-to-program communication using the socket transport paradigm.
Figure 11 illustrates the role of Socket Data Provider.

Open System A

Data
Source

Open System B

Data
Data
Source
Source TCP/IP

Socket Data Universal

Provider Agent

Open System C Network

Data
Source

Open System D

Data
Source

Figure 11. Socket Data Provider

Contacting the Socket Data Provider

A sending program, also referred to as a socket client program, contacts the Socket
Data Provider in either of two ways:
v Opens a TCP socket and connecting it to the host of the Socket Data Provider.
v Opens a UDP socket and sending data to the host address of the Socket Data
Provider.

Note: Most scripting languages, such as REXX and Perl, offer socket APIs for
collecting and sending data, so you can implement the sending program in a
wide variety of ways, not just in a high-level language like C++ or Java.

88 IBM Tivoli Universal Agent: User’s Guide

Changing the default listening port
By default, the Socket Data Provider listens on port 7500. If socket port 7500 is
unavailable or you would prefer that the data provider use another port or if this
variable was automatically reassigned as a result of starting an alternate instance of
IBM Tivoli Universal Agent, set the environment variable KUMP_DP_PORT to the
correct listening port.

You can check the Socket Data Provider’s UAGENT DPLOG report after the Socket
Data Provider has started to verify that the status message clearly identifies the
appropriate listening port number for TCP, UDP, or both.

Host name and TCP/IP address translation

Host name and TCP/IP address translation are critical to the operation of the
Socket Data Provider. The system on which the Socket Data Provider resides must
be properly configured to use network name service for resolving host names and
translating TCP/IP network addresses. If the host name specified in the SOURCE
statement of a data definition metafile cannot be resolved, the SOURCE statement
is ignored. See “SOURCE statement” on page 126 for additional information.

Multiple host machines

Running a Socket Data Provider on a multiple host system, a system with more
than one network interface, requires special consideration. Generally, a system
resolves its own host name to the first installed network interface. If you prefer
that data provider traffic use another interface, you can set the environment
variable KUM_DP_HOSTNAME to the preferred host name.

Associating data sources with metafiles

It is important to understand how a socket client program becomes associated with
a particular metafile. Socket client programs are the data sources for socket
applications, and you must associate the correct client program with the correct
metafile or the incoming data is not processed correctly. In addition, the managed
system for a socket application does not come on-line in the Tivoli Enterprise
Portal Navigator until the socket client program has connected to the Socket Data
Provider and the metafile association has occurred.

When a socket client first connects to the Socket Data Provider, there is a potential
ambiguity in determining which metafile to associate the incoming data with. At
the time of the connection, the Socket Data Provider only knows the IP address
and port number of the client program. If only one socket metafile is activated,
then the Socket Data Provider clearly knows which metafile to use. But if multiple
socket metafiles are active, the Socket Data Provider relies on one of the following
methods to associate the client program with its metafile:
v Metafile SOURCE statement
v Explicit metafile specification

Association by metafile SOURCE statement

The simplest and most direct way to associate a socket client program with its
metafile is through the metafile //SOURCE SOCK hostname statement. You can
specify one or more SOURCE statements for each attribute group (//NAME
statement) in a socket metafile. You typically supply multiple SOURCE statements
if there are multiple host systems that could potentially connect and send data for
a particular metafile application. In that case, list a separate //SOURCE SOCK
statement for each host. For example:

Chapter 4. About data providers 89

 //SOURCE SOCK HostA
//SOURCE SOCK HostB
//SOURCE SOCK HostC

Note: You cannot list multiple host names on the same //SOURCE SOCK
statement.

See “SOURCE statement” on page 126 for additional information on the

//SOURCE statement.

When a client program connects and the Socket Data Provider has determined the
IP address and port number of the connecting program, the data provider scans
the host name values on all of the metafile //SOURCE SOCK statements that are
activated. The first matching //SOURCE SOCK host name statement is assumed to
be the correct metafile to associate with the client program.

The host name parameter of the //SOURCE SOCK statement indicates the origin
of the sending program in the form of an Internet dotted decimal address or a
resolvable host name, followed optionally by a port number. For example,
FIN1[4500] identifies data originating from host FIN1 at port 4500. If the specified
host name cannot be resolved to an IP address, the SOURCE statement is ignored.
If the port number is omitted, data originating from any port on that host is
acceptable. Specifying only the address 198.210.37.147 permits a program bound to
any port on host 198.210.37.147 to connect and send data to the Socket Data
Provider. You can also specify //SOURCE SOCK localhost as a way of indicating
that the socket client program is running on the same host system as the Socket
Data Provider.

Socket metafiles with one attribute group: The port number parameter is only
required to resolve ambiguity if the Socket Data Provider is managing multiple
socket client programs and multiple applications from the same host. The
application NCARPT has only one attribute group and it is the only active
application supplying data to the Socket Data Provider in the following example:
//APPL NCARPT
//NAME Overview P 900
//SOURCE SOCK JOHN
//SOURCE SOCK BOB
//ATTRIBUTES ';'
.
.
.

A socket client program from either host JOHN or host BOB can connect and send
data. In this scenario, there is no need to specify port numbers since no ambiguity
can arise.

However, when multiple socket metafile applications are known to the Socket Data
Provider and input from different client programs is possible from the same host,
port numbers help associate incoming data with particular applications, as
illustrated in the example below:
//APPL NCASYS
//NAME Process P 300
//SOURCE SOCK ENG1[4500]
//SOURCE SOCK ENG2[4500]
//SOURCE SOCK MIS2[4500]
//ATTRIBUTES '@'
.
.
.

90 IBM Tivoli Universal Agent: User’s Guide

//APPL NCANET
//NAME ALERT E 300
//SOURCE SOCK ENG1[3301]
//SOURCE SOCK ENG2[3301]
//SOURCE SOCK ENG3[3301]
//SOURCE SOCK TEST1[3301]
//SOURCE SOCK TEST2[3301]
//SOURCE SOCK TEST3[3301]
//ATTRIBUTES ' '
.
.
.

A socket client program bound to port 4500 on its local host system (ENG1, ENG2,
or MIS2) that connects to the Socket Data Provider is automatically associated with
the NCASYS application. Similarly, a client program bound to port 3301 is
associated with the NCANET application. If this example did not use port number
specifications and a client program bound to any port on, ENG2, for example,
connected to the Socket Data Provider, the wrong metafile application could get
selected for the input data.

Socket metafiles with multiple attribute groups: If a socket metafile has multiple
attribute groups, and one or more socket client programs from the same host
supplies data for these attribute groups, another form of ambiguity can arise. The
Socket Data Provider needs a way of knowing which attribute group each
incoming data record belongs to. There are two ways to resolve the ambiguity:
Port number parameter
Extending the previous example, if the application NCARPT includes more
than one attribute group, port number specifications can clarify which
attribute group each data record belongs to:
//APPL NCARPT
//NAME Overview S 900
//SOURCE SOCK JOHN
//SOURCE SOCK BOB
//ATTRIBUTES ' '
.
.
.
//NAME RedEvent E 3600
//SOURCE SOCK JOHN[1001]
//SOURCE SOCK BOB[2001]
//ATTRIBUTES ' '
.
.
.
//NAME RunStat S 120
//SOURCE SOCK JOHN[1002]
//SOURCE SOCK BOB[2002]
//ATTRIBUTES ' '
.
.
.

In this example, input data for the attribute group, Overview, is accepted
from any port on host JOHN or BOB as in the previous example. Input
data for the attribute group RedEvent, however, can only be received from
a connecting client program bound to port 1001 from host JOHN or port
2001 from host BOB. Similarly, input data for attribute group RunStat can
be received from programs bound to port 1002 and 2002 on hosts JOHN
and BOB, respectively.

Chapter 4. About data providers 91

 Prefixing data records
The disadvantage of associating attribute groups with specific port
numbers is that it is not very flexible and generally requires planning and
attention. The alternative is to use a special self-identifying prefix on every
data record sent to the Socket Data Provider. The format of the prefix is as
follows:
<ApplName=xxxx><AttrGroup=yyyy>the rest of your data...

where:
xxxx The name value specifed on the metafile //APPL statement.
yyyy The name value specified on the metafile //NAME statement.

If the Socket Data Provider receives a data row that begins with this
header, it searchs for a matching application and attribute group in its
in-storage list of online applications. If it finds a match, the Socket Data
Provider associates the received data row with that attribute group.
Therefore, you do not need to specify a [port#] parameter on the
//SOURCE SOCK statement. If you decide to use this data record
prefixing feature, use it for every data row that your socket client program
sends.

Association by explicit specification

You can also associate socket client programs and metafiles through the use of
explicit metafile association records. This method has the following rules:
v The first data record received by the Socket Data Provider from a client program
must contain an explicit application association record starting at offset zero.
Any remaining data in the record is not examined and is ignored. The
association record starts with two slashes, followed by the name of the metafile.
For example:
//myAppl
This example indicates that there is a file called myAppl.mdl in the metafiles
directory. You do not need to specify the .mdl file extension because it is
assumed. Additionally, do not be concerned with the possible differences in
character code representation between the program host and the host of the
target data provider. The data provider automatically detects the need for code
translation even though no metafile or SOURCE statement is yet known.
v The metafile must be available to the Socket Data Provider locally or it must be
retrievable from a centralized metafile server.
v If the metafile defines an application that includes only one attribute group, the
SOURCE statement is optional.
v If the application includes more than one attribute group, SOURCE statements
are required and their specification must not result in ambiguity. If the same
host name is inputting data for multiple attribute groups, either use the port
number method or data record prefixing method described earlier as a way to
resolve the ambiguity.
For example, a program from host MVSA contacts the Socket Data Provider on
system FIN1. The first data record received by the data provider, //JOBCNTL,
indicates that the metafile JOBCNTL.mdl should be used. If the metafile has not
already been loaded, the data provider loads it and discovers that there is no
SOURCE statement definition. The application NCAJOB includes only one
attribute group, PartList. Therefore, the data provider can readily associate the
connecting program with the attribute group PartList of application NCAJOB.

92 IBM Tivoli Universal Agent: User’s Guide

 Metafile: JOBCNTL.mdl
//APPL NCAJOB
//NAME PartList P 900
//ATTRIBUTES’,’
.
.
.
If the application NCAJOB contained more than one attribute group, a SOURCE
statement would be necessary, but only to the extent of preventing ambiguity
within the scope of the application NCAJOB.
The explicit association method is less rigid and easier to use than the SOURCE
statement method. In addition, it is unaffected by other active programs known
to the Socket Data Provider at the same time because, by explicitly specifying a
metafile, the scope of resolution has been narrowed to only one metafile
definition.

Formatting a socket buffer for transmission

The program sending data to a Socket Data Provider must format the data buffer
according to the metafile definitions. The order of values in the sending buffer
must match the order of attributes defined in the metafile and the record delimiter
used must be the one specified in the metafile.

For example, if your metafile has three attributes, your sending buffer should have
the value for the first attribute as the first token in the buffer, the value for the
second attribute as the second token, and the value for the third attribute as the
third token. If your ATTRIBUTE statement specifies a delimiter of ″;″, your sending
buffer must place a semicolon (;) between each value token.

Append a newline character, or carriage return if it is an EBCDIC platform, at the

end of every data row that you send to the Socket Data Provider. The newline
characters serves as a data row delimiter in case the buffer received by the Socket
Data Provider contains multiple data rows in it.

Timing out
UDP communication provides no state information to either sender or receiver.
When UDP communication is used, the Socket Data Provider employs the
following rules for determining the state of the sending program:
v For polled, sampled, and keyed data, the Socket Data Provider times out the
sending program after five TTL intervals without receiving data and notifies
IBM Tivoli Monitoring that the managed system is off-line.
v For Event data, the Socket Data Provider waits indefinitely for program input.

Sending action commands to socket clients

By default, any reflex actions or other automation commands that have been
distributed to a socket application managed system are executed on the local
system where the Socket Data Provider is running, not on the remote system
where the socket client program is running. You can request that actions are sent to
the socket client program by sending the following record after your client
program connects:
//SOCKET-COMMAND-ENABLED=Y

The receipt of this record causes the Socket Data Provider to route any automation
commands to the destination system of the socket client program.

Chapter 4. About data providers 93

 Note: Enabling this feature presupposes that your client program has opened a
read socket that is waiting for action commands to be received from the
Socket Data Provider.

End of input
At the conclusion of a data input session, the sending program can choose one of
two ways of ending the session and allowing the data provider to indicate off-line
status to IBM Tivoli Monitoring:
v The program sends the data provider the transaction end message shown below as
a single record, indicating the normal end of a session:
//END-DP-INPUT
v The program closes the TCP socket, which results in detection of connection
termination by the data provider.

Programs that use a UDP socket but omit sending the transaction end message,
time out after five TTL intervals, as discussed above. Programs that send Event
type data must send the transaction end message or they remain on-line to IBM
Tivoli Monitoring until system shutdown or until the program contacts the data
provider again.

Character code translation

The use of socket transport presupposes that the sending program resides on a
host other than the host where the Socket Data Provider is running. Therefore, it is
possible that the data representation of the sending program differs from that of
the Socket Data Provider. The data provider must be able to detect the difference
and handle translation between the two representations.

The necessity of character code translation is indicated in one of three ways:

v Specification of the code type in the SOURCE statement
v Specification of the locale and code page in the metafile SOURCE statement
v Explicit metafile association

Specifying code type in metafile SOURCE statements

The optional parameter code-type in the SOURCE statement is valid only for
sources of the SOCK type. This parameter defines the character code type of the
host of the sending program as either ASCII or EBCDIC. The default is ASCII. If
the code type of the host of the sending program differs from the code type of the
host of the Socket Data Provider, the data provider translates the data it receives
into the character data type of its own local host.

As an example, if a socket client program is running on an z/OS operating system

and it is communicating with the Socket Data Provider on AIX®, then you must
include the ’E’ parameter on the socket metafile SOURCE statement to signify that
the sending system is using EBCDIC, for example
//SOURCE SOCK MVSA E

Note: If the client program platform is EBCDIC but the program is sending UTF-8
data for a globalized application, do not include the E parameter.

Specifying locale and code page in metafile SOURCE statements

If the language and code page of the data that the socket client program is
inputting is not the default language and code page of the system where the IBM
Tivoli Universal Agent is running, you must specify the CODEPAGE and LOCALE

94 IBM Tivoli Universal Agent: User’s Guide

 keyword parameters on the metafile //SOURCE SOCK statement. These two
parameters tell the Socket Data Provider what character encoding to use when
processing the input data.

See “SOURCE statement” on page 126 for information on using the LOCALE and
CODEPAGE parameters.

Using an explicit association record

The Socket Data Provider checks the first data record it receives from a new
sending program for an explicit application association record. If a record is found
and the metafile is successfully loaded, the code type of the connecting program
has been determined and verified. If the specification of code type in the metafile
SOURCE statement does not agree with the code type determined at runtime, the
value determined at runtime overrides the SOURCE statement definition.

If you do not use explicit metafile association, you must make sure that the correct
code type for the host of the sending program is specified in the SOURCE
statement or make certain that the program and the Socket Data Provider run on
machines of like architecture.

Use of character format for numeric data

The Socket Data Provider and the sending client program can reside on machines
of different architecture with different internal representations of numeric data.
Therefore, the client program must send numeric data in character format instead
of in the system’s binary representation. When the Socket Data Provider parses the
received data into individual attributes, the character representation of numeric
values is converted to the local numeric format.

Managed system names of Socket Data Provider applications

The managed system name of a socket metafile application has the following
format:
Hostname:ApplNameVV

where:
Hostname
The host where the socket client program is running. This host is different
from the host where the IBM Tivoli Universal Agent is running if the
socket client is connecting from a remote system.
ApplName
The name value specified on the metafile application.
VV The two-digit version suffix.

Note: The managed system for a socket metafile application does not come online
in the Tivoli Enterprise Portal navigator until the socket client program has
connected to the Socket Data Provider.
You can customize the Hostname portion of the managed system name with the
//SETSOURCENAME record. You can utilize this feature if a socket application
collects data from a series of application servers, and it would be more meaningful
if the application server name were part of the managed system name, rather than
the host name where the socket client program is running.

The following two steps are required to enable the SETSOURCENAME feature:

Chapter 4. About data providers 95

 1. Add a setsourcename=y parameter on the //SOURCE SOCK metafile
statement. This parameter signals the Socket DP to expect a
//SETSOURCENAME record at the start of the connection.
2. Send a //SETSOURCENAME=xxxxxx record to the Socket Data Provider after
your client program connects. The xxxxxx value is used when registering the
managed system.
For example, if you send a //SETSOURCENAME=AppServer1 record to the
Socket Data Provider for the ThreadMonitor metafile application, then the
following managed system comes online:
APPSERVER1:THREADMONITOR00

TCP outage detection

TCP is a connection-oriented transport protocol. Connecting session partners
immediately detect session disconnections caused by a partner disconnecting or a
network outage. However, if a connecting partner system experiences a power
outage, its session partner cannot detect the interruption because there is no
session disconnect notification from either the connecting partner or the network
service.

The environment variable KUMP_TCP_OUTAGE_WINDOW makes it possible for

the Socket Data Provider to detect such system outages. When an outage is
detected, a managed system off-line notification is immediately presented on the
Tivoli Enterprise Portal.

The default value for this variable is 180 seconds. This enables the IBM Tivoli
Universal Agent to detect any connecting session outage within a three-minute
window.

You can increase detection window period by setting

KUMP_TCP_OUTAGE_WINDOW to a value higher than 180, or decrease the
window by setting a value lower than 180. If you do not need outage detection,
you can disable this feature by specifying a value of 0. Table 32 on page 209
provides the name and location of the variables file by operating system.

Investigate the characteristics of your monitored applications and your network

configuration before changing the default setting. A longer value delays
notification of session outages. A shorter value increases the IBM Tivoli Universal
Agent processing overhead.

Delay of TCP disconnection notification

The Socket Data Provider immediately detects the disconnection of the client
program’s TCP session. However, it can delay notification of IBM Tivoli
Monitoring to provide adequate opportunity for processing of the received data.

By default, the TCP disconnection notification is be withheld until the time-to-live

interval (TTL) has expired. See “NAME statement” on page 119 for additional
information on TTL. For example, an attribute group has a specified TTL of 180
seconds (3 minutes). The Socket Data Provider does not notify IBM Tivoli
Monitoring that the socket client program has disconnected until three minutes
after it has detected the TCP session disconnection.

To disable delay of TCP notification, set the environment variable

kump_tcp_disconnect_by_ttl to No.

96 IBM Tivoli Universal Agent: User’s Guide

Data acknowledgment
You can choose to have the Socket Data Provider acknowledge receipt of data from
a socket client program. This enables both the socket program and the data
provider to detect communication problems immediately and initiate corrective
procedures. Specify the acknowledgment requirement using the CONFIRM
statement. See “CONFIRM statement” on page 139 for further information.

Limitations of the Socket Data Provider

Because the Socket Data Provider is intended to extend system and application
management to unfamiliar operating systems using common tools with a
minimum investment in programming efforts, it is subject to a number of
limitations.

UDP programming is simpler than TCP. However, keep the following points in
mind in choosing UDP or TCP because the choice effects overall recoverability,
error detection, and delay in notifying IBM Tivoli Monitoring.

Limited error detection

A minimal protocol is defined between the Socket Data Provider and the sending
program. This makes it easy to develop an IBM Tivoli Universal Agent application
with minimal logic and programming complexity. However, error detection and
recovery is limited because no status is exchanged between a sending program and
a data provider, unless you use the CONFIRM feature See “CONFIRM statement”
on page 139 for additional information.

Use of TCP enables both the application and the data provider to detect
connectivity problems immediately and to initiate a problem recovery procedure.
With UDP, the parties can rely only upon problem time-outs for status.

Copy mode not supported

The Socket Data Provider does not support blocks of sample data such as the
COPY mode for files or the dp_BeginSample and dp_EndSample API calls, since
there is no defined protocol between a Socket Data Provider and a sending
program to implement this logical construct.

Chapter 4. About data providers 97

98 IBM Tivoli Universal Agent: User’s Guide
Chapter 5. Monitoring applications
This chapter discusses how to use the Tivoli Enterprise Portal to monitor your IBM
Tivoli Universal Agent applications. It covers the following:
v Naming of IBM Tivoli Universal Agent managed systems, workspaces, and
attribute groups
v Customer workspaces for monitoring IBM Tivoli Universal Agent applications
v UAGENT workspaces for monitoring the operational status of data providers
and the actions they support
v Creating situations and automation policies for IBM Tivoli Universal Agent
applications
v Collecting historical data

Monitoring IBM Tivoli Universal Agent data

With the Tivoli Enterprise Portal, you can monitor data from an IBM Tivoli
Universal Agent just as you can data reported by Tivoli Enterprise Monitoring
Agents. The Tivoli Enterprise Portal allow you to perform the following:
v View real-time and historical workspaces for every attribute group you monitor
v Monitor the operational status of data providers
v Create situations using the attributes you defined
v Create policies to automate responses to events on your monitored systems

IBM Tivoli Universal Agent managed systems

Each IBM Tivoli Universal Agent and each application monitored by an IBM Tivoli
Universal Agent is represented on Tivoli Enterprise Portal as a managed system.
The name assigned to a managed system enables you to identify the location of the
data, the corresponding IBM Tivoli Universal Agent application, and the version of
the metafile. When the version number of the metafile changes, a new managed
system comes online and the old one goes offline.

Managed system names

When an IBM Tivoli Universal Agent is started, it registers the following managed
system:
hostname:UA

where:
hostname
The name of the host on which the IBM Tivoli Universal Agent was
started. Each monitored IBM Tivoli Universal Agent application is
displayed in the Tivoli Enterprise Portal Navigator view as:
instname_sourcename:applnameVV

where:
instname Specifies the instance name of the IBM Tivoli Universal
Agent if a non-primary copy of the IBM Tivoli Universal
Agent is being started.

© Copyright IBM Corp. 2003, 2005 99

 sourcename Identifies the location of the data. For File, Script, ODBC,
HTTP, and SNMP Data Providers, sourcename is the host of
the data provider. For other data providers (Socket, Post,
API Server), the source name is the network location of the
client sending the data. For example, if a Socket Data
Provider is running on host PRDSRV1 and a socket client
program is sending it data from host newyork, the source
name component of the managed system name is newyork.
applname Specifies the name of the application defined in the
metafile.
VV Specifies the version number of the metafile.

For example, if a File Data Provider is running on system FIN1 supporting an IBM
Tivoli Universal Agent application and attribute group defined as
//APPL LOGS
//NAME SYSLOG E
//SOURCE FILE /syslog

and this is the first version of the metafile, the name of the managed system for
the attribute group would be FIN1:LOGS00.

Truncation of managed system names

If the length of the entire managed system name exceeds 32 characters, the source
name is truncated from the right to a maximum of 9 characters. If an instance
name is being used, it is truncated from the left until the total managed system
name length equals 32 characters.

Managed system version numbers

Each managed system is assigned a version number. The version number takes the
following form:
AA-VV.RR.MM

where:
AA The first two characters of the IBM Tivoli Universal Agent
application name.
VV The version number of the IBM Tivoli Universal Agent. The current
release is version 06.
RR The version number of the metafile.
MM The modification number of the metafile.

Managed system version changes

When the version number (RR) of a metafile changes, the following occurs. See
“Versioning of metafiles” on page 24 for additional information on changes that
cause the version of a metafile to change.
1. Managed systems with the previous version number go offline.
2. Managed systems with the new version number come online.
3. Managed system list entries are displayed with the new version number.
4. Any running situations distributed to previous versions of the managed
systems are automatically stopped.

100 IBM Tivoli Universal Agent: User’s Guide

 The names of workspaces and attribute groups also change. See “Application
names” on page 102 and “Attribute and attribute group names” on page 106 for
additional information.

Note: You cannot simply restart situations distributed to a previous version of a

managed system. You must create new situations or edit the existing ones to
use the new attribute group names and distribute them to the new versions
of the managed systems. The same applies to policies. For this reason,
attempt to make metafile changes that change only the modification number
and not the version number. See “Versioning of metafiles” on page 24 for a
list of changes that do not affect version number.

When the modification number (MM) of a data definition metafile changes the
following occurs:
1. Managed systems containing the previous version number go offline.
2. Managed systems containing the new version number come online.

You do not have to recreate and redistribute existing situations or policies when
the modification number changes. Change an existing situation only if you want to
use a newly added attribute as one of its predicates.

Application workspaces
The Tivoli Enterprise Portal incorporates a workspace for each attribute group
defined in a metafile application. You access IBM Tivoli Universal Agent
workspaces from the Attribute group level of the Navigator view. The Navigator
offers a high level view of your monitored enterprise. It can show the enterprise as
a physical mapping of systems and applications or as a logical view of entities,
such as the sales and payroll departments. The Physical and Logical tabs at the
bottom of the Navigator enable you to switch between these views.

Physical
The default Navigator view is Physical, with the following levels:
Enterprise
The highest level. It encompasses all the systems in your organization
where monitoring agents are installed.
Operating platform
The operating system the monitoring agent is running on, such as z/OS,
Windows, UNIX, or Linux® operating systems.
System
The name of the computer or z/OS image where monitoring agents are
installed.
Agent The monitoring agent installed on the system. If the agent name is dimmed
it means the agent is offline.
Some IBM Tivoli Monitoring products have both agents and subagents, for
example, MQSeries® and SAP R/3. In such cases another level is added to
subsume the subagents in the managing agent’s folder. Some Tivoli
Enterprise Monitoring Agents are grouped into one folder, particularly
those that have multiple agents of the same type on the same system. For
example, CICSplex, MQSeries, and IBM Tivoli Universal Agent.
Attribute group
The category of attributes the agent is monitoring. An attribute group is

Chapter 5. Monitoring applications 101

 made up of several or many individual attributes, each of which can be
used as a column in a table, a data series in a chart, or as a condition in a
situation. You can see some attribute groups consolidated under one title,
with multiple workspaces available.

Logical
The Logical view groups agents into managed objects. The managed objects and
the managed systems they represent are defined in the Tivoli Enterprise Portal.

Click the Logical tab to see the logical view. This view of the Navigator reflects the
hierarchy of managed objects. The assigned overview object is displayed as the top
level in the logical view. Any managed objects in the overview object are displayed
in the next level.

Application names
The name of the application takes the following form:
application_nameVV

where:
VV The version number of the metafile in which the application is defined.

Workspace names
The names of the Customer Workspaces correspond to the attribute groups for that
application. You select the managed system for which you want to view a
workspace when you open the workspace for that attribute group.

Customizing workspace contents

You can customize the contents of Customer workspaces, just as you can the
contents of other workspaces, in the following ways:
v Create customized workspaces that contain data for only a subset of managed
systems or attributes
v Sort columns on the basis of the value of the entries
v Include or exclude data according to criteria you specify
v Change the order of columns in the workspace

See the Tivoli Enterprise Portal Administrator’s Guide and the Tivoli Enterprise Portal
online help for instructions on customizing your workspaces.

Accessing help for applications, attribute groups, and

attributes
If help has been defined in the IBM Tivoli Universal Agent application metafile for
an application, attribute group, or attribute you can access it in the following ways:
v For information about a particular attribute group, select the attribute group
name in the Situation editor.
v For information about the columns that represent attributes in the workspaces,
mouse-over the column headings that represent each attribute.

See “Creating help for applications, attribute groups, and attributes” on page 17 for
additional information.

102 IBM Tivoli Universal Agent: User’s Guide

UAGENT workspaces
Every data provider registers the special purpose application, UAGENT, at startup.
UAGENT contains the DPLOG and ACTION attribute groups.

The purpose of the DPLOG attribute group is to surface status information for a
particular data provider. The purpose of the ACTION attribute group is to provide
information about the processing of automated actions from situations and policies.

Since each data provider is displayed as a managed system, you can develop
situations and policies for it, just as you can for any other managed system. This
enables you to manage all the data providers in an enterprise from the Tivoli
Enterprise Portal and achieve dynamic self-monitoring of IBM Tivoli Universal
Agent runtime operations. However, you cannot use automation or TakeAction on
the ACTION attribute group.

UAGENT managed system names

Managed system names for the UAGENT applications are constructed similarly to
the managed system names for IBM Tivoli Universal Agent applications. They take
the following form:
instname_hostnameDPtype:UAGENTVV

where:
instname The instance name of IBM Tivoli Universal Agent if a non-primary
copy is being started.
hostname The name of the host on which the data provider resides.
dpType The type of data provider. For example, FILEdp, SOCKdp,
ODBCdp, HTTPdp, or ASFSdp.
VV The version number of the metafile.

For example, the managed system name of a File Data Provider running on a
system named ENG1 is ENG1FILEdp:UAGENT00.

DPLOG workspace
The DPLOG workspace is similar to a system console log. It provides a detailed
audit trail for the data provider. The log workspace contains seven columns,
described in Table 20 on page 103.
Table 20. DPLOG workspace columns
Column name Description
DP Log Category The category of the log entry. The log categories currently
implemented are described in Table 21.
DP Log Text The detailed message text for the data provider log.
DP Name The managed system name for the data provider that issues
the log message.
DP Time The local time for the data provider log event message. The
format is, CYYMMDDHHMMSSmmm.
DP Type The type of data provider. Types include: ASFS, API Server,
Socket, File, Post, Script, SNMP, HTTP, and ODBC.
DP Version The current version number of the data provider.

Chapter 5. Monitoring applications 103

 Table 20. DPLOG workspace columns (continued)
Column name Description
DP Log MsgID The message ID associated with the DPLOG message text.

Table 21. Log categories

Category Description
SYSTEM Entries pertinent to general data provider operations such as
startup, shutdown, thread activities, operational status with
the IBM Tivoli Universal Agent, and periodic system statistics.
ERROR Entries relating to significant error conditions such as
unrecoverable file I/O, execution environment errors,
configuration definition errors, and internal processing errors.
WARNING Messages for noncritical situations such as application data
definitions not defined or an application already registered
with the IBM Tivoli Universal Agent, or circumstances where
default actions were taken or default values were supplied
during normal processing.
INFO Detailed audit trails of processing activities. They represent
general data provider status and work requests, such as
console commands received and processing results, application
definition activities, and reasons for delay in monitoring a file.
APIINFO Informational log entries pertinent to API Data Provider
activities. Examples: dp_Define, dp_Redefine, dp_BeginInput,
dp_EndInput API calls.
APICOMM Communication activities between the API Data Provider and
the client programs such as dp_OpenSession and
dp_CloseSession API calls.
SNMPINFO Informational messages related to interactions with the SNMP
Data Provider. Examples: Trap configuration definitions
loaded, MIB data collection start request, or SNMP network
management started
METAINFO Informational messages related to interactions with the
centralized data provider metafile server. Examples: processing
of a metafile request by the server, outcome of a metafile
retrieval
METACOMM Communication activities between data provider metafile
client and the data provider metafile server. Examples: data
provider metafile client successfully connected to the server,
connection failure and status of automatic retry, or
disconnection detected by either party.
SOCKCOMM Communication activities related to Socket Data Providers.
Examples: new TCP connection accepted, new UDP partner
recognized, connection abandoned due to configuration
mismatch, or UDP partner timed out due to inactivity

ACTION workspace
The ACTION workspace contains eight columns. These columns are described in
Table 22. You can create situations and policies based on ACTION attributes just as
you can with any other workspace attributes.

104 IBM Tivoli Universal Agent: User’s Guide

 Table 22. ACTION workspace columns
Column Description
Action ID The IBM Tivoli Universal Agent internally generated action
sequence number used to keep track of the action activities
and progress.
Action Type The type of action. For example, Reflex or Policy
automation.
Action Owner The name of the object (situation or policy) that initiated
the action. Take Action items are viewed the same as
policies.
Action Node The name of the managed system that is processing the
action.
Action Name The name of the action to run or command to execute.
Action Parms The exact input parameters to pass to the action program or
command.
Action Status The status of the action request. An action can include a
number of stages and the status reflects the progress of the
action as it is handled by various operation components.
Action Results The first 256 characters of the output of the action
processing.
Action Time The timestamp when the action was triggered.

IBM Tivoli Universal Agent situations

This section covers information specific to creating IBM Tivoli Universal Agent
situations. Refer to the Tivoli Enterprise Portal Administrator’s Guide or the online
Help provided with the Tivoli Enterprise Portal for detailed instructions on
creating situations.

A situation is a logical expression involving one or more system conditions.

Situations are used to monitor the condition of systems in your network. You can
manage situations from the Tivoli Enterprise Portal by using the situation editor.

About predefined situations

The Tivoli Enterprise Monitoring Agents you use to monitor your system
environment are shipped with a set of predefined situations, also referred to as
product-provided situations, which you can use as-is or modify to meet your
requirements. All of the predefined situations are set to activate at startup, but you
must assign them to the managed systems on which you want them to run.

Predefined situations contain attributes that check for system conditions common
to many enterprises. Using predefined situations can improve the speed with
which you can begin using the IBM Tivoli Monitoring products. You can examine
and, if necessary, change the conditions or values being monitored by a predefined
situation to those best suited to your enterprise. There are over 20 predefined
situations that are installed with the IBM Tivoli Universal Agent. All of these
situations are used with the SNMP Data Provider. See Table 19 on page 84 for the
complete list of SNMP situations.

Note: Before you modify a predefined situation, make a copy to ensure fallback if
necessary.

Chapter 5. Monitoring applications 105

 Using situations
Modify situations from the Tivoli Enterprise Portal using the Situation editor. You
can do the following when you use the Situation editor:
v Create a situation
v Save a situation
v Display a situation
v Edit a situation
v Start, stop, or delete a situation
v Investigate the event workspace for a situation

When you open the Situation editor, the left frame initially lists the situations
associated with the Navigator item you selected. When you click a situation name
or create a new situation, the right frame of the Situation editor opens to provide
you with the following information about the situation or to let you further define
that situation:
Condition See, add to, and edit the condition being tested
Distribution See the systems to which the situation is assigned
and assign the situation to systems
Expert Advice Write comments or instructions to be read in the
event workspace
Action Specify a command to be sent to the system.
You can also type take action commands by adding
a take action view to a workspace, selecting Take
Action from the pop-up menu for an item in the
Navigator’s physical view, or creating take action
commands and saving them for later use.
Until Reset a true situation when another situation
becomes true or a specified time interval elapses

Attribute and attribute group names

The attributes that you have defined are displayed in the Select Attribute window
which is displayed when you place a predicate object into the workspace of the
Situation editor. The name of the attribute group name is the same as the
workspace that contains data from that group. The names of the attributes in the
group are the same as the column headings in the workspace.

Creating situations with attributes from different groups

You can only create situations that use attributes from the same attribute group. If
you want to use attributes from different groups in your situation, you must create
another situation and embed it in the first. Alternatively, you might consider
creating a new group that contains all the attributes you want to include in the
situation.

Distributing situations to managed systems

After you create a situation, you distribute it to the managed systems on which
you want it to run. You can distribute the situation to any managed system whose
name contains the application name. For example, if the name of the attribute
group is UL3SYSLOG00, you can distribute the situation to any managed system
whose name takes the form hostname:UL300.

106 IBM Tivoli Universal Agent: User’s Guide

 You can always distribute your situation to the *CUSTOM_AAARR Managed System
List, where:
AAA The name of the application
RR The version number of the metafile

Use specific system names for better performance.

Monitoring interval and time-to-live value

If an application attribute group is defined as event (E) type data in the metafile
NAME statement, you do not need to specify a monitoring interval for situations
using attributes from that group. If the attribute group is of the sampled (S), polled
(P), or keyed (K) data type, you need to take the time-to-live (TTL) value into
consideration when you set the monitoring interval.

Specify a TTL to indicate how long the data provided by data providers is
considered valid for evaluation. The TTL value you specify affects both how
situations are evaluated and what you see in the IBM Tivoli Universal Agent
application workspaces.

When you create a situation and distribute it to a managed system, it gets

evaluated by the IBM Tivoli Universal Agent. The IBM Tivoli Universal Agent
ignores any data rows that have an expired TTL —that is, where the age of the
data is greater than the TTL. This means that if you specify a small TTL relative to
your situation sampling interval, your situation can not raise when you think it
should. To avoid this, choose a situation sampling interval smaller than your TTL
or increase your TTL.

The IBM Tivoli Universal Agent emits data for situation evaluation as long as the
TTL has not expired. If the situation monitoring interval is shorter than the TTL,
the situation remains raised for the duration of the TTL.

A sample set is one sample of data that consists of multiple rows of data. For
example, if you are using the File Data Provider and you specify Copy mode in
your SOURCE statement, you are indicating that your samples consist of multiple
rows of data, because of the nature of Copy mode processing. That is, every time
the File Data Provider samples the log file it emits a sample set consisting of all
records in the log file.

The IBM Tivoli Universal Agent treats the sample set as one sample. This means
that the TTL you specify applies to the entire sample set. After the TTL expires,
none of the individual rows making up the sample set are available for workspaces
or for situation evaluation.

Historical data collection

You can use the facilities of the Tivoli Enterprise Portal historical data collection
function to store and save the data that is collected by your IBM Tivoli Universal
Agent or agents. The historical data collection function permits you to specify the
following:
v The attribute group or groups for which data is collected.
v The interval at which data is collected.
v If you choose to use the warehouse, the interval at which data is warehoused.

Chapter 5. Monitoring applications 107

 v The location, either at the agent or at the Tivoli Enterprise Monitoring Server, at
which the collected data is stored.

You can find information about using the Historical Data Collection function in the
Tivoli Enterprise Portal online Help and in the Tivoli Enterprise Portal
Administrator’s Guide.

108 IBM Tivoli Universal Agent: User’s Guide

Chapter 6. Introducing the SNMP emitter
This chapter provides the following information for the IBM Tivoli Universal
Agent SNMP Emitter:
v An introduction to the IBM Tivoli Universal Agent SNMP Emitter
v Instructions for installing and integrating the SNMP Emitter
v Establishing parameters
v Using SNMP Emitter data

Understanding the SNMP emitter

Increasingly, system administrators face the challenge of managing information in
distributed, heterogeneous environments with multiple focal points and different
management tools. The SNMP Emitter is an interface between IBM Tivoli
Monitoring and third-party SNMP managers such as HP OpenView, Netcool, and
CA-Unicenter.

The SNMP Emitter, also referred to as the SNMP Activity Agent, integrates
information from IBM Tivoli Monitoring products with data from third-party
products on a single system. It sends event data monitored by IBM Tivoli
Monitoring products to a third-party manager.

This is the preferred way of integrating best-of-breed solutions like IBM Tivoli
Monitoring into the large-scale frameworks.

The SNMP Emitter provides the following:

Simplifies system and application management
View alerts from applications, operating systems, and resources across your
computing environment from a single focal point of your choice.
Enhances system performance and availability
Correlate information from different management tools to more effectively
manage your networked systems.
Increases efficiency
Allows you access to information so you can troubleshoot system problems
more effectively. Use situations to ensure that you receive only those alerts
you consider important.
Provides flexibility
Allows administrators and operators to use the management tools they are
most familiar with to monitor information, regardless of where it is
collected.

The SNMP Emitter is supported on all IBM Tivoli Universal Agent-supported

operating systems. The SNMP Emitter sends traps in SNMP Version 1 format.

The SNMP Emitter uses native operating system services to communicate events to
a designated SNMP management application running on any host. It has no
dependencies on any operating system SNMP services and can co-exist with other
operating system SNMP services. When an event occurs—that is, when the status
of a situation monitored by an IBM Tivoli Monitoring product changes from False
to True—the Tivoli Enterprise Monitoring Server collects and stores information

© Copyright IBM Corp. 2003, 2005 109

 about the event. If a IBM Tivoli Universal Agent policy with the SNMP Emitter
exists, an SNMP trap is forwarded to a designated SNMP manager.

SNMP emitter environment variables

Designate the hosts to receive the traps in one of two ways:
v As an environment variable named KUMP_TRAP_DESTINATION
v Use the Trap Destination parameter in the SNMP Emitter policy definition

An SNMP trap contains an SNMP community name, which an SNMP manager can
choose to use. By default, this is the public community name. You can change this
default name to another name through environment variable
KUMP_TRAP_EMIT_COMMUNITY.

KUMP_TRAP_DESTINATION
v No default
v Defines the host names where SNMP managers are running. You must separate
multiple host names by commas.

KUMP_TRAP_EMIT_COMMUNITY
v Default is <public>
v Defines the community name for which the SNMP manager is configured.

Installing and integrating the SNMP emitter

Use the following procedures to install and integrate the SNMP emitter.

Installing the SNMP emitter

To install the SNMP Emitter:
1. Install the IBM Tivoli Universal Agent. The SNMP Emitter feature is fully
integrated into the IBM Tivoli Universal Agent installation, and the SNMP
Emitter starts automatically when the IBM Tivoli Universal Agent is started.
2. The SNMP Emitter’s catalog file kum.cat needs to be located in your hub Tivoli
Enterprise Monitoring Server RKDSCATL directory.
3. The SNMP Emitter’s attribute file kum.atr needs to be located in your hub
Tivoli Enterprise Monitoring Server ATTRLIB directory. If you have an
z/OS-based Tivoli Enterprise Monitoring Server, then you need to install the
KUMATR and KUMCAT files into your RKANDATV PDS.
4. The SNMP Emitter’s ODI file dockum needs to be located in your Tivoli
Enterprise Portal Server TAPS directory.

Note: There is no required connection or dependency between the SNMP Data

Provider and the SNMP Emitter. Use the SNMP Emitter without
activating the SNMP Data Provider. You can also use the SNMP Emitter
to emit traps for other agent products besides the IBM Tivoli Universal
Agent.

Integrating the SNMP emitter into third-party solutions

The traps sent out by the SNMP Emitter need to be integrated into an SNMP
manager and its console. Examples of SNMP managers are HP OpenView or
Netcool. To enable these solutions to interpret the trap information properly you
must announce its structure. The structural information is stored in the files
CANBASE.MIB and CANSYSSG.MIB, distributed with the IBM Tivoli Universal

110 IBM Tivoli Universal Agent: User’s Guide

 Agent product.These files are located in the <install_dir>/$ARCH/um/mib
directory on UNIX operating systems and the \IBM\ITM\TMAITM6 directory on
Windows operating systems. However, announcing the information to the specific
SNMP manager is different for each manager. See your SNMP Manager manuals
for information on how to accomplish this task.

Using the SNMP emitter and its data

Use the following information to establish the SNMP emitter parameters and to
use SNMP emitter data.

Establishing SNMP emitter parameters

The SNMP Emitter is accessed from within the Tivoli Enterprise Portal workflow
editor. Create the IBM Tivoli Monitoring situations you want to monitor first. With
your situations in place, you can create one or more policies where the initial
activity is the situation evaluation and a subsequent activity is the SNMP_Event
activity. Perform the following steps to establish SNMP emitter parameters:
1. Select the SNMP_Event icon from the workflow components Emitter activities
tab.
2. Provide the following parameters in the Emitter Settings window:
Emitter target
Select any IBM Tivoli Universal Agent data provider managed system
from the drop-down box. Select one of the data provider managed
systems associated with the UAGENT application. These all have
managed systems called:
HostNameDPTYPEdp:UAGENT00

where:
hostName
The DNS host name where the IBM Tivoli Universal Agent is
running
DPTYPE
The 4-character data provider type, followed by the dp literal.
Data provider examples include: ASFS or SNMP.
Severity
Select one of the following predefined severities:
v Cleared
v Indeterminate
v Warning (default)
v Minor_error
v Critical
v Major
By default, this severity value is only displayed in the trap variable
binding information on the receiving system. If you want the
policy-defined severity to also show up as the Severity value on the
receiving system, set the following environment variable:
KUMP_TRAP_USE_POLICY_SEVERITY=Y
Category
Select one of the following predefined categories:
v Threshold_Events (default)

Chapter 6. Introducing the SNMP emitter 111

 v Network_Topology_Events
v Error_Events
v Status_Events
v Node_Configuration_Events
v Application_Alert_Events
v All_Category_Events
v Log_Only_Events
v Map_Events
v Ignore_Events
TrapDestination
Type one or more IP addresses/host names to receive the traps. If you
use a host name, it must be a resolvable DNS name. If more than one
entry is specified, you must separate them by commas. For example,
Granite, 10.60.152.53, athens.
As an alternative approach, you can specify the environment variable
KUMP_TRAP_DESTINATION in the IBM Tivoli Universal Agent
environment variables file. This variable follows the same format and
rules as TrapDestination. If the TrapDestination parameter is left at
_DEFAULT, then the alerts are sent to the host names identified
through KUMP_TRAP_DESTINATION.

Note: You do not need to specify both the TrapDestination parameter

in the Emitter Settings window and the
KUMP_TRAP_DESTINATION environment variable. If both are
specified, the TrapDestination parameter takes priority.
Specifying the TrapDestination parameter in the Policy definition
allows for more granularity if there is a need to send different
traps to different SNMP managers. But if the destination is
always the same group of one or more IP addresses, and you
have to create many policies, then it’s more convenient to set the
KUMP_TRAP_DESTINATION environment variable in the IBM
Tivoli Universal Agent and leave the policy TrapDestination
values as _DEFAULT.
Attributes
Select attributes associated with the situation being monitored from the
second pop-up window. You select a maximum of 10 attributes. The
values from the attributes you select are forwarded as part of the
SNMP trap in the variable binding list. The SNMP trap emitter can
send Non-English attribute data.
Invoke emitter once for each data row
You do not need to do anything with the default radio button selection.
3. Click OK to save your selections.
4. Distribute the policy to a managed system that is of the same type as the
managed system to which the policy’s situation was distributed. For example, if
the situation was for the Windows agent and was distributed to one of its
related managed systems, then the policy needs to also be distributed to a
managed system associated with the Windows agent.

112 IBM Tivoli Universal Agent: User’s Guide

Using SNMP emitter data
Viewing SNMP Emitter data varies from one SNMP management application to
another. To help your SNMP management application interpret the data, an SNMP
MIB file is included. Following is the trap description using the standard MIB
TRAP-TYPE macro.
candleEvent TRAP-TYPE
ENTERPRISE candle-Alert-MIB
VARIABLES {
sitName,
sitCurrStat-OriginNode,
sitCurrStat-LocalTimeStamp,
sitCurrStat-Severity,
sitCategory,
sitCurrStat-Predicates,
sitAttributeList
}
DESCRIPTION
“An IBM Tivoli Monitoring situation threshold was exceeded. This trap was
generated by the IBM Tivoli Universal Agent SNMP Emitter in response to a
situation threshold being exceeded.”::= 8

This data is always in your trap’s variable binding list. What you see for the
sitAttributeList often varies and depends on which attributes you select when
editing the SNMP Emitter’s parameters in the policy editor. A complete description
of these variables is in the CANSYSSG.MIB file. This MIB file depends on the
CANBASE.MIB file, so you need both.

Use these files to integrate IBM Tivoli Monitoring into another third-party SNMP
Manager product.

Chapter 6. Introducing the SNMP emitter 113

114 IBM Tivoli Universal Agent: User’s Guide
Appendix A. Data definition control statements
This appendix contains the descriptions and syntax for the control statements used
to create a data definition metafile.

Introduction
The control statements described in this appendix are used to create the data
definition metafile that defines an IBM Tivoli Universal Agent application. Some of
the statements are used only for specific data providers.

The following rules apply to metafile syntax:

v Control statements beginning with // in column 1 followed by one or more
blank-separated parameters.
v Blank lines in a metafile are allowed.
v An asterisk (*) in column 1 signifies a comment line.

If present, you must enter the statements in the metafile in the following order:

//SNMP

//APPL

//NAME

//INTERNAL

//SOURCE

//RECORDSET

//CONFIRM

//SQL

//SUMMARY

//ATTRIBUTES

© Copyright IBM Corp. 2003, 2005 115

SNMP statement

Description
This statement introduces the data definition for a customized SNMP application
and is only used for the SNMP Data Provider. It must precede the APPL statement
that names the application.

Syntax
//SNMP TEXT

Parameter
The SNMP statement must contain the parameter TEXT.

116 IBM Tivoli Universal Agent: User’s Guide

APPL statement

Description
The APPL statement specifies the name used by IBM Tivoli Monitoring for your
IBM Tivoli Universal Agent application. A metafile data definition always defines a
complete application and you must adhere to the following requirements:
v Only write one APPL statement per metafile.
v You must have a unique APPL name. If two different metafiles include
application definitions with the same APPL name, even though the content is
different, the second metafile is not loaded.

Syntax
//APPL <applname> [WHEN{<value>}] [@<help text>]

Parameters
<applname>
The name of the IBM Tivoli Universal Agent application you want to
monitor.
Notes:
1. An application name must contain at least 3, but not more than 20
characters. There can be no embedded blanks in the name. Only ASCII
characters are allowed, including letters, numbers, dash (-), underscore
(_), and asterisk (*). An invalid character is automatically replaced by
an underscore.
2. The first 3 characters must be unique in an enterprise. Activating two
IBM Tivoli Universal Agent metafiles with the same first 3 characters in
their //APPL statement leads to unpredictable results, such as empty
reports and frequent application version changes. For example, when
the two metafiles have different attributes or attribute groups.
3. The application name cannot start with the character K, which is
reserved for IBM Tivoli Monitoring products.
WHEN{<value>}
(optional) Indicates whether the metafile application is warehouse enabled
for the summarization and pruning agent. If the WHEN parameter is
omitted, the summarization and pruning agent does not process data for
this application once the data is placed in the warehouse.

Note: The <value> parameter inside the curly braces is a one-character tag
to indicate the warehouse enablement option, specifically, the
minimum level of data summarization found in the application
source data. The following lists valid values:
R Raw or sub-hourly
H Hourly
D Daily
W Weekly
M Monthly
Q Quarterly
Y Yearly

Appendix A. Data definition control statements 117

 <help text>
(optional) Defines the help text for this application.
Notes:
1. The text must be preceded by the ‘at’ (@) sign.
2. The text must not exceed 245 characters.
3. Commas (,) are converted to spaces in help text.
4. If non-English help text is specified, you must save the metafile in
UTF-8 encoding.

118 IBM Tivoli Universal Agent: User’s Guide

NAME statement

Description
A NAME statement defines the name of an attribute group, the data collection
method, and the period for which the data is valid.
v There must be at least one, and up to 64, NAME statements in a metafile.
v Each NAME statement must be followed by its associated SOURCE statement (if
one is required), ATTRIBUTES statement, and individual attribute definition
statements.

Syntax
//NAME <attribute-group-name> method [time-to-live] [<AddSourceName>]
[<AddTimeStamp>] [Interval=] [SkipNonNumeric=Y/N] [@<help text>]

Parameters
The attribute-group-name, method, and time-to-live parameters are positional. If
specified, you must enter them in the sequence shown above. The parameters are
separated by a space.
<attribute-group-name>
Specifies the name of an attribute group. The name identifies a set of data
definitions.
Notes:
1. An attribute group name can contain up to 32 characters. You cannot
use embedded blanks in the name. Only ASCII characters are allowed,
including letters, numbers, dash (-), underscore (_), and asterisk (*). An
invalid character is automatically replaced by an underscore.
2. This parameter is required.
<method>
Specifies the nature of the data. The following four modes are supported:
P Polled (default). Polled data becomes available periodically
and only the latest set of values is available for situation
monitoring and reporting.
S Sampled. Sampled data behaves in the same way as polled
data except that more than one set of attribute data values
can be available for use.
E Event. Event data occurs unpredictably and is reported in
asynchronous fashion as soon as the data becomes
available.
K Keyed. Keyed data behaves in the same way as sampled
data, but allows you to correlate events. You can designate
up to five attributes in each group as key attributes.
For example, an application checks system status such as CPU utilization
and network data traffic rate every 30 seconds. This is polled or sampled
data, or possibly even keyed data if any of the attributes function as
unique keys or indexes. By contrast, network alerts or console messages,
which occur at unpredictable intervals, should be defined in the metafile as
event data.

Appendix A. Data definition control statements 119

 <time-to-live (TTL)>
(optional) Defines the time interval when your data is available, both for
report viewing and situation evaluation, by the IBM Tivoli Universal
Agent. Sample data is available before the expiration of its published TTL
interval. After the TTL interval, the data is discarded or a new sample
arrives.
Notes:
1. TTL is specified in seconds.
2. The default TTL is 300 seconds.
3. In general, the TTL in the metafile should be greater than the largest
interval for any situation defined against the attribute group. The TTL
should also be greater than the frequency at which new data is
collected for the attribute group. For example, if new data samples
become available every minute, you can specify the TTL as 90 seconds.
This value allows the IBM Tivoli Universal Agent to always maintain a
current sample of data. If the TTL is less than the interval of data
availability, the IBM Tivoli Universal Agent discards the data before the
new sample has arrived and therefore has no data to evaluate.
However, if you set the TTL too high, a large number of collected data
rows remain in the IBM Tivoli Universal Agent cache causing process
memory utilization to increase. Ensure that you have a balance between
a TTL value that is large enough to catch situation intervals or data
samples, but not too large that the memory usage grows because of the
old data rows that are not purged.
4. Operationally, the TTL determines the delay before the status of a data
source changes from on-line to off-line on Tivoli Enterprise Portal. For
example, an IBM Tivoli Universal Agent application supplies data to
IBM Tivoli Monitoring using a TCP socket and specifies a TTL of 30
minutes. If the client program closes the socket and disconnects from
the data provider at 3:30 p.m., the off-line status is not reported to IBM
Tivoli Monitoring until 4:00 p.m. The same delay applies to applications
supplying data to an API Server Data Provider using the API call
dp_EndInput.
5. For keyed data, the TTL serves an additional purpose. Key attributes
are identified as candidates for correlation if the difference between the
arrival of their last data values and their new data values is less than
the TTL.
6. Normally, the TTL is ignored for Event data. Event data rows are not
aged and purged like Polled, Sampled, and Keyed data rows. By
default, the most recent 100 rows of Event data remain in the IBM
Tivoli Universal Agent cache. You can modify this value with the
KUMA_MAX_EVENT_ENTRIES environment variable. See Appendix E,
“Environment variables,” on page 209 for additional information.
The TTL is important for Event data when a Socket Data Provider
metafile that uses a TCP socket connection when
KUMP_TCP_DISCONNECT_BY_TTL=Y (the default) is in effect. In this
case, the TTL specified in the metafile determines the amount of time
after a disconnection between the socket client program and the Socket
Data Provider that the metafile application will go off-line in the Tivoli
Enterprise Portal.
<AddSourceName>
(optional) Instructs the IBM Tivoli Universal Agent to automatically add
the attribute DataSourceName to the defined attribute group. This

120 IBM Tivoli Universal Agent: User’s Guide

 attribute contains the host name of the node from which the data
originates. For example, if a socket client program is running on server
PROD1 and connecting to an IBM Tivoli Universal Agent at HQ1, and
//APPL Sock has been specified in the socket metafile, the
DataSourceName attribute has a value of PROD1:SOCK00.
<AddTimeStamp>
(optional) Allows you to insert a timestamp attribute. Application data
often must be correlated with other data based on timestamps. For
example, application events are frequently related to specific network
activities or an operating system status. In cases where application input
data does not include a time attribute field, the IBM Tivoli Universal Agent
supports the automatic insertion of a LocalTimeStamp attribute when the
AddTimeStamp parameter is included on the NAME statement. For
example:

//NAME CUSTOMERDATA E AddTimeStamp

When you specify this parameter, the IBM Tivoli Universal Agent
dynamically generates at runtime a LocalTimeStamp attribute value for
each new data row collected. The following is the format for the timestamp
is CYYMMDDhhmmssuuu, where:
C Specifies the century. Use 1 for the 21st century.

uuu Specifies the milliseconds after the ss value.

By default, the Tivoli Enterprise Portal displays this 16-byte timestamp in a

MM/DD/YY HH:MM:SS format. If you prefer a YYYY/MM/DD
HH:MM:SS uuu format, specify AddTimeStamp=YearMonth on the NAME
statement and the IBM Tivoli Universal Agent generates a 24-byte
LocalTimeStamp attribute. The following is an example of specifying
AddTimeStamp=YearMonth on the NAME statement:
//NAME CUSTOMERDATA E AddTimeStamp=YearMonth
Interval
(optional) Specifies the sampling interval in seconds that is used for
attribute group data collection. Only use this parameter for ODBC and
Script Data Provider metafiles. For example:
//NAME EMPLOYEES K 300 Interval=60

If the Internal parameter is omitted on the NAME statement for an ODBC

or Script attribute group, then demand-driven data collection is in effect.
Demand-driven means that attribute data is collected when a situation
interval occurs for the attribute group, or when a Tivoli Enterprise Portal
workspace open or refresh is issued for the attribute group.
SkipNonNumeric
Specify SkipNonNumeric=Y on the NAME statement if your attribute
group contains numeric attribute types, such as C or G, and you want
collected data rows to be skipped if they contain a non-numeric value in
any numeric attribute. For example,

Appendix A. Data definition control statements 121

 //NAME Process K 300 Interval=60 SkipNonNumeric=Y
//SOURCE SCRIPT /home/myscripts/monitor.sh
//ATTRIBUTES
Attr1 D 32
Attr2 C 999999
Attr3 D 16

As the rows of output from the monitor.sh script are processed by the
Script Data Provider, and there is a data row that has a non-numeric
character in the Attr2 attribute, the entire row will be skipped. Default
behavior for the IBM Tivoli Universal Agent is to write a zero in a numeric
attribute when non-numeric data is detected, but to not skip the entire row.

See Appendix B, “Attribute definitions,” on page 151 for information on

the supported attribute types.
<help text>
(optional) Defines the help text for this attribute group.
Notes:
1. The text must be preceded by the ‘at’ (@) sign.
2. The text must not exceed 230 characters.
3. Commas (,) are converted to spaces in help text.
4. If non-English help text is specified, you must save the metafile in
UTF-8 encoding.

Additional features
The NAME statement provides support for invisible attribute groups. An invisible
attribute group is not part of the customer application from the Tivoli Enterprise
Monitoring Server, Tivoli Enterprise Portal, and end user perspective. By defining
an attribute group as invisible, you can hide unneeded attribute definitions and
workspaces.

The purpose of an invisible attribute group is to collect raw data, such as data
from a file or socket client program, and then redirect the data to other visible
attribute groups in the same metafile where the data is filtered, summarized, and
manipulated to provide more meaningful information. The invisible attribute
group is hidden from an external standpoint. Use this feature in conjunction with
an //INTERNAL OUTPUT statement. See “INTERNAL statement” on page 123 for
more information.

Precede the attribute group name with a tilde symbol (~) to make it invisible. For
example:

//NAME ~INPUTDATA S 600

122 IBM Tivoli Universal Agent: User’s Guide

INTERNAL statement

Description
Data redirection is very useful for application data that contains variable data
types, such as a transaction log file that includes several types of data records, or
for application data that is too complex to construct a single attribute group
definition to handle reliably. In addition, you can use data redirection in situations
where data is received once, but redirected to multiple targets to be manipulated
differently, such as different attribute filters, summarization intervals, or
summarization keys. The //INTERNAL statement defines the data redirection
source or target attribute groups. The redirected application data is identified by
symbolic-name, which must be unique for all currently active applications. You can
redirect application data from one application attribute group to other application
attribute groups.

Syntax
//INTERNAL [INPUT | OUTPUT] symbolic-name

Parameters
OUTPUT statement
The INTERNAL OUTPUT statement defines the source of the data redirection. You
can only identify one source attribute group per redirection by the symbolic name.
All application data sources are supported such as file, socket, or API. The
attribute group data becomes eligible for redirection after passing all defined
attribute filters.

INPUT statement
The INTERNAL INPUT statement defines the target of the data redirection. Having
multiple target attribute groups from one redirected source output is supported.
However, a target attribute group cannot itself be the source of another redirection.

The IBM Tivoli Universal Agent redirects data for an attribute group exactly as if it
arrived from a standard data source such as file, socket, API program, or SNMP
agent. All IBM Tivoli Universal Agent features and services are available, including
attribute filters.

In the following example, the claim details log file is read once. The file records are
redirected to two subsequent attribute group definitions, ClaimInquiry and
ClaimRequest, for further processing.
//NAME TransactionLog e
//SOURCE FILE /users/Claim/DETAILS.log
//INTERNAL OUTPUT ClaimDetailRec
//ATTRIBUTES ’,’
RecData R 4096
*
//NAME ClaimInquiry e AddTimeStamp
//INTERNAL INPUT ClaimDetailRec
//ATTRIBUTES ’,’
RecType D 1 -FILTER={MATCH(0,3)}
ClaimID C 9999
ClaimType C 99
CustomerSSN D 9
. . . . .
. . . . .
. . . . .
*

Appendix A. Data definition control statements 123

 //NAME ClaimRequest e
//INTERNAL INPUT ClaimDetailRec
//ATTRIBUTES ’,’
RecType D 1 -FILTER={MATCH(0,2)}
CustomerName D 64
CustomerSSN D 9
CustomerAddr D 100
. . . . .
. . . . .
. . . . .

In the following example, the internet server log is first processed by attribute
group WEB_W3C_Log. It selects data by excluding file records without client
location or request content, or with no data transferred. The selected file records
are then passed to attribute groups Error_STAT and DataTransfer_STAT.

The Error_STAT is only interested in error codes greater than 200 and a few
selected attributes. All other attributes are defined as SKIP type so that they are not
visible to the end-user.

The DataTransfer_STAT attribute group shows the bytes exchanged between the
client and the server. It is only interested in client identity, request, and the bytes
count.

Two additional derived attributes are defined to show the total byte count and the
percentage of input data of the total data count. These derived attributes are
TotalBytes and PercentReceived.
//NAME WEB_W3C_Log e
//INTERNAL OUTPUT InternetLog
//ATTRIBUTES ’,’
ClientLocation D 32 -FILTER={MATCH(0,-)}
ClientUserName D 32
Date D 12
Time D 12
Service D 32
ComputerName K 64
ServerAddress D 32
RequestElapsedTime C 99999999
BytesReceived C 99999999 –FILTER={NUMBER<=(0,0)}
BytesSend C 99999999
ServiceStatus C 99999999
WindowsStatus C 99999999
OperationName D 32
OperationObject D 256 -FILTER={MATCH(0,-)}
RequestParameters D 256
*
//NAME Error_STAT e
//INTERNAL INPUT InternetLog
//ATTRIBUTES ’,’
ClientLocation D 32
SkipField1 K
Date D 12
Time D 12
Service D 32
SkipField2 K
SkipField3 K
SkipField4 K
SkipField5 K
SkipField6 K
ServiceStatus C 99999999 –FILTER={NUMBER=(0,200)}
WindowsStatus C 99999999
OperationName D 32
OperationObject D 256

124 IBM Tivoli Universal Agent: User’s Guide

RequestParameters D 256
*
//NAME DataTransfer_STAT e
//INTERNAL OUTPUT InternetLog
//ATTRIBUTES ’,’
ClientLocation D 32
SkipField1 K
Date D 12
Time D 12
Service D 32
SkipField1 K
SkipField2 K
SkipField3 K
BytesReceived C 99999999
BytesSend C 99999999
TotalBytes (BytesReceived + BytesSend)
PercentReceived (BytesReceived % TotalBytes)
SkipField4 K
SkipField5 K
SkipField6 K
OperationObject D 256
*

Appendix A. Data definition control statements 125

SOURCE statement

Description
The SOURCE statement defines the location and characteristics of the data being
collected.
v When the SOURCE statement is specified, it must follow immediately after the
NAME statement.
v Each SOURCE statement specifies one source.
v The SOURCE statement is not required for API and SNMP metafiles.
v The SOURCE statement is not required for Socket metafiles that have only one
attribute group. However, if the SOURCE statement is omitted, the socket client
program must send an explicit application association record that identifies the
corresponding metafile.
v You can have only one SOURCE statement per NAME statement unless you use
the ManagedSystemName parameter to uniquely identify each of the multiple
SOURCEs that is associated with the one attribute group.

Syntax
//SOURCE <type> [<script-interpreter>] <location> [<script-args>]
[<code-type>] [<file-mode>] [<number-of-file-records>] [User=] [Pswd=]
[Database=] [Server=] [Maxrows=] [Locale=] [Codepage=] [Envfile=]
[Interval=] [SetSourceName=Y/N] [ManagedSystemName=]

Parameters
The <type>, <script-interpreter>, <location>, <script-args>, <code-type>, <file-mode>,
and <number-of-file-records> parameters are positional. If specified, they must
appear in the sequence shown above. The remaining SOURCE statement
parameters use a keyword=<value> format and they can appear in any order after
the positional parameters.
<type> Specifies the form of the data source.
FILE Indicates that the data source is a local file.
ODBC
Indicates that the data source is a relational table.
SOCK Specifies data that arrives through a TCP/IP socket. A NAME
statement can have multiple sock sources.
SCRIPT
Indicates that the data source is a local script or program.
<script-interpreter>
(optional) For sources of the type SCRIPT, specifies the script interpreter
program that is required to execute the script. Examples of script
interpreters are Perl, REXX, and VBScript. If the Script Data Provider
cannot locate the script interpreter program at runtime, then you must
provide a script interpreter parameter before entering the script file name
in the <location> field. If the full path to the script interpreter contains any
embedded blanks, enclose it in single quotation marks. For example,
//SOURCE SCRIPT ’c:\program files\ObjREXX\rexx.exe’ myscript.rex
<location>
v For sources of the type FILE, <location> is the file name.

126 IBM Tivoli Universal Agent: User’s Guide

 – The file name can be case-sensitive on some operating systems.
Specify the name according to the requirements of the local system
where the File Data Provider is running.
– If the monitored file exists in a directory other than the one where the
File Data Provider binary resides, you must fully-qualify the file
name, that is, it must include the full path.
– As a rule, you cannot have a runtime substitution of symbolic
parameters or variables in the file name. You must spell out the
complete file name. The one exception is if you use the dynamic file
name feature, which allows you to specify a file name pattern. See
“Dynamic file name support” on page 42 for additional information.
– If the fully qualified file name contains any embedded blanks, enclose
the file name in single quotation marks.
v For sources of the type SOCK, <location> is the internet dot decimal
address or a resolvable host name, optionally followed by a port
number, of the socket client program that is functioning as the data
source. For example, sp2n03[4500] identifies a data source from host
sp2n03, port 4500.
– If the port number is omitted, the first connecting socket client
program from the specified host location is assumed. In general, the
port number is needed only if there are multiple socket client
programs connecting from the same host for the same metafile
application.
– If host name is specified for the location but cannot be resolved to an
address, the SOURCE statement is ignored.
v For sources of the type ODBC, location is the data source name.
– It must be already have been configured in the ODBC Data Sources
applet on the Windows operating system where the ODBC Data
Provider is running.
– If the data source name contains any embedded blanks, enclose it in
single quotation marks.
v For sources of type SCRIPT, location is the script file name.
– The script file name is case-sensitive on some operating systems.
Specify the name according to the requirements of the local system
where the Script Data Provider is running.
– You must fully qualify the script file if it does not exist in the IBM
Tivoli Universal Agent scripts directory.
– If the fully qualified script file name contains any embedded blanks,
enclose the file name in single quotation marks.
<script-args>
(optional) For sources of type SCRIPT, specifies one or more arguments to
pass to the script. You must enclose the entire set of script arguments in
double quotation marks immediately after the script file name. For
example,
//SOURCE SCRIPT cscript.exe listfreespace.vbs "/S myhost /U myuserid"

You must double the double quotation marks if a single argument being
passed to a script contains embedded blanks, for example:

//SOURCE SCRIPT c:\perl\bin\perl.exe 1234.pl ““bash.exe c:\temp\customString.sh””

The metafile parser strips off the outer set of double quotation marks and

Appendix A. Data definition control statements 127

 passes “bash.exe c:\temp\customString.sh” to the Perl interpreter. The
surrounding double quotation marks cause Perl to process the bash
executable and shell script as a single argument, even though they are
separated by a blank.
<code-type>
(optional) Specifies the one of the following character code pages of the
source data. The default is ASCII.
A ASCII
E EBCDIC
Notes:
1. The <code-type> parameter is valid only for the SOCK source type. It is
ignored for all other source types.
2. If the <code-type> of the source differs from the data representation
where the Socket Data Provider is running, the data provider translates
the application data it receives into the local machine representation.
3. As an alternative to supplying a code-type value, you can also specify a
CODEPAGE parameter on the SOURCE SOCK statement. For example,
if the socket client program is running on an OS/390® EBCDIC
platform, you can specify either an “E” for EBCDIC or the default
codepage of the mainframe system. For example,
//SOURCE SOCK MVSA CODEPAGE=ibm-37_P100-1995
<file-mode>
(optional) Specifies either COPY, TAILBYRECORD, TAIL, TAILRESTART,
TAILRESTARTFROMTOP, or TAILBYCOUNT monitoring mode. If this
parameter is not specified, TAIL mode is the default.
COPY Indicates to process the file in block mode. Each time the file is
polled or sampled, the entire contents of the file are read as
multiple rows of data. If the file contents are not cleared, the same
file records are input again. Copy mode is not valid for the Event
data type. This mode is also not appropriate for the Keyed data
type because it nullifies the Keyed behavior of correlating data
rows. Copy mode requires that the monitored file have a minimum
of two rows of data because it operates in block mode and needs a
beginning and ending record. Otherwise, the data is not displayed
in the Tivoli Enterprise Portal.
TAILBYRECORD
Indicates that the file is cumulative but that the end-of-file mark
does not change. Instead, the record count is checked at each
sampling interval to determine when new records have been
added.
TAIL Indicates that the file is cumulative. Each time the file is read, only
new records added to the end of the file are read for input.
When monitoring a file in TAIL mode, the File Data Provider
behaves as follows:
v If file records are deleted from the monitored file, the total file
size is reduced, the File Data Provider assumes that the
monitored file has been recreated and begins processing from
the beginning of the file.

128 IBM Tivoli Universal Agent: User’s Guide

 v If the content of the first file record has changed in any way, the
File Data Provider assumes that the monitored file has been
recreated and begins processing from the beginning of the file.
v If the monitored file does not exist at IBM Tivoli Universal
Agent startup time and is later created, the File Data Provider
processes the monitored file from the beginning.
v Copying a cumulative application file to an existing file
currently being monitored does not cause any change in the
monitoring. If the copied file is not a cumulative file of the
monitored file, the data provider begins processing from the
beginning of the file.
v The File Data Provider experiences a brief delay in recognizing
that a monitored file has been recreated or copied. For event
data, the delay is the interval set by environment variable
KUMP_DP_EVENT or the default of 15 seconds. For sampled
data, the delay is the TTL divided by the sample factor defined
by environment variable KUMP_DP_SAMPLE_FACTOR or the
default sample factor of 5. For example, expect a delay of up to
3 minutes (180 seconds) for a monitored file with a TTL of 900
seconds.
TAILRESTART
Indicates to monitor the file in Tail mode, but that a restart file is
being maintained in the IBM Tivoli Universal Agent work
directory. To ensure uniqueness, the restart filename uses the
following naming convention:
<ApplName>_<TableName>_<SourceName>.rst

where:
<ApplName>
Specifies the value on the metafile //APPL statement.
<TableName>
Specifies the value on the metafile //NAME statement.
<SourceName>
Specifies the managed system name associated with the file
data source.
Every time new records are added to the monitored file and its file
size increases, the File Data Provider stores the updated size value
in the restart file, along with the file name, file creation time, and
the last time the file was modified. If file monitoring is stopped
and started for any reason, the File Data Provider compares the
current file size against the size value stored in the restart file. If
the size has increased, the File Data Provider processes the delta
between the two sizes as if the records were added through normal
tail processing.
Use TailRestart if you are monitoring a critical file, such as a
transaction or audit log, and it is vital that no file records are
missed even if the IBM Tivoli Universal Agent is recycled.

Note:
For TailRestart, every new record added to the monitored file
requires input and output to the restart the file, so TailRestart is
probably not a good choice in all file monitoring scenarios.

Appendix A. Data definition control statements 129

 TAILRESTARTFROMTOP
Identical to TailRestart except in the handling of mismatches when
file monitoring begins. A mismatch is defined as a discrepancy
between the current information about the monitored file and the
information stored in the restart file. The following are examples of
discrepancies:
v The file name or file creation time has changed
v The current file size is less than the size stored in the restart file
v The file last modification time is earlier than the last
modification time stored in the restart file
If any of these types of mismatches is identified in TailRestart
mode, the restart file is not used because the mismatches indicate
that the monitored file has been altered and therefore the File Data
Provider cannot be certain of the accuracy of the restart file
information. In this case, a new restart file is created and normal
TailRestart mode is in effect.
By specifying TailRestartFromTop, you are indicating to handle a
mismatch detected at startup as a file switch to restart monitoring
from the beginning of the file.
TAILBYCOUNT
Indicates to monitor the file in Tail mode, but that a fixed number
of previous records should be processed when file monitoring
begins. This parameter must be followed by the
number-of-file-records parameter.
<number-of-file-records>
(optional) Only valid for sources of type FILE that are using TailByCount
mode. You must use an integer from 1-5000 for this parameter. Indicates
the number of previous file records to process when file monitoring begins.
The File Data Provider uses this parameter to count backwards the
<number-of-file-records> from the end of the file. Those records are
processed as if they have just been added to the end of the file.
User= (optional) Specifies a userid that connects to the ODBC data source or
executes the script. This parameter is only valid for the ODBC and SCRIPT
source types. It is ignored for all other source types. If multiple userids
have been defined to the ODBC data source, choose a userid with
sufficient authority to perform the table selects specified on the //SQL
statement.
Pswd=
(optional) Specifies the password that is to be used with the associated
user= parameter when connecting to the ODBC data source or executing
the script. This parameter is only valid for the ODBC and SCRIPT source
types. It is ignored for all other source types. You must precede The pswd=
parameter by a user= parameter. For example,
//SOURCE ODBC SAMPLE user=db2admin pswd=tivoli
Database=
(optional) Indicates a specific database context for the user= and pswd=
parameters to connect to. This parameter is only required for those
database products that support multiple database associations for a single
data source. Supply this parameter if you want to connect to a database
context other than the default. This parameter is only valid for the ODBC

130 IBM Tivoli Universal Agent: User’s Guide

 source type and it is ignored for all other source types. The following is an
example that uses the database= parameter:
//SOURCE ODBC cnps user=db2admin pswd=tivoli database=pubs
Server=
(optional) Specifies the name of the server that is used with the associated
database= parameter. This parameter is only necessary if the default
database/server connection is not appropriate for the user tables you want
to access. This parameter is only valid for the ODBC source type and it is
ignored for all other source types.
Maxrows=
(optional) Specifies the maximum number of rows that are processed by
the ODBC Data Provider after executing the Select statement or stored
procedure listed on the //SQL statement. The following example tells the
ODBC Data Provider to process up to 1000 rows for this attribute group.
The default maxrows= value is 100. You can make a global change with the
KUMP_ODBC_MAX_ROWS environment variable. The maxrows=
parameter is only valid for the ODBC source type. It is ignored for all
other source types.
//SOURCE ODBC cnps user=Admin pswd=xyz maxrows=1000

If more rows than the maxrows limit are returned from the metafile SQL
Select statement, only the first <nnn> rows up to that limit are used for
reporting and situation evaluation. This is an important point to remember.
If you have a situation against an ODBC table that is not firing when it
should, it could mean that the row or rows which would cause the
situation to fire happen to come after the maxrows limit. The following are
solutions to this problem:
v Increase the maxrows value for that particular table by using
maxrows=<nnn>.
v Use KUMP_ODBC_MAX_ROWS to change the maxrows value globally
so that maxrows is big enough to handle the expected number of
returned rows.
v Use a more qualified Where clause in the Select statement so that the
number of returned rows fit within the current maxrows limit.

The disadvantage of increasing maxrows to a very high number to handle

large volumes of returned SQL table data is the increased system overhead
caused by storing all of these rows in memory until their time-to-live value
has expired. So a balance needs to be achieved between setting maxrows
high enough to process all rows of interest, and low enough to not place
an unnecessary memory and CPU burden on the ODBC Data Provider.
Locale=
(optional) Enables you to specify that the data source on the SOURCE
statement is supplying data in a language which is different from the
default language of the system where the IBM Tivoli Universal Agent is
™
running. According to the Unicode standard, locale values are specified in
the following format:
<Language>_<Territory>.Codeset@Modifiers

where:

Appendix A. Data definition control statements 131

 <Language>
Specifies the two or three lowercase letter language code. For
example, en or ja.
<Territory>
Specifies the two letter region or country code. For example, US or
JP.
In general, you only need to specify <Language_Territory> on the Locale
parameter. You can optionally supply Codeset@Modifiers value to indicate
the coded character set to be used along with one or more
keyword=<value. modifiers. For example,
ISO-8859-15.im=INPUT-METHOD-NAME

The <Codeset> value on the Locale= parameter is synonymous with the

Codepage= parameter on the SOURCE statement. You do not need to
specify the value in both places
Codepage=
(optional) Enables you to specify that the data source on the SOURCE
statement is supplying data in a code page which is different from the
default code page of the system where the IBM Tivoli Universal Agent is
running. Some typical Codepage values are UTF-16BE, ISO-8859-15,
GB-2312, windows-1252, and ibm037. For example, if the Socket Data
Provider is running on a non-Japanese system, but it is receiving data from
a socket client program running on a Japanese system, you can specify the
following:
//SOURCE SOCK Host1 locale=ja_JP codepage=ibm-943_P15A-2003
Envfile=
(optional) Enables you to specify one or more environment variables to be
set when a script executes. The envfile= parameter is only valid for the
SCRIPT source type. It is ignored for all other source types. The following
is an example of coding the envfile:
//SOURCE SCRIPT 79001.bat "/temp 10" envfile=c:\endpoint\79001.env

The first time a script is about to execute, the Script Data Provider reads
the contents of the envfile parameter into memory and passes the
environment variable settings to the script process

Before every subsequent script execution, the Script Data Provider checks
the last modification timestamp of the envfile parameter. If it has been
modified, the Script Data Provider re-reads the envfile parameter contents
into memory and uses the new environment variable settings for the next
script execution. Otherwise, the previously read values are used. Because
the envfile parameter is checked before each script execution, you can
change the envfile parameter while your script is active, and your changes
are included in the next script execution without needing to refresh the
metafile or recycle the IBM Tivoli Universal Agent.
Notes:
1. The envfile name is case-sensitive on some operating systems. Specify
the file name according to the requirements of the local system where
the Script Data Provider is running.
2. You can use any name or file extension for the envfile name. There is
no special naming convention that the Script Data Provider expects.

132 IBM Tivoli Universal Agent: User’s Guide

 3. If the fully qualified envfile name contains any embedded blanks,
enclose the file name in single quotation marks.
4. The environment variables set in the envfile only apply to the launched
script process. For example, if there is a special PATH setting that a
script requires, you can add it in the envfile for that script and it does
not alter the PATH of other scripts that are running. Additionally, it
does not affect the PATH of the IBM Tivoli Universal Agent process.
5. The environment variables are coded in the envfile in a series of
VARIABLE=<value> statements, one per line. For example,
ENDPOINT_CLASS=ENDPOINT
LCF_DATDIR=C:\endpoint\dat\1
LCF_BINDIR=C:\endpoint\bin\w32-ix86\mrt
Interval=
(optional) Enables you to specify the sampling interval in seconds that is
used for attribute group data collection. This parameter is only valid for
ODBC and Script Data Provider metafiles. For example,
//SOURCE ODBC testSource Interval=120

The purpose of the Interval parameter on the SOURCE statement is to

override the Interval parameter on the NAME statement. If the Interval
parameter is specified on both the NAME and SOURCE statements, the
SOURCE value takes precedence.
SetSourceName=Y/N
(optional) If set to Y, indicates that the socket client program overrides the
default source name portion of the managed system name when the socket
client program connects. This parameter is only valid for the SOCK source
type. It is ignored for all other source types. By default, the following is the
managed system name of a socket application is:
<Hostname>:ApplNameVV

where:
<Hostname>
Specifies the host of the socket client program. Hostname in this
context is synonymous with the source name. If you want to
override this portion of the managed system name to something
more meaningful for your socket application, you must add a
SetSourceName=Y parameter on the //SOURCE SOCK statement
and then send a //SETSOURCENAME=xxxxx record to the Socket
Data Provider after your client program connects. The xxxxx will
be used when constructing and registering the managed system
ManagedSystemName=
(optional) Enables you to specify multiple sources for FILE, SOCK, ODBC,
or SCRIPT type data, uniquely identifying each data source. For example,
the following metafile definition:
//APPL MVS
//NAME SYSTEM
//SOURCE FILE /home/logs/abc.log tail ManagedSystemName=Boston
//SOURCE FILE /home/logs/xyz.log tail ManagedSystemName=Chicago
//SOURCE FILE /home/logs/mno.log tail ManagedSystemName=LosAngeles

processes three different files that all have the same attribute layout under
the SYSTEM attribute group. The metafile results in the creation of three
managed systems:

Appendix A. Data definition control statements 133

 Boston:MVS00

Chicago:MVS00

LosAngeles:MVS00

Under one NAME statement, you can specify a maximum of 128 SOURCE
statements with unique ManagedSystemName parameters.

You cannot have two identical ManagedSystemName values in the same

attribute group. Using unique ManagedSystemName values allows the
data provider to correctly identify which source the incoming data belongs.
For example, the following metafile is incorrect:
//APPL MVS
//NAME SYSTEM
//SOURCE FILE /home/logs/abc.log tail ManagedSystemName=Boston
//SOURCE FILE /home/logs/xyz.log tail ManagedSystemName=Boston

To keep the multiple file sources unique, the ManagedSystemName values

must be unique.

134 IBM Tivoli Universal Agent: User’s Guide

RECORDSET statement

Description
The RECORDSET statement, which is for File Data Provider metafiles only, enables
the File Data Provider to extract attribute data from multiple records. The
statement specifies the following:
v A delimiter pattern that indicates the end of a record set
v The maximum number of records that comprise the record set
v The maximum number of records that comprise the record set and a rule for
identifying either the beginning or end of the record set

Syntax
Format A: end-of-record delimiter pattern
//RECORDSET ‘delimiter_pattern’

Format B: maximum number of records in set

//RECORDSET maximum_number_of_records

Format C: maximum number of records and identification rule

//RECORDSET maximum_number_of_records NEW(offset,==
| !=,comparison_string)
or
//RECORDSET maximum_number_of_records END(offset,==
| !=,comparison_string)

Parameters
<delimiter pattern>
Specifies the pattern for the end of a record set. The delimiter must be
enclosed by single quotation marks (‘ ‘). Data exceeding the defined
attribute size is truncated to the defined size.
The end-record-set delimiter record is used only to delimit a record set and
is discarded. It should not contain valid attribute data.
Example 1 shows the definition for an attribute group named ERRORLOG,
using the record set delimiter. In this case, the data provider reads and
concatenates all file records until it encounters 1) a record containing the
specified delimiter pattern (ten dashes), or 2) the end-of-file condition.
//NAME ERRORLOG E
//SOURCE FILE c:\error.log tail
//RECORDSET ‘----------’
//ATTRIBUTES NONE
Error_Message R 2048

Example 2 shows the definition of an attribute group named

CONSOLELOG, in which a semicolon (;) delimits the attributes. In this
example, the data provider reads multiple records to extract the values for
the five defined attributes until it does one of the following:
v Encounters the end-record-set pattern
v Fills all five attributes
v Reaches the end-of-file condition.
//NAME CONSOLELOG E
//SOURCE FILE c:\console.log tail
//RECORDSET ‘----------’

Appendix A. Data definition control statements 135

 //ATTRIBUTES ‘;’
Message_Date D 12
Message_Time D 8
Message_ID D 8
Message_Text D 512
Message_Action D 512
<maximum_number_of_records>
indicates the maximum number of records that the data provider should
read in a record set.
In example 3, the attribute group APPLALERT contains only one attribute
of the type Record. The data provider reads and concatenates all file
records up to a maximum of 4 or until it reaches the end of the file,
whichever comes first.
//NAME APPLALERT E
//SOURCE FILE c:\alert.log tail
//RECORDSET 4
//ATTRIBUTES NONE
Alert_Description R 2048

In Example 4, the data provider uses the attribute delimiter (a blank space)
to extract values for the seven attributes by reading file records until it
does one of the following:
v Has read four records
v Has filled all seven attributes
v Reaches the end of the file
//NAME NETALERT E
//SOURCE FILE c:\net.log tail
//RECORDSET 4
//ATTRIBUTES ’ ’
Alert_Date D 12
Alert_Time D 8
Alert_ID D 16
Alert_Type C 99
Alert_Severity C 99
Alert_Origin D 64
Alert_Text D 256
<maximum records and identification rule>
Specifies both the maximum number of records in the record set and a rule
for identifying the beginning or end of the set. The identification rule
defines the offset in a file record, the comparison operator (equal [==] or
not equal [!=]), and the comparison string. The delimiting record is treated
as part of the record set and is not discarded.
The NEW keyword indicates a rule for beginning a record set. In this case,
the data provider processes file records from the current file position up to,
but not including the record that satisfies the comparison criterion, or until
one of the following:
v The specified maximum number of records has been processed
v All attributes have been filled
v The end of the file is reached

The END keyword indicates a rule for the end of a record set. In this case,
the data provider processes records from the current file position up to and
including the file record that satisfies the comparison criterion, or until one
of the following:

136 IBM Tivoli Universal Agent: User’s Guide

 v The specified maximum number of records has been processed
v All attributes have been filled
v The end of the file is reached

In the data definition in example 5, a record set consists of from one to

twenty file records and each new record set is identified by a nonblank at
offset 0. Therefore, in the monitored file shown, each new record set begins
with the date. Since there is no attribute delimiter, all the records until the
next date are read into the attribute Status_Record.
//NAME STATUS_LOG E
//SOURCE FILE c:\status.log tail
//RECORDSET 20 NEW(0,!=, )
//ATTRIBUTES NONE
Status_Record R 2048

Sat Jun 29 18:47:41 2002

Msg #UM12751 Entering UPDATE Mode
Sat June 29 18:47:41 2002
Msg #UM1202E Error in parameter file
FIX: See additional messages.
(0,2) STATUS.DAT
No such file or directory
Sat Jun 29 18:47:42 2002
Msg #KA3129E Error occurred while testing for remote
initiation
Msg #KA1709E Error occurred during a GET ALLOCATE verb
There was an error checking for a remote request of
UPDATE functions.
FIX: (OS/2 or Windows) Verify that you have configured
for remotely attachable programs correctly.
Primary return code = f0040000

Missing attribute delimiters

For multiple record input, the File Data Provider is programmed to accommodate
missing or omitted attribute delimiters at the beginning or the end of a record. For
the following application:
//APPL NewClass
//NAME PHYSICS101 K
//RECORDSET 4
//ATTRIBUTES ’;’
First_Name D 24 KEY
Last_Name D 24 KEY
Grade D 1
Telephone D 14
the following records are acceptable:
Bob;Smith;B;(555) 323-1919
Susan;Barber
B
(555) 323-2346;
Jack
Thomas
A
(555) 323-5656

If an attribute definition specifies both beginning and ending delimiters, as in the

following definition:
//APPL NewClass
//NAME CHILD_PSYCHOLOGY221 K
//SOURCE FILE c:\psy221.log
//RECORDSET 4
//ATTRIBUTES ’@;’

Appendix A. Data definition control statements 137

 First_Name D 24 KEY
Last_Name D 24 KEY
Grade D 1
Telephone D 14

the following file records are acceptable:

Bob;@Smith;@B;@(555) 323-1919
Susan;@Barber
@B
(555) 323-2346;
Jack
Thomas
A
(555) 323-5656

138 IBM Tivoli Universal Agent: User’s Guide

CONFIRM statement

Description
The CONFIRM statement provides a vehicle for specifying data acknowledgment
requirements and is for Socket Data Provider metafiles only. You must enter this
statement after the //NAME and //SOURCE statements and before the
//ATTRIBUTES statement.

Syntax
//CONFIRM confirmation_type

Parameters
<confirmation_type>
Specifies one of the following types of confirmation required:
SIZE The data provider acknowledges receipt of data by returning the
data length as a 32-bit unsigned integer, in network byte order.
SEQ The data provider acknowledges receipt of data by returning the
data record sequence number as a 32-bit unsigned integer, in
network byte order. For each new TCP connection or new UDP
exchange, the sequence number starts from one and wraps
accordingly.
X<nn> The data provider acknowledges receipt of data by sending the
specified hexadecimal character <nn>. For example, X70.
<’message’>
The data provider acknowledges receipt of data by sending the
specified message character string. You must enclose the message
in single quotation marks. For example, ‘Data received.’
If the client program and the data provider are on dissimilar
machines, the data provider translates the message into the format
of the system of the client before transmission.

Appendix A. Data definition control statements 139

SQL statement

Description
The SQL statement tells the ODBC Data Provider what table data to select from the
data source specified on the //SOURCE statement. One //SQL statement is
required for every //SOURCE ODBC statement.

Syntax
//SQL [Select statement] [proc=stored procedure]

Parameters
Select statement specifies an SQL Select of any type or form that is supported by
the data source being accessed, for example,
//SQL Select * from sysxlogins

Although this example uses a simple Select statement, there is nothing to prevent
you from exploiting additional SQL features, such as ORDER BY, GROUP BY,
nested Selects, built-in functions, and so on. You can select individual columns as
well as columns from multiple tables. You can use it in the ODBC metafile as long
as the ODBC driver supports the feature. In most cases, the drivers support all of
the standard SQL query syntax.

The IBM Tivoli Universal Agent metafile parser does not examine the contents of
the //SQL Select statement for possible syntax errors. The string that is contained
on the statement is passed to the ODBC driver, and it is the driver software that
does the work of parsing the statement and preparing it for run-time. One
consequence of this approach is that if there are any syntax errors in the //SQL
Select statement, they will not be detected until the ODBC metafile has been
imported and the first attempt to run the statement is made by the ODBC Data
Provider. At that time, the syntax errors are written to the UA RAS1 log. Therefore,
test the Select statement through an SQL ad hoc query tool or command-line utility
before inserting it into the metafile.
<proc=stored procedure>
Specifies a stored procedure that performs an SQL Select against the data
source being accessed.
Notes:
1. If the stored procedure name contains any embedded blanks, it must be
surrounded with single quotation marks.
2. If there are input parameters to the stored procedure, they must be
blank-separated tokens after the stored procedure name.

140 IBM Tivoli Universal Agent: User’s Guide

SUMMARY statement

Description
The //SUMMARY statement defines the requirements for gathering the frequency
of data input during monitoring. At a minimum, the requirements include a
defined interval and if appropriate, defined sort keys.

The resulting output attribute group consists of timestamp, interval, key attributes,
and occurrence (total count). Attributes that are not defined as key attributes are
not included in the output attribute group.

The summary of data occurrence is particularly useful in situations where the

frequency of input is more important than the input data details. For example,
when the IBM Tivoli Universal Agent is monitoring alerts received from a device,
all alerts are of some significance. However, it is the total number of alerts received
in a period of time that can indicate trends or problems.

It is helpful to use the filtering options, Accept Filters or Reject Filters, to limit the
scope of the summary. The summarization takes place after the input data is
filtered.

The application data must include the LocalTimeStamp attribute. If the data does
not include this attribute, then you can add it by specifying the AddTimeStamp
parameter on the //NAME statement. Otherwise, the IBM Tivoli Universal Agent
automatically inserts a LocalTimeStamp attribute at runtime. The LocalTimeStamp
attribute value and the interval defined in the //SUMMARY statement trigger the
summarization process.

Attributes that are not defined as key attributes are not included in the output.
This does not mean that detail application attributes are not available. You can
define an attribute group with or without filters for detail monitoring of
application data. And you can redirect the application data to one or more
additional attribute groups for summary using various attributes as sort keys.

Only one //SUMMARY statement is allowed per //NAME statement. This

statement is entered after the //NAME statement and before the //ATTRIBUTES
statement.

Syntax
//SUMMARY [<interval>] [Force]
attribute-name attribute-type maximum-size SKEY=n

Parameters
<interval>
Specifies the summarization period in seconds. The minimum interval
value is 60 (1 minute) and the maximum interval value is 86400 (1 day).
The default of 300 is used if an interval is not specified.
Force (optional) Enables you to always see a summary row at every interval,
regardless of whether new data was collected during that interval. The
interval value specified on the //SUMMARY statement is used to
determine when to output a new data row to the summary attribute group.
However, if no new input data is collected during a summary interval, a
row is not added to the summary attribute group for that interval. The

Appendix A. Data definition control statements 141

 default behavior of the Summary feature is that it is data-driven rather
than interval-driven. The following is an example of using the Force
parameter:
//SUMMARY 900 Force

This metafile syntax means that a new row will be output to the summary
attribute group every 15 minutes, even if the row contains zeroes for
Occurrences and the other summary attributes.
SKEY=<n>
Identifies an attribute as a summarization sort key. The <n> sequence
number specifies the sort order (such as 1, 2, 3 for sorting first, second, and
third).
You can make any display or numeric attribute a summarization sort key.
An attribute group can include either no sort keys or sort keys
representing all attributes in the attribute group. An attribute group without
a sort key definition is summarized by LocalTimeStamp interval only. The
output consists of one row of data per summarization interval. An attribute
group with sort keys is summarized by the LocalTimeStamp interval and
breaks on each sort key. Its output includes as many rows as there are
unique sort key combinations per summary interval.

Example 1
The following metafile specifies an hourly request summary:
//APPL eLog
//NAME ServerLog e
//INTERNAL OUTPUT InternetLog
//ATTRIBUTES
*-------------------------------------------*
* Apache Server Log Record Format Layout *
*-------------------------------------------*
ClientLocation D 256
ClientUserName D 32
Authorized_User K 32
Date_Time DL 20
Time_Zone K 5
Request D 256 DLM=’’ –FILTER={MATCH(0,-)}
ServiceStatus C 99999999
BytesReceived C 99999999
Referral D 256 DLM=’/"’
Browser D 256 DLM=’""’
Service D 32
ServerName D 256
RequestParameters D 256
BytesSent C 99999999
RequestElapsedTime C 99999999
*
//NAME RequestSummary e
//INTERNAL INPUT InternetLog
//SUMMARY 3600 Force
//ATTRIBUTES
LogRecord R 2048

The log records are redirected to the attribute group RequestSummary, which
counts the number of records per hour. Log records without request information
(signified by a - in the first position of the Request attribute) are immediately
rejected. The actual attributes that are presented for the RequestSummary attribute
group include:

142 IBM Tivoli Universal Agent: User’s Guide

 LocalTimeStamp
The CT® timestamp indicating the beginning of a summary interval
Interval_Unit
As defined on //SUMMARY statement (3600)
Occurrences
The summary count

Because the Force parameter is specified, a data row is output with 0 in the
Occurrences column if no qualifying records are received in the RequestSummary
attribute group in the previous hour.

Example 2
The following attribute group metafile definition shows an internet server log
summary of all requests that resulted in an error status greater than 400. Notice
that the error requests or interest (+FILTER={NUMBER>=(0,400)}) are already
filtered on input.
//NAME RequestErrorStatus e
//INTERNAL INPUT InternetLog
//SUMMARY 86400
//ATTRIBUTES
ClientLocation D 256
ClientUserName D 32
Authorized_User K 32
Date_Time DL 20
Time_Zone K 5
Request D 256 SKEY=2 DLM=’’
ServiceStatus C 99999999 SKEY=1 +FILTER={NUMBER>=(0,400)}
BytesReceived C 99999999
Referral D 256 DLM=’/"’
Browser D 256 DLM=’""’
Service D 32
ServerName D 256
RequestParameters D 256
BytesSent C 99999999
RequestElapsedTime C 99999999
*

The IBM Tivoli Universal Agent accumulates input log record data during the
summarization interval. At the end of an interval, the accumulated data is sorted
based on defined sort keys, and then summarized. The following are the output
attributes:
ServiceStatus
The input status value
Request
The input request attribute value
LocalTimeStamp
The CT timestamp indicating the beginning of a summary interval
Interval_Unit
As defined on //SUMMARY statement (86400)
Occurrences
The summary count

The output attributes of an attribute group that have been summarized always
consist of key attributes, LocalTimeStamp, Interval, and Occurrences. Attributes
that are not defined as key attributes are not included in the output.

Appendix A. Data definition control statements 143

 Example 3
You only need to define the metafiles in as much detail as necessary to correctly
extract the key attributes for summarization. The abbreviated attribute group
definition that follows results in the same output as the previous example:
//NAME RequestErrorStatus e
//INTERNAL INPUT InternetLog
//SUMMARY 86400
//ATTRIBUTES
PlaceHolder1 K 4
PlaceHolder2 K 4
PlaceHolder3 K 4
PlaceHolder4 K 4
PlaceHolder5 K 4
Request D 256 SKEY=2 DLM=’’
ServiceStatus C 99999999 SKEY=1 +FILTER={NUMBER>=(0,400)}
*

If more input data fields are defined than attributes the IBM Tivoli Universal
Agent stops interpreting input data at the last defined attribute. A timestamp is
automatically inserted.

Total counts for a summarizing Interval

Application data frequently includes count fields such as the number of events,
number of processes, and bytes sent or received. It is very useful to show total
result counts for a summarizing interval. You can total any numeric attribute field
by specifying the SKEY=SUM keyword parameter.
//SUMMARY [interval] [Force]
attribute-name attribute-type maximum-size SKEY=SUM

Example 4
In the following example, the sent and received byte counts are totaled by
ClientLocation each hour.
//NAME DataTransferByLocation e
//INTERNAL INPUT InternetLog
//SUMMARY 3600 Force
//ATTRIBUTES
ClientLocation D 256 SKEY=1
PlaceHolder1 K 4
PlaceHolder2 K 4
Date_Time DL 20
PlaceHolder3 K 4
PlaceHolder4 K 4 DLM=’’
PlaceHolder5 K 4
BytesReceived C 99999999 SKEY=SUM
PlaceHolder6 K 4 DLM=’/"’
PlaceHolder7 K 4 DLM=’""’
PlaceHolder8 K 4
PlaceHolder9 K 4
PlaceHolder10 K 4
BytesSent C 99999999 SKEY=SUM
PlaceHolder11 K 4
*

Special attribute delimiters are needed for interpretation of input data, even though
the data contents are of no consequence. The attribute group outputs the following
attributes:
ClientLocation
The location information, such as address or node name

144 IBM Tivoli Universal Agent: User’s Guide

 BytesReceived
The sum of this attribute value during this interval
BytesSent
The sum of this attribute value during this interval
LocalTimeStamp
The CT timestamp indicating the beginning of a summary interval.
Interval_Unit
The definition on //SUMMARY statement (3600)
Occurrences
The summary count (number of records summarized)

Creating new attributes

Derived attributes allow you to create new attributes based on existing defined
attributes, including internal summarization attributes and results. You can use the
following attributes to create derived attributes:
_Occurrences
The summary count
_Interval_Unit
The defined summarization interval
Numeric attribute summarization result
A numeric attribute defined with SKEY=SUM

Example 5
The following example expands the previous metafile definition by specifying
attributes for RequestsPerSecond, TotalBytesTransfer, BytesTransferPerSecond, and
BytesTransferPerRequest for each client location:
//NAME DataTransferByLocation e
//INTERNAL INPUT InternetLog
//SUMMARY 3600
//ATTRIBUTES
ClientLocation D 256 SKEY=1
PlaceHolder1 K 4
PlaceHolder2 K 4
Date_Time DL 20
PlaceHolder3 K 4
PlaceHolder4 K 4 DLM=’ ’
PlaceHolder5 K 4
BytesReceived C 99999999 SKEY=SUM
PlaceHolder6 K 4 DLM=’/"’
PlaceHolder7 K 4 DLM=’""’
PlaceHolder8 K 4
PlaceHolder9 K 4
PlaceHolder10 K 4
BytesSent C 99999999 SKEY=SUM
PlaceHolder11 K 4
*
RequestsPerSecond (_Occurrences / _Interval_Unit)
*
TotalBytesTransfer (BytesReceived + BytesSent)
*
BytesTransferPerSec (TotalBytesTransfer / _Interval_Unit)
*
BytesTransferPerReq (TotalBytesTransfer / _Occurrences)

Appendix A. Data definition control statements 145

ATTRIBUTES statement
The ATTRIBUTES statement introduces the attribute definitions. It also allows
specification of attribute delimiters in the data string. Each record that follows the
ATTRIBUTES statement contains one attribute definition.

An attribute group can contain a maximum of 63 attributes, unless the

KIB_MAXCOLS environment variable overrides it. You can set the KIB_MAXCOLS
environment variable to a maximum of 127. Note that KIB_MAXCOLS=127 is
already specified by default in the IBM Tivoli Universal Agent environment files
on Windows and UNIX operating systems.

Syntax
//ATTRIBUTES [<‘delimiter-string’>] [DLM=] [DLMSTR=] [DLMSTRBGN=] [DLMSTREND=]

Parameters
<’delimiter-string’>
Identifies optional delimiter characters that separate attribute data in input.
v You must enclose delimiter characters in single quotation marks. For
example,
//ATTRIBUTES ‘;’

indicates that the attributes fields in a row of data are separated by a

semicolon, as in the following example of a data row,
John;Doe;System Analyst;Engineering

Note: The delimiter characters do not appear in the attribute values

displayed in the Tivoli Enterprise Portal workspace. The IBM
Tivoli Universal Agent uses the delimiter specified on the
ATTRIBUTES statement to parse incoming data. After it parses
incoming data, the delimiter is discarded before the data is used
for reports or situation evaluation.
In the following example, three single quotation marks indicate that the
attribute fields in a row of data are separated by a single quotation
mark. Whenever the specified delimiter character is not a space, it means
that leading, trailing, or in-between space characters are not removed
from the data row.
//ATTRIBUTES‘’’
v When using single delimiter characters, it is not required to have a
delimiter character after the last attribute value in the data row because
the end-of-record or newline character serves the same purpose as the
delimiter. In the data row example above, there is no semicolon after
"Engineering" but it is understood that end-of-record has been reached
so the semicolon delimiter is unnecessary.
v If no delimiter string is specified, the attributes are assumed to be
separated by a space. In the data row example above, a space delimiter
would not be a good choice because it would divide "System" and
"Analyst" into two different attribute values in the Tivoli Enterprise
Portal workspace.
v If your data source is providing non-English input data, it is sometimes
necessary to specify non-English delimiter characters. All forms of the
delimiter specification on the ATTRIBUTES statement accept non-English

146 IBM Tivoli Universal Agent: User’s Guide

 characters. However, you must save the metafile itself in UTF-8
encoding. The IBM Tivoli Universal Agent is only able to read ASCII
and UTF-8 metafile formats.
v A double delimiter specification, such as ‘””’, indicates that the attribute
fields are enclosed by beginning and ending delimiters.
“John” “Doe” “System Analyst” “Engineering”
The beginning and ending delimiters need not be the same character. For
example, you can specify the attribute delimiters as ‘$?’ for the file:
$John? $Doe? $System Analyst? $Engineering?

With double delimiters, both beginning and ending delimiters are

required for each attribute, including the last attribute in the data record.
v The TAB keyword specifies the horizontal tab character as the attribute
delimiter:
//ATTRIBUTES TAB
v The NONE special keyword indicates that no delimiters are used:
//ATTRIBUTES NONE
If NONE is used, the attribute data values are retrieved by field offset
and the defined attribute data length. No interpretation or data
conversion is made to the data values. You must make certain that the
data value types and sizes exactly match the attribute specification in the
application metafile. In the following metafile example,
//ATTRIBUTES NONE
First-Name D 12
Last-Name D 12
Job D 20
Department D 16
The following is an example of a typical data record for this metafile,
John[8 spaces]Doe[9 spaces]System Analyst[6 spaces] Engineering[5 spaces]
The non-delimited data input also supports additional binary short- and
long-integer data types. The data is copied directly from input records to
memory. Therefore, it is important to ensure that the sending application
and the data provider start on machines with like system architectures,
since integer size and its internal memory data representation are not
interpreted.

Note: Do not use NONE as an attribute delimiter when using the File
Data Provider metafile to monitor a file that contains numeric
attributes defined as Counter or Gauge. The number of digits
required to represent the numeric value in the monitored file do
not necessarily match the 2 or 4 byte representation of the number
that the File Data Provider must store, so the attribute values can
end up displaying incorrectly in the Tivoli Enterprise Portal
workspace.
DLM (optional) As an alternative to the <‘delimiter-string’> format, you can also
use this keyword-based form of delimiter specification. Like the
<‘delimiter-string’> format, it supports single delimiter characters as well as
double delimiter specifications in which the two characters signify
beginning and ending delimiters. For example, you would use the
following format if you are monitoring a non-English file and want to
specify the delimiter character using the DLM= format:
//ATTRIBUTES DLM=’†’

Appendix A. Data definition control statements 147

 Note: If there are any non-English characters in an IBM Tivoli Universal
Agent metafile, whether as a delimiter, caption, or help text, you
must save the metafile in UTF-8 encoding.
DLMSTR
(optional) If the data row being parsed contains a delimiter pattern
consisting of two or more characters, use the DLMSTR keyword parameter
in place of the delimiter-string format. For example, while you analyze a
sample record from the Orders.log file, you notice that there are always
three blanks between each major field of a file record:
May 24 2005 Acme Corp AE47938 John Doe Denver 9583759374 998123

Use a DLMSTR=' ' specification on the ATTRIBUTES statement as follows:

//APPL OrderInfo
//NAME CustomerData S 300
//SOURCE FILE C:\CustomerData\Orders.log Tail
//ATTRIBUTES DLMSTR=’ ’
Date D 24
CustomerName D 32
CustomerPO D 32
CustomerContact D 24
CustomerLocation D 24
OrderNumber D 12
OrderTotal C 9999999
DLMSTRBGN and DLMSTREND
(optional) As an extension of support for double delimiter specifications in
which the two characters signify beginning and ending delimiters, you can
also specify that there are multiple characters that mark the beginning and
ending of every attribute value. The following example indicates that every
attribute value in the data row being processed begins with 3 asterisks and
ends with 3 exclamation points.
//ATTRIBUTES DLMSTRBGN=’***’ DLMSTREND=’!!!’

As with all delimiter specifications, the delimiter characters themselves are

not included in the attribute data. They are discarded before the data row
is output for report viewing and situation evaluation.

Any delimiter character, string, or beginning and ending string that is specified at
the //ATTRIBUTES level is in effect for every individual attribute defined under
that //ATTRIBUTES statement. However, if your input data is not completely
consistent in its use of delimiters, there is provision in the IBM Tivoli Universal
Agent metafile syntax to override the delimiter value at the individual attribute
level. This feature is called attribute-specific-delimiters. See Appendix B, “Attribute
definitions,” on page 151 for additional information.

148 IBM Tivoli Universal Agent: User’s Guide

Metafile examples
This section provides examples illustrating metafiles created according to the
guidelines presented in the previous sections. For information about creating
attribute definitions, see Appendix B, “Attribute definitions,” on page 151.

Metafile example 1
This example illustrates an APIS Data Provider application named UXstat,
comprised of one attribute group, UXsysSta. UXsysSta contains 22 attributes, using
polled data with a TTL of 150 seconds. No SOURCE statement is required in this
data definition because the data is sent using APIs.
//APPL UXstat @help text
//NAME UXsysSta p 150 @help text
//ATTRIBUTES
SystemName D 16 @help text
OSversion D 16 @help text
PendingIOwaitRate C 100000 @help text
IOstartRate C 100000 @help text
IOcompleteRate C 100000 @help text
AvgWaitThreadQueueSize C 4096 @help text
AvgRunThreadQueueSize C 4096 @help text
AvgNumbActivePageFrames C 100000 @help text
AvgNumbFreePageFrames C 100000 @help text
PageInRate C 65000 @help text
PageOutRate C 65000 @help text
DevInterruptRate C 65000 @help text
SystemCallRate C 65000 @help text
ThreadContentSwitchRate C 65000 @help text
AvgUserCPUPercent C 100 @help text
AvgSystemCPUPercent C 100 @help text
AvgIdleCPUPercent C 100 @help text
AvgWaitCPUPercent C 100 @help text
UDPpktInRate C 100000000 @help text
UDPpktOutRate C 100000000 @help text
TCPpktInRate C 100000000 @help text
TCPpktOutRate C 100000000 @help text

Metafile example 2
This second metafile example illustrates the definition of data extracted from a log
file for an application named SysEvent. It consists of a single attribute group
named ConLog, which uses Event data collected in TAIL mode.
//APPL SysEvent @help text
//NAME ConLog E @help text
//SOURCE FILE e:\system\event.log TAIL
//ATTRIBUTES
MessageID D 12
MessageNumb C 999999
MessageType D 1
ProcessNumb C 9999
TimeMonth D 3
TimeDay C 31 T
TimeYear C 9999
TimeHour C 24
TimeMinute C 60
TimeSecond C 60
MessageText D 100

Appendix A. Data definition control statements 149

150 IBM Tivoli Universal Agent: User’s Guide
Appendix B. Attribute definitions
This appendix contains the description, syntax, and parameters for the attribute
definitions used in creating a data definition metafile. It explores characteristics of
attribute definitions that can enhance performance monitoring when creating a
data definition metafile. In addition, this appendix discusses how to derive and
filter attributes, and how to sequence attribute definitions.

Defining attributes

Description
Attribute definitions specify the name of the attribute, its type, and its maximum
size. The order of the definitions must match the sequence of the data fields in the
data record.

Syntax
<attribute-name> <attribute-type> <maximum-size> [KEY] [ATOMIC]
[CAPTION{<text>}] [SCALE{<nn>}] [PRECISION{<nn>}] [DLM=] [DLMSTR=]
[DLMSTRBGN=] [DLMSTREND=] [<attribute-specific-delimiter>]
[<aggregate-behavior>] [@<help text>]

Parameters
The <attribute-name>, <attribute-type>, <maximum-size>, KEY, and ATOMIC
parameters are positional. If specified, they must appear in the sequence shown
above. The remaining parameters use a keyword=<value> format and they can
appear in any order after the positional parameters. The <help-text> parameter is
the exception to this rule.

Note: There are additional attribute definition parameters. These additional

attribute parameters include: filtering, deriving, and sequencing. These
attribute parameters are described later in this Appendix.
<attribute-name>
Specifies the name of an attribute.
Notes:
1. Attribute names can contain up to 200 characters.
2. There cannot be any embedded blanks in the name. Only ASCII
characters are allowed, including letters, numbers, dash (-), underscore
(_), and asterisk (*). An incorrect character is automatically replaced by
an underscore.
<attribute-type>
Specifies the one of the following valid attribute types.
Notes:
1. You can only specify the following attributes in single instance attribute
groups. The IBM Tivoli Universal Agent does not support historical
collection for attributes that exist in multiple row tables.
2. Numeric attribute values cannot exceed 2,147,483,648.
# Delta value. Presents the value of the attribute as the difference

© Copyright IBM Corp. 2003, 2005 151

 between samples. For example, if the value for sample 1 is 100 and
for sample 2 is 120, the delta is 20.
% Percentage of change. Presents the value of the attribute as the
difference between samples expressed as a percentage. For
example, if ReceiveCount is defined as % data type, and the value
for sample 1 is 100 and for sample 2 is 120, the percentage of
change is 20.
? Rate of change. Presents the value of the attribute as the delta per
second between samples. For example, if ReceiveCount is defined
as ? data type, the value for the first sample is 100, the value for
the second sample is 120, and the elapsed time between samples 1
and 2 is 5 seconds, the rate of change 4 per second.
A Average. Data to be averaged over all collections.
C Counter. Positive integer.
D DisplayString. Series of characters.
G Gauge. Positive or negative integer.
K Skip. Input positional field. Of no interest and is skipped.
N DisplayNumeric. Series of numeric characters. This attribute type is
a string representation of a number and not an integer.
R Record. Read entire record until carriage control/linefeed character.
S Switch. Boolean 0 or 1.
T Time. The format is CYYMMDDHHMMSSmmm (where C=1 for
the 21st century).
U Unicode. A series of globalized characters.
Z Last. Ignore specified delimiter and treat all input data from the
current position to end of input data record as one field.
If no value is given for an attribute when the data is sampled, a default
value is assumed. The default value for an attribute type depends upon the
method of data collection. For polled, sampled, and keyed data, the default
value assumes the previous sample data value. The default values for
event data are shown in Table 23.
Table 23. Default values for event data
Attribute type Default value
A (Average) No change from current average
C (Counter) 0
D (DisplayString) Space character
G (Gauge) 0
K (Skip) Not applicable
N (DisplayNumeric) 0
R (Record) Not applicable
S (Switch) 0
T (Time) Current time
U (Unicode)
Z (Last) Space character

152 IBM Tivoli Universal Agent: User’s Guide

<maximum-size>
Specifies the maximum expected size of the data.
Notes:
1. For attribute types D, K, N, R, U, and Z, this parameter specifies the
maximum number of bytes of the attribute. The maximum size allowed
is 2048 bytes.
2. For numeric attributes such as Counter or Gauge, this parameter
specifies the maximum expected number. For example, an attribute for
CPU utilization expressed as a percentage could have a maximum size
of 100. A Counter attribute for the total number of packets received
might expect a maximum value of 1,000,000 packets per system
implementation. The IBM Tivoli Universal Agent only supports
numeric attribute values up to 2 Gigabytes; therefore do not specify a
maximum size for any numeric attribute that is greater than
2,147,483,647.
3. For the Unicode attribute type, the globalized data is internally
represented in the IBM Tivoli Universal Agent as UTF-8. Because UTF-8
typically requires 2-4 bytes to represent a non-English Unicode
character, the maximum size specification for all U attributes is
automatically multiplied by 3 when the IBM Tivoli Universal Agent
imports a metafile.
KEY (optional) Indicates that an attribute is a key attribute. This only applies if
the sample method in the NAME statement is specified as K.
The IBM Tivoli Universal Agent uses key attributes to determine whether
multiple events have the same cause. Key attributes help correlate data
rows with identical keyed attribute values. As the IBM Tivoli Universal
Agent receives data rows for keyed attribute data, it checks to see if it
already has a data row with matching values for keyed attribute. If so, the
new data row replaces the existing one. Furthermore, the replacement
occurs only if the time difference between the new data row and the
existing data row is less than the specified TTL.
Notes:
1. You can designate up to five attributes as key attributes.
2. If no attribute is designated as key in a Keyed attribute group, the IBM
Tivoli Universal Agent uses the first attribute as the key attribute.
ATOMIC
(optional) The IBM Tivoli Universal Agent allows you to atomize attributes
in your metafiles. Atomizing an attribute permits the use of the display
item option during situation definition. The display item option allows you
to do the following:
v Generate separate events for a single true condition
v Easily display the value that caused the situation to become true.
For example, if process_cpu > 10 percent represents a situation, a situation
could be raised for one or more processes on a system. If only one
situation event is raised, the “responsible” process is ambiguous. In
different intervals, different processes could be causing the problem.
If you atomize the situation using the display item option for the
process_cpu attribute, separate situation events would be raised and reset

Appendix B. Attribute definitions 153

 for each process that caused the situation to be true. This feature can
greatly reduce the number of situation definitions and also aid in problem
determination.
To activate the feature, add the keyword ″Atomic″ to the right of the
attribute you want to atomize in your IBM Tivoli Universal Agent metafile.

Note: You can specify ″Atomic″ in upper or lower case.

EmployeeName D 20 Atomic
EmployeeExt N 4
EmployeeID D 8

The ″EmployeeName″ attribute is atomized. ″Atomic″ is similar to the

″Key″ keyword in that it must follow the size specification. You can
include both ″key″ and ″atomic″ for the same attribute. There must be at
least one blank separating them.

Note: Adding the ″atomic″ keyword to an existing attribute only causes a

minor version change in the associated IBM Tivoli Universal Agent
application.

Several IBM Tivoli Universal Agent-provided attributes in the SNMP Data

Provider SNMP-MANAGER application and in the HTTP Data Provider
INTERNET application are atomized by default. This enables situations
referencing those attributes to use the display item capability.

Note: Although there is no limit to the number of attributes you can

atomize in a metafile, you can only specify one display item
attribute per situation. Numeric attribute types such as Counter and
Gauge are not eligible to use the atomic parameter.
<attribute-specific-delimiter>
Allows you to override the attribute group delimiter that is defined on the
//ATTRIBUTES statement. The delimiter defined on the //ATTRIBUTES
statement applies to all attributes in the attribute group. However,
application data is not always uniformly delimited. If this is the case, it is
necessary to override the normal delimiter with a special delimiter to use
at the individual attribute level. For example, the following metafile
statements,
//APPL XYZ
//NAME TransactionLog E
//SOURCE FILE /home/logs/transaction.log tail
//ATTRIBUTES ’’
ClientName D 32
Date_Time DL 20
Time_Zone D 5
Transaction D 256
TransactionSize C 999999

cannot correctly parse the following sample log record:

JohnDoe [01/Sep/2005:02:06:31 -0700] „GET /ITM05.html” 5914

The delimiter in effect at the attribute group level is a single space. This
generally works to separate each attribute value in this log record, except
for the Transaction attribute value which is enclosed by double quotation
marks. You can correctly parse the Transaction value in the sample log
record (as GET/ITM05.html) by redefining the Transaction attribute with
the following attribute specific begin and end delimiter:

154 IBM Tivoli Universal Agent: User’s Guide

 Transaction D 256 DLM=’””’

The types and syntax of the attribute-specific delimiter parameters that you
define at the individual attribute level are the same parameters that you
can specify on the //ATTRIBUTES statement: DLM, DLMSTR, and
DLMSTRBGN combined with DLMSTREND.

As with the delimiter specifications on the //ATTRIBUTES statement, you

must enclose the attribute-specific delimiter characters in single quotation
marks. If they include any non-English characters, you must save the
metafile with UTF-8 encoding. There is no restriction on the number of
attribute-specific delimiters within an attribute group.
CAPTION
The Tivoli Enterprise Portal allows you to specify an alternate name for an
attribute. This alternate name is referred to as a Caption. Generally, you
specify a CAPTION parameter in your attribute definition to provide a
more readable version of an attribute in the workspace column headings.
The following is an example of specifying a caption,
AvgDiscarded C 999999 Caption{Average\nDiscarded} @Avg packets
discarded per sec

The presence of the newline character, \n, in the Caption parameter

specifies that the column heading AvgDiscarded appears in the Tivoli
Enterprise Portal as:
Average
Discarded
SCALE and PRECISION
To support floating point numbers in Tivoli Enterprise Portal, the IBM
Tivoli Universal Agent allows you to specify a Scale and Precision factor
when defining a numeric attribute. The Tivoli Enterprise Portal uses the
Scale value to know how many positions to shift the decimal point to the
left, and the Precision value to determine the overall width of the floating
point number. These floating point numbers are then eligible for graphs
and charts and other numeric-based Tivoli Enterprise Portal presentation
features.
To enable this capability, specify SCALE{<nn>} PRECISION{<nn>} to the
right of an attribute definition. For example,
FloatAttr1 C 999999 Scale{2} Precision{5}

Alternatively, specify SCALE{<nn>} PRECISION{<nn>} in a derived

attribute. For example,
PktReceivedPerSec C 1000000
PktDiscardedPerSec C 1000000
DiscardedRatio (PktDiscardedPerSec / PktReceivedPerSec) Scale{3}
Precision{6}
@ratio of packets discarded to packets received

The maximum allowed Scale value is 10 and the maximum allowed

Precision value is 12.
<aggregate-behavior>
Allows you to specify the following details for aggregating data:
AGPRF
Indicates the column or attribute that is displayed when the Query
Editor performs post-filtering on summarized data. When a post

Appendix B. Attribute definitions 155

 filter is defined in the Query Editor, the column that is suppled in
the filter is a real-time column. This exact column name most likely
does not exist in the summarized data table, but is displayed
instead as xxx_min, xxx_max, or xxx_avg. This keyword is used at
the column level.
AGTIM
Indicates an alternate column in the table to be used as a time
stamp during aggregation instead of the default writetime column.
You can only specify the AGTIM keyword for a Time type
attribute. Each table can have only one AGTIM keyword. The
column or attribute containing AGTIM should contain a time
stamp of when the measurement or point in time data was
collected. This keyword is used at the column level.
BEHAV{<value>}
Describes the content of the data. You can only specify the BEHAV
keyword for a numeric attribute type, such as Counter or Gauge.
This keyword is used at the column level. The following list shows
the valid values:
Gauge A range-based number (such as a percentile).
State An enumerated list of options that refers to the condition
of the resource, such as up or down.
Count The number of iterations that have passed. The counter can
be reset.
Property
A characteristic of the resource that rarely changes, such as
the amount of memory or processor speed.
Low The smallest value reported over a particular period of
time.
Peak The largest value reported over a particular period of time.
SampleCount
The number of averaged readings by the Summarization
and Pruning Agent. By default, the SampleCount is stored
in the SAMPLECOUNT column.
DEPRECATED
Indicates columns or attributes in a table that are no longer
supported. Avoid new uses of these columns. This keyword is used
at the column level.
OPTION{HISTORICALTIMESTAMP}
Identifies the timestamp attributes that you want to appear in the
Tivoli Enterprise Portal Timespan window. You can only specify
the OPTION{HISTORICALTIMESTAMP} keyword for a Time type
attribute.
OPTION{PRIMARYKEY=<n>}
Used to designate a key attribute. Required for every table. The
variable n starts at 0 for each attribute and increases by 1 as
necessary. Use PRIMARYKEY=0 for the key of the unique identifier
in a multirow table. For example, if a table describes disk drives,
you should specify PRIMARYKEY=0 with each attribute that
contains the unique ID for each disk drive. This keyword is used at
the column level.

156 IBM Tivoli Universal Agent: User’s Guide

 WHEN{<value>}
Indicates that warehouse functionality is enabled and that data is
already aggregated at the hour level. This optional keyword is
used at the application level. The following list shows the valid
values:
R raw
H hourly
D daily
W weekly
M monthly
Q quarterly
Y yearly
WHSC{<attribute>}
Indicates the column that contains the sample count for the record
so that averages can be calculated. This keyword can be a
comma-separated list of columns that specifies the column and
metrics to which the sample count applies. If a table has multiple
WHSC keywords, each sample count applies only to the columns
specified in the attribute list. If the attribute value is ALL, the
column in which the WHSC tag is supplied is the sample count
field for all metrics in the table.
The following is an example of how you can use the aggregation
parameters in a metafile:
//APPL Disk_Monitor WHEN{R}
//NAME Physical_Disk S 300 Interval=60
//SOURCE ODBC mydatasource
//SQL Select * from Physical_Disk
//ATTRIBUTES
TMZDIFF N 12 @attimezone difference from GMT
WRITETIME D 16 AGTIM
Disk_Name D 64 OPTON{PRIMARYKEY=0}
Timestamp T 16 OPTION{HistoricalTimestamp} @time disk last checked
User_Name D 64 BEHAV{PROPERTY}
OS_Type D 16 BEHAV{PROPERTY}
Avg_Disk_Bytes_Read C 999999 BEHAV{GAUGE}
Disk_Bytes_Sec C 999999 BEHAV{GAUGE}
System_Up_Time C 999999 BEHAV{COUNT}
<help text>
(optional) Defines the help that is displayed when the cursor is moved
over a column heading within a table view.
Notes:
1. The text must be preceded by the “at” (@) sign.
2. The text can not exceed 245 characters.
3. Commas (,) are converted to spaces.
4. If non-English help text is specified, the metafile must have UTF-8
encoding.
<caption>
A meaningful name that you provide for the attribute name. The caption is
displayed in the Tivoli Enterprise Portal. You can specify a caption for
non-English languages.

Appendix B. Attribute definitions 157

Exploring attribute characteristics
You can use the following attribute characteristics to enhance performance
monitoring:
v Attribute duplication
v Invisible attributes
v Left/right truncation
v Support for enumeration

Duplication of attributes
Within an attribute group, as defined by a NAME statement, duplicate attributes
are not allowed. The following procedures handle duplicate attributes.

Attributes of same name and type. Subsequent attributes are deleted and the
validation message KUMPV15W identifies the deleted attribute. Attribute size
helps determine whether attributes are duplicates. If two attributes have the same
name and same type, but differ in size, the IBM Tivoli Universal Agent keeps the
attribute with the larger size. For example, in the following attribute definitions:
InventorySum C10000
.
.
.
InventorySum C 9999

the definition InventorySum C 9999 is deleted.

Attributes of same name but different type. A sequence number is appended to the
duplicate attributes and the warning message KUMPV16W indicates that the
attribute name has changed. For example, the following attribute definitions:
InventorySum D 12
.
.
.
InventorySum C 10000

is modified to:
InventorySum D 12
.
.
.
InventorySum2 C 10000

Note: Unique attribute definitions can become duplicate attributes if the name is
truncated.

Invisible attributes
-attribute-name attribute-type maximum-size

You can use an attribute as an intermediary to derive other attributes. You must
define the attribute in a metafile because it is part of the input application data, or
perhaps serves as a placeholder. Removing this attribute from the output, however,
reduces attribute group complexity and simplifies its use.

158 IBM Tivoli Universal Agent: User’s Guide

 The ClientAddress, Date, Time, and Date_Time attributes listed in the following
example become invisible when output. You cannot have any blank spaces
between the hyphen and the attribute name.
//NAME RequestErrorStatus e
//INTERNAL INPUT InternetLog
//SUMMARY 86400
//ATTRIBUTES
-ClientAddress D 256
ClientLocation (ipAddressToName = ClientAddress)
ClientUserName D 32
Authorized_User K 32
-Date D 10
-Time D 10
-Date_Time (Date + Time)
LocalTimeStamp (CandleTimeStamp = Date_Time)
Time_Zone K 5
Request D 256 SKEY=2
ServiceStatus C 999 SKEY=1 +FILTER={NUMBER>=(0,400)}
BytesReceived C 99999999
Referral D 256 DLM=’/"’
Browser D 256 DLM=’""’
Service D 32
ServerName D 256
RequestParameters D 256
BytesSend C 99999999
RequestElapsedTime C 99999999
*

The attributes ClientLocation and LocalTimeStamp provide information in a format

suitable for output without any information loss. See “Derived attribute functions”
on page 161 for more information about this example.

Left truncation of display attributes

By default, a display type attribute whose data size exceeds the defined data size is
truncated from the right. For example, an attribute data value of ABCDEFGHIJK
for attribute definition
TestName D 8

results in a data value of ABCDEFGH. The same attribute defined using the left
truncation specification DL
attribute-name DL maximum-size

results in a data value of DEFGHIJK.

Enumeration support
For numeric type attributes, you can specify enumeration strings that make
reading the data values much easier. The specification
enumString(numeric_value)

can include as many numeric values as you want within the ENUM{ } block. A
blank space after the ″{″ and another before the ″}″ are required. The enumeration
must come before the ″@″ for the help text.

For example,
ifOperStatus C 999999 ENUM{ up(1) down(2) } @The interface status

specifies enumeration strings of up and down.

Appendix B. Attribute definitions 159

 After you specify an enumeration list, the enumeration strings are displayed in the
Tivoli Enterprise Portal workspace instead of the raw integer values. Exceptions
include integer values without an associated enumeration. You can also code Tivoli
Enterprise Portal situations to compare the enumeration string instead of the raw
value.

If non-English enumeration strings are defined in a metafile, you must save the
metafile in UTF-8 encoding.

Deriving attributes
You can define attributes which are derived from other attributes using the
following specification:
attribute_name (attribute_1 operator attribute_2)

The supported operators are:

Operator Meaning
- attribute_1 minus attribute_2
+ attribute_1 plus attribute_2
* attribute_1 multiplied by attribute_2
/ attribute_1 divided by attribute_2
% attribute_1 divided by attribute_2 times 100

Both of the attributes in the formula must be numeric and either input or derived.
For example,
//APPL NewType
//NAME NewTable K 3600
//SOURCE FILE c:\test.log
//ATTRIBUTES ‘;’
Item_Name D 24 KEY
Width C 1000000
Depth C 1000000
Difference (Width - Depth)
Sum (Width + Depth)
Area (Width * Depth)
Factors (Width / Depth)
Percent (Width % Depth)
Height C 1000000
Volume (Area * Height)

Derived numeric attributes can use hard-coded numeric values. For example,
BytesSent C 999999
KilobytesSent (BytesSent/ 1024)

You can also create a derived numeric attribute from two hard-coded numeric
values.

Derived attributes as real numbers

Derived attributes often prove more useful if displayed as real numbers rather
than as integers. For example, derived attributes such as RequestsPerSecond or
BytesTransferPerSecond can result in numbers too small to be shown as an integer.
If only 100 requests were received in an interval of 3600 seconds, then the result is
0.03. This number is rounded to zero for an integer attribute. To display output
values as real numbers, use the following format:

160 IBM Tivoli Universal Agent: User’s Guide

 attribute-name REAL(derive attribute formula)

The REAL keyword specifies that the attribute output value displays as a floating
point number with up to three decimal point precision.

Note: An attribute which uses the REAL keyword is defined to the Tivoli
Enterprise Portal as a character string and not an integer. Therefore, the
attribute is not eligible for charts or graphs.

Derived attribute string concatenation

attribute-name (character_attribute_1 + character_attribute_2)

The derived attribute feature dictates that input attributes must be numeric
attributes. The exception to this rule is character string concatenation. Both input
attributes are character type attributes joined by the plus (+) operator.

For example, if an attribute group contains the attribute Date and the attribute
Time, you can combine them into one attribute Date_Time for use. If the Date
attribute has the value “Sep 15, 2005 ” and the Time attribute contains “10:31:21”
then the resulting Date_Time attribute is
“Sep 15, 2005 10:31:21”.

Concatenated attribute strings can use literal string values. For example,
SystemName D 32
FullSystemName (SystemName + "_Prod")

You can also create a derived string attribute from two literal strings.

Derived attribute functions

attribute-name (function = from_derive attribute_name)

Derived attribute functions are IBM Tivoli Universal Agent defined functions that
operate on input attribute values. The results as derived attribute values. This
function modifies or reformats a given attribute so that its value becomes more
intuitive for display. It can also be used to reformat an unconventional format into
a standard form to improve comparisons or data correlation.

The following table includes descriptions of derived attribute functions.

Table 24. Descriptions of derived attribute functions
Function name Description Input type
ipAddressToName Convert decimal form ip address to host name. Display
If the address cannot be resolved, then the host
name shown is the input decimal ip address.
CandleTimeStamp Convert free form date and time input character Display
string into standard 16 digit CT time stamp.
NetWareTimeToText Convert special NetWare hexadecimal time Display
value to standard display time format.
UTCtoLocalTime Convert Coordinated Universal Time to local Integer
time in standard 16 digit timestamp.
UTCtoGMT Convert Coordinated Universal Time to GMT Integer
time in standard 16 digit timestamp.

Appendix B. Attribute definitions 161

 The following example includes derived attribute functions:
//NAME RequestErrorStatus e
//INTERNAL INPUT InternetLog
//SUMMARY 86400
//ATTRIBUTES
ClientAddress D 256
ClientLocation (ipAddressToName = ClientAddress)
ClientUserName D 32
Authorized_User K 32
Date D 10
Time D 10
Date_Time (Date + Time)
LocalTimeStamp (CandleTimeStamp = Date_Time)
Time_Zone K 5
Request D 256 SKEY=2
ServiceStatus C 999 SKEY=1 +FILTER={NUMBER>=(0,400)}
BytesReceived C 99999999
Referral D 256 DLM=’/"’
Browser D 256 DLM=’""’
Service D 32
ServerName D 256
RequestParameters D 256
BytesSend C 99999999
RequestElapsedTime C 99999999
*

Filtering attributes
To control the amount of data you see from workspaces, you can specify criteria
for data to be included or excluded. This feature is known as “filtering” attributes.
Filtering attributes can enhance performance of your solution by reducing the
amount of data the IBM Tivoli Universal Agent processes.

Syntax
attribute-name attribute-type maximum-size +FILTER=
{filter1 OR|AND filter2 OR|AND filter3}
attribute-name attribute-type maximum-size -FILTER=
{filter1 OR|AND filter2 OR|AND filter3...}

Description
You can define a maximum of ten filters for an attribute. Attribute filters must be
logically connected entirely by OR operators or by AND operators, but not by a
combination of OR and AND operators. The first two examples
attribute-name attribute-type maximum-size +FILTER={filter1 OR filter2 OR filter3}
attribute-name attribute-type maximum-size +FILTER={filter1 AND filter2 AND filter3}

are supported. The following example is not supported:

attribute-name type size +FILTER={filter1 OR filter2 AND filter3}

Every attribute in an attribute group can have its own filter definition. The Accept
Filter (+FILTER) specifies that the application data is accepted for input. The Reject
Filter (-FILTER) specifies that the application data is excluded. Accept filter
specifications and reject filter specifications must be enclosed by braces { }. An
accept filter and a reject filter on the same attribute is not supported.

You must capitalize the -FILTER, +FILTER, SCAN, MATCH, NUMBER, and the
logical operators OR and AND.

162 IBM Tivoli Universal Agent: User’s Guide

You must define each filter specification in the following format:
filter-function(data-offset, filter-value)

The filter-function consists of character string functions and number functions. The
character string functions are used for filter definition against character types of
attribute data, such as DisplayType or RecordType. The number functions work
with numeric attribute data, such as CounterType. If non-English text is specified
for any character-string filter functions, you must save the metafile in UTF-8
encoding.

The filter-function must include two positional operands, data-offset and

filter-value, enclosed in parentheses. The data-offset defines the offset from the
beginning of attribute data where comparison is made against the filter-data. For
number filter functions, the positional data-offset parameter cannot be omitted, but
must be zero.

The table below summarizes the characteristics of various filter functions.

Table 25. Filter function characteristics
Attribute
Function Description type Data offset Filter value
SCAN Check for filter character string D,R,T,Z,N 0<=max size Characters
occurrence in the attribute string
starting from offset position to the
end of attribute data string or up
to maximum defined attribute
size.
MATCH Check for exact match of filter D,R,T,Z,N 0<=max size Characters
character string occurrence in the
attribute string starting from
offset position.
NUMBER= Compare attribute value equal to A,C,G,?, 0 Numeric
filter value. #,%
NUMBER> Compare attribute value greater A,C,G,?, 0 Numeric
than filter value. #,%
NUMBER< Compare attribute value less than A,C,G,?, 0 Numeric
filter value. #,%
NUMBER>= Compare attribute value greater A,C,G,?, 0 Numeric
than or equal to filter value. #,%
NUMBER<= Compare attribute value less than A,C,G,?, 0 Numeric
or equal to filter value. #,%

Note: For the File Data Provider in COPY monitoring mode, the first record in a
file that is being monitored starts a block of records. Therefore, it always is
displayed in the report, whether or not it should have been eliminated by
the filter. For a complete description of file-mode, see“SOURCE statement” on
page 126.

Example 1

The IBM Tivoli Universal Agent File Data Provider monitors a file for customer
sign-on activities. The attribute filter performs early filtering by accepting file
records containing the character string Processing Signon or FIRST TIME SIGNON
only.

Appendix B. Attribute definitions 163

 //APPL ABC
//NAME SignOn S 900
//SOURCE FILE f:\IB.log tail
//ATTRIBUTES
Date D 4
Time D 8
Message Z 256 +FILTER={SCAN(0,Processing Signon) OR SCAN(0,FIRST TIME SIGNON)}

Example 2

The IBM Tivoli Universal Agent monitors application transactions. The application
program outputs a dash character whenever a customer provides a transaction
request that is not valid. The attribute filter rejects all input data with transaction
attribute “-“ to remove application records that are not valid.
//NAME Transaction_Stat e
//ATTRIBUTES ’,’
CustomerName D 256
CustomerAddress D 32
Date D 12
Time D 12
TransactionName D 256 -FILTER={MATCH(0,-)}
TransactionParameters D 256

Example 3

The IBM Tivoli Universal Agent monitors an internet server log for internet server
request status codes greater than 400®.
//NAME Status_Stat e
//SOURCE FILE ’c:\program files\WebServer\server.log’
//ATTRIBUTES
ClientLocation D 256
ClientUserName D 32
Authorized_User K 32
Date_Time DL 20
Time_Zone K 5
Request D 256
ServiceStatus C 99999999 +FILTER={NUMBER>=(0,400)}
BytesReceived C 99999999
Referral D 256
Browser D 256

Sequencing attribute definitions

The definition sequence of an attribute group defines the order in which the IBM
Tivoli Universal Agent extracts input application data. This sequence is also the
order of data presented to other IBM Tivoli Monitoring components. The IBM
Tivoli Universal Agent assigns a new application definition version number when
the attribute sequence changes. For example, when new attributes have been
added or existing attributes deleted.

Syntax
attribute-name attribute-type maximum-size SEQ=n

Description
When you define an attribute sequence, attribute definitions match the application
data as delivered to the IBM Tivoli Universal Agent. The IBM Tivoli Universal
Agent can also present a consistent attribute sequence to the CT components.

164 IBM Tivoli Universal Agent: User’s Guide

You can use the input sources from different applications as a single application.
For instance, the WEB server logs from an Apache server or Netscape server or
Microsoft IIS contain similar information. However, the log record layouts are
different. Without the attribute sequence definition, three metafiles of three unique
application names are needed. Each metafile contains similar attributes, sequenced
in the order corresponding to the specific WEB server log file format. The three
applications require a considerable amount of work to create IBM Tivoli
Monitoring situations and policies and, as a result, increase the complexity of
application management.

The following example represents a metafile definition for an Apache server log
and an MS IIS log. They are displayed as the same application eLog when you use
an attribute sequence definition.
//APPL eLog
//NAME ServerLog e
//SOURCE FILE d:\Apache\logs\Apache.log
//ATTRIBUTES
*-------------------------------------------*
* Apache Server Log Record Format Layout *
*-------------------------------------------*
ClientLocation D 256 SEQ=1
ClientUserName D 32 SEQ=2
Authorized_User K 32
Date_Time DL 20 SEQ=3
Time_Zone K 5
Request D 256 SEQ=9
ServiceStatus C 99999999 SEQ=8
BytesReceived C 99999999 SEQ=6
Referral D 256 SEQ=12 DLM=’/"’
Browser D 256 SEQ=13 DLM=’""’
Service D 32 SEQ=4
ServerName D 256 SEQ=5
RequestParameters D 256 SEQ=10
BytesSend C 99999999 SEQ=7
RequestElapsedTime C 99999999 SEQ=11
*

//APPL eLog
//NAME ServerLog e
//SOURCE FILE c:\Inetpub\logs\IIS.log
//ATTRIBUTES ’,’
*-------------------------------------------*
* Microsoft IIS W3C Log Record Format Layout*
*-------------------------------------------*
ClientLocation D 256 SEQ=1
ClientUserName D 32 SEQ=2
Date_Time D 20 SEQ=3
Service D 32 SEQ=4
ComputerName K 64
ServerName D 256 SEQ=5
RequestElapsedTime C 99999999 SEQ=11
BytesReceived C 99999999 SEQ=6
BytesSend C 99999999 SEQ=7
ServiceStatus C 99999999 SEQ=8
WindowsStatus K 99999999
OperationName K 8
Request D 256 SEQ=9
RequestParameters D 256 SEQ=10
PadParm2 K 8
PadParm3 K 8
PadParm4 K 8
PadParm5 K 8
Referral D 256 SEQ=12
Browser D 256 SEQ=13

Appendix B. Attribute definitions 165

 In the following example, the application program added three new attributes. By
using an attribute sequence definition, version change is avoided.

Old application data definition:

//APPL DTY
//NAME ConsoleMessage e
//ATTRIBUTEs ‘;’
MessageID D 12
MessageSeverity C 99
MessageCategory C 99
MessageDescription Z 255

New application data definition:

//APPL DTY
//NAME ConsoleMessage e
//ATTRIBUTEs ‘;’
MessageOrigin D 80 SEQ=5
MessageID D 12 SEQ=1
MessageSeverity C 99 SEQ=2
MessageCategory C 99 SEQ=3
MessageAction D 80
MessageStatus D 16
MessageDescription Z 255 SEQ=4

An attribute that does not include a sequence definition appears after attributes
with sequence specifications in the order as defined in the metafile. In the example
above, the attribute MessageAction appears after attribute MessageOrigin and is
followed by the attribute MessageStatus.

SNMP attributes
This appendix presents information about the attributes defined in the IBM Tivoli
Universal Agent applications supported by the SNMP Data Provider. It discusses
how MIB variables are mapped to IBM Tivoli Monitoring attributes, how attribute
groups are named, and how attribute characteristics are determined. It also
provides descriptions of the attributes in the seven attribute groups associated with
the SNMP-MANAGER application.

About attributes and attribute groups

You use attributes to create situations that define rules for monitoring alerts and
exceptions. For example, you can create situations that monitor for alerts of a
specific severity or from a particular device. When the values for attributes of
alerts relayed to a Tivoli Enterprise Monitoring Server match the values you
specify in situations, the managed objects associated with the situations change
appearance, alerting you to problems or any actions startd in association with
situations.

Mapping of MIB variables to attributes

The process of translating MIB variables to IBM Tivoli Universal Agent attribute
groups consists of walking down the OID tree for a MIB, starting at a specified
MIB object name. A new attribute group is created for each new group of scalar
variables encountered and one for each new conceptual table. Each time a new
attribute group is created, all MIB variables within the scope of that group are
defined as attributes within the group.

Naming of attribute groups

The names of attribute groups take the form
AAANNNVV

166 IBM Tivoli Universal Agent: User’s Guide

where:
AAA is the application name
NNN is the name of the attribute group
VV is the version number of the application

For example, the name of the attribute group that corresponds to the
SNMP-MANAGER TRAP workspace is:
SNMP-MANAGERTRAP00

Determining attribute characteristics

IBM Tivoli Monitoring recognizes only two types of data: integer and character. In
the process of converting MIBs to metafiles, the IBM Tivoli Universal
Agenttranslates ASN.1 types to IBM Tivoli Monitoring integers or characters and
defines a length in the generated metafiles. Table 26 shows the SMIv1 defined
types and their corresponding IBM Tivoli Monitoring types.
Table 26. Translation table for ASN.1 to IBM Tivoli Monitoring types
IBM Tivoli Monitoring
ASN.1 type Definition type
INTEGER INTEGER (0...2147483647) Positive 32-bit signed
integer
OCTETS A sequence of zero or more octets Char array of size N
(SIZE(0..n)) (bytes). If size is not defined, a default of
256 is used and truncation can occur
OID A sequence of non-negative integers in Char array of size 1024
dotted notation. Treated as a character
string with a maximum length 1024.
ENUM An enumeration list Positive 32-bit signed
integer
TimeTicks INTEGER (0..2147483647) Positive 32-bit signed
integer
Gauge INTEGER (-2147483648..2147483647) 32 -bit signed integer
Counter INTEGER (0..2147483647) Positive 32-bit signed
integer
IpAddress Octet string SIZE((4)). This is the 4 byte Char array of size 32
integer address converted to a string
with either host name or dotted decimal
address.
NetworkAddress Same as above Char array of size 32
Opaque Octet string Char array of size 256

MIB-2 attribute groups

The MIB-2 application consists of 17 attribute groups:
v ATTABLE
v EGP
v EGPNEIGHTABLE
v GLOBALVARIABLES
v ICMP
v IFTABLE
v INTERFACE
Appendix B. Attribute definitions 167
 v IP
v IPADDRTABLE
v IPNETTOMEDIATABLE
v IPROUTETABLE
v SNMP
v SYSTEM
v TCP
v TCPCONNTABLE
v UDP
v UDPTABLE

Where to find further information on MIB-2 attributes

For information about the MIB-2 attributes, consult the corresponding MIB or view
the attribute descriptions available in the IBM Tivoli Universal Agent online help
system.

SNMP-MANAGER attribute groups

The SNMP-MANAGER application consists of seven attribute groups:
v MANAGED-NODES
v MIBNODATA
v MIBSTATUS
v NETSUMMARY
v NETWORK
v ROUTER
v TRAP

The attributes in these groups are discussed in detail in the following sections.

168 IBM Tivoli Universal Agent: User’s Guide

MANAGED-NODES attribute group
This attribute group enables you to monitor information about the nodes you
identified in your Hot List. For example, you might create a situation that notifies
you whenever one of the devices or hosts listed goes off-line.

Address
The IP address of the managed node.

Valid entries: A dotted decimal IP address.

Example:
*SCAN SNMP-MANAGERMANAGED-NODES00.Address *EQ 127.0.0.0

Current_Response_Time_ms
The round trip response time for ping requests sent from the SNMP Data Provider
to the node.

Valid entries: Milliseconds

Example:
*SCAN SNMP-MANAGERMANAGED-NODES00.Current_Response_Time_ms *GE 500

Name
The resolvable node name

Valid entries:
v Ttext string
v Up to 128 characters

Example:
*SCAN SNMP-MANAGERMANAGED-NODES00.Name *EQ Everest

Node_Description
The description of the node characteristics as defined by a network administrator
or device manufacturer.

Valid entries:
v Text string
v Up to 256 characters

Example:
*SCAN SNMP-MANAGERMANAGED-NODES00.Node_Description *EQ hub

Node_Status
The current operational status of the node.

Valid entries:
v On-line
v Off-line

Example:
*SCAN SNMP-MANAGERMANAGED-NODES00.Node_Status *EQ Off-line

Appendix B. Attribute definitions 169

 Node_Type
The network type, as defined by the Internet standard RFC 1213 System group
sysServices MIB variable specification

Valid entries: The valid types are:

Repeaters The node supports Layer 1 (physical layer) protocols.
Bridges The node supports Layer 2 (data link and subnetwork) protocols.
Gateways The node supports Layer 3 (internetwork) protocols such as IP
routers.
Hosts The node supports end-to-end network operation.
Applications The node is capable of running network applications such as mail
servers.
IP Node A valid IP host without active SNMP agents.

Usage: Use a comma-delimited string to specify several types.

Example:
*VALUE MANAGED-NODES00.Node_Type *EQ Gateways,Hosts,IP Node

Status_TimeStamp
The date and time the status of the node was last checked

Valid entries: The format is yyyy/mm/dd hh:mm:ss mmm

Example:
2005/04/30 14:23:55 010

170 IBM Tivoli Universal Agent: User’s Guide

MIBNODATA attribute group
The MIBNODATA attributes identify the MIB tables for which monitoring agents
do not return data.

Enterprise_Module
The data collection MIB enterprise name.

Valid entries:
v Text string
v Up to 64 characters.

No_Data_Tables
A list of Enterprise tables for which the agent returns no data.

Valid entries:
v Text string
v Up to 216 characters.

Node_Name
Node name of the monitored system.

Valid entries:
v Text string
v Up to 32 characters.

Appendix B. Attribute definitions 171

 MIBSTATUS attribute group
The MIBSTATUS attributes enable you to monitor the status of MIBs, attribute
groups, and agents for which you are collecting data.

Attribute_Group
The name of the attribute group for which data is being collected

Valid entries:
v Text string
v Up to 32 characters

Example:
*SCAN SNMP-MANAGERMIBSTATUS00.Attribute_Group *EQ MIB-2EGP00

Enterprise
The enterprise name of the MIB on which the monitored application is based

Valid entries:
v text string
v up to 64 characters

Monitor_Agent_Info
A string of host name–community name pairs for the hosts currently being
monitored

Valid entries:
v enclosed in braces
v separated by commas

Example:
{athens public},{sparta public}

Monitor_Interval
The currently active monitor interval

Valid entries:
v seconds

Last_Sample_TimeStamp
The data and time at which the data was last sampled

Valid entries: The format is yyyy/mm/dd hh:mm:ss mmm

Example:
2005/04/30 14:23:55 010

172 IBM Tivoli Universal Agent: User’s Guide

NETSUMMARY attribute group
The attributes of the NETSUMMARY group provide high-level information for all
the networks in your enterprise.

Active_Nodes
The total number of network nodes that are currently active

Valid entries:
v integer

Curr_RespTime_ms
The current response time, in milliseconds, for data packets from the SNMP Data
Provider to nodes located in this network

Valid entries:
v integer

Inactive_Nodes
Total number of network nodes that are inactive, including available unoccupied
network addresses on this network

Valid entries:
v integer

Managed
Indicates whether a particular network is being managed

Valid entries:
v Yes
v No

Max_RespTime_ms
The maximum observed response time, in milliseconds, for data packets from the
SNMP Manager to nodes located in this network

Valid entries:
v integer

Min_RespTime_ms
The minimum observed response time, in milliseconds, for data packets from the
SNMP Data Provider to nodes located in this network

Valid entries:
v integer

Network_Address
The TCP/IP network subnet 32-bit Internet address

Valid entries:
v dotted decimal format

Example:
127.0.0.0

Appendix B. Attribute definitions 173

 Network_Mask
The corresponding network mask of a discovered network address

Valid entries:
v dotted decimal format

Example:
127.0.0.0

Network_Routers
A list of routers serving this network

Valid entries:
v up to 256 characters
v separated by commas

Example:
smbb7k-s23,wlbbags-s3,198.210.36.1

174 IBM Tivoli Universal Agent: User’s Guide

NETWORK attribute group
The NETWORK group contains attributes pertaining to network topology.

Address
The Internet network address of a node within a managed network

Valid entries:
v dotted decimal address

Description
The description of the node characteristics as defined by a network administrator
or device manufacturer. This attribute value corresponds to the RFC 1213 System
Group sysDescr MIB variable specification.

Valid entries:
v up to 256 characters

Location
The node location information as defined by a network administrator. This
attribute value corresponds to the RFC 1213 System Group sysLocation MIB
variable specification.

Valid entries:
v up to 128 characters

Name
The name assigned to this node

Valid entries:
v up to 128 characters

SNMP_Enabled
Indicates whether an SNMP MIB-2 agent is active on the network node

Valid entries:
v Yes
v No

Status
The current operational status of the network node

Valid entries: The possible node statuses are:

On-line the node has been contacted and is operational
Inactive the node is not operational and it is not responding to SNMP Get
requests or ping requests

Type
The network type, as defined by the Internet standard RFC 1213 System group
sysServices MIB variable specification

Valid entries: The valid types are:

Repeaters The node supports Layer 1 (physical layer) protocols.
Bridges The node supports Layer 2 (data link and subnetwork) protocols.

Appendix B. Attribute definitions 175

 Gateways The node supports Layer 3 (internetwork) protocols such as IP
routers.
Hosts The node supports end-to-end network operation.
Applications The node is capable of running network applications such as mail
servers.
IP Node A valid IP host without active SNMP agents.

Usage: You can enter a comma-delimited string to specify several types.

Example:
Applications,Hosts,Gateways,Bridges

176 IBM Tivoli Universal Agent: User’s Guide

ROUTER attribute group
The ROUTER group contains information pertaining to routers in your enterprise.

Destination_Networks
A list of the network addresses serviced by a router

Valid entries:
v dotted decimal addresses
v comma delimited

Example:
127.0.0.0, 127.0.0.1

Route_Count
The total number of routable subnetworks defined to this router

Valid entries:
v integers

Router_Address
The Internet network address of the router

Valid entries:
v dotted decimal format

Example:
127.0.0.0

Router_Description
A description of the router characteristics, as defined by the device manufacturer.
This attribute value corresponds to the RFC 1213 System Group sysDescr MIB
variable specification.

Valid entries:
v up to 256 characters

Router_Name
The name assigned to this router

Valid entries:
v up to 64 characters

Router_Status
The current router status

Valid entries: The possible statuses are:

Verify The SNMP Data Provider is in the process of verifying router
status.
On-line The router is active and operational.
Off-line The router is not operational.
Passive The router is a daemon and it is not actively participating in
network operation.

Appendix B. Attribute definitions 177

 TRAP attribute group
The TRAP attributes describe all the information known about traps received by
the SNMP Data Provider. Most of the values for the attributes in this group can be
defined in the trap configuration file. See Appendix D, “SNMP trap configuration,”
on page 203 for more information.

Alert_Name
The alert name associated with an SNMP trap as defined in the trap configuration
file

Valid entries:
v up to 32 characters

Category
The category of the event that caused the trap as defined in the trap configuration
file

Valid entries: The default categories are:

v Threshold Events
v Network Topology Events
v Error Events
v Status Events
v Node Configuration Events
v Application Alert Events (default)
v All Category Events
v Log Only Events
v Map Events
v Ignore Events

Usage: In the situation definition, enclose values in quotation marks (““).

Description
The trap description as defined in the trap configuration file

Valid entries:
v up to 256 characters

Enterprise_Name
The abbreviated texual form of the enterprise object ID as defined in the trap
configuration file

Valid entries:
v up to 64 characters

Usage: You must specify the name exactly as it is displayed in the trap
configuration file. The name is case-sensitive. In the situation definition, enclose
values in quotation marks (““).

Generic_Trap
The generic trap number

Valid entries: One of:

0 ColdStart

178 IBM Tivoli Universal Agent: User’s Guide

1 WarmStart
2 LinkDown
3 LinkUp
4 Authentication Failure
5 EGPNeighborLoss
6 Enterprise specific trap

Example:
*SCAN SNMP-MANAGERTRAP00.Generic_Trap *EQ 2

Object ID
The identifier that uniquely identifies the trap in the MIB

Valid entries:
v text string
v up to 512 characters

Severity
The severity of the trap as defined in the trap configuration file

Valid entries:
v text string
v up to 32 characters

Source_Name
The host name or IP address of the SNMP agent that sent the trap

Valid entries:
v text string
v up to 64 characters

Source_Status
Identifies a status with a source as defined in the trap configuration file

Valid entries:
v text string
v up to 32 characters

Source_Type
Further specifies a source category of SNMP trap as defined in the trap
configuration file

Valid entries:
v text string
v up to 32 characters

Specific_Trap
The enterprise-specific trap number. Applies only when Generic_Trap = 6.

Valid entries:
v integer

Appendix B. Attribute definitions 179

 Time_Stamp
The date and time at which the trap occurred

Valid entries: The format is CYYMMDDHHMMSSmmm, where

C = Century (1 for 21st)

YY = Year
MM = Month
DD = Day
HH = Hour
MM = Minute
SS = Second
mmm = Millisecond

Value_List
A string with all the data from a trap variable binding list

Valid entries: The string is constructed as:

{OID[type]=value}{OID[type]=value}{oid[type]=value}...

where:
oid defines the MIB variable object identifier
type is the ASN.1 type
value is the variable value

Each triplet is surrounded by braces ({ }).

If a metafile has been imported which contains names for the variables in the
received trap, use the variable names instead of the raw OIDs:
{variableName=value}

Example:
*SCAN SNMP-MANAGERTRAP00.Value_List *EQ datagram=error

180 IBM Tivoli Universal Agent: User’s Guide

Appendix C. Console commands
This appendix contains descriptions and syntax of the console commands you can
use with the IBM Tivoli Universal Agent data providers.

Using console commands

The Console Command Interface lets you control the operational configuration of
an IBM Tivoli Universal Agent dynamically. This service is particularly useful since
it enables the IBM Tivoli Universal Agent to support applications without
interruption when new applications come online or attributes change. You invoke
the interface using the KUMPCON program.

In addition, you have the option of issuing console commands from the Tivoli
Enterprise Portal. To issue commands from the Tivoli Enterprise Portal, right-click
an IBM Tivoli Universal Agent managed system and select the Take Action...
option. For more information about TakeAction commands, see the Tivoli Enterprise
Portal Administrator’s Guide or the online Help for IBM Tivoli Universal Agent.

The console commands are summarized in Table 27 on page 183 and discussed in
greater length in the following sections. Commands that are available through
TakeAction are tagged with an asterisk (*).

Invoking the console command interface on Windows

operating systems
You invoke the console commands from the command line by invoking the
program KUMPCON:
KUMPCON command [parameter]

You can also call the kumpcon program from inside a script, which is useful for
automating frequently performed tasks. For the KUMPCON program to run, it
must be able to find its shared libraries. On Windows operating systems, the
shared libraries reside in the same directory as the KUMPCON program so it has
no trouble locating them. You can obtain a list of valid console commands by
entering:
KUMPCON ?

You can enter a command in abbreviated form. For example, you can enter the
DELETE command as either DELETE or D and the SHOW command as SHOW or
SHO. Both uppercase or lowercase characters are allowed. The program converts
all input command characters to uppercase for validation.

Invoking the console command interface on UNIX operating

systems
On UNIX operating systems, you cannot run the KUMPCON program directly.
Instead use the um_console shell script, which serves as a wrapper around
KUMPCON. The um_console script sets the correct environment variables so that
KUMPCON can find the shared libraries it needs to start.

On UNIX operating systems, enter:

um_console -h <install_dir>

© Copyright IBM Corp. 2003, 2005 181

 Note: The -h parameter is required if you have not previously set the <install_dir>
environment variable.

Call um_console without specifying a console command. After the script invokes
the KUMPCON program, you are prompted for a command:
Enter console command <Application name or Metafile name or file name>

Specifying metafile and application names in commands

When specifying a metafile, you must use exactly the same name you used when
the metafile was first defined to the IBM Tivoli Universal Agent. For instance, if a
metafile was imported to the IBM Tivoli Universal Agent using its fully-qualified
name, you must use the fully-qualified name in other console commands.
Conversely, if a metafile was first defined to the IBM Tivoli Universal Agent using
an unqualified name, the unqualified file name must be used on all other
commands.

Some console commands accept the IBM Tivoli Universal Agent application name
as an input parameter instead of the metafile name. In those cases, the name of the
application is case-sensitive and must exactly match the name of the application as
specified in the APPL statement in the metafile.

If you have created subdirectories in the working directory, you can refer to a
metafile or an application using a relative path:
kumpcon import .\SNMP\standard\RFC1213_mib-2.mdl

Multi-interface systems
If you run kumpcon on a host with multiple interfaces and you have configured
the IBM Tivoli Universal Agent to use a particular interface through environment
variable kum_dch_hostname, you need to set environment variable
kump_api_dpapi_host to the same value if you are sending commands to the ASFS
or APIS Data Provider.

Sending console commands to an alternate IBM Tivoli

Universal Agent instance
The console command interface to a non-primary IBM Tivoli Universal Agent
requires you to specify the KUMP_DPCONSOLE_PORT environment variable to
target the correct IBM Tivoli Universal Agent. By default, the target IBM Tivoli
Universal Agent is the primary and it uses console port 7700. To prevent you from
accidentally issuing commands against the wrong IBM Tivoli Universal Agent
when an alternate instance of the IBM Tivoli Universal Agent is being accessed
through the console interface, the Instance Name is displayed next to each data
provider in the prompt for the target data provider. The following screen shot
shows how setting KUMP_DPCONSOLE_PORT to 8700 causes the TEST data
providers to be listed so that you know which IBM Tivoli Universal Agent instance
you are accessing. You can determine the correct console listening port to use by
checking the UAGENT DPLOG workspace.

182 IBM Tivoli Universal Agent: User’s Guide

The Take Action interface does not have this ambiguity problem. When
distributing an action such as Import or Refresh, the list of available managed
system names includes the Instance Name prefix so you can always select the
appropriate data provider.
Table 27. Summary of console commands
Console command Description
DELETE* Removes a defined application data
specification.
GENERATE Builds a complete and syntactically correct
ODBC metafile when given a data source
name as input.
IMPORT* Loads and initializes an application data
definition.
LIST List currently defined applications.
LOADCOMM* Loads and initializes the agent community
name table, KUMSCOMM.
LOADLIST* Loads managed node lists (hot lists).
LOADNAME* Loads and initializes the network symbolic
name table, KUMSNAME.
MNL ADD NODE* Adds an entry into a managed node list.
MNL REMOVE NODE* Removes an entry from a managed node list.
REFRESH* Re-initializes an application data definition.
SET Allows you to redirect console commands to
an IBM Tivoli Universal Agent running on a
host other than the host on which you issue
the commands.
SHOW Displays application data definition details.
SHUTDOWN* Initiates normal shutdown procedure.
TRAPCNFG* Instructs the SNMP Data Provider to refresh
the SNMP trap configuration file.
UNPACK Unpacks the input SNMP metafile and
outputs the identical uncompressed version
of the metafile in the same input metafile
location.
VALIDATE Instructs the IBM Tivoli Universal Agent to
validate the specified metafile.

* These commands are also available using a TakeAction selection.

Appendix C. Console commands 183

DELETE
The DELETE command removes a defined application from the IBM Tivoli
Universal Agent repository. If the application is active, the IBM Tivoli Universal
Agent disconnects the connection to the application and ″unregisters″ it. Any IBM
Tivoli Monitoring managed systems associated with the application that are online
go offline. The name of the metafile is automatically removed from the
KUMPCNFG configuration initialization file so that the application will not be
activated the next time the IBM Tivoli Universal Agent is restarted.

Syntax
KUMPCON DELETE [application-name | metafile-name]

Parameters
You can specify either the name of the IBM Tivoli Universal Agent application or
the name of the metafile.
<application-name>
Specifies the IBM Tivoli Universal Agent application. The name of the IBM
Tivoli Universal Agent application is specified in the APPL statement in the
data definition metafile.
<metafile-name>
Specifies the metafile name.

Usage
Use the following example prior to invoking the kumpcon delete command to
avoid a delete confirmation prompt:
KUMP_DPCONSOLE_NOCONFIRM=Y

When the delete command is issued from an automated script is an example for
when you would want to use this option.

184 IBM Tivoli Universal Agent: User’s Guide

GENERATE
The GENERATE command automatically builds a complete and syntactically
correct ODBC metafile when given a data source name as input. This command
supports full generation of all tables defined to the specified data source. You can
also limit which tables are generated by selecting user tables, system tables, views,
or some combination of the three, and specify a beginning string of characters to
pattern match against any of the three table types.

The GENERATE command does not support metafile creation for stored
procedures. You can start this command even when the IBM Tivoli Universal
Agent is not running. GENERATE is only accessible on Windows operating
systems and only through the kumpcon console interface. It is not available
through Take Action.

Syntax
KUMPCON GENERATE dataSourceName user=userid pswd=password

Parameters
<dataSourceName>
Indicates the specific name of the configured data source that is used to
create the ODBC metafile. This parameter is required. If the data source
contains any embedded blanks, it must be surrounded with single
quotation marks.
<userid>
The userid what connect to the ODBC data source. If no user/password
combination is required for this particular data source, then you can omit
the user= parameter from the GENERATE command.
<password>
The password associated with the userid connecting to the ODBC data
source. If specified, the user and pswd values are inserted into every
//SOURCE statement in the generated ODBC metafile.

Examples
The following examples illustrate ways of invoking GENERATE:
KUMPCON GENERATE nwind

This command generates a metafile in the metafiles directory called nwind.mdl

that contains every table and column in the nwind data source.
KUMPCON GENERATE cnps user=sa pswd=abcdef

This command generates a metafile in the metafiles directory called cnps.mdl that
contains every table and column in the cnps data source. The ″user=″ and ″pswd=″
parameters are required to connect to that data source.

After the console input is accepted, you can indicate whether to include user
tables, system tables, and/or views through the menu options and prompts
depicted in the following figure.

Appendix C. Console commands 185

Figure 12. KUMPCON GENERATE example

By entering a menu options other than ″4) All of the above″, you can build a more
focused and targeted metafile. You can also pattern match on a beginning string in
the table name, for example, all system tables starting with ″sys″. An important
benefit of generating specific tables, instead of all tables, for an ODBC data source
is that it can sometimes significantly reduce the time it takes for metafile
generation to complete.

Certain database products, such as SQL Server and Sybase, allow you to connect to
one of several databases associated with a particular data source. If you are
generating a metafile for one of these database products, you are prompted to
enter a specific database to use. Each database context can have a different set of
user tables associated with it. If you want to generate a metafile for a non-default
database context, reply Y to the prompt, enter the name of the database and,
optionally, the name of a specific server associated with that database. If the
default database context is adequate, then you can skip this prompt.

GENERATE uses the data source name to determine the output metafile name. If a
metafile by that name already exists in the \TMAITM6\metafiles directory, you are
prompted as to whether you want to replace it.

Usage
The resulting generated metafile provides a good first step towards creating a
useful ODBC metafile, but most likely will require some changes. After
KUMPCON GENERATE completes, review the following areas in the metafile for
possible modification:
v The first three characters of the //APPL name need to be changed to make them
unique. No other IBM Tivoli Universal Agent applications with those same first
three characters should connect to the same Tivoli Enterprise Monitoring Server.
v A default maximum of 64 tables is allowed in a metafile. Full generation of an
ODBC data source can result in hundreds or even thousands of //NAME
statements. If so, you need to divide the metafile.

186 IBM Tivoli Universal Agent: User’s Guide

v A default maximum of 63 attributes is allowed in a single attribute group. This
value is automatically updated to 127 at run-time through the use of the
KIB_MAXCOLS environment variable. It is possible that 127 is not enough if
there are more columns than that in a single SQL table. If this is the case,
consider dividing the attribute group into smaller attribute groups that each
select a subset of all of the possible SQL columns.
v The preceding two issues could require that unwanted tables and attributes be
removed.
v Review the attribute data types and maximum sizes for correctness in case they
are not exactly what you want.
v If the default “Select * from &tableName” is not appropriate, use a more
qualified Select statement with specific columns listed or with Where clause
filtering.
v Some database products, such as DB2 and Oracle, require double quotation
marks around table names that contain lowercase or special characters. Review
the //SELECT statements in the generated metafile for table names that require
double quotation marks.For example, in the metafile for an Oracle table,
change //SELECT * from Tivoli.System to //SELECT * from "Tivoli"."System".
v Review any attribute defined as KEY, which corresponds to an indexed column
in the SQL table. Each KEY attribute in every data row must have a non-blank,
non-NULL value or the row is not sent to the data server. If the table you are
monitoring is occasionally missing values for a KEY attribute, then remove the
KEY designation.
v By default, each //NAME statement uses the SQL table name as its attribute
group name. You can change some or all of these to more meaningful names.
v Check any numeric attributes that you plan to use for comparison purposes in
situations or for creating derived attributes. These must be defined with one of
the true numeric attribute types, such as ’C’ for Counter. If a numeric attribute is
generated, for example, as attribute type ’N’, then it is treated as a display string
type value instead of as an integer, and your greater than/less than situation
comparisons won’t work as expected.
v You can insert optional IBM Tivoli Universal Agent metafile features, such as
filters, derived attributes, AddTimeStamp, and attribute help text.
v A maxrows=<nnn> parameter override on the //SOURCE statement is
necessary if the default value is inadequate. By default, maxrows is set to 100
unless overridden with the KUMP_ODBC_MAX_ROWS environment variable.
v Ensure that the default time-to-live value of 300 seconds is appropriate.
v If any character attributes in the relational table contain non-English data,
change the 'D' or 'N' attribute type to 'U' for Unicode.

After making changes to the generated metafile, run VALIDATE against it to make
sure there are no errors or warning messages to correct.

Appendix C. Console commands 187

IMPORT
The IMPORT command adds an application to the IBM Tivoli Universal Agent
repository. If the metafile is successfully imported, the name of the metafile is
automatically added to the KUMPCNFG configuration initialization file.
Subsequently, the metafile is loaded automatically when the agent is restarted.

Syntax
KUMPCON IMPORT metafile-name

Parameters
<metafile-name>
Specifies an existing metafile name that is accessible to the data provider.

188 IBM Tivoli Universal Agent: User’s Guide

LIST
The LIST command displays a list of metafile applications currently known by the
IBM Tivoli Universal Agent.

Syntax
KUMPCON LIST

Parameters
This command requires no input parameters. Any specified parameter is ignored.

Output
The output of the LIST command can look like the following:
No application defined

or
Active application definitions:
vmstat.mdl
TCPioQ.mdl
CustInq.mdl

Appendix C. Console commands 189

LOADCOMM
The LOADCOMM command instructs the SNMP Data Provider to reload the
KUMSCOMM file. The KUMSCOMM file matches host names to SNMP
community names.

Syntax
KUMPCON LOADCOMM

Parameters
This command requires no input parameters. Any specified parameter is ignored.

190 IBM Tivoli Universal Agent: User’s Guide

LOADLIST
Loads the SNMP Managed Node list (also known as Hot List).

Syntax
KUMPCON LOADLIST managed_node_list_name

Parameters
<managed_node_list_name>
The name of the file in which the hot list is defined.

Appendix C. Console commands 191

LOADNAME
The LOADNAME command instructs the SNMP Data Provider to reload the
KUMSNAME file. The KUMSNAME file defines symbolic names for networks.

Syntax
KUMPCON LOADNAME

Parameters
This command requires no input parameters. Any specified parameter is ignored.

192 IBM Tivoli Universal Agent: User’s Guide

MNL ADD NODE
Adds a network resource to a managed node list

Syntax
KUMPCON MNL Add Node LIST=managed_node_list_name NODE=node_name

Parameters
<managed_node_list_name>
The name of an existing SNMP Managed Node List file.
<node_name>
The resource name to be added to the list.

Appendix C. Console commands 193

MNL REMOVE NODE
Removes a network resource from a managed node list

Syntax
KUMPCON MNL Remove Node LIST=managed_node_list_name NODE=node_name

Parameters
<managed_node_list_name>
The name of an existing SNMP Managed Node List file.
<node_name>
The resource name to be removed from the list.

194 IBM Tivoli Universal Agent: User’s Guide

REFRESH
The REFRESH command performs the combined functions of the DELETE and
IMPORT commands.

Syntax
KUMPCON REFRESH metafile-name

Parameters
<metafile-name>
Specifies an existing metafile name that is accessible to the data provider.

Usage
Use the following example prior to invoking the kumpcon refresh command to
avoid a refresh confirmation prompt:
KUMP_DPCONSOLE_NOCONFIRM=Y

When the refresh command is issued from an automated script is an example for
when you would want to use this option.

Appendix C. Console commands 195

SET
You can run the KUMPCON program on a different host than the IBM Tivoli
Universal Agent. By default KUMPCON assumes that it is to communicate with
the IBM Tivoli Universal Agent on the same host. To direct your commands to the
IBM Tivoli Universal Agent on a different host, issue the SET command. You are
then prompted for the command you want to issue on the remote host.

You need to issue SET every time you want to issue a KUMPCON command to a
remote host.

Syntax
KUMPCON SET hostname

Parameters
<hostname>
Specifies the host name of the system to which you want to direct the
command.

196 IBM Tivoli Universal Agent: User’s Guide

SHOW
The SHOW command displays the details of an IBM Tivoli Universal Agent
application data definition.

Syntax
KUMPCON SHOW [application-name | metafile-name]

Parameters
You can specify either the name of the IBM Tivoli Universal Agent application or
the name of the metafile.
<application-name>
Specifies the IBM Tivoli Universal Agent application. The name of the IBM
Tivoli Universal Agent application is specified in the APPL statement in the
data definition metafile.
<metafile-name>
Specifies the metafile name.

Messages
The SHOW command output can look like the following:
Metafile name entered not defined

or
Console input accepted.
MetaFile: vmstat.mdl
Application: UXstatus
Group: UXsysSta Poll Data TTL=15
SOURCE: API -
SystemName Display Type Max Size 16
OSversion Display Type Max Size 16
PendingIOwaitRate Counter Type
IOstartRate Counter Type
OcompleteRate Counter Type
AvgWaitThreadQueueSi Counter Type
AvgRunThreadQueueSiz Counter Type
AvgNumbActivePageFra Counter Type
AvgNumbFreePageFrame Counter Type
PageInRate Counter Type
PageOutRate Counter Type
DevInterruptRate Counter Type
SystemCallRate Counter Type
ThreadContentSwitchR Counter Type
AvgUserCPU% Counter Type
AvgSystemCPU% Counter Type
AvgIdleCPU% Counter Type
AvgWaitCPU% Counter Type
UDPpktInRate Counter Type
UDPpktOutRate Counter Type
TCPpktInRate Counter Type
TCPpktOutRate Counter Type

Appendix C. Console commands 197

SHUTDOWN
The SHUTDOWN command instructs the IBM Tivoli Universal Agent to initiate
the termination procedure. The IBM Tivoli Universal Agent disconnects all
application connections and performs ″unregistration″ for each active application.
If you do not specify IMMED, you are prompted for which data provider you
want to stop.

Syntax
KUMPCON SHUTDOWN [IMMED]

Parameters
IMMED or I
(optional) Initiates immediate shutdown of one or all data providers
without further prompts or confirmation.

198 IBM Tivoli Universal Agent: User’s Guide

TRAPCNFG
The TRAPCNFG command instructs the SNMP Data Provider to refresh the SNMP
trap configuration file.

See Appendix D, “SNMP trap configuration,” on page 203 for additional

information on the TRAPCNFG command.

Syntax
KUMPCON TRAPCNFG

Parameters
This command requires no input parameters. Any specified parameter is ignored.

Appendix C. Console commands 199

UNPACK
The IBM Tivoli Universal Agent SNMP MIB metafiles are distributed in
compressed format. This is intended to prevent inadvertent modification of
supported product parts. Frequently, you might need to create your own versions
of vendor or standard metafiles or tailor the existing vendor metafiles to
accommodate local management needs and preferences. The compressed SNMP
metafiles make the local customization process very cumbersome.

The unpack command unpacks the input SNMP metafile and outputs the identical
uncompressed version of the metafile in the same input metafile location. You can
start unpack even when the IBM Tivoli Universal Agent is not active.

For example, to unpack metafile Novell_nwServer.mdl located in directory

\IBM\ITM\TMAITM6\metafiles\SNMP\vendor, you can issue the following
console command which results in the creation of text file Novell_nwServer.txt in
the same directory as the original metafile.
C:\IBM\Omegamon\TMAITM6>kumpcon unpack .\SNMP\vendor\Novel_nwServer.mdl

In this command, the local metafiles directory on a Windows operating system is

automatically assumed to be C:\IBM\Omegamon\TMAITM6\metafiles. Therefore,
you do not need to include that portion of the path name.

Syntax
KUMPCON U metafile-name

Parameters
<metafile-name>
The name of the metafile you want to unpack.

200 IBM Tivoli Universal Agent: User’s Guide

VALIDATE
The VALIDATE command instructs the IBM Tivoli Universal Agent parser and
syntax checker routines to validate the specified metafile. These same routines are
invoked at runtime so it is useful to run VALIDATE before activating a new or
changed metafile. You can start the VALIDATE command even when the IBM
Tivoli Universal Agent is not active. An application metafile validation report, with
an .rpt extension, is saved in the same directory where the metafile is located.

Note: To validate a metafile, you must use the KUMPCON program or

um_console script on UNIX operating systems. This is because the
validation must be performed on the host where your metafiles reside.

Syntax
KUMPCON VALIDATE metafile-name

Parameters
<metafile-name>
The name of the metafile you want to validate.

Appendix C. Console commands 201

202 IBM Tivoli Universal Agent: User’s Guide
Appendix D. SNMP trap configuration
This appendix documents the configuration file used by the SNMP Data Provider
to render trap information in a more easily readable form and to assign categories,
severities, status, and source IDs to traps. It also contains instructions for
modifying the default file or substituting your own configuration file.

The SNMP trap configuration trapcnfg file

At startup the SNMP Data Provider reads the configuration file named trapcnfg.
One purpose of this file is to translate SNMP trap information into a more readable
form. Another is to assign categories, severities, status, and source IDs to specific
traps, since these are not defined by SNMP.

You can modify the trapcnfg file to suit your site-specific needs by adding new
trap or enterprise definitions or changing the existing ones. You can also use your
own configuration file.

If the MIB on which an SNMP metafile is based contains trap definitions, a

trapcnfg_mibName file, where mibName is the enterprise MIB name, is also
distributed along with the MIB metafile. The purpose of these trapcnfg_mibName
files is to help you construct your final trapcnfg file. In them you can find
enterprise and trap definition records which you can copy and paste into your
official trap configuration file.

Location of configuration file

You can place the trap configuration file wherever you choose. The SNMP Data
Provider determines the location of the file as follows: If the environment variable
KUMP_SNMP_TRAPCNFG_FILE is set, the data provider searches for the specified
file in the specified directory location. If this variable is not set, the data provider
looks for trapcnfg in the work directory specified in KUM_WORK_PATH.

Using the HP OpenView trapd.conf file

The SNMP trapcnfg file is similar in format to the HP OpenView Network Node
Manager trapd.conf trap configuration file, so you can copy the OpenView file,
make any necessary modifications, and use it if you want to maintain the
formatting that you are accustomed to.

To use trapd.conf as your configuration file, use KUMP_SNMP_TRAPCNFG_FILE.

For example:
KUMP_SNMP_TRAPCNFG_FILE=C:\HPOV\trapd.conf

Types of records
trapcnfg contains three types of records or record blocks:
comments
Comment records begin with a pound sign (#).
enterprise definitions
Enterprise definitions consist of two blank-delimited tokens, where the first
token is a name and the second is an object identifier (OID) surrounded by
curly brackets ({ }).

© Copyright IBM Corp. 2003, 2005 203

 trap definitions
Trap definitions consist of eight blank-delimited tokens. Trap definitions
are block records, because each definition might consist of multiple
records.

The first type is self-explanatory. Figure 13 on page 205 shows examples of the
second and third types.

The first example in Figure 13 shows an enterprise definition record which defines
enterprise OID 1.3.6.1.4.1.311.1.1.3.1.1 as being MS-Windows NT.

The second example shows a trap definition record that defines trapName
MSNTCOLD as being associated with enterprise OID 1.3.6.1.4.1.311.1.1.3.1.1,
generic trap number 0, and specific trap number 0. Notice that the severity is in
decimal form whereas the category is in textual form. Severities are translated into
their textual form before being displayed in MIB reports. The next record in the
type 3 record block is the short description, which the IBM Tivoli Universal Agent
does not use. The IBM Tivoli Universal Agent uses the long description enclosed
within the delimiters SDESC and EDESC.

204 IBM Tivoli Universal Agent: User’s Guide

 Example of record type 2

MS- WindowsNT {1.3.6.1.4.1.311.1.1.3.1.1}

enterprise Name enterprise OID

Example of record type 3

MSNTCOLD {1.3.6.1.4.1.311.1.1.3.1.1} 0 0 A 1 0 “Status Events”

TrapName enterprise OID category

generic trap number

specific trap number

source ID

severity

status

MSNT - agent up with possible changes (coldStart trap)

SDESC

A coldStart trap signifies that the sending protocol entity is reinitializing itself in
such a way that the agent’s configuration or the protocol entity implementation
may be altered.

EDESC

Figure 13. Examples of configuration record types 2 and 3

Appendix D. SNMP trap configuration 205

Defaults for the trapcnfg file
The tables in this section list the defaults supported by the SNMP Data Provider.

Supported categories
Table 28 shows the categories supported by the IBM Tivoli Universal Agent.
Table 28. Categories supported by the SNMP Data Provider
Category Textual representation
0 Threshold Events
1 Network Topology Events
2 Error Events
3 Status Events
4 Node Configuration Events
5 Application Alert Events
6 All Category Events
7 Log Only Events
8 Map Events
9 Ignore Events

Table 29 lists the severities supported by the IBM Tivoli Universal Agent.
Table 29. Severities supported by the SNMP Data Provider
Severity Textual representation
0 Clear
1 Indeterminate
2 Warning
3 Minor Error
4 Critical
5 Major Error

Supported statuses
Table 30 shows the statuses defined in the IBM Tivoli Universal Agent
configuration file.
Table 30. Statuses supported by the SNMP Data Provider
Status Textual representation
0 Unchanged
1 Unknown
2 Up
3 Marginal
4 Down
5 Unmanaged
6 Acknowledge
7 User1

206 IBM Tivoli Universal Agent: User’s Guide

 Table 30. Statuses supported by the SNMP Data Provider (continued)
Status Textual representation
8 User2

Supported source IDs

Table 31 lists the source IDs supported by trapcnfg.
Table 31. Source IDs supported by the SNMP Data Provider
Source ID Description
a Application
A Agent
C Xnmcollect
d Demo
D Data Collector
E Nvevents
I Ipmap
L LoadMIB
m Shpmon
M IP topology
n netmon related
N netmon-generated traps
O OSI SA
P Non-IP traps
r Tralertd
s Spappld
S Security Agent
t Xnmtrap
T Trapd
V Vendor related
? Unknown

Modifying the trapcnfg file

You can add enterprise or trap definition records to trapcnfg to suit your
monitoring needs. You can also modify the existing records.

Any changes you make to trapcnfg are not picked up until you:
v restart the SNMP Data Provider, or
v issue the console command KUMPCON TRAPCNFG command to reload the file

Modifying default definitions

The default definitions are listed as comments in trapcnfg. To modify them, delete
the comment marker (#) and change the values.

Appendix D. SNMP trap configuration 207

 TRAPCNFG console command
The IBM Tivoli Universal Agent console interface, kumpcon on Windows and
um_console on UNIX, accepts an argument of TRAPCNFG that instructs the SNMP
Data Provider to reload the trapcnfg file, picking up changes.

208 IBM Tivoli Universal Agent: User’s Guide

Appendix E. Environment variables
This appendix documents the environment variables for the IBM Tivoli Universal
Agent and its data providers.

Setting environment variables

The IBM Tivoli Universal Agent and its data providers support a number of
environment variables which specify values for locations, ports, working
directories, and the like. Unless you specify otherwise, the default values for these
variables are in force. After you have installed the IBM Tivoli Universal Agent, you
can override the defaults for some of these variables.

Name and location of environment variables file

To change the default values, you must enter the appropriate variable and the
desired value in a environment variables file. The name and location of the
variables file differ by operating system.

Table 32 contains the name and location of the environment variables file on each
of the supported operating systems.
Table 32. Name and location of variables file by operating system
Operating system Location Name
UNIX <install_dir>/config/ um.ini
Windows IBM\ITM\TMAITM6\ KUMENV

Editing environment variables on Windows operating systems

On Windows operating systems, you can edit environment variables in the
KUMENV file directly using a text editor or using Manage Tivoli Enterprise
Monitoring Services. If you choose to use a text editor, the KUMENV file is located
by default in the IBM\Omegamon\TMAITM6\ directory.

Editing KUMENV on Windows operating systems using Manage

Tivoli Enterprise Monitoring Services
Perform the following steps to edit KUMENV using Manage Tivoli Enterprise
Monitoring Services:
1. From the Start menu, select Programs → IBM Tivoli Monitoring → Manage
Tivoli Enterprise Monitoring Services.
The Manage Tivoli Enterprise Monitoring Services window is displayed.
2. Right-click the IBM Tivoli Universal Agent, then select Advanced → Edit ENV
file . . .
KUMENV is opened in Notepad.
3. Edit or add the variables you want to specify.
4. Save the changes and close Notepad.

© Copyright IBM Corp. 2003, 2005 209

 Editing environment variables on UNIX operating systems
Use a text editor to set the environment variables in the um.ini file, located in
<install_dir>/config, where <install_dir> is the directory in which you installed
the IBM Tivoli Universal Agent.

Note: You must edit the um.ini file, not the um.config file or your updates will be
lost the next time the IBM Tivoli Universal Agent is started. The agent
startup scripts perform environment variable substitutions and copy the
contents of the um.ini file to the um.config file. Every time you start the
IBM Tivoli Universal Agent on UNIX operating systems, the um.config file
is completely rebuilt from the um.ini file.

Setting the working directory

The working directory is where the IBM Tivoli Universal Agent looks for
configuration files and where it places its working files. On Windows operating
systems, a separate directory, named work, is created for you and the variable
KUM_WORK_PATH preset to specify IBM\ITM\TMAITM6\work as the working
directory. On UNIX operating systems, a separate directory, named work, is created
for you and the variable KUM_WORK_PATH preset to specify
<install_dir>/<architecture>/um/work, where <architecture> is the operating
system and version. For example:
/TivoliHome/sol283/um/work

Indicates the Solaris 2.8 32-bit operating system.

You can use KUM_WORK_PATH to specify whatever directory you like.

IBM Tivoli Universal Agent and data provider environment variables

The environment variables for the IBM Tivoli Universal Agent and its data
providers allow you to override default values for locations, ports, working
directories, and the like.

The following table presents the variables for the IBM Tivoli Universal Agent and
each of its data providers.
Table 33. IBM Tivoli Universal Agent environment variables
Environment variable Description Default Example
KUM_WORK_PATH Sets the default working Directory home/
directory for the IBM where IBM MyWork
Tivoli Universal Agent. Tivoli
Universal
Agent stores
configuration
files and
working files.
KUM_UMC Controls the sending of Yes No
SNMP trap and network
information to the
Universal Message
Console.
IBM Tivoli Universal Agent

210 IBM Tivoli Universal Agent: User’s Guide

Table 33. IBM Tivoli Universal Agent environment variables (continued)
Environment variable Description Default Example
KUMA_DCH_PORT Overrides the agent’s 1919 6134
default data clearinghouse
port.
KUMA_MAX_ATTRGROUPS_ Controls the maximum 64 128
PER_APPL number of attribute
groups that can be in a
single metafile. You cannot
set it higher than 256.
KUMA_MAX_EVENT_ENTRIES Controls the maximum 100 500
number of rows of event
data in a Tivoli Enterprise
Portal workspace.
KUMA_WRITE_OPTLOG Controls the writing of Y N
action data to the Tivoli
Enterprise Portal
Operations Log.
KUMA_STARTUP_DP Specifies which data ASFS SNMP,
providers to start. ODBC
KUMA_REPORT_REQUEST_ Used to establish the 15 30
EXPIRATION amount of time, in
seconds, to wait for a
response to a
demand-driven report
request. When the request
times out, the last
available rows for that
table is displayed.
All data providers
AGENT_LOCALE Specifies a locale setting in The default ja_JP
the Language_Territory locale on the
format. All IBM Tivoli local system
Universal Agent data
providers use this locale.
You only need to specify
this environment variable
if you want to use a
non-default locale.
KUMP_DEFAULT_CODEPAGE Specifies a code page The default GB-18030
value that is used for all code page on
IBM Tivoli Universal the local
Agent data providers. You system
only need to specify this
environment variable if
you want to use a
non-default code page.
KUMP_DPCONSOLE_PORT Overrides the default 7700 8700
listening port for receiving
console commands. Must
be specified if sending a
console command to an
alternate instance of the
IBM Tivoli Universal
Agent.

Appendix E. Environment variables 211

 Table 33. IBM Tivoli Universal Agent environment variables (continued)
Environment variable Description Default Example
KUMP_DCH_HOST Directs the data provider Same host as fin1
to an IBM Tivoli Universal the data
Agent residing somewhere provider
other than the same host
as the data provider.
KUMP_INIT_CONFIG_PATH Specifies the location of work /Tivoli/
the data provider directory MyConfig
configuration file if
somewhere other than the
work directory.
KUMP_META_PATH Specifies the location of metafiles /home/
the data provider metafiles directory metafiles/
if somewhere other than test
the metafiles directory.
KUMP_META_SERVER Directs the data provider No metafile fin1
to use a centralized server
metafile server.
KUMA_ATOMIC_SITUATIONS Identifies specific None CICS_
atomized attributes within Abend:2
situations for use in
suppressing duplicate
actions in successive
sampling intervals. Enable
this feature by adding the
variable to your IBM
Tivoli Universal Agent
configuration file
(KUMENV or um.ini). Use
the following format:
KUMA_ATOMIC_
SITUATIONS=sitname1:#,
sitname2:#,...where each
entry consists of a
Sitname:Attribute
ColumnNumber pair. If
you specify more than one
situation, they must be
comma separated. Each
atomized situation name
must be followed by a
colon delimiter, which in
turn is followed by the
column number of the
atomic attribute used by
the situation. The column
number equates to the
numeric sequence of the
attribute in the IBM Tivoli
Universal Agent metafile.
File Data Provider

212 IBM Tivoli Universal Agent: User’s Guide

Table 33. IBM Tivoli Universal Agent environment variables (continued)
Environment variable Description Default Example
KUMP_DP_SAMPLE_FACTOR For polled data, sets the 5 10
sampling factor, which
together with the
time-to-live value
determines the sampling
frequency.
KUMP_DP_EVENT Sets the sampling 2 5
frequency for Event data,
in seconds.
KUMP_DP_FILE_EXIST_WAIT Specifies that the data NO YES
provider should terminate
the monitoring thread if it
detects that the file is
absent or empty.
KUMP_DP_FILE_SWITCH_ Specifies the frequency in 600 120
CHECK_INTERVAL seconds that the File Data
Provider searches for a
different monitoring file to
switch to when dynamic
file name support is being
used.
API Server Data Provider
KUMP_API_BYPASS_VAL Bypasses parameter NO YES
validation for API calls.
KUMP_API_DPAPI_HOST Identifies the host of the same host as atlantis
API Server if not the same API client
as the client.
KUMP_API_DPAPI_PORT Overrides the API Server 7600 5028
default listening port.
KUMP_API_TRANSPORT Elects one of three modes TCP/IP IPC
of communication between
the API client and the
server.
KUMP_API_REQUEST_WAIT Governs how long the API 30 60
client waits for a reply to
a request to the API Server
Data Provider (in
seconds).
KUMP_API_VERBOSE Toggles detailed trace for NO YES
API client.
Socket Data Provider
KUM_DP_HOSTNAME Sets the preferred host name of the fin1
name (network interface) first installed
on a multiple host system network
if the data provider interface
resides on another system.
KUMP_DP_PORT Overrides the default 7500 5028
Socket Data Provider
listening port.

Appendix E. Environment variables 213

 Table 33. IBM Tivoli Universal Agent environment variables (continued)
Environment variable Description Default Example
KUMP_TCP_DISCONNECT_ Governs whether or not YES NO
BY_TTL the IBM Tivoli Universal
Agent delays notifying
IBM Tivoli Monitoring
that a TCP disconnection
has occurred until the TTL
has expired. If this value
is set to N, the managed
system for the socket
metafile application
remains online even after
the socket client program
has disconnected.
KUMP_TCP_OUTAGE_ Controls the length of time 180 90
WINDOW the IBM Tivoli Universal
Agent has to detect a
network or system power
outage causing a lost
connection from a socket
client program.
Post Data Provider
KUMP_POST_DP_PORT Overrides the default Post 7575 5028
Data Provider listening
port.
KUMP_POST_APPL_NAME Overrides the application MAS MSG
name defined in the
KUMPOST metafile.
KUMP_POST_GROUP_NAME Overrides the name of the dpPost messages
attribute group defined in
the KUMPOST metafile.
KUMP_POST_APPL_TTL Overrides the time-to-live 3600 1800
value of the attribute
group.
KUMP_POST_CATEGORY Redefines default post See, “Post See, “Post
categories or adds new Data Data
ones. Provider” on Provider”
page 54 on page 54
SNMP Data Provider - Network reports
KUMP_SNMP_NETDATA_TTL Controls the frequency at 14400 seconds 12200
which the network
discovery and
management reports are
updated. A shorter
interval increases the rate
of network discovery
messages and overall
network load, but ensures
that the reports reflect the
current network resource
status more closely.
SNMP Data Provider - Network discovery

214 IBM Tivoli Universal Agent: User’s Guide

Table 33. IBM Tivoli Universal Agent environment variables (continued)
Environment variable Description Default Example
KUMP_SNMP_NET_ Serves as a switch Yes No
DISCOVERY indicating whether or not
to perform discovery of
network resources. If set
to “No,” the SNMP Data
Provider will have
knowledge of only default
gateways and routers and
the local network segment
the data provider is part
of: the ROUTER
workspace will show data
only for the default
gateways and routers, and
the NETSUMMARY
workspace will show only
data for the local network.
KUMP_SNMP_MANAGE_ Serves as a switch Yes No
LOCAL_NETWORK indicating whether or not
to manage the local
network. Set the value to
“No” to automatically
disable management of the
local network.
KUMP_SNMP_NET_ Serves as a switch No Yes
DISCOVER_ENTERPRISE indicating whether or not
network discovery should
determine the status of the
entire enterprise network.
This variable is
meaningful only if
KUMP_SNMP_NET
_DISCOVERY is set to
“Yes.” If this variable is set
to “No,” several of the
attributes in the
NETSUMMARY
workspace will show a
value of zero for networks
other than the SNMP Data
Provider local network.
KUMP_SNMP_NET_ Specifies the public Tivoli
COMMUNITY enterprise-wide default
community name for
SNMP agents.
KUMP_SNMP_CHECK_ Specifies the base 1800 3600
CONFIG_INTERVAL discovery window (BDW),
in seconds.
KUMP_SNMP_DEBUG_ Used to debug router No Yes
DISCOVERY_ROUTE discovery processing.
KUMP_SNMP_DEBUG_ Used to debug the general No Yes
DISCOVERY_ENTERPRISE network discovery
processing.

Appendix E. Environment variables 215

 Table 33. IBM Tivoli Universal Agent environment variables (continued)
Environment variable Description Default Example
KUMP_SNMP_DEBUG_ Used to debug the No Yes
DISCOVERY_NETWORK discovery of resources
within a network.
KUMP_SNMP_DEBUG_MIB_ Used to debug the MIB No Yes
MANAGER data collection request
flow.
KUMP_SNMP_DEBUG_MIB_IO Used to debug SNMP No Yes
Protocol Data Unit (PDU)
processing.
KUMP_SNMP_DEBUG_TRAP Used to debug SNMP trap No Yes
reception and processing
logic.
SNMP Data Provider - Trap management
KUMP_SNMP_MONITOR_ Serves as a switch Yes No
TRAP indicating whether or not
monitoring of SNMP
network traps is required.
KUMP_SNMP_TRAP_ Controls which traps are 2 3
CONSOLE_SEV forwarded to the
Universal Message
Console, on the basis of
their severity.
KUMP_SNMP_TRAP_PORT Specifies an installation None 1952
specific trap destination
port that the SNMP Data
Provider must monitor in
addition to the standard
trap listening port 162.
KUMP_SNMP_TRAP_VERBOSE Acts as a switch to enable No Yes
or disable verbose
debugging messages
which help in trap-related
problem determination.
KUMP_SNMP_TRAPCNFG_ Specifies the name of the trapcnfg trapd.cfg
FILE configuration file where
installation-specific traps
are defined.
KUMP_SNMP_TRAPCNFG_ Specifies the keyword in CATEGORY cat
CATEGORY the trap configuration file
that signals the SNMP
trap category definitions.
KUMP_SNMP_TRAPCNFG_ Specifies the keyword in SEVERITY Importance
SEVERITY the trap configuration file
that contains the
definitions of the SNMP
trap severities.
KUMP_SNMP_TRAPCNFG_ Specifies a keyword in the SOURCEID Source
SOURCEID trap configuration file that
contains the definitions of
SNMP agent source types.

216 IBM Tivoli Universal Agent: User’s Guide

Table 33. IBM Tivoli Universal Agent environment variables (continued)
Environment variable Description Default Example
KUMP_SNMP_TRAPCNFG_ Specifies a keyword in the STATUS CurrStat
STATUS trap configuration file that
contains the definitions of
SNMP trap status.
SNMP Emitter
KUMP_TRAP_DESTINATION Defines the host names of None HostA,
the SNMP Manager that HostB
receives traps that are sent
by the IBM Tivoli
Universal Agent SNMP
Emitter. If multiple host
names are specified, you
must separate them by
commas.
KUMP_TRAP_EMIT_ Defines the community public secret
COMMUNITY name that the receiving
SNMP Manager product
has been configured to
use.
KUMP_TRAP_USE_POLICY_ Determines whether the N Y
SEVERITY severity value specified in
the SNMP Emitter policy
definition will be sent as
the main Severity value in
the emitted trap.
HTTP Data Provider
KUMP_URL_OUTPUT_STAT Used to output URL No Yes
statistics to a CSV file for
EXCEL spreadsheet
analysis. The CSV file
name is URLSTATS.csv
and it is located in the
IBM Tivoli Universal
Agent product installation
WORK directory.
KUMP_URL_MAX_REPLY_ Used to establish the wait 45 60
WAIT time for a URL reply. If
the default of 45 seconds
results in frequent
“Timeout occurred” status
messages, set a higher
value.
KUMP_URL_OUTPUT_HTML Used to download the No Yes
HTML file associated with
the URL being monitored
to a subdirectory within
the IBM Tivoli Universal
Agent WORK directory.
The name of the
subdirectory match the
URL name.

Appendix E. Environment variables 217

 Table 33. IBM Tivoli Universal Agent environment variables (continued)
Environment variable Description Default Example
KUMP_HTTP_PROXY_USERID Used for proxy servers to <none> Admin for
KUMP_HTTP_PROXY_ establish userid/password User
PASSWORD validation before you can IDtivoli for
access the external Web Password
sites. Specify the two
variables to allow the
HTTP Data Provider to
perform proxy
authentication.
KUMP_HTTP_DEBUG Used to help diagnose a No Yes
URL monitoring problem.
IBM Customer Support
can ask you to provide
detailed tracing of the
HTTP Data Provider
component and send the
generated UA RAS1 log.
KDH_CLIENTPROXY Used to specify a None 1920
particular proxy host
name and port number
that the HTTP Data
Provider uses when
accessing URLs.
ODBC Data Provider
KUMP_ODBC_MAX_ROWS Used to globally specify 100 50
the maximum number of
rows to return for each
ODBC table in a metafile.
KUMP_ODBC_DEBUG Used to help diagnose an N Y
ODBC monitoring
problem. IBM Customer
Support can ask you to
provide detailed tracing of
the ODBC Data Provider
component and send the
generated UA RAS1 log.
Script Data Provider
KUMP_SCRIPT_DEBUG Used to help diagnose a N Y
Script Data Provider
monitoring problem. IBM
Customer Support can ask
you to capture detailed
tracing of the Script Data
Provider component and
send the generated IBM
Tivoli Universal Agent
RAS1 log file.
Console interface

218 IBM Tivoli Universal Agent: User’s Guide

Table 33. IBM Tivoli Universal Agent environment variables (continued)
Environment variable Description Default Example
KUMP_DPCONSOLE_PORT Specifies a non-default 7700 8700
listening port that the IBM
Tivoli Universal Agent
console server is using to
service console command
requests. You must set this
environment variable
when sending commands
to an alternate instance of
the IBM Tivoli Universal
Agent.
KUMP_DPCONSOLE_ Determines whether to N Y
NOCONFIRM bypass the confirmation
prompt for a Delete or
Refresh command.

Appendix E. Environment variables 219

220 IBM Tivoli Universal Agent: User’s Guide
Appendix F. Migration
This Appendix explains migration from previous versions of the Universal Agent
to Version 6.1.0 of the IBM Tivoli Universal Agent.

Migrating to version 6.1.0 of the IBM Tivoli Universal Agent

Migrating to the IBM Tivoli Universal Agent, version 6.1.0 from a previous version
is a simple process. Be aware of the following:
v All of your existing Universal Agent metafiles and configuration work files are
reusable, as is, in the IBM Tivoli Universal Agent, V6.1.
v There are no migration utilities or special conversion tools that you need to run.
v A migration to the IBM Tivoli Universal Agent, V6.1 does require that you
recompile and relink any C/C++ API client programs you have written. Update
your API client program development environment with the UA610 API client
package. Also copy the UA610 KUMPAPI DLL or shared library to the directory
or path where your client program runs.

Migration process
Use the following steps to migrate from a previous version:
1. Backup all of your critical Universal Agent files. For example, metafiles and
configuration files that you have customized. Such files include KUMPCNFG,
KUMPURLS, TRAPCNFG and KUMSMIBI. Back up files where yo have set
special environment variables.For example, the KUMENV or um.ini/um.config
files.
2. Uninstall your previous version of the Universal Agent. This removes all of the
previous version binaries and registry entries.
3. Install the IBM Tivoli Universal Agent, V6.1.

Note: If you are upgrading from Universal Agent, Version 350, you must run
the following command after you install the IBM Tivoli Universal Agent,
V6.1:
<install_dir>/bin/itmcmd config -A um
4. Restore any metafiles that you want to reuse.
5. Restore any customized configuration files that you want to reuse.
6. Review KUMENV and um.ini/um.config files to determine whether or not you
want to update the KUMA_STARTUP_DP list or if you have any special
environment variable settings to restore from your backup copy.

Note: On UNIX operating systems, configure the IBM Tivoli Universal Agent,
V6.1 and specify the data providers you want to start.
7. Start the IBM Tivoli Universal Agent.
8. Verify that all of your IBM Tivoli Universal Agent monitoring applications
come online.

Note: The IBM Tivoli Universal Agent product-provided situations have not
changed since Universal Agent, Version 4.1.0. Therefore, it is normal to see
messages such as seed data already exists or rc = 80 when adding Tivoli
Enterprise Monitoring Server application support for the IBM Tivoli

© Copyright IBM Corp. 2003, 2005 221

 Universal Agent, V6.1. These messages simply indicate that the Tivoli
Enterprise Monitoring Server already contains definitions for the IBM Tivoli
Universal Agent product-provided situations.

222 IBM Tivoli Universal Agent: User’s Guide

Appendix G. Starting data providers as separate processes
This appendix is intended for advanced users who want to start IBM Tivoli
Universal Agent data providers as separate processes.

Starting data providers

In most monitoring scenarios, data providers run as threads of the IBM Tivoli
Universal Agent. This is the default mode of operation. It simplifies configuration
and reduces the incidence of problems. Some users, however, can find it necessary
to run data providers as separate, standalone processes, and usually on different
hosts from where the IBM Tivoli Universal Agent is running. This technique is
useful if data collection needs to occur in any of the following ways:
v Outside a firewall
v On a special machine with limited resources
v To monitor a file on a remote system

The IBM Tivoli Universal Agent does support running data providers as separate
processes, but you must set some additional environment variables and create
scripts or commands for running the data provider executables.

Startup programs
You can start data providers as separate processes by invoking the programs
shown in Table 34. These standalone data provider programs are distributed with
the IBM Tivoli Universal Agent product. The names of the programs can vary
slightly between operating systems. For example, the programs on Windows
operating systems have an .exe extension.
Table 34. Starting data providers
To start Invoke
API Server Data Provider KUMPAPIS
API, Socket, File, and Script KUMPASFS
File Data Provider KUMPFILE
HTTP Data Provider KUMPHTTP
ODBC Data Provider KUMPODBC
Post Data Provider KUMPPOST
Script Data Provider KUMPSCRP
Socket Data Provider KUMPSOCK
SNMP Data Provider KUMPSNMP

Execution environment
You must have the following execution environment in place when you start data
providers as separate processes:
v The following three IBM Tivoli Universal Agent, DLLs for Windows operating
systems and shared libraries on UNIX operating systems, must either be in the
same directory as the data provider program or accessible through the library
search path:

© Copyright IBM Corp. 2003, 2005 223

 – KUM0610
– KUMP610
– KUMS1API
v On Windows and UNIX operating systems, the data providers also require the
following IBM Tivoli Monitoring building block libraries:
– KBB
– KDC
– KDE
– KDH
– KNS
– KDSFILT
– KGLBASE
– KHDXCL1
– KLX
– KRA
These libraries, along with the IBM Tivoli Universal Agent libraries, must either
be in the same directory as the data provider program or accessible through the
library search path.
v The IBM Tivoli Universal Agent KUMPSF and KUMPCNFG configuration files, must
be in a \work subdirectory below the directory where the data provider
program resides. If you are running the HTTP Data Provider as a standalone
process, include the KUMPURLS configuration file in the \work subdirectory.
v The KUMENV and um.ini/um.config files are not required to run a standalone data
provider because they are only required for running the IBM Tivoli Universal
Agent.
v Any metafiles that you want the data provider to load must be located in a
\metafiles subdirectory below the directory where the data provider program
resides. If your metafiles are located in a different directory, you must set the
search path using the KUMP_META_PATH environment variable.

Note: If you are running the HTTP Data Provider in standalone mode, you do
not need the \metafiles subdirectory because there are no metafiles with
the HTTP Data Provider.

Connecting to the IBM Tivoli Universal Agent

You must set environment variables to successfully connect your standalone data
provider to the IBM Tivoli Universal Agent. By default, a data provider assumes
that the IBM Tivoli Universal Agent to which it is connecting is running on the
local host. To connect the standalone data provider to an IBM Tivoli Universal
Agent running elsewhere, you must set the KUMP_DCH_HOST environment variable to
the proper remote host name.

The following example connects a standalone data provider to the IBM Tivoli
Universal Agent running on a machine named FIN1:
KUMP_DCH_HOST=FIN1

The following is a list of additional environment variables that you can use to set a
standalone data provider:
v The following example assumes an IP connection to the IBM Tivoli Universal
Agent:

224 IBM Tivoli Universal Agent: User’s Guide

 KDC_FAMILIES=use:n ip use:y
v The following example is used to control process signal handling:
KBB_SIG1=dumpoff -asyncoff
v The following example is used as needed to log standalone data provider
activity:
KBB_RAS1=ERROR ^>logfile

You must set additional environment variables if your data provider is connecting
to an alternative instance of the IBM Tivoli Universal Agent, or to a primary
instance that has overridden the DCH port value. If you are not using the default
data provider listening port (port 1919) of the IBM Tivoli Universal Agent the data
provider fails to connect and the data provider managed systems do not come
online.

Note: The first alternate instance of the IBM Tivoli Universal Agent uses a DCH
port number of 49219, while you can use the KUMA_DCH_PORT environment
variable to override the default 1919 value for a primary instance. If you
need to connect your data provider to a DCH port number other than 1919,
you must also set KUMA_DCH_PORT to the appropriate port number in your list
of environment variables.

Because you must set environment variables before launching the data provider
executable file, as a convenience, create a script or .bat file that sets the
environment variables and then calls the data provider program. You can use the
following example of a Windows .bat file to start the File Data Provider executable,
kumpfile:
set KDC_FAMILIES=use:n ip use:y
set KBB_SIG1=dumpoff -asyncoff
set KUMP_DCH_HOST=UAHOST1
set KUMP_META_PATH=c:\standalone\metafiles
set KBB_RAS1=ERROR ^>filedp.log

start /min kumpfile

exit

You can create an equivalent shell script for UNIX operating systems.

Note: The IBM Tivoli Universal Agent you are connecting to does not need to be
running the same data provider type that you are starting. For example, if
you are running a standalone File Data Provider to monitor a file on a
remote system, you do not need to also start the ASFS or File Data Provider
on the target IBM Tivoli Universal Agent.

Starting sequence
You can start standalone data providers either before or after you start the IBM
Tivoli Universal Agent. If the data provider attempts to connect to a IBM Tivoli
Universal Agent that has not yet started, the data provider waits and continues to
retry until a successful connection is made. If the IBM Tivoli Universal Agent is
recycled, the data provider detects the condition and synchronizes its operation
with the IBM Tivoli Universal Agent. However, the data collected by the data
provider during the connectivity outage is lost.

Appendix G. Starting data providers as separate processes 225

Stopping data providers
To stop a standalone data provider, you can terminate the script or .bat file that
launched the data provider executable. As an alternative, you can invoke the
SHUTDOWN command either from the Take Action window or from the console
command program, kumpcon on Windows operating systems and um_console on
UNIX operating systems.

The SHUTDOWN command

The IBM Tivoli Universal Agent console command SHUTDOWN stops a data
provider normally. If more than one data provider is running, the program
prompts you to specify which type you want to stop.

Termination delays
The data provider synchronizes its internal operations and initiates orderly
termination of all execution threads. Therefore, it is normal to observe a slight
delay in final process termination after issuing the SHUTDOWN command.

Managed system offline

After the data provider shutdown completes, the managed systems activated by
the data provider are dimmed out in the Tivoli Enterprise Portal navigator to
reflect their offline status.

226 IBM Tivoli Universal Agent: User’s Guide

Appendix H. Accessibility
Accessibility features help users with physical disabilities, such as restricted
mobility or limited vision, to use software products successfully. The major
accessibility features in this product enable users to do the following:
v Use assistive technologies, such as screen-reader software and digital speech
synthesizer, to hear what is displayed on the screen. Consult the product
documentation of the assistive technology for details on using those technologies
with this product.
v Operate specific or equivalent features using only the keyboard.
v Magnify what is displayed on the screen.

In addition, the product documentation was modified to include the following

features to aid accessibility:
v All documentation is available in both HTML and convertible PDF formats to
give the maximum opportunity for users to apply screen-reader software.
v All images in the documentation are provided with alternative text so that users
with vision impairments can understand the contents of the images.

Navigating the interface using the keyboard

Standard shortcut and accelerator keys are used by the product and are
documented by the operating system. Refer to the documentation provided by
your operating system for more information.

Magnifying what is displayed on the screen

You can enlarge information on the product windows using facilities provided by
the operating systems on which the product is run. For example, in a Microsoft
Windows environment, you can lower the resolution of the screen to enlarge the
font sizes of the text on the screen. Refer to the documentation provided by your
operating system for more information.

© Copyright IBM Corp. 2003, 2005 227

228 IBM Tivoli Universal Agent: User’s Guide
Appendix I. Support information
If you have a problem with your IBM software, you want to resolve it quickly. This
section describes the following options for obtaining support for IBM software
products:
v “Searching knowledge bases”
v “Obtaining fixes”
v “Receiving weekly support updates” on page 230
v “Contacting IBM Software Support” on page 230

Searching knowledge bases

You can search the available knowledge bases to determine whether your problem
was already encountered and is already documented.

Searching the information center

IBM provides extensive documentation that can be installed on your local
computer or on an intranet server. You can use the search function of this
information center to query conceptual information, instructions for completing
tasks, and reference information.

Searching the Internet

If you cannot find an answer to your question in the information center, search the
Internet for the latest, most complete information that might help you resolve your
problem.

To search multiple Internet resources for your product, use the Web search topic in
your information center. In the navigation frame, click Troubleshooting and
support  Searching knowledge bases and select Web search. From this topic, you
can search a variety of resources, including the following:
v IBM technotes
v IBM downloads
v IBM Redbooks
v IBM developerWorks
v Forums and newsgroups
v Google

Obtaining fixes
A product fix might be available to resolve your problem. To determine what fixes
are available for your IBM software product, follow these steps:
1. Go to the IBM Software Support Web site at
http://www.ibm.com/software/support.
2. Click Downloads and drivers in the Support topics section.
3. Select the Software category.
4. Select a product in the Sub-category list.
5. In the Find downloads and drivers by product section, select one software
category from the Category list.

© Copyright IBM Corp. 2003, 2005 229

 6. Select one product from the Sub-category list.
7. Type more search terms in the Search within results if you want to refine your
search.
8. Click Search.
9. From the list of downloads returned by your search, click the name of a fix to
read the description of the fix and to optionally download the fix.

For more information about the types of fixes that are available, see the IBM
Software Support Handbook at
http://techsupport.services.ibm.com/guides/handbook.html.

Receiving weekly support updates

To receive weekly e-mail notifications about fixes and other software support news,
follow these steps:
1. Go to the IBM Software Support Web site at
http://www.ibm.com/software/support.
2. Click My support in the upper right corner of the page.
3. If you have already registered for My support, sign in and skip to the next
step. If you have not registered, click register now. Complete the registration
form using your e-mail address as your IBM ID and click Submit.
4. Click Edit profile.
5. In the Products list, select Software. A second list is displayed.
6. In the second list, select a product segment, for example, Application servers.
A third list is displayed.
7. In the third list, select a product sub-segment, for example, Distributed
Application & Web Servers. A list of applicable products is displayed.
8. Select the products for which you want to receive updates, for example, IBM
HTTP Server and WebSphere Application Server.
9. Click Add products.
10. After selecting all products that are of interest to you, click Subscribe to email
on the Edit profile tab.
11. Select Please send these documents by weekly email.
12. Update your e-mail address as needed.
13. In the Documents list, select Software.
14. Select the types of documents that you want to receive information about.
15. Click Update.

If you experience problems with the My support feature, you can obtain help in
one of the following ways:
Online
Send an e-mail message to erchelp@ca.ibm.com, describing your problem.
By phone
Call 1-800-IBM-4You (1-800-426-4968).

Contacting IBM Software Support

IBM Software Support provides assistance with product defects.

230 IBM Tivoli Universal Agent: User’s Guide

 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 Web site at
http://www.lotus.com/services/passport.nsf/
WebDocs/Passport_Advantage_Home and click How to Enroll.
By phone
For the phone number to call in your country, go to the IBM Software
Support Web site 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 Web site at
https://techsupport.services.ibm.com/ssr/login.
v For customers with IBMLink, CATIA, Linux, OS/390, iSeries, pSeries, zSeries,
and other support agreements, go to the IBM Support Line Web site 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 Web site 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://techsupport.services.ibm.com/guides/contacts.html and click the name of
your geographic region for phone numbers of people who provide support for
your location.

To contact IBM Software support, follow these steps:

1. “Determining the business impact”
2. “Describing problems and gathering information” on page 232
3. “Submitting problems” on page 232

Determining the business impact

When you report a problem to IBM, you are asked to supply a severity level.
Therefore, you need to understand and assess the business impact of the problem
that you are reporting. Use the following criteria:
Severity 1
The problem has a critical business impact. You are unable to use the
program, resulting in a critical impact on operations. This condition
requires an immediate solution.

Appendix I. Support information 231

 Severity 2
The problem has a significant business impact. The program is usable, but
it is severely limited.
Severity 3
The problem has some business impact. The program is usable, but less
significant features (not critical to operations) are unavailable.
Severity 4
The problem has minimal business impact. The problem causes little impact
on operations, or a reasonable circumvention to the problem was
implemented.

Describing problems and gathering information

When describing a problem to IBM, be as specific as possible. Include all relevant
background information so that IBM Software Support specialists can help you
solve the problem efficiently. To save time, know the answers to these questions:
v What software versions were you running when the problem occurred?
v Do you have logs, traces, and messages that are related to the problem
symptoms? IBM Software Support is likely to ask for this information.
v Can you re-create the problem? If so, what steps were performed to re-create the
problem?
v Did you make any changes to the system? For example, did you make changes
to the hardware, operating system, networking software, and so on.
v Are you currently using a workaround for the problem? If so, be prepared to
explain the workaround when you report the problem.

Submitting problems
You can submit your problem to IBM Software Support in one of two ways:
Online
Click Submit and track problems on the IBM Software Support site
athttp://www.ibm.com/software/support/probsub.html. Type your
information into the appropriate problem submission form.
By phone
For the phone number to call in your country, go to the contacts page of
the IBM Software Support Handbook at
http://techsupport.services.ibm.com/guides/contacts.html and click the
name of your geographic region.

If the problem you submit is for a software defect or for missing or inaccurate
documentation, IBM Software Support creates an Authorized Program Analysis
Report (APAR). The APAR describes the problem in detail. Whenever possible,
IBM Software Support provides a workaround that you can implement until the
APAR is resolved and a fix is delivered. IBM publishes resolved APARs on the
Software Support Web site daily, so that other users who experience the same
problem can benefit from the same resolution.

232 IBM Tivoli Universal Agent: User’s Guide

Appendix J. Notices
This information was developed for products and services offered in the U.S.A.
IBM can not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service can be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right can
be used instead. However, it is the user’s responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.

IBM can 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:

IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation

Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS

PUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certain

transactions, therefore, this statement might not apply to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes is
incorporated in new editions of the publication. IBM can make improvements
and/or changes in the products and/or the programs described in this publication
at any time without notice.

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.

© Copyright IBM Corp. 2003, 2005 233

 IBM can use or distribute any of the information you supply in any way it believes
appropriate without incurring any obligation to you.

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.

Such information can be available, subject to appropriate terms and conditions,

including in some cases payment of a fee.

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.

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:

This information contains sample application programs in source language, which

illustrate programming techniques on various operating systems. You can copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
system for which the sample programs are written. These examples have not been
thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply
reliability, serviceability, or function of these programs. You can copy, modify, and
distribute these sample programs in any form without payment to IBM for the
purposes of developing, using, marketing, or distributing application programs
conforming to IBM’s application programming interfaces.

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

Trademarks
IBM, the IBM logo, CT, developerWorks, DB2, IBMLink, iSeries, Lotus, OS/390,
Passport Advantage, pSeries, Rational, Redbooks, Tivoli, and the Tivoli logo, Tivoli
Enterprise Console, VSE/ESA, WebSphere, z/OS, and zSeries are trademarks or
registered trademarks of International Business Machines Corporation in the
United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the
United States, other countries, or both.

234 IBM Tivoli Universal Agent: User’s Guide

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

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

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

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

both.

Other company, product, and service names may be trademarks or service marks
of others.

Appendix J. Notices 235

236 IBM Tivoli Universal Agent: User’s Guide
Index
Special characters attributes (continued)
invisible 158
*UNIVERSAL_DATA_aaavv 83 key 153
left truncation 159
mapping to MIB variables 166
A overview 166
accessibility xiii, 227 selecting 106
ACTION workspace 104 sequencing definitions 164, 166
activating metafiles ATTRIBUTES statement 51, 146, 158
using a configuration file 21 automation policy 6
using console commands 22
using Take Action commands 20
with console commands 19 B
address translation 89 BEHAV 156
Agent_Info attribute 30 books
Agent_Name attribute 30, 83 feedback on xi
AgentData, 70 online xi
AGPRF 155 ordering xi
AGTIM 156 see publications xii
API Server Data Provider 37, 39
calling programs 38
console commands 38
specifying host 39 C
specifying port 39 character code specification
APPL statement 117 association record 95
Application workspaces 101 in SOURCE statements 94
applications 30 cleanup programs 26
importing definitions of 28 client programs
overview 27 for Socket Data Provider 88
SNMP-MANAGER 67 CODEPAGE 41, 94
versioning of 28 commands
viewing definitions of 28 special characters xiv
ASFS Data Provider 11 syntax xiv
ASN.1 types 167 community name, specifying 70
associating data sources with metafiles CompareBySize 44
explicit association 92 configuration file
SOURCE statements 89 creating 21
ATOMIC 153 location 22
attrGroup 70 sharing 22
attribute definitions 151, 158 CONFIRM statement 139
attribute group console command interface, invoking on UNIX operating
data redirection 135 systems 181
attribute groups console command interface, invoking on Windows operating
MANAGED NODES 169, 170 systems 181
MIB-2 167 console commands 181, 201
MIBNODATA 171 DELETE 184
MIBSTATUS 172 GENERATE 185
NETSUMMARY 173, 174 IMPORT 188
NETWORK 175, 176 LIST 189
ROUTER 177, 178 LOADCOMM 190
SNMP-MANAGER groups 168 LOADLIST 191
TRAP 178, 180 LOADNAME 192
attribute groups, naming of 166 MNL ADD NODE 193
attributes 166, 172 MNL REMOVE NODE 194
defining 151, 158 REFRESH 195
derived 160 sending 35
descriptions of 168 SET 196
determining characteristics of 167 SHOW 197
duplicate 158 SHUTDOWN 198
enumeration support 159 specifying names in 182
filtering 162, 164 summary 181

© Copyright IBM Corp. 2003, 2005 237

console commands (continued) Destination System(s) 71
TRAPCNFG 199 disconnection notification 96
UNPACK 200 distributing situations 83
using 181, 183 DLM 147
VALIDATE 201 DLMSTR 148
Consolidated Data Provider, DLMSTRBGN 148
See </ph> ASFS Data Provider DLMSTREND 148
control statements 115, 149 DPLOG workspace 103
APPL 117 duplicate applications 36
attribute definitions 151, 158 duplicate attributes 158
ATTRIBUTES 146, 158 dynamic file name support 42, 43
CONFIRM 139
INTERNAL 123
NAME 119, 122
RECORDSET 135, 138
E
editing variables 209
SNMP 116
education
SOURCE 126, 134
see Tivoli technical training xiii
SQL 140
END 136
SUMMARY 141, 145
environment variables 209, 210
conventions
location of 209
typeface xiv
setting 209
creating situations
Agent_Name 83
overview 83
customer support F
See Software Support File Data Provider 40, 44
Customer workspaces 102 multiple record input 41
creating help for 102 required location 40
customizing contents 102 sampling frequency 40
names 102 special extracting routines 41
customizing applications 29, 30 fixes, obtaining 229
customizing workspace contents 102

G
D GENERATE command 53
data acknowledgment 97 GENERATE console command 185
data collection 72 generating metafiles 53
starting 70
stopping 71
data definitions
See </ph>metafiles
H
help
data providers 33, 53
creating 17
API Server 37, 39
viewing 102
ASFS 11
help text, defining 157
connecting to IBM Tivoli Universal Agent 224
hot console
execution environment for 223
See </ph>Universal Message Console
File 40, 44
hot lists
HTTP 45, 48
See </ph>managed node lists
ODBC 50, 53
HTTP Data Provider 45, 48
Post 54, 58
monitoring a URL 45
running multiple instances 33
URL attributes 47
Script 59
SNMP 64
Socket 88
starting as separate processes 223, 226 I
starting sequence 225 IBM Tivoli Monitoring data types 167
startup programs 223 IBM Tivoli Universal Agent API client package 37
types 33 IBM Tivoli Universal Agent APIs, invoking 37
data redirection IBM Tivoli Universal Agent applications
INPUT statement 123 creating 15
OUTPUT statement 123 definition 15
overview 135 monitoring 99, 108
data types 167 IBM Tivoli Universal Agent applications
DELETE console command 184 See </ph> metafiles
deleting managed systems 26 IBM Tivoli Universal Agent managed systems 99, 101
DEPRECATED 156 IMPORT console command 188
derived attributes 160 importing metafiles 30

238 IBM Tivoli Universal Agent: User’s Guide

information centers, searching for problem resolution 229 managed system
initiating data collection names 45
overview 69 managed system list 83, 107
initiating network discovery 78, 79 managed systems
INPUT statement 123 deleting 26
instance names 34 distributing situations to 83
INTERNAL statement 123 names 99, 100
Internet naming of 64
searching for problem resolution 229 overview 99
Interval 70 version changes 100, 101
version numbers 100
MANAGED-NODES attribute group 169, 170
K MANAGED-NODES report 73
manuals
key attributes 153
feedback on xi
knowledge bases, searching for problem resolution 229
online xi
KUM_DCH_HOST_NAME 182
ordering xi
KUM_UMC 83
see publications xii
KUM_WORK_PATH 203
MAS application 55
KUMA_DCH_PORT 225
metafile server 22, 24
KUMA_STARTUP_DP 11, 12, 50, 68
designating 23
KUMDPLOG 24
determining client/server roles 23
KUMENV 209
overriding definition 24
KUMENV file 209
storing metafiles 23
KUMP_API_DPAPI_HOST 39, 182
synchronization with client 23
KUMP_API_DPAPI_PORT 39
metafiles
KUMP_DCH_HOST 224
activating 19
KUMP_DP_EVENT 40
associating with data sources 89
KUMP_DP_HOSTNAME 89
creating 15
KUMP_DP_PORT 89
defining applications with 27
KUMP_DP_SAMPLE_FACTOR 40
examples 149
KUMP_DPCONSOLE_PORT 35
importing 28
KUMP_INIT_CONFIG_PATH 22
location of 27
KUMP_META_PATH 23, 29
naming 17
KUMP_META_SERVER 23
naming of 27
KUMP_POST_DP_PORT 54
resetting version number of 26
KUMP_SNMP_CONFIG_FILE 203
storing 18, 23
KUMP_SNMP_TRAP_CONSOLE_SEV 83
validating 18
KUMP_TCP_DISCONNECT_BY_TTL 96
versioning of 24, 27, 28
KUMP_TCP_OUTAGE_WINDOW 96
viewing 28
KUMPCNFG 21
MIB-2 attribute groups 167
location 22
MIBNODATA attribute group 171
sharing 22
MIBSTATUS attribute group 172
KUMPCON program 181
MIBSTATUS report 74
KUMPOST metafile 55
migration 221
KUMPSEND program 55, 57
MNL ADD NODE console command 193
MNL REMOVE NODE console command 194
modification number 25
L modifying metafiles 24, 27
legal notices 233 Monitor Start 70
LIST console command 189 Monitor Stop 71
LOADCOMM 190 monitoring IBM Tivoli Universal Agent applications 99, 108
LOADLIST 191 monitoring interval 107
LOADNAME 192 monitoring SNMP applications 69
LOCALE 41, 94 multi-interface systems 182
multiple host machines 89
multiple record input 41
M
Manage Start 78
Manage Stop 78 N
Manage Tivoli Enterprise Monitoring Services 12 NAME statement 51, 52, 119, 122
managed node lists 79, 82 NETSUMMARY attribute group 173, 174
activating 80 NETSUMMARY report 74
creating 80 NETWORK attribute group 175, 176
deactivating 81 network discovery 78, 79
location of 80 excluding a network 79
modifying 81 initiating 78

Index 239
network discovery (continued)
stopping 78, 79
S
NETWORK report 75, 76 sampling interval 83
network resources scalar variables 29
adding and removing 82 scenario 4
automatic grouping 81 Script Data Provider 59
NEW 136 managed system names 61
non-standard ports SET command 86, 87
data collection 71 SET console command 196
NONE 147 SET operations 86, 87
notification of disconnection 96 procedure 87
requirements 86
SHOW console command 197
SHUTDOWN console command 198
O Situation editor 106
ODBC Data Provider 50, 53 situations 83, 84, 105, 107
data collection 51 creating 83
generating metafiles definition 105
automatically 53 distributing 83, 106
sample metafile 50, 52 predefined 105
starting 50 selecting attributes 106
online publications setting monitoring interval 107
accessing xii specifying monitoring intervals for 83
OPTION{HISTORICALTIMESTAMP} 156 using 106
OPTION{PRIMARYKEY=<n>} 156 SMIv1 data types 167
ordering publications xi, xiii SNMP applications
outages 96 initiating data collection for 69
OUTPUT statement 123 monitoring 69, 83
SNMP-MANAGER 67
version numbers 28
P SNMP Data Provider 64
policy, automation 6 starting automatically 68
Post Data Provider 54, 58 SNMP emitter 113
acknowledgment stamp 55 environment variables 110
configuring runtime specifications 56, 57 establishing parameters 111
customizing 55 installing 110
default configuration 54, 55 integrating 110
environment variables 56 overview 109
message categories 55 using data 113
product-provided data 57 SNMP statement 116
sending data to 58 SNMP-MANAGER application 67
problem determination SNMP-MANAGER attribute groups 168
describing problems 232 SNMP-MANAGER reports 72, 78
determining business impact 231 accessing 73
submitting problems 232 MANAGED-NODES 73
product-provided situations 84 MIBSTATUS 74
descriptions of 84 NETSUMMARY 74
publications NETWORK 75, 76
accessing online xii overview 72
feedback on xi ROUTER 76
online xi TRAP 77
ordering xi, xiii Socket Data Provider 88
address translation 89
associating sources with metafiles 89
changing default port 89
R character code translation 94, 95
REAL 160 contacting 88
RECORDSET statement 135, 138 end of input 94
REFRESH console command 195 formatting buffers 93
reports 72, 78 limitations 97
SNMP-MANAGER 72, 78 name and address translation 89
resetting version numbers 26 on multiple host machines 89
ROUTER attribute group 177, 178 overview 88
ROUTER report 76 timing out 93
Software Support
contacting 230
describing problems 232
determining business impact 231

240 IBM Tivoli Universal Agent: User’s Guide

Software Support (continued) um_cleanup 26
receiving weekly updates 230 um_cleanup.bat 26
submitting problems 232 um.ini file 209
SOURCE statement 51, 52, 126, 134 Universal Message Console 82
specifying situation monitoring intervals 83 UNPACK command 28
SQL statement 51, 53, 140 UNPACK console command 200
starting data collection 70
starting data providers 223, 226
starting the data provider
automatically 68
V
VALIDATE command 28, 29, 30
on UNIX operating systems 69
VALIDATE program 201
on Windows operating systems 68
description 18
startup parameters
running 19
UNIX 12
validating metafiles 18
Windows operating systems 12
validation reports 29
stopping data collection 71
variables file
stopping the data provider 69
location 209
storing metafiles 18
name of 209
storing server metafiles 23
variables, editing 209
SUMMARY statement 141, 145
version number
incrementing 24, 25
resetting 26
T versions
TAB 147 of managed systems 100
tailbyrecord 44 of metafiles 24, 27
Take Action feature viewing metafiles 28
Manage Start 78
Manage Stop 78
Monitor Start 70
Monitor Stop 71
W
WHEN{<value>} 156
TCP 88, 97
WHSC{<attribute>} 157
TCP outage detection 96
working directory, setting 210
TEXT parameter 30
workspaces
time to live 84
ACTION 104
time-to-live (TTL) interval 40, 107, 119
application 101
timestamp insertion 121
DPLOG 103
Tivoli software information center xii
UAGENT 103
Tivoli technical training xiii
trademarks 234
training, Tivoli technical xiii
TRAP attribute group 178, 180
trap configuration 203, 208
TRAP report 77
TRAPCNFG 199
trapcnfg configuration file 203, 208
defaults in 206, 207
location of 203
modifying 207
overview 203
types of records in 203, 204
TRAPCNFG console command 208
trapcnfg defaults
supported categories 206
supported severities 206
supported source IDs 207
supported statuses 206
trapd.conf, using 203
truncation 35
TTL, see time-to-live interval 119
typeface conventions xiv

U
U 93
UAGENT workspaces 103
UDP 88, 94, 97

Index 241
242 IBM Tivoli Universal Agent: User’s Guide



Printed in USA

SC32-9459-00